@softistx/janus 0.0.0-stage → 0.73.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (911) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +2928 -2
  3. package/dist/auth/api-keys/authenticate-key.d.ts +21 -0
  4. package/dist/auth/api-keys/authenticate-key.d.ts.map +1 -0
  5. package/dist/auth/api-keys/bound.d.ts +11 -0
  6. package/dist/auth/api-keys/bound.d.ts.map +1 -0
  7. package/dist/auth/api-keys/count.d.ts +8 -0
  8. package/dist/auth/api-keys/count.d.ts.map +1 -0
  9. package/dist/auth/api-keys/create/checks.d.ts +42 -0
  10. package/dist/auth/api-keys/create/checks.d.ts.map +1 -0
  11. package/dist/auth/api-keys/create/index.d.ts +10 -0
  12. package/dist/auth/api-keys/create/index.d.ts.map +1 -0
  13. package/dist/auth/api-keys/events.d.ts +22 -0
  14. package/dist/auth/api-keys/events.d.ts.map +1 -0
  15. package/dist/auth/api-keys/expiry.d.ts +11 -0
  16. package/dist/auth/api-keys/expiry.d.ts.map +1 -0
  17. package/dist/auth/api-keys/flows.d.ts +13 -0
  18. package/dist/auth/api-keys/flows.d.ts.map +1 -0
  19. package/dist/auth/api-keys/index.d.ts +11 -0
  20. package/dist/auth/api-keys/index.d.ts.map +1 -0
  21. package/dist/auth/api-keys/read.d.ts +10 -0
  22. package/dist/auth/api-keys/read.d.ts.map +1 -0
  23. package/dist/auth/api-keys/shape.d.ts +24 -0
  24. package/dist/auth/api-keys/shape.d.ts.map +1 -0
  25. package/dist/auth/api-keys/to-api-key.d.ts +8 -0
  26. package/dist/auth/api-keys/to-api-key.d.ts.map +1 -0
  27. package/dist/auth/api-keys/token.d.ts +23 -0
  28. package/dist/auth/api-keys/token.d.ts.map +1 -0
  29. package/dist/auth/api-keys/user-bound.d.ts +10 -0
  30. package/dist/auth/api-keys/user-bound.d.ts.map +1 -0
  31. package/dist/auth/at.d.ts +9 -0
  32. package/dist/auth/at.d.ts.map +1 -0
  33. package/dist/auth/avatar/any-type.d.ts +13 -0
  34. package/dist/auth/avatar/any-type.d.ts.map +1 -0
  35. package/dist/auth/avatar/flows.d.ts +7 -0
  36. package/dist/auth/avatar/flows.d.ts.map +1 -0
  37. package/dist/auth/avatar/id.d.ts +10 -0
  38. package/dist/auth/avatar/id.d.ts.map +1 -0
  39. package/dist/auth/avatar/index.d.ts +7 -0
  40. package/dist/auth/avatar/index.d.ts.map +1 -0
  41. package/dist/auth/avatar/remove.d.ts +10 -0
  42. package/dist/auth/avatar/remove.d.ts.map +1 -0
  43. package/dist/auth/avatar/set.d.ts +12 -0
  44. package/dist/auth/avatar/set.d.ts.map +1 -0
  45. package/dist/auth/concurrency-limit.d.ts +13 -0
  46. package/dist/auth/concurrency-limit.d.ts.map +1 -0
  47. package/dist/auth/config/api-keys-config.d.ts +33 -0
  48. package/dist/auth/config/api-keys-config.d.ts.map +1 -0
  49. package/dist/auth/config/hasher.d.ts +22 -0
  50. package/dist/auth/config/hasher.d.ts.map +1 -0
  51. package/dist/auth/config/index.d.ts +24 -0
  52. package/dist/auth/config/index.d.ts.map +1 -0
  53. package/dist/auth/config/invitations-config.d.ts +74 -0
  54. package/dist/auth/config/invitations-config.d.ts.map +1 -0
  55. package/dist/auth/config/janus-config.d.ts +233 -0
  56. package/dist/auth/config/janus-config.d.ts.map +1 -0
  57. package/dist/auth/config/magic-link-config.d.ts +6 -0
  58. package/dist/auth/config/magic-link-config.d.ts.map +1 -0
  59. package/dist/auth/config/names.d.ts +9 -0
  60. package/dist/auth/config/names.d.ts.map +1 -0
  61. package/dist/auth/config/normalize.d.ts +26 -0
  62. package/dist/auth/config/normalize.d.ts.map +1 -0
  63. package/dist/auth/config/passkeys-config.d.ts +49 -0
  64. package/dist/auth/config/passkeys-config.d.ts.map +1 -0
  65. package/dist/auth/config/password-config.d.ts +22 -0
  66. package/dist/auth/config/password-config.d.ts.map +1 -0
  67. package/dist/auth/config/reserved.d.ts +14 -0
  68. package/dist/auth/config/reserved.d.ts.map +1 -0
  69. package/dist/auth/config/resolve-api-keys.d.ts +5 -0
  70. package/dist/auth/config/resolve-api-keys.d.ts.map +1 -0
  71. package/dist/auth/config/resolve-config.d.ts +9 -0
  72. package/dist/auth/config/resolve-config.d.ts.map +1 -0
  73. package/dist/auth/config/resolve-cookie.d.ts +5 -0
  74. package/dist/auth/config/resolve-cookie.d.ts.map +1 -0
  75. package/dist/auth/config/resolve-devices.d.ts +5 -0
  76. package/dist/auth/config/resolve-devices.d.ts.map +1 -0
  77. package/dist/auth/config/resolve-invitation-types.d.ts +5 -0
  78. package/dist/auth/config/resolve-invitation-types.d.ts.map +1 -0
  79. package/dist/auth/config/resolve-invitations.d.ts +5 -0
  80. package/dist/auth/config/resolve-invitations.d.ts.map +1 -0
  81. package/dist/auth/config/resolve-magic-link.d.ts +4 -0
  82. package/dist/auth/config/resolve-magic-link.d.ts.map +1 -0
  83. package/dist/auth/config/resolve-passkeys.d.ts +5 -0
  84. package/dist/auth/config/resolve-passkeys.d.ts.map +1 -0
  85. package/dist/auth/config/resolve-second-factor.d.ts +5 -0
  86. package/dist/auth/config/resolve-second-factor.d.ts.map +1 -0
  87. package/dist/auth/config/resolve-social.d.ts +17 -0
  88. package/dist/auth/config/resolve-social.d.ts.map +1 -0
  89. package/dist/auth/config/resolve-throttle.d.ts +37 -0
  90. package/dist/auth/config/resolve-throttle.d.ts.map +1 -0
  91. package/dist/auth/config/resolve-type.d.ts +6 -0
  92. package/dist/auth/config/resolve-type.d.ts.map +1 -0
  93. package/dist/auth/config/resolved-config.d.ts +126 -0
  94. package/dist/auth/config/resolved-config.d.ts.map +1 -0
  95. package/dist/auth/config/social-config.d.ts +154 -0
  96. package/dist/auth/config/social-config.d.ts.map +1 -0
  97. package/dist/auth/config/user-type.d.ts +79 -0
  98. package/dist/auth/config/user-type.d.ts.map +1 -0
  99. package/dist/auth/config/warn-throttle-window.d.ts +14 -0
  100. package/dist/auth/config/warn-throttle-window.d.ts.map +1 -0
  101. package/dist/auth/context/create-context.d.ts +31 -0
  102. package/dist/auth/context/create-context.d.ts.map +1 -0
  103. package/dist/auth/context/index.d.ts +17 -0
  104. package/dist/auth/context/index.d.ts.map +1 -0
  105. package/dist/auth/context/logins.d.ts +28 -0
  106. package/dist/auth/context/logins.d.ts.map +1 -0
  107. package/dist/auth/context/password.d.ts +34 -0
  108. package/dist/auth/context/password.d.ts.map +1 -0
  109. package/dist/auth/context/records.d.ts +27 -0
  110. package/dist/auth/context/records.d.ts.map +1 -0
  111. package/dist/auth/context/user.d.ts +21 -0
  112. package/dist/auth/context/user.d.ts.map +1 -0
  113. package/dist/auth/context/validate-fields.d.ts +12 -0
  114. package/dist/auth/context/validate-fields.d.ts.map +1 -0
  115. package/dist/auth/counter-key.d.ts +20 -0
  116. package/dist/auth/counter-key.d.ts.map +1 -0
  117. package/dist/auth/derived-keys.d.ts +9 -0
  118. package/dist/auth/derived-keys.d.ts.map +1 -0
  119. package/dist/auth/devices/cookie.d.ts +56 -0
  120. package/dist/auth/devices/cookie.d.ts.map +1 -0
  121. package/dist/auth/devices/hint.d.ts +42 -0
  122. package/dist/auth/devices/hint.d.ts.map +1 -0
  123. package/dist/auth/devices/index.d.ts +11 -0
  124. package/dist/auth/devices/index.d.ts.map +1 -0
  125. package/dist/auth/devices/report.d.ts +11 -0
  126. package/dist/auth/devices/report.d.ts.map +1 -0
  127. package/dist/auth/devices/token.d.ts +13 -0
  128. package/dist/auth/devices/token.d.ts.map +1 -0
  129. package/dist/auth/email-flows/any-type-change-email.d.ts +18 -0
  130. package/dist/auth/email-flows/any-type-change-email.d.ts.map +1 -0
  131. package/dist/auth/email-flows/any-type-reset-password.d.ts +19 -0
  132. package/dist/auth/email-flows/any-type-reset-password.d.ts.map +1 -0
  133. package/dist/auth/email-flows/any-type-verify-email.d.ts +18 -0
  134. package/dist/auth/email-flows/any-type-verify-email.d.ts.map +1 -0
  135. package/dist/auth/email-flows/change-email-token.d.ts +47 -0
  136. package/dist/auth/email-flows/change-email-token.d.ts.map +1 -0
  137. package/dist/auth/email-flows/change-email.d.ts +17 -0
  138. package/dist/auth/email-flows/change-email.d.ts.map +1 -0
  139. package/dist/auth/email-flows/confirm-reset.d.ts +16 -0
  140. package/dist/auth/email-flows/confirm-reset.d.ts.map +1 -0
  141. package/dist/auth/email-flows/email-token.d.ts +30 -0
  142. package/dist/auth/email-flows/email-token.d.ts.map +1 -0
  143. package/dist/auth/email-flows/flows.d.ts +13 -0
  144. package/dist/auth/email-flows/flows.d.ts.map +1 -0
  145. package/dist/auth/email-flows/index.d.ts +10 -0
  146. package/dist/auth/email-flows/index.d.ts.map +1 -0
  147. package/dist/auth/email-flows/owner-of.d.ts +17 -0
  148. package/dist/auth/email-flows/owner-of.d.ts.map +1 -0
  149. package/dist/auth/email-flows/prove-first.d.ts +45 -0
  150. package/dist/auth/email-flows/prove-first.d.ts.map +1 -0
  151. package/dist/auth/email-flows/reset-password.d.ts +17 -0
  152. package/dist/auth/email-flows/reset-password.d.ts.map +1 -0
  153. package/dist/auth/email-flows/set-email-verified.d.ts +19 -0
  154. package/dist/auth/email-flows/set-email-verified.d.ts.map +1 -0
  155. package/dist/auth/email-flows/verify-email.d.ts +25 -0
  156. package/dist/auth/email-flows/verify-email.d.ts.map +1 -0
  157. package/dist/auth/email-sign-in.d.ts +51 -0
  158. package/dist/auth/email-sign-in.d.ts.map +1 -0
  159. package/dist/auth/events.d.ts +166 -0
  160. package/dist/auth/events.d.ts.map +1 -0
  161. package/dist/auth/first-proof.d.ts +43 -0
  162. package/dist/auth/first-proof.d.ts.map +1 -0
  163. package/dist/auth/hashers.d.ts +52 -0
  164. package/dist/auth/hashers.d.ts.map +1 -0
  165. package/dist/auth/index.d.ts +22 -0
  166. package/dist/auth/index.d.ts.map +1 -0
  167. package/dist/auth/invitations/accept.d.ts +10 -0
  168. package/dist/auth/invitations/accept.d.ts.map +1 -0
  169. package/dist/auth/invitations/change-pending.d.ts +17 -0
  170. package/dist/auth/invitations/change-pending.d.ts.map +1 -0
  171. package/dist/auth/invitations/claim.d.ts +31 -0
  172. package/dist/auth/invitations/claim.d.ts.map +1 -0
  173. package/dist/auth/invitations/events.d.ts +46 -0
  174. package/dist/auth/invitations/events.d.ts.map +1 -0
  175. package/dist/auth/invitations/find-invitee.d.ts +20 -0
  176. package/dist/auth/invitations/find-invitee.d.ts.map +1 -0
  177. package/dist/auth/invitations/find-pending.d.ts +5 -0
  178. package/dist/auth/invitations/find-pending.d.ts.map +1 -0
  179. package/dist/auth/invitations/flows.d.ts +7 -0
  180. package/dist/auth/invitations/flows.d.ts.map +1 -0
  181. package/dist/auth/invitations/history-input.d.ts +29 -0
  182. package/dist/auth/invitations/history-input.d.ts.map +1 -0
  183. package/dist/auth/invitations/history.d.ts +10 -0
  184. package/dist/auth/invitations/history.d.ts.map +1 -0
  185. package/dist/auth/invitations/index.d.ts +11 -0
  186. package/dist/auth/invitations/index.d.ts.map +1 -0
  187. package/dist/auth/invitations/input.d.ts +30 -0
  188. package/dist/auth/invitations/input.d.ts.map +1 -0
  189. package/dist/auth/invitations/invited-type.d.ts +22 -0
  190. package/dist/auth/invitations/invited-type.d.ts.map +1 -0
  191. package/dist/auth/invitations/invitee.d.ts +11 -0
  192. package/dist/auth/invitations/invitee.d.ts.map +1 -0
  193. package/dist/auth/invitations/issue.d.ts +9 -0
  194. package/dist/auth/invitations/issue.d.ts.map +1 -0
  195. package/dist/auth/invitations/limit.d.ts +7 -0
  196. package/dist/auth/invitations/limit.d.ts.map +1 -0
  197. package/dist/auth/invitations/password-invitee.d.ts +18 -0
  198. package/dist/auth/invitations/password-invitee.d.ts.map +1 -0
  199. package/dist/auth/invitations/passwordless-invitee.d.ts +13 -0
  200. package/dist/auth/invitations/passwordless-invitee.d.ts.map +1 -0
  201. package/dist/auth/invitations/preview.d.ts +8 -0
  202. package/dist/auth/invitations/preview.d.ts.map +1 -0
  203. package/dist/auth/invitations/read.d.ts +10 -0
  204. package/dist/auth/invitations/read.d.ts.map +1 -0
  205. package/dist/auth/invitations/resend.d.ts +12 -0
  206. package/dist/auth/invitations/resend.d.ts.map +1 -0
  207. package/dist/auth/invitations/to-invitation.d.ts +11 -0
  208. package/dist/auth/invitations/to-invitation.d.ts.map +1 -0
  209. package/dist/auth/invitations/write.d.ts +17 -0
  210. package/dist/auth/invitations/write.d.ts.map +1 -0
  211. package/dist/auth/issuers/cache.d.ts +21 -0
  212. package/dist/auth/issuers/cache.d.ts.map +1 -0
  213. package/dist/auth/issuers/create.d.ts +18 -0
  214. package/dist/auth/issuers/create.d.ts.map +1 -0
  215. package/dist/auth/issuers/index.d.ts +3 -0
  216. package/dist/auth/issuers/index.d.ts.map +1 -0
  217. package/dist/auth/issuers/types.d.ts +45 -0
  218. package/dist/auth/issuers/types.d.ts.map +1 -0
  219. package/dist/auth/janus.d.ts +39 -0
  220. package/dist/auth/janus.d.ts.map +1 -0
  221. package/dist/auth/magic-link.d.ts +25 -0
  222. package/dist/auth/magic-link.d.ts.map +1 -0
  223. package/dist/auth/mail-requests.d.ts +55 -0
  224. package/dist/auth/mail-requests.d.ts.map +1 -0
  225. package/dist/auth/one-time/codes.d.ts +46 -0
  226. package/dist/auth/one-time/codes.d.ts.map +1 -0
  227. package/dist/auth/one-time/index.d.ts +15 -0
  228. package/dist/auth/one-time/index.d.ts.map +1 -0
  229. package/dist/auth/one-time/issue.d.ts +45 -0
  230. package/dist/auth/one-time/issue.d.ts.map +1 -0
  231. package/dist/auth/one-time/refusals.d.ts +26 -0
  232. package/dist/auth/one-time/refusals.d.ts.map +1 -0
  233. package/dist/auth/one-time/spend.d.ts +24 -0
  234. package/dist/auth/one-time/spend.d.ts.map +1 -0
  235. package/dist/auth/one-time/window.d.ts +50 -0
  236. package/dist/auth/one-time/window.d.ts.map +1 -0
  237. package/dist/auth/outage.d.ts +66 -0
  238. package/dist/auth/outage.d.ts.map +1 -0
  239. package/dist/auth/parse-sealing-keys.d.ts +26 -0
  240. package/dist/auth/parse-sealing-keys.d.ts.map +1 -0
  241. package/dist/auth/passkeys/assert.d.ts +51 -0
  242. package/dist/auth/passkeys/assert.d.ts.map +1 -0
  243. package/dist/auth/passkeys/assertion-options.d.ts +9 -0
  244. package/dist/auth/passkeys/assertion-options.d.ts.map +1 -0
  245. package/dist/auth/passkeys/challenge.d.ts +19 -0
  246. package/dist/auth/passkeys/challenge.d.ts.map +1 -0
  247. package/dist/auth/passkeys/commit.d.ts +33 -0
  248. package/dist/auth/passkeys/commit.d.ts.map +1 -0
  249. package/dist/auth/passkeys/flows.d.ts +13 -0
  250. package/dist/auth/passkeys/flows.d.ts.map +1 -0
  251. package/dist/auth/passkeys/index.d.ts +12 -0
  252. package/dist/auth/passkeys/index.d.ts.map +1 -0
  253. package/dist/auth/passkeys/manage.d.ts +11 -0
  254. package/dist/auth/passkeys/manage.d.ts.map +1 -0
  255. package/dist/auth/passkeys/name.d.ts +4 -0
  256. package/dist/auth/passkeys/name.d.ts.map +1 -0
  257. package/dist/auth/passkeys/register.d.ts +20 -0
  258. package/dist/auth/passkeys/register.d.ts.map +1 -0
  259. package/dist/auth/passkeys/registration-options.d.ts +22 -0
  260. package/dist/auth/passkeys/registration-options.d.ts.map +1 -0
  261. package/dist/auth/passkeys/remove-all.d.ts +26 -0
  262. package/dist/auth/passkeys/remove-all.d.ts.map +1 -0
  263. package/dist/auth/passkeys/sign-in-options.d.ts +12 -0
  264. package/dist/auth/passkeys/sign-in-options.d.ts.map +1 -0
  265. package/dist/auth/passkeys/sign-in.d.ts +21 -0
  266. package/dist/auth/passkeys/sign-in.d.ts.map +1 -0
  267. package/dist/auth/passkeys/verifier.d.ts +113 -0
  268. package/dist/auth/passkeys/verifier.d.ts.map +1 -0
  269. package/dist/auth/passkeys/view.d.ts +5 -0
  270. package/dist/auth/passkeys/view.d.ts.map +1 -0
  271. package/dist/auth/passkeys/wiring.d.ts +24 -0
  272. package/dist/auth/passkeys/wiring.d.ts.map +1 -0
  273. package/dist/auth/password-written.d.ts +55 -0
  274. package/dist/auth/password-written.d.ts.map +1 -0
  275. package/dist/auth/port/assert-api-keys.d.ts +21 -0
  276. package/dist/auth/port/assert-api-keys.d.ts.map +1 -0
  277. package/dist/auth/port/assert-invitations.d.ts +15 -0
  278. package/dist/auth/port/assert-invitations.d.ts.map +1 -0
  279. package/dist/auth/port/assert-stores.d.ts +16 -0
  280. package/dist/auth/port/assert-stores.d.ts.map +1 -0
  281. package/dist/auth/port/memory/api-keys/capabilities.d.ts +8 -0
  282. package/dist/auth/port/memory/api-keys/capabilities.d.ts.map +1 -0
  283. package/dist/auth/port/memory/api-keys/index.d.ts +13 -0
  284. package/dist/auth/port/memory/api-keys/index.d.ts.map +1 -0
  285. package/dist/auth/port/memory/api-keys/pages.d.ts +7 -0
  286. package/dist/auth/port/memory/api-keys/pages.d.ts.map +1 -0
  287. package/dist/auth/port/memory/copy.d.ts +6 -0
  288. package/dist/auth/port/memory/copy.d.ts.map +1 -0
  289. package/dist/auth/port/memory/index.d.ts +10 -0
  290. package/dist/auth/port/memory/index.d.ts.map +1 -0
  291. package/dist/auth/port/memory/invitations-pending.d.ts +6 -0
  292. package/dist/auth/port/memory/invitations-pending.d.ts.map +1 -0
  293. package/dist/auth/port/memory/invitations.d.ts +12 -0
  294. package/dist/auth/port/memory/invitations.d.ts.map +1 -0
  295. package/dist/auth/port/memory/passkeys.d.ts +9 -0
  296. package/dist/auth/port/memory/passkeys.d.ts.map +1 -0
  297. package/dist/auth/port/memory/sessions.d.ts +4 -0
  298. package/dist/auth/port/memory/sessions.d.ts.map +1 -0
  299. package/dist/auth/port/memory/social-links.d.ts +10 -0
  300. package/dist/auth/port/memory/social-links.d.ts.map +1 -0
  301. package/dist/auth/port/memory/stores.d.ts +26 -0
  302. package/dist/auth/port/memory/stores.d.ts.map +1 -0
  303. package/dist/auth/port/memory/tokens.d.ts +4 -0
  304. package/dist/auth/port/memory/tokens.d.ts.map +1 -0
  305. package/dist/auth/port/memory/user-index.d.ts +20 -0
  306. package/dist/auth/port/memory/user-index.d.ts.map +1 -0
  307. package/dist/auth/port/memory/user-update.d.ts +10 -0
  308. package/dist/auth/port/memory/user-update.d.ts.map +1 -0
  309. package/dist/auth/port/memory/users.d.ts +4 -0
  310. package/dist/auth/port/memory/users.d.ts.map +1 -0
  311. package/dist/auth/port/types/api-keys.d.ts +199 -0
  312. package/dist/auth/port/types/api-keys.d.ts.map +1 -0
  313. package/dist/auth/port/types/credentials.d.ts +46 -0
  314. package/dist/auth/port/types/credentials.d.ts.map +1 -0
  315. package/dist/auth/port/types/index.d.ts +75 -0
  316. package/dist/auth/port/types/index.d.ts.map +1 -0
  317. package/dist/auth/port/types/invitations/index.d.ts +15 -0
  318. package/dist/auth/port/types/invitations/index.d.ts.map +1 -0
  319. package/dist/auth/port/types/invitations/page.d.ts +52 -0
  320. package/dist/auth/port/types/invitations/page.d.ts.map +1 -0
  321. package/dist/auth/port/types/invitations/records.d.ts +101 -0
  322. package/dist/auth/port/types/invitations/records.d.ts.map +1 -0
  323. package/dist/auth/port/types/invitations/store.d.ts +82 -0
  324. package/dist/auth/port/types/invitations/store.d.ts.map +1 -0
  325. package/dist/auth/port/types/json.d.ts +27 -0
  326. package/dist/auth/port/types/json.d.ts.map +1 -0
  327. package/dist/auth/port/types/passkeys.d.ts +94 -0
  328. package/dist/auth/port/types/passkeys.d.ts.map +1 -0
  329. package/dist/auth/port/types/sessions.d.ts +142 -0
  330. package/dist/auth/port/types/sessions.d.ts.map +1 -0
  331. package/dist/auth/port/types/social-links.d.ts +64 -0
  332. package/dist/auth/port/types/social-links.d.ts.map +1 -0
  333. package/dist/auth/port/types/stores.d.ts +48 -0
  334. package/dist/auth/port/types/stores.d.ts.map +1 -0
  335. package/dist/auth/port/types/tokens.d.ts +168 -0
  336. package/dist/auth/port/types/tokens.d.ts.map +1 -0
  337. package/dist/auth/port/types/users.d.ts +260 -0
  338. package/dist/auth/port/types/users.d.ts.map +1 -0
  339. package/dist/auth/prepared.d.ts +21 -0
  340. package/dist/auth/prepared.d.ts.map +1 -0
  341. package/dist/auth/proven-sign-in.d.ts +22 -0
  342. package/dist/auth/proven-sign-in.d.ts.map +1 -0
  343. package/dist/auth/sealer-for.d.ts +44 -0
  344. package/dist/auth/sealer-for.d.ts.map +1 -0
  345. package/dist/auth/sealing.d.ts +36 -0
  346. package/dist/auth/sealing.d.ts.map +1 -0
  347. package/dist/auth/second-factor/activate.d.ts +9 -0
  348. package/dist/auth/second-factor/activate.d.ts.map +1 -0
  349. package/dist/auth/second-factor/app-code-attempts.d.ts +47 -0
  350. package/dist/auth/second-factor/app-code-attempts.d.ts.map +1 -0
  351. package/dist/auth/second-factor/challenge.d.ts +15 -0
  352. package/dist/auth/second-factor/challenge.d.ts.map +1 -0
  353. package/dist/auth/second-factor/codes-left.d.ts +14 -0
  354. package/dist/auth/second-factor/codes-left.d.ts.map +1 -0
  355. package/dist/auth/second-factor/disable.d.ts +10 -0
  356. package/dist/auth/second-factor/disable.d.ts.map +1 -0
  357. package/dist/auth/second-factor/enroll.d.ts +6 -0
  358. package/dist/auth/second-factor/enroll.d.ts.map +1 -0
  359. package/dist/auth/second-factor/factor.d.ts +33 -0
  360. package/dist/auth/second-factor/factor.d.ts.map +1 -0
  361. package/dist/auth/second-factor/flows.d.ts +36 -0
  362. package/dist/auth/second-factor/flows.d.ts.map +1 -0
  363. package/dist/auth/second-factor/lifecycle.d.ts +14 -0
  364. package/dist/auth/second-factor/lifecycle.d.ts.map +1 -0
  365. package/dist/auth/second-factor/passkey-confirm.d.ts +21 -0
  366. package/dist/auth/second-factor/passkey-confirm.d.ts.map +1 -0
  367. package/dist/auth/second-factor/recovery-codes.d.ts +36 -0
  368. package/dist/auth/second-factor/recovery-codes.d.ts.map +1 -0
  369. package/dist/auth/second-factor/recovery.d.ts +20 -0
  370. package/dist/auth/second-factor/recovery.d.ts.map +1 -0
  371. package/dist/auth/second-factor/redeem.d.ts +42 -0
  372. package/dist/auth/second-factor/redeem.d.ts.map +1 -0
  373. package/dist/auth/second-factor/refusal.d.ts +6 -0
  374. package/dist/auth/second-factor/refusal.d.ts.map +1 -0
  375. package/dist/auth/second-factor/regenerate.d.ts +12 -0
  376. package/dist/auth/second-factor/regenerate.d.ts.map +1 -0
  377. package/dist/auth/second-factor/reseal.d.ts +17 -0
  378. package/dist/auth/second-factor/reseal.d.ts.map +1 -0
  379. package/dist/auth/second-factor/spend-recovery-code.d.ts +15 -0
  380. package/dist/auth/second-factor/spend-recovery-code.d.ts.map +1 -0
  381. package/dist/auth/secrets.d.ts +17 -0
  382. package/dist/auth/secrets.d.ts.map +1 -0
  383. package/dist/auth/sessions/amr.d.ts +36 -0
  384. package/dist/auth/sessions/amr.d.ts.map +1 -0
  385. package/dist/auth/sessions/authenticate.d.ts +12 -0
  386. package/dist/auth/sessions/authenticate.d.ts.map +1 -0
  387. package/dist/auth/sessions/collect-expired.d.ts +15 -0
  388. package/dist/auth/sessions/collect-expired.d.ts.map +1 -0
  389. package/dist/auth/sessions/cookie.d.ts +9 -0
  390. package/dist/auth/sessions/cookie.d.ts.map +1 -0
  391. package/dist/auth/sessions/fresh.d.ts +35 -0
  392. package/dist/auth/sessions/fresh.d.ts.map +1 -0
  393. package/dist/auth/sessions/index.d.ts +12 -0
  394. package/dist/auth/sessions/index.d.ts.map +1 -0
  395. package/dist/auth/sessions/open-session.d.ts +22 -0
  396. package/dist/auth/sessions/open-session.d.ts.map +1 -0
  397. package/dist/auth/sessions/presented-token.d.ts +25 -0
  398. package/dist/auth/sessions/presented-token.d.ts.map +1 -0
  399. package/dist/auth/sessions/shared-api.d.ts +17 -0
  400. package/dist/auth/sessions/shared-api.d.ts.map +1 -0
  401. package/dist/auth/sessions/standing.d.ts +32 -0
  402. package/dist/auth/sessions/standing.d.ts.map +1 -0
  403. package/dist/auth/shared-api.d.ts +139 -0
  404. package/dist/auth/shared-api.d.ts.map +1 -0
  405. package/dist/auth/sign-in-attempts.d.ts +45 -0
  406. package/dist/auth/sign-in-attempts.d.ts.map +1 -0
  407. package/dist/auth/sign-in-code.d.ts +26 -0
  408. package/dist/auth/sign-in-code.d.ts.map +1 -0
  409. package/dist/auth/social/attach.d.ts +31 -0
  410. package/dist/auth/social/attach.d.ts.map +1 -0
  411. package/dist/auth/social/begin.d.ts +30 -0
  412. package/dist/auth/social/begin.d.ts.map +1 -0
  413. package/dist/auth/social/complete-link.d.ts +17 -0
  414. package/dist/auth/social/complete-link.d.ts.map +1 -0
  415. package/dist/auth/social/complete.d.ts +54 -0
  416. package/dist/auth/social/complete.d.ts.map +1 -0
  417. package/dist/auth/social/cookie.d.ts +16 -0
  418. package/dist/auth/social/cookie.d.ts.map +1 -0
  419. package/dist/auth/social/find-provider.d.ts +23 -0
  420. package/dist/auth/social/find-provider.d.ts.map +1 -0
  421. package/dist/auth/social/finish.d.ts +60 -0
  422. package/dist/auth/social/finish.d.ts.map +1 -0
  423. package/dist/auth/social/flow-cookie-value.d.ts +26 -0
  424. package/dist/auth/social/flow-cookie-value.d.ts.map +1 -0
  425. package/dist/auth/social/flow-secret.d.ts +40 -0
  426. package/dist/auth/social/flow-secret.d.ts.map +1 -0
  427. package/dist/auth/social/index.d.ts +19 -0
  428. package/dist/auth/social/index.d.ts.map +1 -0
  429. package/dist/auth/social/link-holder.d.ts +33 -0
  430. package/dist/auth/social/link-holder.d.ts.map +1 -0
  431. package/dist/auth/social/provider-call.d.ts +31 -0
  432. package/dist/auth/social/provider-call.d.ts.map +1 -0
  433. package/dist/auth/social/redeem.d.ts +45 -0
  434. package/dist/auth/social/redeem.d.ts.map +1 -0
  435. package/dist/auth/social/return-to.d.ts +18 -0
  436. package/dist/auth/social/return-to.d.ts.map +1 -0
  437. package/dist/auth/social/sign-in.d.ts +41 -0
  438. package/dist/auth/social/sign-in.d.ts.map +1 -0
  439. package/dist/auth/social/sign-up.d.ts +37 -0
  440. package/dist/auth/social/sign-up.d.ts.map +1 -0
  441. package/dist/auth/social/start.d.ts +21 -0
  442. package/dist/auth/social/start.d.ts.map +1 -0
  443. package/dist/auth/social/step-up-proof.d.ts +26 -0
  444. package/dist/auth/social/step-up-proof.d.ts.map +1 -0
  445. package/dist/auth/social/step-up-request.d.ts +28 -0
  446. package/dist/auth/social/step-up-request.d.ts.map +1 -0
  447. package/dist/auth/social/step-up.d.ts +19 -0
  448. package/dist/auth/social/step-up.d.ts.map +1 -0
  449. package/dist/auth/social/types-of.d.ts +12 -0
  450. package/dist/auth/social/types-of.d.ts.map +1 -0
  451. package/dist/auth/social/unlink.d.ts +16 -0
  452. package/dist/auth/social/unlink.d.ts.map +1 -0
  453. package/dist/auth/social/wiring.d.ts +10 -0
  454. package/dist/auth/social/wiring.d.ts.map +1 -0
  455. package/dist/auth/standard-schema.d.ts +41 -0
  456. package/dist/auth/standard-schema.d.ts.map +1 -0
  457. package/dist/auth/step-up/codes.d.ts +35 -0
  458. package/dist/auth/step-up/codes.d.ts.map +1 -0
  459. package/dist/auth/step-up/flows.d.ts +18 -0
  460. package/dist/auth/step-up/flows.d.ts.map +1 -0
  461. package/dist/auth/step-up/open.d.ts +23 -0
  462. package/dist/auth/step-up/open.d.ts.map +1 -0
  463. package/dist/auth/step-up/passkey.d.ts +31 -0
  464. package/dist/auth/step-up/passkey.d.ts.map +1 -0
  465. package/dist/auth/step-up/request.d.ts +15 -0
  466. package/dist/auth/step-up/request.d.ts.map +1 -0
  467. package/dist/auth/step-up/spend.d.ts +4 -0
  468. package/dist/auth/step-up/spend.d.ts.map +1 -0
  469. package/dist/auth/totp.d.ts +36 -0
  470. package/dist/auth/totp.d.ts.map +1 -0
  471. package/dist/auth/types/api-keys-of.d.ts +19 -0
  472. package/dist/auth/types/api-keys-of.d.ts.map +1 -0
  473. package/dist/auth/types/api-keys.d.ts +164 -0
  474. package/dist/auth/types/api-keys.d.ts.map +1 -0
  475. package/dist/auth/types/avatar.d.ts +72 -0
  476. package/dist/auth/types/avatar.d.ts.map +1 -0
  477. package/dist/auth/types/change-email.d.ts +82 -0
  478. package/dist/auth/types/change-email.d.ts.map +1 -0
  479. package/dist/auth/types/checks.d.ts +147 -0
  480. package/dist/auth/types/checks.d.ts.map +1 -0
  481. package/dist/auth/types/email-flows.d.ts +117 -0
  482. package/dist/auth/types/email-flows.d.ts.map +1 -0
  483. package/dist/auth/types/find-by-email.d.ts +31 -0
  484. package/dist/auth/types/find-by-email.d.ts.map +1 -0
  485. package/dist/auth/types/find-or-create.d.ts +59 -0
  486. package/dist/auth/types/find-or-create.d.ts.map +1 -0
  487. package/dist/auth/types/index.d.ts +38 -0
  488. package/dist/auth/types/index.d.ts.map +1 -0
  489. package/dist/auth/types/inference.d.ts +62 -0
  490. package/dist/auth/types/inference.d.ts.map +1 -0
  491. package/dist/auth/types/invitations/api.d.ts +203 -0
  492. package/dist/auth/types/invitations/api.d.ts.map +1 -0
  493. package/dist/auth/types/invitations/history.d.ts +87 -0
  494. package/dist/auth/types/invitations/history.d.ts.map +1 -0
  495. package/dist/auth/types/invitations/index.d.ts +10 -0
  496. package/dist/auth/types/invitations/index.d.ts.map +1 -0
  497. package/dist/auth/types/invitations/invitation.d.ts +76 -0
  498. package/dist/auth/types/invitations/invitation.d.ts.map +1 -0
  499. package/dist/auth/types/invitations/issue-type.d.ts +15 -0
  500. package/dist/auth/types/invitations/issue-type.d.ts.map +1 -0
  501. package/dist/auth/types/invitations-of.d.ts +26 -0
  502. package/dist/auth/types/invitations-of.d.ts.map +1 -0
  503. package/dist/auth/types/janus.d.ts +51 -0
  504. package/dist/auth/types/janus.d.ts.map +1 -0
  505. package/dist/auth/types/magic-link.d.ts +69 -0
  506. package/dist/auth/types/magic-link.d.ts.map +1 -0
  507. package/dist/auth/types/passkeys.d.ts +183 -0
  508. package/dist/auth/types/passkeys.d.ts.map +1 -0
  509. package/dist/auth/types/password.d.ts +113 -0
  510. package/dist/auth/types/password.d.ts.map +1 -0
  511. package/dist/auth/types/prepared.d.ts +68 -0
  512. package/dist/auth/types/prepared.d.ts.map +1 -0
  513. package/dist/auth/types/proven-sign-in.d.ts +43 -0
  514. package/dist/auth/types/proven-sign-in.d.ts.map +1 -0
  515. package/dist/auth/types/reset-password.d.ts +46 -0
  516. package/dist/auth/types/reset-password.d.ts.map +1 -0
  517. package/dist/auth/types/second-factor.d.ts +164 -0
  518. package/dist/auth/types/second-factor.d.ts.map +1 -0
  519. package/dist/auth/types/session.d.ts +68 -0
  520. package/dist/auth/types/session.d.ts.map +1 -0
  521. package/dist/auth/types/shared-api.d.ts +96 -0
  522. package/dist/auth/types/shared-api.d.ts.map +1 -0
  523. package/dist/auth/types/sign-in.d.ts +102 -0
  524. package/dist/auth/types/sign-in.d.ts.map +1 -0
  525. package/dist/auth/types/social-flow.d.ts +28 -0
  526. package/dist/auth/types/social-flow.d.ts.map +1 -0
  527. package/dist/auth/types/social-step-up.d.ts +38 -0
  528. package/dist/auth/types/social-step-up.d.ts.map +1 -0
  529. package/dist/auth/types/social.d.ts +193 -0
  530. package/dist/auth/types/social.d.ts.map +1 -0
  531. package/dist/auth/types/step-up.d.ts +133 -0
  532. package/dist/auth/types/step-up.d.ts.map +1 -0
  533. package/dist/auth/types/type-api.d.ts +29 -0
  534. package/dist/auth/types/type-api.d.ts.map +1 -0
  535. package/dist/auth/types/user-type.d.ts +106 -0
  536. package/dist/auth/types/user-type.d.ts.map +1 -0
  537. package/dist/auth/types/user.d.ts +62 -0
  538. package/dist/auth/types/user.d.ts.map +1 -0
  539. package/dist/auth/types/verify-email.d.ts +190 -0
  540. package/dist/auth/types/verify-email.d.ts.map +1 -0
  541. package/dist/auth/users/any-type-api.d.ts +6 -0
  542. package/dist/auth/users/any-type-api.d.ts.map +1 -0
  543. package/dist/auth/users/by-login.d.ts +10 -0
  544. package/dist/auth/users/by-login.d.ts.map +1 -0
  545. package/dist/auth/users/change-password.d.ts +26 -0
  546. package/dist/auth/users/change-password.d.ts.map +1 -0
  547. package/dist/auth/users/delete.d.ts +10 -0
  548. package/dist/auth/users/delete.d.ts.map +1 -0
  549. package/dist/auth/users/email-move-guard.d.ts +20 -0
  550. package/dist/auth/users/email-move-guard.d.ts.map +1 -0
  551. package/dist/auth/users/email-prefix.d.ts +23 -0
  552. package/dist/auth/users/email-prefix.d.ts.map +1 -0
  553. package/dist/auth/users/fields-patch.d.ts +21 -0
  554. package/dist/auth/users/fields-patch.d.ts.map +1 -0
  555. package/dist/auth/users/find-by-email.d.ts +11 -0
  556. package/dist/auth/users/find-by-email.d.ts.map +1 -0
  557. package/dist/auth/users/find-many.d.ts +29 -0
  558. package/dist/auth/users/find-many.d.ts.map +1 -0
  559. package/dist/auth/users/find-or-create.d.ts +12 -0
  560. package/dist/auth/users/find-or-create.d.ts.map +1 -0
  561. package/dist/auth/users/flow-types.d.ts +15 -0
  562. package/dist/auth/users/flow-types.d.ts.map +1 -0
  563. package/dist/auth/users/index.d.ts +9 -0
  564. package/dist/auth/users/index.d.ts.map +1 -0
  565. package/dist/auth/users/insert.d.ts +15 -0
  566. package/dist/auth/users/insert.d.ts.map +1 -0
  567. package/dist/auth/users/name-prefix.d.ts +19 -0
  568. package/dist/auth/users/name-prefix.d.ts.map +1 -0
  569. package/dist/auth/users/password-flows.d.ts +11 -0
  570. package/dist/auth/users/password-flows.d.ts.map +1 -0
  571. package/dist/auth/users/record-flows.d.ts +11 -0
  572. package/dist/auth/users/record-flows.d.ts.map +1 -0
  573. package/dist/auth/users/sign-in.d.ts +24 -0
  574. package/dist/auth/users/sign-in.d.ts.map +1 -0
  575. package/dist/auth/users/sign-up.d.ts +13 -0
  576. package/dist/auth/users/sign-up.d.ts.map +1 -0
  577. package/dist/auth/users/type-api.d.ts +10 -0
  578. package/dist/auth/users/type-api.d.ts.map +1 -0
  579. package/dist/auth/users/update.d.ts +16 -0
  580. package/dist/auth/users/update.d.ts.map +1 -0
  581. package/dist/background/background.d.ts +22 -0
  582. package/dist/background/background.d.ts.map +1 -0
  583. package/dist/chunks/index-2ttdcz7n.js +354 -0
  584. package/dist/chunks/index-2ttdcz7n.js.map +16 -0
  585. package/dist/chunks/index-5dxynm32.js +85 -0
  586. package/dist/chunks/index-5dxynm32.js.map +10 -0
  587. package/dist/chunks/index-ftz0ne6j.js +127 -0
  588. package/dist/chunks/index-ftz0ne6j.js.map +11 -0
  589. package/dist/chunks/index-k6y18nx9.js +724 -0
  590. package/dist/chunks/index-k6y18nx9.js.map +24 -0
  591. package/dist/chunks/index-n8jxmxeg.js +64 -0
  592. package/dist/chunks/index-n8jxmxeg.js.map +11 -0
  593. package/dist/conformance/api-keys/cases/bound.d.ts +3 -0
  594. package/dist/conformance/api-keys/cases/bound.d.ts.map +1 -0
  595. package/dist/conformance/api-keys/cases/expiry.d.ts +3 -0
  596. package/dist/conformance/api-keys/cases/expiry.d.ts.map +1 -0
  597. package/dist/conformance/api-keys/cases/index.d.ts +4 -0
  598. package/dist/conformance/api-keys/cases/index.d.ts.map +1 -0
  599. package/dist/conformance/api-keys/cases/insert.d.ts +3 -0
  600. package/dist/conformance/api-keys/cases/insert.d.ts.map +1 -0
  601. package/dist/conformance/api-keys/cases/outage.d.ts +3 -0
  602. package/dist/conformance/api-keys/cases/outage.d.ts.map +1 -0
  603. package/dist/conformance/api-keys/cases/revoke.d.ts +3 -0
  604. package/dist/conformance/api-keys/cases/revoke.d.ts.map +1 -0
  605. package/dist/conformance/api-keys/cases/touch.d.ts +3 -0
  606. package/dist/conformance/api-keys/cases/touch.d.ts.map +1 -0
  607. package/dist/conformance/api-keys/cases/user-bound.d.ts +3 -0
  608. package/dist/conformance/api-keys/cases/user-bound.d.ts.map +1 -0
  609. package/dist/conformance/api-keys/describe.d.ts +20 -0
  610. package/dist/conformance/api-keys/describe.d.ts.map +1 -0
  611. package/dist/conformance/api-keys/fixtures.d.ts +4 -0
  612. package/dist/conformance/api-keys/fixtures.d.ts.map +1 -0
  613. package/dist/conformance/api-keys/index.d.ts +18 -0
  614. package/dist/conformance/api-keys/index.d.ts.map +1 -0
  615. package/dist/conformance/api-keys/reference.d.ts +4 -0
  616. package/dist/conformance/api-keys/reference.d.ts.map +1 -0
  617. package/dist/conformance/api-keys/types.d.ts +42 -0
  618. package/dist/conformance/api-keys/types.d.ts.map +1 -0
  619. package/dist/conformance/assert.d.ts +40 -0
  620. package/dist/conformance/assert.d.ts.map +1 -0
  621. package/dist/conformance/cases/outage.d.ts +3 -0
  622. package/dist/conformance/cases/outage.d.ts.map +1 -0
  623. package/dist/conformance/cases/outage.passkeys.d.ts +12 -0
  624. package/dist/conformance/cases/outage.passkeys.d.ts.map +1 -0
  625. package/dist/conformance/cases/passkeys/deletion.d.ts +4 -0
  626. package/dist/conformance/cases/passkeys/deletion.d.ts.map +1 -0
  627. package/dist/conformance/cases/passkeys/index.d.ts +8 -0
  628. package/dist/conformance/cases/passkeys/index.d.ts.map +1 -0
  629. package/dist/conformance/cases/passkeys/inserts.d.ts +4 -0
  630. package/dist/conformance/cases/passkeys/inserts.d.ts.map +1 -0
  631. package/dist/conformance/cases/passkeys/reads.d.ts +4 -0
  632. package/dist/conformance/cases/passkeys/reads.d.ts.map +1 -0
  633. package/dist/conformance/cases/passkeys/uses.d.ts +4 -0
  634. package/dist/conformance/cases/passkeys/uses.d.ts.map +1 -0
  635. package/dist/conformance/cases/sessions/deletion.d.ts +4 -0
  636. package/dist/conformance/cases/sessions/deletion.d.ts.map +1 -0
  637. package/dist/conformance/cases/sessions/extension.d.ts +4 -0
  638. package/dist/conformance/cases/sessions/extension.d.ts.map +1 -0
  639. package/dist/conformance/cases/sessions/index.d.ts +4 -0
  640. package/dist/conformance/cases/sessions/index.d.ts.map +1 -0
  641. package/dist/conformance/cases/sessions/inserts.d.ts +4 -0
  642. package/dist/conformance/cases/sessions/inserts.d.ts.map +1 -0
  643. package/dist/conformance/cases/sessions/list.d.ts +4 -0
  644. package/dist/conformance/cases/sessions/list.d.ts.map +1 -0
  645. package/dist/conformance/cases/sessions/reads.d.ts +4 -0
  646. package/dist/conformance/cases/sessions/reads.d.ts.map +1 -0
  647. package/dist/conformance/cases/sessions/reauthentication.d.ts +4 -0
  648. package/dist/conformance/cases/sessions/reauthentication.d.ts.map +1 -0
  649. package/dist/conformance/cases/sessions/revocation.d.ts +4 -0
  650. package/dist/conformance/cases/sessions/revocation.d.ts.map +1 -0
  651. package/dist/conformance/cases/social-links/deletion.d.ts +4 -0
  652. package/dist/conformance/cases/social-links/deletion.d.ts.map +1 -0
  653. package/dist/conformance/cases/social-links/index.d.ts +8 -0
  654. package/dist/conformance/cases/social-links/index.d.ts.map +1 -0
  655. package/dist/conformance/cases/social-links/inserts.d.ts +4 -0
  656. package/dist/conformance/cases/social-links/inserts.d.ts.map +1 -0
  657. package/dist/conformance/cases/social-links/reads.d.ts +4 -0
  658. package/dist/conformance/cases/social-links/reads.d.ts.map +1 -0
  659. package/dist/conformance/cases/tokens/attempts.d.ts +7 -0
  660. package/dist/conformance/cases/tokens/attempts.d.ts.map +1 -0
  661. package/dist/conformance/cases/tokens/change-email.d.ts +8 -0
  662. package/dist/conformance/cases/tokens/change-email.d.ts.map +1 -0
  663. package/dist/conformance/cases/tokens/deletion.d.ts +4 -0
  664. package/dist/conformance/cases/tokens/deletion.d.ts.map +1 -0
  665. package/dist/conformance/cases/tokens/index.d.ts +4 -0
  666. package/dist/conformance/cases/tokens/index.d.ts.map +1 -0
  667. package/dist/conformance/cases/tokens/inserts.d.ts +7 -0
  668. package/dist/conformance/cases/tokens/inserts.d.ts.map +1 -0
  669. package/dist/conformance/cases/tokens/kinds.d.ts +7 -0
  670. package/dist/conformance/cases/tokens/kinds.d.ts.map +1 -0
  671. package/dist/conformance/cases/tokens/redemption.d.ts +7 -0
  672. package/dist/conformance/cases/tokens/redemption.d.ts.map +1 -0
  673. package/dist/conformance/cases/tokens/social-flow.d.ts +8 -0
  674. package/dist/conformance/cases/tokens/social-flow.d.ts.map +1 -0
  675. package/dist/conformance/cases/tokens/spending.d.ts +7 -0
  676. package/dist/conformance/cases/tokens/spending.d.ts.map +1 -0
  677. package/dist/conformance/cases/users/avatar.d.ts +8 -0
  678. package/dist/conformance/cases/users/avatar.d.ts.map +1 -0
  679. package/dist/conformance/cases/users/batch.d.ts +8 -0
  680. package/dist/conformance/cases/users/batch.d.ts.map +1 -0
  681. package/dist/conformance/cases/users/deletion.d.ts +4 -0
  682. package/dist/conformance/cases/users/deletion.d.ts.map +1 -0
  683. package/dist/conformance/cases/users/index.d.ts +4 -0
  684. package/dist/conformance/cases/users/index.d.ts.map +1 -0
  685. package/dist/conformance/cases/users/inserts.d.ts +4 -0
  686. package/dist/conformance/cases/users/inserts.d.ts.map +1 -0
  687. package/dist/conformance/cases/users/listing.d.ts +4 -0
  688. package/dist/conformance/cases/users/listing.d.ts.map +1 -0
  689. package/dist/conformance/cases/users/patches.d.ts +7 -0
  690. package/dist/conformance/cases/users/patches.d.ts.map +1 -0
  691. package/dist/conformance/cases/users/reads.d.ts +7 -0
  692. package/dist/conformance/cases/users/reads.d.ts.map +1 -0
  693. package/dist/conformance/cases/users/second-factor.d.ts +16 -0
  694. package/dist/conformance/cases/users/second-factor.d.ts.map +1 -0
  695. package/dist/conformance/cases/users/versions.d.ts +7 -0
  696. package/dist/conformance/cases/users/versions.d.ts.map +1 -0
  697. package/dist/conformance/describe.d.ts +82 -0
  698. package/dist/conformance/describe.d.ts.map +1 -0
  699. package/dist/conformance/fixtures.d.ts +31 -0
  700. package/dist/conformance/fixtures.d.ts.map +1 -0
  701. package/dist/conformance/index.d.ts +46 -0
  702. package/dist/conformance/index.d.ts.map +1 -0
  703. package/dist/conformance/index.js +4411 -0
  704. package/dist/conformance/index.js.map +86 -0
  705. package/dist/conformance/invitations/cases/actors.d.ts +3 -0
  706. package/dist/conformance/invitations/cases/actors.d.ts.map +1 -0
  707. package/dist/conformance/invitations/cases/find-pending.d.ts +3 -0
  708. package/dist/conformance/invitations/cases/find-pending.d.ts.map +1 -0
  709. package/dist/conformance/invitations/cases/imported.d.ts +3 -0
  710. package/dist/conformance/invitations/cases/imported.d.ts.map +1 -0
  711. package/dist/conformance/invitations/cases/index.d.ts +4 -0
  712. package/dist/conformance/invitations/cases/index.d.ts.map +1 -0
  713. package/dist/conformance/invitations/cases/insert.d.ts +3 -0
  714. package/dist/conformance/invitations/cases/insert.d.ts.map +1 -0
  715. package/dist/conformance/invitations/cases/list-lapsed.d.ts +3 -0
  716. package/dist/conformance/invitations/cases/list-lapsed.d.ts.map +1 -0
  717. package/dist/conformance/invitations/cases/list-status.d.ts +3 -0
  718. package/dist/conformance/invitations/cases/list-status.d.ts.map +1 -0
  719. package/dist/conformance/invitations/cases/list.d.ts +3 -0
  720. package/dist/conformance/invitations/cases/list.d.ts.map +1 -0
  721. package/dist/conformance/invitations/cases/outage.d.ts +3 -0
  722. package/dist/conformance/invitations/cases/outage.d.ts.map +1 -0
  723. package/dist/conformance/invitations/cases/scope.d.ts +3 -0
  724. package/dist/conformance/invitations/cases/scope.d.ts.map +1 -0
  725. package/dist/conformance/invitations/cases/update.d.ts +3 -0
  726. package/dist/conformance/invitations/cases/update.d.ts.map +1 -0
  727. package/dist/conformance/invitations/describe.d.ts +20 -0
  728. package/dist/conformance/invitations/describe.d.ts.map +1 -0
  729. package/dist/conformance/invitations/fixtures.d.ts +4 -0
  730. package/dist/conformance/invitations/fixtures.d.ts.map +1 -0
  731. package/dist/conformance/invitations/index.d.ts +18 -0
  732. package/dist/conformance/invitations/index.d.ts.map +1 -0
  733. package/dist/conformance/invitations/reference.d.ts +4 -0
  734. package/dist/conformance/invitations/reference.d.ts.map +1 -0
  735. package/dist/conformance/invitations/types.d.ts +34 -0
  736. package/dist/conformance/invitations/types.d.ts.map +1 -0
  737. package/dist/conformance/reference.d.ts +13 -0
  738. package/dist/conformance/reference.d.ts.map +1 -0
  739. package/dist/conformance/relations/cases/deletion.d.ts +4 -0
  740. package/dist/conformance/relations/cases/deletion.d.ts.map +1 -0
  741. package/dist/conformance/relations/cases/holders.d.ts +9 -0
  742. package/dist/conformance/relations/cases/holders.d.ts.map +1 -0
  743. package/dist/conformance/relations/cases/index.d.ts +4 -0
  744. package/dist/conformance/relations/cases/index.d.ts.map +1 -0
  745. package/dist/conformance/relations/cases/outage.d.ts +3 -0
  746. package/dist/conformance/relations/cases/outage.d.ts.map +1 -0
  747. package/dist/conformance/relations/cases/reads.d.ts +8 -0
  748. package/dist/conformance/relations/cases/reads.d.ts.map +1 -0
  749. package/dist/conformance/relations/cases/traversal.d.ts +7 -0
  750. package/dist/conformance/relations/cases/traversal.d.ts.map +1 -0
  751. package/dist/conformance/relations/cases/writes.d.ts +4 -0
  752. package/dist/conformance/relations/cases/writes.d.ts.map +1 -0
  753. package/dist/conformance/relations/describe.d.ts +20 -0
  754. package/dist/conformance/relations/describe.d.ts.map +1 -0
  755. package/dist/conformance/relations/fixtures.d.ts +8 -0
  756. package/dist/conformance/relations/fixtures.d.ts.map +1 -0
  757. package/dist/conformance/relations/index.d.ts +18 -0
  758. package/dist/conformance/relations/index.d.ts.map +1 -0
  759. package/dist/conformance/relations/reference.d.ts +4 -0
  760. package/dist/conformance/relations/reference.d.ts.map +1 -0
  761. package/dist/conformance/relations/types.d.ts +34 -0
  762. package/dist/conformance/relations/types.d.ts.map +1 -0
  763. package/dist/conformance/types.d.ts +79 -0
  764. package/dist/conformance/types.d.ts.map +1 -0
  765. package/dist/errors/janus-error/base.d.ts +47 -0
  766. package/dist/errors/janus-error/base.d.ts.map +1 -0
  767. package/dist/errors/janus-error/codes.credentials.d.ts +36 -0
  768. package/dist/errors/janus-error/codes.credentials.d.ts.map +1 -0
  769. package/dist/errors/janus-error/codes.d.ts +23 -0
  770. package/dist/errors/janus-error/codes.d.ts.map +1 -0
  771. package/dist/errors/janus-error/codes.invitations.d.ts +52 -0
  772. package/dist/errors/janus-error/codes.invitations.d.ts.map +1 -0
  773. package/dist/errors/janus-error/codes.one-time.d.ts +63 -0
  774. package/dist/errors/janus-error/codes.one-time.d.ts.map +1 -0
  775. package/dist/errors/janus-error/codes.records.d.ts +86 -0
  776. package/dist/errors/janus-error/codes.records.d.ts.map +1 -0
  777. package/dist/errors/janus-error/codes.social.d.ts +88 -0
  778. package/dist/errors/janus-error/codes.social.d.ts.map +1 -0
  779. package/dist/errors/janus-error/index.d.ts +17 -0
  780. package/dist/errors/janus-error/index.d.ts.map +1 -0
  781. package/dist/errors/janus-error/options.d.ts +105 -0
  782. package/dist/errors/janus-error/options.d.ts.map +1 -0
  783. package/dist/errors/janus-error/refusals.d.ts +151 -0
  784. package/dist/errors/janus-error/refusals.d.ts.map +1 -0
  785. package/dist/errors/janus-error/status.d.ts +21 -0
  786. package/dist/errors/janus-error/status.d.ts.map +1 -0
  787. package/dist/errors/janus-error/store.d.ts +36 -0
  788. package/dist/errors/janus-error/store.d.ts.map +1 -0
  789. package/dist/ids/derived.d.ts +25 -0
  790. package/dist/ids/derived.d.ts.map +1 -0
  791. package/dist/ids/id.d.ts +55 -0
  792. package/dist/ids/id.d.ts.map +1 -0
  793. package/dist/index.d.ts +32 -0
  794. package/dist/index.d.ts.map +1 -0
  795. package/dist/index.js +6933 -0
  796. package/dist/index.js.map +208 -0
  797. package/dist/pagination/cursor-page.d.ts +53 -0
  798. package/dist/pagination/cursor-page.d.ts.map +1 -0
  799. package/dist/permissions/bound-model.d.ts +10 -0
  800. package/dist/permissions/bound-model.d.ts.map +1 -0
  801. package/dist/permissions/can.d.ts +13 -0
  802. package/dist/permissions/can.d.ts.map +1 -0
  803. package/dist/permissions/engine.d.ts +49 -0
  804. package/dist/permissions/engine.d.ts.map +1 -0
  805. package/dist/permissions/holders.d.ts +12 -0
  806. package/dist/permissions/holders.d.ts.map +1 -0
  807. package/dist/permissions/index.d.ts +36 -0
  808. package/dist/permissions/index.d.ts.map +1 -0
  809. package/dist/permissions/index.js +924 -0
  810. package/dist/permissions/index.js.map +28 -0
  811. package/dist/permissions/input.d.ts +43 -0
  812. package/dist/permissions/input.d.ts.map +1 -0
  813. package/dist/permissions/list.d.ts +16 -0
  814. package/dist/permissions/list.d.ts.map +1 -0
  815. package/dist/permissions/model/can.d.ts +41 -0
  816. package/dist/permissions/model/can.d.ts.map +1 -0
  817. package/dist/permissions/model/config.d.ts +36 -0
  818. package/dist/permissions/model/config.d.ts.map +1 -0
  819. package/dist/permissions/model/constraint.d.ts +37 -0
  820. package/dist/permissions/model/constraint.d.ts.map +1 -0
  821. package/dist/permissions/model/ctx.d.ts +23 -0
  822. package/dist/permissions/model/ctx.d.ts.map +1 -0
  823. package/dist/permissions/model/define.d.ts +78 -0
  824. package/dist/permissions/model/define.d.ts.map +1 -0
  825. package/dist/permissions/model/from-field.d.ts +31 -0
  826. package/dist/permissions/model/from-field.d.ts.map +1 -0
  827. package/dist/permissions/model/grant.d.ts +81 -0
  828. package/dist/permissions/model/grant.d.ts.map +1 -0
  829. package/dist/permissions/model/list.d.ts +48 -0
  830. package/dist/permissions/model/list.d.ts.map +1 -0
  831. package/dist/permissions/model/names.d.ts +51 -0
  832. package/dist/permissions/model/names.d.ts.map +1 -0
  833. package/dist/permissions/model/permissions.d.ts +48 -0
  834. package/dist/permissions/model/permissions.d.ts.map +1 -0
  835. package/dist/permissions/model/refs.d.ts +36 -0
  836. package/dist/permissions/model/refs.d.ts.map +1 -0
  837. package/dist/permissions/model/refusal.d.ts +13 -0
  838. package/dist/permissions/model/refusal.d.ts.map +1 -0
  839. package/dist/permissions/model/unions.d.ts +3 -0
  840. package/dist/permissions/model/unions.d.ts.map +1 -0
  841. package/dist/permissions/model/when.d.ts +16 -0
  842. package/dist/permissions/model/when.d.ts.map +1 -0
  843. package/dist/permissions/port/holders.d.ts +38 -0
  844. package/dist/permissions/port/holders.d.ts.map +1 -0
  845. package/dist/permissions/port/memory.d.ts +17 -0
  846. package/dist/permissions/port/memory.d.ts.map +1 -0
  847. package/dist/permissions/port/types.d.ts +101 -0
  848. package/dist/permissions/port/types.d.ts.map +1 -0
  849. package/dist/permissions/replace.d.ts +25 -0
  850. package/dist/permissions/replace.d.ts.map +1 -0
  851. package/dist/permissions/resolve/declared-names.d.ts +24 -0
  852. package/dist/permissions/resolve/declared-names.d.ts.map +1 -0
  853. package/dist/permissions/resolve/refuse-data-beyond-root.d.ts +11 -0
  854. package/dist/permissions/resolve/refuse-data-beyond-root.d.ts.map +1 -0
  855. package/dist/permissions/resolve/refuse-loops.d.ts +10 -0
  856. package/dist/permissions/resolve/refuse-loops.d.ts.map +1 -0
  857. package/dist/permissions/resolve/resolve-model.d.ts +13 -0
  858. package/dist/permissions/resolve/resolve-model.d.ts.map +1 -0
  859. package/dist/permissions/resolve/resolve-relation.d.ts +9 -0
  860. package/dist/permissions/resolve/resolve-relation.d.ts.map +1 -0
  861. package/dist/permissions/resolve/resolve-rule.d.ts +12 -0
  862. package/dist/permissions/resolve/resolve-rule.d.ts.map +1 -0
  863. package/dist/permissions/resolve/resolved.d.ts +52 -0
  864. package/dist/permissions/resolve/resolved.d.ts.map +1 -0
  865. package/dist/permissions/resolve/step.d.ts +4 -0
  866. package/dist/permissions/resolve/step.d.ts.map +1 -0
  867. package/dist/permissions/reverse.d.ts +53 -0
  868. package/dist/permissions/reverse.d.ts.map +1 -0
  869. package/dist/permissions/walk.d.ts +29 -0
  870. package/dist/permissions/walk.d.ts.map +1 -0
  871. package/dist/stores/guard.d.ts +24 -0
  872. package/dist/stores/guard.d.ts.map +1 -0
  873. package/dist/stores/storable.d.ts +15 -0
  874. package/dist/stores/storable.d.ts.map +1 -0
  875. package/dist/subjects/notation.d.ts +39 -0
  876. package/dist/subjects/notation.d.ts.map +1 -0
  877. package/dist/subjects/subject.d.ts +128 -0
  878. package/dist/subjects/subject.d.ts.map +1 -0
  879. package/dist/testing/index.d.ts +12 -0
  880. package/dist/testing/index.d.ts.map +1 -0
  881. package/dist/testing/index.js +26 -0
  882. package/dist/testing/index.js.map +10 -0
  883. package/dist/time/clock.d.ts +31 -0
  884. package/dist/time/clock.d.ts.map +1 -0
  885. package/dist/time/duration.d.ts +23 -0
  886. package/dist/time/duration.d.ts.map +1 -0
  887. package/docs/README.md +46 -0
  888. package/docs/guide/adapters.md +858 -0
  889. package/docs/guide/api-keys.md +316 -0
  890. package/docs/guide/avatars.md +334 -0
  891. package/docs/guide/devices.md +441 -0
  892. package/docs/guide/email-flows.md +880 -0
  893. package/docs/guide/errors.md +180 -0
  894. package/docs/guide/events.md +467 -0
  895. package/docs/guide/invitations.md +465 -0
  896. package/docs/guide/issuers.md +107 -0
  897. package/docs/guide/magic-link.md +580 -0
  898. package/docs/guide/migrating-invitations.md +142 -0
  899. package/docs/guide/passkeys.md +425 -0
  900. package/docs/guide/passwords.md +325 -0
  901. package/docs/guide/permissions.md +719 -0
  902. package/docs/guide/second-factor.md +1124 -0
  903. package/docs/guide/sessions.md +521 -0
  904. package/docs/guide/sign-in-code.md +631 -0
  905. package/docs/guide/social.md +639 -0
  906. package/docs/guide/step-up.md +262 -0
  907. package/docs/guide/users.md +557 -0
  908. package/docs/guide/vocabulary.md +316 -0
  909. package/docs/roadmap.md +101 -0
  910. package/docs/troubleshooting.md +3305 -0
  911. package/package.json +77 -5
