RFC: Definition of Challenge / Verification structure

[coolaj86]

This is for the structure that keeps the state for verification challenges - such as sending a code via email or phone.

I would prefer to define the challenge structure as "opaque, just call JSON.stringify and save it as a string"... but since this will go in databases and whatnot, it seems prudent to be more explicit than that.

/**
 * @typedef Challenge
 * @property {number} attempts
 * @property {string} secret // TODO rename to code
 * @property {string} ordered_at
 * @property {string} ordered_by // TODO rename _agent
 * @property {string} ordered_ip
 * @property {string} verified_at // RFC3339 / ISO Timestamp
 * @property {string} verified_by
 * @property {string} verified_ip
 * @property {string} exchanged_at
 * @property {string} exchanged_by
 * @property {string} exchanged_ip
 * @property {string} type // such as 'email' or 'tel'
 * @property {string} value // such as 'me@example.com'
 * @property {string} deleted_at
 */

{
  "attempts": 3,
  "secret": "xxxxxx",
  "ordered_at": "2021-08-10T13:59:59.000",
  "ordered_by": "Mozilla Firefox 1.2.3 like Gecko Windows 1.2",
  "ordered_ip": "6.54.321.9",
  "verified_at": new Date().toISOString(),
  "verified_by": "Mozilla Firefox 1.2.3 like Gecko Windows 1.2",
  "verified_ip": "6.54.321.9",
  "exchanged_at": "",
  "exchanged_by": "",
  "exchanged_ip": "",
  "type": "email", // or "tel",
  "value": "me@example.com"
}

This may also need an expires_at and ordered_ could be instead created_.