@@ -0,0 +1,880 @@
1
+ # E-mail verification, password reset and changing an e-mail
2
+
3
+ This page is for the one-time-token flows: proving a user holds their
4
+ e-mail, resetting a forgotten password, and moving a user to a new e-mail.
5
+ `janus` issues and redeems the tokens; **sending the e-mail is yours**.
6
+
7
+ ```ts
8
+ import { z } from 'zod';
9
+ import { createMemoryStores, janus, scryptHasher } from '@softistx/janus';
10
+
11
+ async function sendMail(to: string, link: string): Promise<void> {
12
+ // your mailer
13
+ }
14
+
15
+ const auth = janus({
16
+ user: z.object({ email: z.email(), name: z.string() }),
17
+ password: { login: 'email' },
18
+ store: createMemoryStores(),
19
+ hasher: scryptHasher(),
20
+ });
21
+
22
+ const { user } = await auth.signUp({ email: 'ada@example.com', name: 'Ada', password: 'correct horse' });
23
+
24
+ const sent = await auth.verifyEmail.send(user); // { token, email, expiresAt }
25
+ await sendMail(sent.email, `https://app.example/verify?token=${sent.token}`);
26
+
27
+ // when the link is followed: the token comes back from the query string
28
+ const verified = await auth.verifyEmail.confirm(sent.token);
29
+ verified.emailVerified; // true
30
+ ```
31
+
32
+ ## Ready-made e-mails — `@softistx/janus-mail`
33
+
34
+ `sendMail` above is yours to write, or
35
+ [`@softistx/janus-mail`](https://github.com/softistx/nxgt-janus/tree/develop/packages/janus-mail)
36
+ writes it: it takes what `send` and `request` answer, as they answer it, and
37
+ sends the verification, reset, sign-in code and sign-in link e-mails — with the notices
38
+ of a password, an e-mail or a second factor changed, and a welcome on
39
+ `user.created` — in English and French, over any `@softistx/mail` transport.
40
+ Every link is required but three: `getStarted`, since janus-mail 0.4.0, is
41
+ where the welcome's **Get started** button leads; `recoveryCodes`,
42
+ `magicLink` — the page a [sign-in link](magic-link.md) opens, since
43
+ janus-mail 0.7.0 — and `changeEmail`, the page that confirms a new address,
44
+ since janus-mail 0.10.0, are optional. **`changeEmail.send`'s link has its
45
+ own e-mail**: `mail.changeEmail(issued, { name })` sends it to
46
+ `issued.email`, the new address, and janus-mail sends the notice to the
47
+ former address (`emailChanged`) once the link is redeemed. It needs
48
+ `@softistx/janus-mail` 0.10.0 or later; `mail.verifyEmail(issued)` is not the
49
+ change-of-e-mail mail: it would ask the new address to verify, not say the
50
+ account moves there.
51
+
52
+ ```ts
53
+ import { janusMail } from '@softistx/janus-mail';
54
+
55
+ const mail = janusMail({
56
+ mailer, // an @softistx/mail transport
57
+ from: 'noreply@app.example',
58
+ brand: 'App',
59
+ links: {
60
+ verifyEmail: (token) => `https://app.example/verify?token=${token}`,
61
+ resetPassword: (token) => `https://app.example/reset?token=${token}`,
62
+ secureAccount: () => 'https://app.example/account/security',
63
+ getStarted: () => 'https://app.example/',
64
+ changeEmail: (token) => `https://app.example/email/confirm?token=${token}`, // optional
65
+ },
66
+ });
67
+
68
+ await mail.verifyEmail(await auth.verifyEmail.send(user), { name: user.name });
69
+
70
+ // to the NEW address; the account moves when changeEmail.confirm(token) redeems the link
71
+ await mail.changeEmail(await auth.changeEmail.send(user, newEmail), { name: user.name });
72
+
73
+ const issued = await auth.resetPassword.request(email);
74
+ if (issued !== null) await mail.resetPassword(issued, { name: issued.user.name });
75
+ ```
76
+
77
+ Each e-mail goes to `issued.email`. A send that fails rejects with the
78
+ mailer's `MailFailure` — never report it as sent — and one refused, a link
79
+ that is not `http(s)` or `mailto:` or an address that is not one, with
80
+ `MailRefused`. A `mailto:` link is accepted on purpose —
81
+ `secureAccount: () => 'mailto:security@app.example'` points a user who made
82
+ no change at your support desk. Each link must answer a string at once: an
83
+ `async` function is a `TypeError` naming the call.
84
+
85
+ ## Which types have these flows
86
+
87
+ `verifyEmail` exists on a type with an e-mail field: the one `email` names, or
88
+ a required string field called `email`. `resetPassword` needs an e-mail **and**
89
+ a password. On a type without them the flows are **absent from its type**, not
90
+ failing at run time:
91
+
92
+ ```ts
93
+ const clinic = janus({
94
+ users: {
95
+ staff: { schema: z.object({ username: z.string() }), password: { login: 'username' } },
96
+ patient: { schema: z.object({ contact: z.email() }), password: { login: 'contact' }, email: 'contact' },
97
+ },
98
+ store: createMemoryStores(),
99
+ hasher: scryptHasher(),
100
+ });
101
+
102
+ clinic.patient.verifyEmail.send; // exists: `email` names the field
103
+ // @ts-expect-error — staff has no e-mail, so no verifyEmail
104
+ clinic.staff.verifyEmail;
105
+ ```
106
+
107
+ A type with an e-mail can also sign in with a code or a link sent to it,
108
+ with or without a password — see [sign-in codes](sign-in-code.md) and
109
+ [sign-in links](magic-link.md).
110
+
111
+ ## Options
112
+
113
+ | Option | Type | Default | Effect |
114
+ | --- | --- | --- | --- |
115
+ | `email` | a field name | `'email'` | The field the tokens are sent to, per type |
116
+ | `tokens.verifyEmail` | `Duration` | `'24h'` | How long a verification token lives |
117
+ | `tokens.resetPassword` | `Duration` | `'1h'` | How long a reset token lives |
118
+ | `tokens.changeEmail` | `Duration` | `'1h'` | How long the link sent to a new address lives |
119
+
120
+ ## `verifyEmail`
121
+
122
+ ```ts
123
+ readonly verifyEmail: {
124
+ send(user: UserRef): Promise<IssuedToken>; // { token, email, expiresAt }
125
+ confirm(token: string, options?: { firstProof?: boolean }): Promise<User>;
126
+ proveFirst(user: UserRef): Promise<FirstProof<User>>; // { user, proved } — privileged, below
127
+ };
128
+
129
+ setEmailVerified(user: UserRef, verified: boolean, options?: WriteOptions): Promise<User>; // an admin's flag, below
130
+ ```
131
+
132
+ `send` issues a token for the user's **current** e-mail. It is throttled
133
+ **per user**, five per 10-minute window: past it, `MailThrottledError`
134
+ (`MAIL_THROTTLED`, with `userId`) and no token. The application calls it for a
135
+ user it knows, so an unauthenticated loop on the address cannot spend the
136
+ count, and a user who changes e-mail buys no extra sends. `confirm` redeems it
137
+ and sets `emailVerified`. A token sent to an e-mail the user has since changed
138
+ is `TOKEN_STALE`: confirming it would verify an address nobody holds any more.
139
+ The address is checked again on the very record the write replaces, so an
140
+ e-mail changed while the link is being redeemed is `TOKEN_STALE` too, and
141
+ nothing is written.
142
+ A confirm that verifies the e-mail sends a [`user.emailVerified`
143
+ event](events.md); one for an e-mail already verified sends nothing.
144
+
145
+ Changing the e-mail with `update` sets `emailVerified` back to `false` — and
146
+ is refused (`EMAIL_CHANGE_NEEDS_PROOF`) for a user who holds a second factor or a
147
+ passkey: use `changeEmail`. The next sign-in by code or link then [drops the password and the second
148
+ factor, and signs out every session](magic-link.md#an-account-someone-else-registered).
149
+
150
+ **With several user types**, a type's own `confirm` answers `TOKEN_UNKNOWN`
151
+ for a token issued to another type's user, and spends it. A page that does
152
+ not know the type calls the root's `confirm`, which reads the user the token
153
+ was issued to and confirms as their type does: same write, same event, same
154
+ errors, and `type` in the answer says which type it was. Call it from a
155
+ `POST`, not from the `GET` of the link. `send` and `proveFirst` stay on each
156
+ type. The root's exists when one type has an e-mail, which is why no type may
157
+ be named `verifyEmail`.
158
+
159
+ ```ts
160
+ // one anonymous page for every type
161
+ const verified = await auth.verifyEmail.confirm(token); // verified.type: 'admin' | 'member'
162
+ ```
163
+
164
+ ## Making the verification link a first proof — `confirm(token, { firstProof: true })`
165
+
166
+ With open sign-up, somebody can register an address they do not own and choose
167
+ its password (and enrol a second factor). The real holder then clicks the
168
+ verification link: a plain `confirm(token)` marks the address verified and
169
+ **keeps** that password, that factor and the sessions. Pass `firstProof: true`
170
+ and, for an address never proved, the link does what `magicLink.confirm` does:
171
+
172
+ ```ts
173
+ // POST handler behind the link
174
+ const user = await auth.verifyEmail.confirm(token, { firstProof: true });
175
+ // the squatter's password, second factor and avatar are gone, every session and API key is revoked;
176
+ // the holder sets a password through resetPassword
177
+ ```
178
+
179
+ One write marks the e-mail verified and drops the password and the second
180
+ factor (active or waiting, with its recovery codes); every session and API key
181
+ is revoked and the reset links and second-factor challenges are spent, before and after
182
+ the write. Events: `user.emailVerified`, then `user.passwordChanged` and
183
+ `user.secondFactorDisabled` when something was dropped. An address **already
184
+ proved** is confirmed exactly as without the option, and a stale token is still
185
+ `TOKEN_STALE`. The option is opt-in: without it nothing changes. It works at the
186
+ root of several types too. Use it when the link is the first thing that proves
187
+ the address (sign-up sends the link). **The trade-off:** a genuine user who
188
+ signed up and has not verified yet also loses their password, second factor, avatar and
189
+ sessions when they follow the link, and sets a new password through
190
+ `resetPassword`. Leave the option off where you would rather keep that
191
+ credential. If a write lands between reading the link's user and the proof, the
192
+ call fails with `VERSION_CONFLICT`, the link is spent and nothing is proved:
193
+ send a new link (unlike `proveFirst`, `confirm` does not retry).
194
+
195
+ ## Proving an e-mail on your own proof — `proveFirst`
196
+
197
+ `verifyEmail.confirm` proves an address and, by default, changes nothing else (pass [`firstProof: true`](#making-the-verification-link-a-first-proof--confirmtoken--firstproof-true-) to drop a squatter's credential): the user
198
+ asked for the link from inside their own account. A first sign-in by link
199
+ or code goes further, since anybody may have signed up with the address
200
+ before its holder ([why](magic-link.md#an-account-someone-else-registered)).
201
+ `verifyEmail.proveFirst(user)` applies that same first proof when the proof
202
+ is **yours** — an invitation token your server mailed to the address, and
203
+ the person followed:
204
+
205
+ ```ts
206
+ interface FirstProof<User> {
207
+ readonly user: User; // after the call: emailVerified is true either way
208
+ readonly proved: boolean; // true: this call proved it; false: it was already proved
209
+ }
210
+
211
+ const { user, proved } = await auth.verifyEmail.proveFirst(invited);
212
+ ```
213
+
214
+ On an e-mail **never proved**, it is exactly the ending of
215
+ `magicLink.confirm` and `signInCode.confirm` — the same code runs:
216
+
217
+ - one write, under the version it read, marks the e-mail verified and drops
218
+ the password, the avatar and the second factor, active or waiting, with its
219
+ recovery codes, and clears the avatar (`user.avatarRemoved`);
220
+ - every session and every API key is revoked, and the reset links and second-factor
221
+ challenges are spent — before the write, so an outage there leaves the
222
+ e-mail unproved and a retry runs it all again, and after it, so a sign-in
223
+ landing in between is ended too;
224
+ - `user.emailVerified` is sent, then `user.passwordChanged` when a password
225
+ was dropped and `user.secondFactorDisabled` when an active factor was.
226
+
227
+ On an e-mail **already proved**, nothing is written, revoked or sent, and
228
+ `proved` is `false`. Whether it was proved is read off the user, as the
229
+ confirms read it: `emailVerified`.
230
+
231
+ **Call it before `setPassword` and before `signInProven`.** It drops the
232
+ password and revokes every session, so in the other order it erases the
233
+ password the invitee just chose, and signs out the session just opened.
234
+ Accepting an invitation is `findByEmail` (or `create`; `findOrCreate` does both
235
+ in one call), `proveFirst`,
236
+ `setPassword` for a type with a password, then `signInProven` —
237
+ [sessions](sessions.md#accepting-an-invitation) has the route in full.
238
+
239
+ **It is privileged.** janus checks no credential: call it only right after
240
+ your server verified a proof that reached the inbox — an invitation token
241
+ it mailed to that address — on the user the proof names, whose current
242
+ e-mail is the address it reached. Never with an id a request supplied:
243
+ whoever chooses it can drop anybody's password, second factor and avatar.
244
+
245
+ It sends no e-mail, issues no token, and counts in neither the mail
246
+ throttle nor the sign-in throttle. An inactive user is `USER_INACTIVE`; a
247
+ malformed id, an unknown one or one of another type is `NOT_FOUND`, as for
248
+ `signInProven`; an outage is `STORE_FAILED`.
249
+
250
+ **A write landing between the read and the proof is retried once.** The
251
+ proof is written under the version read, so a write in between (the user
252
+ renaming themselves, a second acceptance of the same invitation) makes it
253
+ `VERSION_CONFLICT`. `proveFirst` then runs the whole flow again on a fresh
254
+ read, and what that read finds decides:
255
+
256
+ - the user is gone or of another type: `NOT_FOUND`; inactive:
257
+ `USER_INACTIVE`;
258
+ - **the e-mail is no longer the address first read, or the one your `User`
259
+ carries** (compared as e-mails
260
+ are, so a change of case or spacing is the same address): the original
261
+ `VERSION_CONFLICT`, with nothing proved: the address changed since the first
262
+ read, or is not the one the `User` you passed carries. The proof you hold
263
+ reached the inbox of the address you read;
264
+ - the e-mail was proved meanwhile: `{ user, proved: false }`;
265
+ - otherwise the proof runs under the new version, and one
266
+ `user.emailVerified` is sent.
267
+
268
+ **The address you hold is checked.** Pass the `User` you read (any object
269
+ carrying the type's e-mail field) and `proveFirst` compares that address,
270
+ normalised as e-mails are, with the one it reads, on the first read and on
271
+ the retry read: a stale `User` whose address changed is `VERSION_CONFLICT`
272
+ and nothing is proved. Pass a bare id string, or an object without the e-mail
273
+ field, and it proves the current address, whatever it is.
274
+
275
+ A second `VERSION_CONFLICT` propagates: nothing is proved, and calling
276
+ again is safe. Running the proof twice is harmless: a failed attempt wrote
277
+ nothing and sent no event, and the sessions it revoked and the tokens it
278
+ spent before the write are revoked and spent again to the same end.
279
+ `@softistx/janus-telemetry` traces it as `janus.<type>.verifyEmail.proveFirst`
280
+ and writes `janus.email.verified` with `janus.email.proveFirst: true` when
281
+ it proved — the user's id, never the address.
282
+
283
+ ## Marking an e-mail verified as an administrator — `setEmailVerified`
284
+
285
+ An administrator who checked an address out of band sets or clears the flag
286
+ with `auth.setEmailVerified(user, verified, options?)`, on every type with an
287
+ e-mail:
288
+
289
+ ```ts
290
+ await auth.setEmailVerified(user, true); // verified
291
+ await auth.setEmailVerified(user, false, { ifVersion: 3 }); // cleared; a user written since is VERSION_CONFLICT
292
+ ```
293
+
294
+ It is `update` for that one field, in one write under the version read: the
295
+ password, avatar and second factor stay, and no session, API key or token is
296
+ revoked or spent. It sends `user.emailVerified` when it turned the flag on and
297
+ nothing when it cleared it (no event type reports that). A flag already as
298
+ asked is no write and no event. It works on an inactive user; an unknown id is
299
+ `NOT_FOUND`.
300
+
301
+ **Which to use.** `proveFirst` answers "this person proved the inbox": it
302
+ takes over the account from whoever registered the address first (password,
303
+ avatar, second factor, sessions all go). `setEmailVerified` answers "an
304
+ administrator vouches for this address on an account that stays as it is":
305
+ it does none of that, so a squatter's password survives it. Use it only for an
306
+ address you checked yourself, with an id your server chose. Clearing the flag
307
+ means the next first sign-in by link or code applies the first proof again.
308
+
309
+ ## `changeEmail`
310
+
311
+ ```ts
312
+ readonly changeEmail: {
313
+ send(user: UserRef, email: string): Promise<IssuedToken>; // { token, email, expiresAt } — email is the NEW address
314
+ confirm(token: string): Promise<User>;
315
+ };
316
+ ```
317
+
318
+ `send` issues a token for the **new** address and changes nothing. The
319
+ address is validated as `update` validates it (`USER_INVALID`), the user must
320
+ be active (`USER_INACTIVE`), and an address equal to the user's current one
321
+ once normalised is `USER_INVALID` too — a change moves to another address;
322
+ verifying the current one is `verifyEmail`'s job. The call is throttled **per
323
+ new address and per user**, five per window each, before anything is issued;
324
+ a refusal carries the user's id. A `USER_INVALID` or a `USER_INACTIVE`
325
+ spends nothing. The user is counted first, so an account past its own count
326
+ spends no address's and can exhaust at most one address per window; an
327
+ address other people exhausted costs the asking user one of their own. The user's
328
+ earlier links are spent: only the last one works. Whether another user holds
329
+ the address is not checked, so `send` tells nobody who has an account.
330
+
331
+ `confirm` spends the token, moves the user to the address and marks it
332
+ verified (an address already verified keeps its date). The password, the
333
+ second factor and the sessions are untouched — the whole account moves with
334
+ the user, so the mail should say "ignore it if it was not you". If
335
+ the address was taken meanwhile, the store answers `LOGIN_TAKEN` and nothing
336
+ is written — the token is already spent. After an `update` that moves the
337
+ e-mail, the pending links are `TOKEN_SPENT`: `update` spends them, so a move
338
+ back to the old address revives none. `TOKEN_STALE` is a link whose e-mail
339
+ is no longer the one it was asked from although nothing spent it: a write
340
+ outside janus, or a `send` racing an `update`. `confirm` sends `user.emailChanged` (with
341
+ `formerEmail`) and `user.emailVerified`.
342
+
343
+ **With several user types**, a type's own `confirm` answers `TOKEN_UNKNOWN`
344
+ for a token issued to another type's user, and spends it — a later
345
+ confirmation through the right type is then `TOKEN_SPENT`. A page that does
346
+ not know the type calls the root's `confirm`, which reads the user the token
347
+ was issued to and confirms as their type does: same move, same events, same
348
+ errors, and `type` in the answer says which type it was. `send` stays on each
349
+ type. The root's exists when one type has an e-mail, which is why no type may
350
+ be named `changeEmail`.
351
+
352
+ ```ts
353
+ // one anonymous page for every type
354
+ const changed = await auth.changeEmail.confirm(token); // changed.type: 'admin' | 'member'
355
+ ```
356
+
357
+ **Gate `send`, and tell the former address.** Whoever changes the e-mail
358
+ takes over every reset: call `send` behind a fresh sign-in or a step-up.
359
+
360
+ ```ts
361
+ import { assertFresh, janus } from '@softistx/janus';
362
+
363
+ declare function sendMail(to: string, body: string): Promise<void>; // your mailer
364
+
365
+ const auth = janus({
366
+ // …
367
+ // the former address hears of it
368
+ events: async (event) => {
369
+ if (event.type === 'user.emailChanged' && event.formerEmail != null) {
370
+ await sendMail(event.formerEmail, 'Your e-mail was changed.');
371
+ }
372
+ },
373
+ });
374
+
375
+ app.post('/email/change', async (c) => {
376
+ const current = await auth.authenticate(c.req.raw);
377
+ if (current === null) return c.body(null, 401);
378
+ assertFresh(current.session, '5m'); // STEP_UP_REQUIRED past five minutes — or a step-up
379
+ const { email } = await c.req.json<{ email: string }>();
380
+ const issued = await auth.changeEmail.send(current.user, email);
381
+ await sendMail(issued.email, `https://app.example/email/confirm?token=${issued.token}`);
382
+ return c.body(null, 202);
383
+ });
384
+
385
+ // the confirm page POSTs the token back — never confirm on the GET
386
+ app.post('/email/confirm', async (c) => {
387
+ const { token } = await c.req.json<{ token: string }>();
388
+ await auth.changeEmail.confirm(token);
389
+ return c.body(null, 204);
390
+ });
391
+ ```
392
+
393
+ The adapter's store must list the `changeEmail` token kind first:
394
+ `@softistx/janus-drizzle` 0.8's migration, `@softistx/janus-mongo` 0.9's sync.
395
+
396
+ ## `resetPassword`
397
+
398
+ ```ts
399
+ readonly resetPassword: {
400
+ request(email: string): Promise<(IssuedToken & { user: User }) | null>;
401
+ prepare(email: string): Promise<PreparedRequest<IssuedToken & { user: User }>>; // { send() }, below
402
+ confirm(token: string, password: string): Promise<User>;
403
+ };
404
+ ```
405
+
406
+ `request` answers `null` for an e-mail nobody holds. **Never tell the visitor
407
+ which**: answer the same page either way.
408
+
409
+ ```ts
410
+ export async function forgotPassword(request: Request): Promise<Response> {
411
+ const { email } = (await request.json()) as { email: string };
412
+ const issued = await auth.resetPassword.request(email);
413
+ if (issued !== null) {
414
+ await sendMail(issued.email, `https://app.example/reset?token=${issued.token}`);
415
+ }
416
+ return new Response(null, { status: 202 }); // the same answer either way
417
+ }
418
+ ```
419
+
420
+ **At most one reset link is live per user.** A `request` issues its link,
421
+ then spends every other reset link of the user, so the link in an earlier
422
+ e-mail answers `TOKEN_SPENT` — only the last one works, as for [sign-in
423
+ codes](sign-in-code.md):
424
+
425
+ ```ts
426
+ const first = await auth.resetPassword.request(email);
427
+ const second = await auth.resetPassword.request(email); // the visitor asked again
428
+ if (first !== null && second !== null) {
429
+ await auth.resetPassword.confirm(first.token, newPassword); // TOKEN_SPENT
430
+ await auth.resetPassword.confirm(second.token, newPassword); // reset
431
+ }
432
+ ```
433
+
434
+ Requests that arrive at once cannot each keep a link: each spends the
435
+ others' once it issued its own, so at most one survives — sometimes none, and
436
+ the visitor asks again. **`request` is throttled per address**, as for
437
+ sign-in codes: each one sends an e-mail and cancels the link before it, so
438
+ past five requests for one address in a 10-minute window it throws
439
+ `MailThrottledError` (`MAIL_THROTTLED`) and issues nothing; the link last sent
440
+ still works. An address nobody holds is counted and refused alike, and under
441
+ the limit still answers `null`. Somebody who knows an address can fill its
442
+ inbox with at most five reset e-mails a window, but cannot shut the reset:
443
+ the last one sent still works. Limit the route per client yourself too, and
444
+ see [the mail throttle](#requests-that-send-e-mail-are-throttled).
445
+
446
+ `request`'s time still tells an account from nobody — a lookup, then a link
447
+ written and the earlier ones spent, against a lookup alone. To keep that off
448
+ the visitor's request and still answer them `MAIL_THROTTLED`, call
449
+ `resetPassword.prepare(email)` there and its `send()` in the background:
450
+ [requests in two steps](#requests-in-two-steps).
451
+
452
+ **Writing a password spends every reset link still live.** A `confirm`,
453
+ `changePassword` and `setPassword` each do, so a link sent before the
454
+ password changed cannot replace it again:
455
+
456
+ ```ts
457
+ const issued = await auth.resetPassword.request(email);
458
+ await auth.changePassword(user, { current, next });
459
+ if (issued !== null) {
460
+ await auth.resetPassword.confirm(issued.token, other); // TOKEN_SPENT
461
+ }
462
+ ```
463
+
464
+ The links are spent **after** the password is written, so a link issued
465
+ during the write is spent too. If the store fails at that step, the call
466
+ rejects with `STORE_FAILED` although the password is written — answer 503 as
467
+ usual — and the older links may still be live until the next `request`,
468
+ which spends them. Sign-in codes, sign-in links and step-ups are not spent:
469
+ the password proves none of them.
470
+
471
+ `confirm` sets the password, marks the e-mail verified — the link proved it —
472
+ and **signs the user out everywhere**: their sessions are revoked, and every
473
+ second-factor challenge still open is spent, so a sign-in started with the
474
+ old password cannot be finished. The e-mail is checked again on the record
475
+ written, as for `verifyEmail`. It sends a [`user.passwordReset` event](events.md),
476
+ then `user.emailVerified` when the link verified the e-mail. It opens no session: call `signIn` next
477
+ if that is your policy. A password refused for its length does not spend the
478
+ token, so the visitor can try again with the same link.
479
+
480
+ **With several user types**, a type's own `confirm` answers `TOKEN_UNKNOWN`
481
+ for a token issued to another type's user, and spends it. A page that does
482
+ not know the type calls the root's `confirm`, which reads the user the token
483
+ was issued to and resets as their type does: same write, same sign-out, same
484
+ events, same errors, and `type` in the answer says which type it was. Call it
485
+ from a `POST`. `request` and `prepare` stay on each type: they need the type
486
+ to find the holder of the address. The root's exists when one type has a
487
+ password and an e-mail, which is why no type may be named `resetPassword`.
488
+
489
+ The type is only known once the token is spent, so the root checks the
490
+ password **before** that against the **strictest `minLength`** of the types
491
+ with a password — a password type with no e-mail counts too, since the root
492
+ cannot tell; it can never be reset, but its rule still applies at the root. A
493
+ refused password never costs the link.
494
+ A type with a shorter rule sees the stricter one at the root only — its own
495
+ `confirm` applies its own. See [the password
496
+ policy](passwords.md#resetting-a-password-at-the-root-of-several-types).
497
+
498
+ ```ts
499
+ // one anonymous page for every type
500
+ const reset = await auth.resetPassword.confirm(token, newPassword); // reset.type: 'admin' | 'member'
501
+ ```
502
+
503
+ ```ts
504
+ import { JanusError } from '@softistx/janus';
505
+
506
+ export async function resetPassword(request: Request): Promise<Response> {
507
+ const { token, password } = (await request.json()) as { token: string; password: string };
508
+ try {
509
+ await auth.resetPassword.confirm(token, password);
510
+ return new Response(null, { status: 204 });
511
+ } catch (error) {
512
+ if (!(error instanceof JanusError)) throw error;
513
+ switch (error.code) {
514
+ case 'TOKEN_UNKNOWN':
515
+ case 'TOKEN_SPENT':
516
+ case 'TOKEN_EXPIRED':
517
+ case 'TOKEN_STALE':
518
+ return Response.json({ error: 'link' }, { status: 400 });
519
+ case 'PASSWORD_TOO_SHORT':
520
+ return Response.json({ minLength: error.minLength }, { status: 400 });
521
+ default:
522
+ throw error; // STORE_FAILED: your 503
523
+ }
524
+ }
525
+ }
526
+ ```
527
+
528
+ ## Requests that send e-mail are throttled
529
+
530
+ **Every request that hands out something to e-mail is counted**, on by default:
531
+ five per 10 minutes, per flow. Past the limit the request throws
532
+ `MailThrottledError` (`MAIL_THROTTLED`, 429) with `retryAfter` — the whole
533
+ seconds to the end of the window, at least 1 — and **a refused request spends,
534
+ invalidates and rotates nothing**: no token, code or challenge is minted, and
535
+ nothing earlier is spent, so **the last link or code sent still confirms until
536
+ it expires**, whoever asked for it. The count comes before anything is issued,
537
+ and the earlier tokens are spent only after a new one is issued.
538
+
539
+ ```ts
540
+ import { MailThrottledError } from '@softistx/janus';
541
+
542
+ try {
543
+ await auth.resetPassword.request(email);
544
+ } catch (error) {
545
+ if (error instanceof MailThrottledError) {
546
+ // 429 and Retry-After: error.retryAfter — safe to show, it reveals nothing about accounts.
547
+ // Tell the visitor: "Check your inbox: the last e-mail we sent still works.
548
+ // You can ask for a new one in N minutes."
549
+ }
550
+ throw error;
551
+ }
552
+ ```
553
+
554
+ | Flow | Counted per | Why |
555
+ | --- | --- | --- |
556
+ | `magicLink.request(email)` | address | Anybody can call it with any address. Counted before the address is looked up, so an address nobody holds is refused like a registered one |
557
+ | `signInCode.request(email)` | address | The same |
558
+ | `resetPassword.request(email)` | address | The same |
559
+ | `changeEmail.send(user, email)` | user, and new address | Counted twice (the user, then the new address), five per window each, before anything is issued — a refusal carries the user's id: a loop on one user cannot fill an inbox, and one address cannot be flooded from many users |
560
+ | `verifyEmail.send(user)` | user | The application calls it for a user it knows: an unauthenticated loop on the address cannot spend this count, so it never blocks the user's own verification, and a user changing e-mail buys no extra sends |
561
+ | `stepUp.request(user)`, when it e-mails a code (`via: 'email'`) | user | The same. A step-up confirmed with the app (`via: 'secondFactor'`) sends nothing and is not counted |
562
+
563
+ **Keep the window no longer than the shortest token lifetime you set.** A
564
+ refused request spends nothing, but the last link or code sent still has to be
565
+ alive. With `tokens.signInCode: '5m'` and the 10-minute window, a code can lapse
566
+ while the visitor is still refused. `janus()` warns for it, once per call, with
567
+ `process.emitWarning` and the code `JANUS_THROTTLE_WINDOW`, naming each flow
568
+ whose lifetime is shorter than the window:
569
+
570
+ ```
571
+ janus: tokens.signInCode is 5m, shorter than mail.throttle.window, 10m — past the limit the last token sent can expire before the refusal ends. Set mail.throttle.window to 5m or less, or raise tokens.signInCode to 10m or more.
572
+ ```
573
+
574
+ Shorten `mail.throttle.window`, or raise the lifetime. Nothing is refused, so
575
+ a window you chose on purpose only costs the warning.
576
+
577
+ **`prepare` counts as `request` does**, in the same window: see
578
+ [requests in two steps](#requests-in-two-steps), for an application that
579
+ sends the e-mail off the visitor's request and still wants to tell them
580
+ they are throttled.
581
+
582
+ **Each flow counts on its own**: a loop on `magicLink.request` never shuts
583
+ `signInCode.request`. The address is normalised (trimmed, lowercased) and is
584
+ the same count whatever the user type.
585
+
586
+ | Option | Type | Default | Effect |
587
+ | --- | --- | --- | --- |
588
+ | `mail.throttle.attempts` | whole number above zero | `5` | Requests per flow, per address or user, per window |
589
+ | `mail.throttle.window` | `Duration` | `'10m'` | How long a window lasts |
590
+ | `mail.throttle` | `false` | | Counts nothing: limit those requests yourself |
591
+
592
+ ```ts
593
+ janus({ user, store, mail: { throttle: { attempts: 3, window: '1h' } } });
594
+ janus({ user, store, mail: { throttle: false } });
595
+ ```
596
+
597
+ ```ts
598
+ export interface MailConfig {
599
+ readonly throttle?: MailThrottleConfig | false;
600
+ }
601
+ export interface MailThrottleConfig {
602
+ readonly attempts?: number;
603
+ readonly window?: Duration;
604
+ }
605
+ ```
606
+
607
+ Five per ten minutes is no longer than the shortest default token lifetime
608
+ (`signInCode` and `stepUp` `'10m'`; `magicLink` `'15m'`, `resetPassword` `'1h'`,
609
+ `verifyEmail` `'24h'`), so under the defaults the last link or code sent —
610
+ issued inside the window — is still live for the whole refusal. It leaves room
611
+ for a visitor who asks again, and holds a loop to thirty e-mails an hour per
612
+ flow and address. A wrong value is refused when `janus()` is called, with
613
+ a `TypeError`: `janus: mail must be an object — { throttle }`, `janus:
614
+ mail.throttle must be { attempts, window }, or false to count nothing`,
615
+ `janus: mail.throttle.attempts must be a whole number above zero`, or a
616
+ `janus: mail.throttle.window` duration message.
617
+
618
+ **Fixed windows, and nothing locks.** The window is a fixed slice of the
619
+ clock, as the sign-in throttle's. Requests at once are counted in one store
620
+ write each: of twenty at once, exactly five are issued. The next window
621
+ answers again. A refused request is counted too but cannot extend the wait.
622
+
623
+ **Where the counts live.** In the tokens store, as `secondFactor` tokens named
624
+ by a keyed hash of the flow and the address or user id: no port change, no new
625
+ infrastructure, and never the address. That is one row per flow per address or
626
+ user per window. `collectExpired()` collects the lapsed ones on a tokens store that implements
627
+ `deleteExpiredTokens`; a store with a TTL expires them on its own. A flushed or evicting
628
+ Redis forgets the counts, and a tokens store that cannot count throws
629
+ `STORE_FAILED` with nothing issued: it fails closed.
630
+
631
+ **What it does not do.**
632
+
633
+ - **It cannot lock somebody out.** Somebody who asks for an address in a loop
634
+ can fill its inbox with at most five e-mails per window per flow, but the
635
+ last e-mail they caused to be sent was a real e-mail to the real owner and
636
+ still works until it expires. The password sign-in is untouched.
637
+ - **A lifetime shorter than the window breaks that.** With
638
+ `tokens.signInCode: '5m'` and the default window, the last code can expire
639
+ before the window ends and the visitor has no live code until it does. Keep
640
+ `mail.throttle.window` no longer than the shortest of the `tokens.*`
641
+ lifetimes you use.
642
+ - **It is not per client.** `janus` never sees IP addresses, so one client
643
+ asking for many addresses is not counted. Add a per-IP ceiling in front of
644
+ the routes: `@softistx/redis` (0.5.0 and later) has rate limits for it.
645
+
646
+ ```ts
647
+ import { bindRateLimit, defineRateLimit, GuardError } from '@softistx/redis';
648
+
649
+ export const mailRequests = defineRateLimit({
650
+ name: 'mail-requests',
651
+ key: (p: { ip: string }) => p.ip,
652
+ limit: 20,
653
+ per: 3_600_000,
654
+ });
655
+ const perIp = bindRateLimit(client, mailRequests); // or redis.limits.<name> when wired
656
+
657
+ try {
658
+ await perIp.enforce({ ip }); // before auth.magicLink.request(email)
659
+ } catch (error) {
660
+ if (error instanceof GuardError && error.code === 'RATE_LIMITED') {
661
+ // error.retryAfter is in MILLISECONDS: Math.ceil(error.retryAfter / 1000) for Retry-After
662
+ }
663
+ throw error;
664
+ }
665
+ ```
666
+ - **A test suite** that requests more than five of one flow for one address or
667
+ user over a `fixedClock` is throttled: advance the clock past `retryAfter`,
668
+ or wire `mail: { throttle: false }`.
669
+
670
+ **Not throttled**, because they follow a write or a sign-in, which are bounded
671
+ elsewhere (the [sign-in throttle](passwords.md#password-guessing-is-throttled)
672
+ bounds sign-ins), not a request to mail an address:
673
+
674
+ - `update` changing the e-mail: an application write. Its notice to the former
675
+ address is sent from the `user.emailChanged` event.
676
+ - The notices sent from [events](events.md): a new device, a password changed,
677
+ a recovery code used, and the like.
678
+
679
+ `@softistx/janus-hono` and `@softistx/janus-graphql` answer `MAIL_THROTTLED` with 429,
680
+ `retryAfter` in the body (or the extensions) and a `Retry-After` header;
681
+ `@softistx/janus-telemetry` writes a `janus.mail.throttled` warning with
682
+ `janus.mail.flow` and `janus.mail.retryAfter`, never the address.
683
+
684
+ ## Requests in two steps
685
+
686
+ `request(email)` counts the address, then looks it up and issues. Its time
687
+ tells what its answer does not: an address with an account costs a lookup,
688
+ a token written and the earlier ones spent; one nobody holds stops at the
689
+ lookup. So an application that must not tell the two apart runs `request`
690
+ **off the visitor's request** — and there, a `MAIL_THROTTLED` reaches
691
+ nobody: the visitor is never told to use the last e-mail they received.
692
+
693
+ `prepare(email)` cuts `request` in two at the count, on the three flows
694
+ counted per address:
695
+
696
+ | Call | Does | Answers |
697
+ | --- | --- | --- |
698
+ | `magicLink.prepare(email)` | validates, counts the address, looks nobody up | `PreparedRequest<IssuedToken & { user }>`: `{ send() }` |
699
+ | `signInCode.prepare(email)` | the same, and mints the challenge | `PreparedCode<User>`: `{ challenge, send() }` |
700
+ | `resetPassword.prepare(email)` | the same, refusing a type with no password as `request` does | `PreparedRequest<IssuedToken & { user }>`: `{ send() }` |
701
+ | `send()`, on any of them | the rest of `request` — the lookup, the token issued, the earlier ones spent — **once**, and counts nothing | what `request` answers: the token or code, or `null` for nobody |
702
+
703
+ Two more flows are cut the same way, for sign-up and an anonymous resend of
704
+ the verification: [`signUp.prepare` and `verifyEmail.prepare`](#verifying-at-sign-up-without-revealing-taken-addresses).
705
+
706
+ Call `prepare` in the visitor's request, where its `MailThrottledError` can be
707
+ answered; call `send()` off it:
708
+
709
+ ```ts
710
+ import { Hono } from 'hono';
711
+ import { janusErrors } from '@softistx/janus-hono';
712
+
713
+ const app = new Hono();
714
+ app.onError(janusErrors()); // MAIL_THROTTLED → 429, Retry-After and retryAfter in the body
715
+
716
+ app.post('/reset-password', async (c) => {
717
+ const { email } = await c.req.json();
718
+ const pending = await auth.resetPassword.prepare(email); // counted: throws MAIL_THROTTLED past the limit
719
+ void mailOff(async () => {
720
+ const issued = await pending.send(); // looked up and issued, off the visitor's request
721
+ if (issued !== null) {
722
+ await mailer.send(issued.email, `https://app.example/reset?token=${issued.token}`);
723
+ }
724
+ });
725
+ return c.body(null, 202); // the same answer either way
726
+ });
727
+
728
+ /** Runs `work` off the request, and reports what it throws: nobody else will see it. */
729
+ function mailOff(work: () => Promise<void>): Promise<void> {
730
+ return work().catch((error: unknown) => console.error(error));
731
+ }
732
+ ```
733
+
734
+ The visitor sees `429` with `retryAfter` past the limit — "use the last
735
+ e-mail you received, or wait" — and `202` otherwise, in the same time whether
736
+ the address has an account or not. In production, `send()` belongs in the
737
+ queue that sends the e-mail, so a failure is retried by preparing again.
738
+
739
+ **What `prepare` does is the same for every address.** It looks nobody up:
740
+ the store calls are the count's, the same calls whoever holds the address,
741
+ and none at all with `mail: { throttle: false }`, where `prepare` still
742
+ validates and answers a pending request. `prepare` and `request` share one
743
+ count: three `prepare` and two `request` of one flow for one address fill
744
+ the window.
745
+
746
+ **`send()` runs once.** The count `prepare` made pays for one issue, and
747
+ nothing a caller passes can skip it — there is no option to say "already
748
+ counted". A second `send()` is a `TypeError`:
749
+
750
+ ```
751
+ magicLink.prepare(…).send: already called — a prepared request sends once; call magicLink.prepare again for another
752
+ ```
753
+
754
+ A `send()` that failed — `STORE_FAILED` — is spent too: prepare again, which
755
+ counts again. Two `send()` at once issue one token; the other is the
756
+ `TypeError`.
757
+
758
+ **A sign-in code's challenge comes with `prepare`.** The visitor keeps the
759
+ challenge, and the code goes to the inbox, so a code requested in the
760
+ background still needs its challenge in the foreground answer.
761
+ `signInCode.prepare` mints it before the lookup, so it is in the visitor's
762
+ cookie whoever holds the address — the decoy an unknown address needed is
763
+ no longer yours to make. For an address nobody holds, `send()` answers
764
+ `null` and the challenge is `TOKEN_UNKNOWN`; otherwise the code `send()`
765
+ issues is checked against it. See
766
+ [the sign-in code guide](sign-in-code.md#requesting-a-code-in-two-steps).
767
+
768
+ **`verifyEmail.send`, `changeEmail.send` and `stepUp.request` have no
769
+ `prepare`.** They are counted per user, and called for a user the application already holds — the
770
+ session's, or one it just created — so their time tells nothing about who
771
+ has an account, and their `MAIL_THROTTLED` already reaches the visitor in
772
+ the request that asked.
773
+
774
+ **`@softistx/janus-telemetry`** traces `prepare` as
775
+ `janus.magicLink.prepare` and its `send()` as `janus.magicLink.prepare.send`;
776
+ `janus.mail.throttled` names `janus.mail.flow: magicLink.prepare`, and
777
+ `janus.magicLink.sent` and `janus.signInCode.sent` are written by `send()`,
778
+ as by `request`.
779
+
780
+ ## What a token refusal means
781
+
782
+ | Code | When |
783
+ | --- | --- |
784
+ | `TOKEN_UNKNOWN` | No token holds that secret — or it was issued for the other flow: a verification token is not a reset token |
785
+ | `TOKEN_SPENT` | Already redeemed — every token is single use. A reset link is also spent by a newer `request` for the same user, and by any password written since it was sent; a change link, by a newer send or an update that moves the e-mail |
786
+ | `TOKEN_EXPIRED` | Its lifespan passed. It is spent all the same, so it cannot be retried |
787
+ | `TOKEN_STALE` | Asked for an e-mail the user no longer has: the link was sent to an address they have since left — or, for `changeEmail`, asked while they held an address they have since changed. Send a new link |
788
+
789
+ Of twenty concurrent redemptions of one token, exactly one succeeds: the store
790
+ spends it in one conditional write. The store holds the token's `sha256`,
791
+ never the token, and no refusal's message contains it.
792
+
793
+ ## See also
794
+
795
+ - [Users](users.md) — `email`, `update`, and the other per-type methods
796
+ - [Sign-in codes](sign-in-code.md) — the third flow that sends an e-mail: a code, not a link
797
+ - [Sign-in links](magic-link.md) — the fourth: a link that signs in, confirmed from a `POST` so a mail scanner spends nothing
798
+ - [Sessions](sessions.md) — `signOutEverywhere`, which `resetPassword.confirm` calls for you
799
+ - [User events](events.md) — `user.emailVerified`, `user.emailChanged` and `user.passwordReset`, which the confirms and `proveFirst` send
800
+ - [Errors](errors.md) — every code, and the status it deserves
801
+
802
+ ## Verifying at sign-up without revealing taken addresses
803
+
804
+ `signUp` signs the visitor in at once and throws `LOGIN_TAKEN` for a taken
805
+ address, which tells a guesser who has an account. For an application that
806
+ verifies the address and answers the same either way, three pieces work
807
+ together.
808
+
809
+ ```ts
810
+ const auth = janus({
811
+ user: User,
812
+ hasher,
813
+ store,
814
+ password: { login: 'email', requireVerifiedEmail: true },
815
+ });
816
+
817
+ app.post('/sign-up', async (c) => {
818
+ const { email, name, password } = await c.req.json();
819
+ // In the request: USER_INVALID and PASSWORD_TOO_SHORT are answered here, and the
820
+ // attempt is counted per address (MAIL_THROTTLED). Nobody is looked up.
821
+ const pending = await auth.signUp.prepare({ email, name, password });
822
+ void mailOff(async () => {
823
+ const outcome = await pending.send(); // hashes, writes — the time tells which
824
+ if (outcome.status === 'created') {
825
+ await mailer.send(outcome.issued.email, `https://app.example/verify?token=${outcome.issued.token}`);
826
+ } else {
827
+ await mailer.send(outcome.user.email, 'Somebody tried to sign up with your address.');
828
+ }
829
+ });
830
+ return c.body(null, 202); // "check your inbox": the same for a new and a taken address
831
+ });
832
+
833
+ app.post('/verify/resend', async (c) => {
834
+ const { email } = await c.req.json();
835
+ const pending = await auth.verifyEmail.prepare(email); // counted per address
836
+ void mailOff(async () => {
837
+ const issued = await pending.send(); // null for nobody, an inactive user or a verified address
838
+ if (issued !== null) {
839
+ await mailer.send(issued.email, `https://app.example/verify?token=${issued.token}`);
840
+ }
841
+ });
842
+ return c.body(null, 202);
843
+ });
844
+ ```
845
+
846
+ | Call | Does | Answers |
847
+ | --- | --- | --- |
848
+ | `signUp.prepare(input)` | validates the fields and the password policy, counts the attempt per address, looks nobody up | `PreparedSignUp<User>`: `{ send() }` |
849
+ | `send()` on it | creates the user and issues a `verifyEmail` token, or finds the login held; **once**, counts nothing | `{ status: 'created', user, issued }` or `{ status: 'taken', user }` |
850
+ | `verifyEmail.prepare(email)` | counts the address, looks nobody up | `PreparedRequest<IssuedToken & { user }>`: `{ send() }` |
851
+ | `send()` on it | issues for the active user holding the address, if unverified | the token, or `null` for anybody else |
852
+
853
+ - **No session is opened** by `signUp.prepare`'s `send()`. Confirm the token
854
+ with `verifyEmail.confirm`, then the user signs in. `requireVerifiedEmail`
855
+ makes that rule hold for the password too: until then a correct password is
856
+ `EMAIL_UNVERIFIED` (403), where a wrong one stays `CREDENTIALS_INVALID`.
857
+ - **`taken` carries the holder**, so the application can mail them a notice.
858
+ A password-less holder (created by an admin or a link) counts as taken.
859
+ Nothing of the sign-up is written, and the holder's password is unchanged.
860
+ - **The counts**: `signUp.prepare` counts per address in its own window
861
+ (`janus({ mail: { throttle } })`; none with `throttle: false`);
862
+ `verifyEmail.prepare` counts per address too, apart from the per-user
863
+ count of `verifyEmail.send`.
864
+ - **Only a type whose login is its e-mail field has `signUp.prepare`**
865
+ (typed away elsewhere, `TypeError` at run time): the address typed is the
866
+ holder's, so the `taken` notice reaches the person who owns it, and a
867
+ taken username reveals no account. A schema that lets the e-mail be
868
+ absent refuses with `USER_INVALID`.
869
+ - **Account pre-hijacking.** Somebody can sign up with another person's
870
+ address and choose its password; if the real owner confirms the
871
+ verification mail, the address is verified and the squatter's password
872
+ stays. Put a `resetPassword` link in the `taken` notice (a reset proves
873
+ the address and replaces the password), end every verification mail with
874
+ "ignore this if it was not you". Keep the password with
875
+ `requireVerifiedEmail`: `verifyEmail.confirm(token, { firstProof: true })`
876
+ would drop every honest signer's password too, so use it only where users
877
+ set the password after proving the address (or sign in by link or code).
878
+ Janus changes no behaviour for this: it is the mails you write.
879
+ - `send()` is `TypeError` on a second call, like the other prepared
880
+ requests. `signUp` itself is unchanged.