@softistx/janus 0.0.0-stage → 0.74.0
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.
- package/LICENSE +21 -0
- package/README.md +2929 -2
- package/dist/auth/api-keys/authenticate-key.d.ts +21 -0
- package/dist/auth/api-keys/authenticate-key.d.ts.map +1 -0
- package/dist/auth/api-keys/bound.d.ts +11 -0
- package/dist/auth/api-keys/bound.d.ts.map +1 -0
- package/dist/auth/api-keys/count.d.ts +8 -0
- package/dist/auth/api-keys/count.d.ts.map +1 -0
- package/dist/auth/api-keys/create/checks.d.ts +42 -0
- package/dist/auth/api-keys/create/checks.d.ts.map +1 -0
- package/dist/auth/api-keys/create/index.d.ts +10 -0
- package/dist/auth/api-keys/create/index.d.ts.map +1 -0
- package/dist/auth/api-keys/events.d.ts +22 -0
- package/dist/auth/api-keys/events.d.ts.map +1 -0
- package/dist/auth/api-keys/expiry.d.ts +11 -0
- package/dist/auth/api-keys/expiry.d.ts.map +1 -0
- package/dist/auth/api-keys/flows.d.ts +13 -0
- package/dist/auth/api-keys/flows.d.ts.map +1 -0
- package/dist/auth/api-keys/index.d.ts +11 -0
- package/dist/auth/api-keys/index.d.ts.map +1 -0
- package/dist/auth/api-keys/read.d.ts +10 -0
- package/dist/auth/api-keys/read.d.ts.map +1 -0
- package/dist/auth/api-keys/shape.d.ts +24 -0
- package/dist/auth/api-keys/shape.d.ts.map +1 -0
- package/dist/auth/api-keys/to-api-key.d.ts +8 -0
- package/dist/auth/api-keys/to-api-key.d.ts.map +1 -0
- package/dist/auth/api-keys/token.d.ts +23 -0
- package/dist/auth/api-keys/token.d.ts.map +1 -0
- package/dist/auth/api-keys/user-bound.d.ts +10 -0
- package/dist/auth/api-keys/user-bound.d.ts.map +1 -0
- package/dist/auth/at.d.ts +9 -0
- package/dist/auth/at.d.ts.map +1 -0
- package/dist/auth/avatar/any-type.d.ts +13 -0
- package/dist/auth/avatar/any-type.d.ts.map +1 -0
- package/dist/auth/avatar/flows.d.ts +7 -0
- package/dist/auth/avatar/flows.d.ts.map +1 -0
- package/dist/auth/avatar/id.d.ts +10 -0
- package/dist/auth/avatar/id.d.ts.map +1 -0
- package/dist/auth/avatar/index.d.ts +7 -0
- package/dist/auth/avatar/index.d.ts.map +1 -0
- package/dist/auth/avatar/remove.d.ts +10 -0
- package/dist/auth/avatar/remove.d.ts.map +1 -0
- package/dist/auth/avatar/set.d.ts +12 -0
- package/dist/auth/avatar/set.d.ts.map +1 -0
- package/dist/auth/concurrency-limit.d.ts +13 -0
- package/dist/auth/concurrency-limit.d.ts.map +1 -0
- package/dist/auth/config/api-keys-config.d.ts +33 -0
- package/dist/auth/config/api-keys-config.d.ts.map +1 -0
- package/dist/auth/config/hasher.d.ts +22 -0
- package/dist/auth/config/hasher.d.ts.map +1 -0
- package/dist/auth/config/index.d.ts +24 -0
- package/dist/auth/config/index.d.ts.map +1 -0
- package/dist/auth/config/invitations-config.d.ts +74 -0
- package/dist/auth/config/invitations-config.d.ts.map +1 -0
- package/dist/auth/config/janus-config.d.ts +233 -0
- package/dist/auth/config/janus-config.d.ts.map +1 -0
- package/dist/auth/config/magic-link-config.d.ts +6 -0
- package/dist/auth/config/magic-link-config.d.ts.map +1 -0
- package/dist/auth/config/names.d.ts +9 -0
- package/dist/auth/config/names.d.ts.map +1 -0
- package/dist/auth/config/normalize.d.ts +26 -0
- package/dist/auth/config/normalize.d.ts.map +1 -0
- package/dist/auth/config/passkeys-config.d.ts +49 -0
- package/dist/auth/config/passkeys-config.d.ts.map +1 -0
- package/dist/auth/config/password-config.d.ts +22 -0
- package/dist/auth/config/password-config.d.ts.map +1 -0
- package/dist/auth/config/reserved.d.ts +14 -0
- package/dist/auth/config/reserved.d.ts.map +1 -0
- package/dist/auth/config/resolve-api-keys.d.ts +5 -0
- package/dist/auth/config/resolve-api-keys.d.ts.map +1 -0
- package/dist/auth/config/resolve-config.d.ts +9 -0
- package/dist/auth/config/resolve-config.d.ts.map +1 -0
- package/dist/auth/config/resolve-cookie.d.ts +5 -0
- package/dist/auth/config/resolve-cookie.d.ts.map +1 -0
- package/dist/auth/config/resolve-devices.d.ts +5 -0
- package/dist/auth/config/resolve-devices.d.ts.map +1 -0
- package/dist/auth/config/resolve-invitation-types.d.ts +5 -0
- package/dist/auth/config/resolve-invitation-types.d.ts.map +1 -0
- package/dist/auth/config/resolve-invitations.d.ts +5 -0
- package/dist/auth/config/resolve-invitations.d.ts.map +1 -0
- package/dist/auth/config/resolve-magic-link.d.ts +4 -0
- package/dist/auth/config/resolve-magic-link.d.ts.map +1 -0
- package/dist/auth/config/resolve-passkeys.d.ts +5 -0
- package/dist/auth/config/resolve-passkeys.d.ts.map +1 -0
- package/dist/auth/config/resolve-second-factor.d.ts +5 -0
- package/dist/auth/config/resolve-second-factor.d.ts.map +1 -0
- package/dist/auth/config/resolve-social.d.ts +17 -0
- package/dist/auth/config/resolve-social.d.ts.map +1 -0
- package/dist/auth/config/resolve-throttle.d.ts +37 -0
- package/dist/auth/config/resolve-throttle.d.ts.map +1 -0
- package/dist/auth/config/resolve-type.d.ts +6 -0
- package/dist/auth/config/resolve-type.d.ts.map +1 -0
- package/dist/auth/config/resolved-config.d.ts +126 -0
- package/dist/auth/config/resolved-config.d.ts.map +1 -0
- package/dist/auth/config/social-config.d.ts +154 -0
- package/dist/auth/config/social-config.d.ts.map +1 -0
- package/dist/auth/config/user-type.d.ts +79 -0
- package/dist/auth/config/user-type.d.ts.map +1 -0
- package/dist/auth/config/warn-throttle-window.d.ts +14 -0
- package/dist/auth/config/warn-throttle-window.d.ts.map +1 -0
- package/dist/auth/context/create-context.d.ts +31 -0
- package/dist/auth/context/create-context.d.ts.map +1 -0
- package/dist/auth/context/index.d.ts +17 -0
- package/dist/auth/context/index.d.ts.map +1 -0
- package/dist/auth/context/logins.d.ts +28 -0
- package/dist/auth/context/logins.d.ts.map +1 -0
- package/dist/auth/context/password.d.ts +34 -0
- package/dist/auth/context/password.d.ts.map +1 -0
- package/dist/auth/context/records.d.ts +27 -0
- package/dist/auth/context/records.d.ts.map +1 -0
- package/dist/auth/context/user.d.ts +21 -0
- package/dist/auth/context/user.d.ts.map +1 -0
- package/dist/auth/context/validate-fields.d.ts +12 -0
- package/dist/auth/context/validate-fields.d.ts.map +1 -0
- package/dist/auth/counter-key.d.ts +20 -0
- package/dist/auth/counter-key.d.ts.map +1 -0
- package/dist/auth/derived-keys.d.ts +9 -0
- package/dist/auth/derived-keys.d.ts.map +1 -0
- package/dist/auth/devices/cookie.d.ts +56 -0
- package/dist/auth/devices/cookie.d.ts.map +1 -0
- package/dist/auth/devices/hint.d.ts +42 -0
- package/dist/auth/devices/hint.d.ts.map +1 -0
- package/dist/auth/devices/index.d.ts +11 -0
- package/dist/auth/devices/index.d.ts.map +1 -0
- package/dist/auth/devices/report.d.ts +11 -0
- package/dist/auth/devices/report.d.ts.map +1 -0
- package/dist/auth/devices/token.d.ts +13 -0
- package/dist/auth/devices/token.d.ts.map +1 -0
- package/dist/auth/email-flows/any-type-change-email.d.ts +18 -0
- package/dist/auth/email-flows/any-type-change-email.d.ts.map +1 -0
- package/dist/auth/email-flows/any-type-reset-password.d.ts +19 -0
- package/dist/auth/email-flows/any-type-reset-password.d.ts.map +1 -0
- package/dist/auth/email-flows/any-type-verify-email.d.ts +18 -0
- package/dist/auth/email-flows/any-type-verify-email.d.ts.map +1 -0
- package/dist/auth/email-flows/change-email-token.d.ts +47 -0
- package/dist/auth/email-flows/change-email-token.d.ts.map +1 -0
- package/dist/auth/email-flows/change-email.d.ts +17 -0
- package/dist/auth/email-flows/change-email.d.ts.map +1 -0
- package/dist/auth/email-flows/confirm-reset.d.ts +16 -0
- package/dist/auth/email-flows/confirm-reset.d.ts.map +1 -0
- package/dist/auth/email-flows/email-token.d.ts +30 -0
- package/dist/auth/email-flows/email-token.d.ts.map +1 -0
- package/dist/auth/email-flows/flows.d.ts +13 -0
- package/dist/auth/email-flows/flows.d.ts.map +1 -0
- package/dist/auth/email-flows/index.d.ts +10 -0
- package/dist/auth/email-flows/index.d.ts.map +1 -0
- package/dist/auth/email-flows/owner-of.d.ts +17 -0
- package/dist/auth/email-flows/owner-of.d.ts.map +1 -0
- package/dist/auth/email-flows/prove-first.d.ts +45 -0
- package/dist/auth/email-flows/prove-first.d.ts.map +1 -0
- package/dist/auth/email-flows/reset-password.d.ts +17 -0
- package/dist/auth/email-flows/reset-password.d.ts.map +1 -0
- package/dist/auth/email-flows/set-email-verified.d.ts +19 -0
- package/dist/auth/email-flows/set-email-verified.d.ts.map +1 -0
- package/dist/auth/email-flows/verify-email.d.ts +25 -0
- package/dist/auth/email-flows/verify-email.d.ts.map +1 -0
- package/dist/auth/email-sign-in.d.ts +51 -0
- package/dist/auth/email-sign-in.d.ts.map +1 -0
- package/dist/auth/events.d.ts +166 -0
- package/dist/auth/events.d.ts.map +1 -0
- package/dist/auth/first-proof.d.ts +43 -0
- package/dist/auth/first-proof.d.ts.map +1 -0
- package/dist/auth/hashers.d.ts +52 -0
- package/dist/auth/hashers.d.ts.map +1 -0
- package/dist/auth/index.d.ts +22 -0
- package/dist/auth/index.d.ts.map +1 -0
- package/dist/auth/invitations/accept.d.ts +10 -0
- package/dist/auth/invitations/accept.d.ts.map +1 -0
- package/dist/auth/invitations/change-pending.d.ts +17 -0
- package/dist/auth/invitations/change-pending.d.ts.map +1 -0
- package/dist/auth/invitations/claim.d.ts +31 -0
- package/dist/auth/invitations/claim.d.ts.map +1 -0
- package/dist/auth/invitations/events.d.ts +46 -0
- package/dist/auth/invitations/events.d.ts.map +1 -0
- package/dist/auth/invitations/find-invitee.d.ts +20 -0
- package/dist/auth/invitations/find-invitee.d.ts.map +1 -0
- package/dist/auth/invitations/find-pending.d.ts +5 -0
- package/dist/auth/invitations/find-pending.d.ts.map +1 -0
- package/dist/auth/invitations/flows.d.ts +7 -0
- package/dist/auth/invitations/flows.d.ts.map +1 -0
- package/dist/auth/invitations/history-input.d.ts +29 -0
- package/dist/auth/invitations/history-input.d.ts.map +1 -0
- package/dist/auth/invitations/history.d.ts +10 -0
- package/dist/auth/invitations/history.d.ts.map +1 -0
- package/dist/auth/invitations/index.d.ts +11 -0
- package/dist/auth/invitations/index.d.ts.map +1 -0
- package/dist/auth/invitations/input.d.ts +30 -0
- package/dist/auth/invitations/input.d.ts.map +1 -0
- package/dist/auth/invitations/invited-type.d.ts +22 -0
- package/dist/auth/invitations/invited-type.d.ts.map +1 -0
- package/dist/auth/invitations/invitee.d.ts +11 -0
- package/dist/auth/invitations/invitee.d.ts.map +1 -0
- package/dist/auth/invitations/issue.d.ts +9 -0
- package/dist/auth/invitations/issue.d.ts.map +1 -0
- package/dist/auth/invitations/limit.d.ts +7 -0
- package/dist/auth/invitations/limit.d.ts.map +1 -0
- package/dist/auth/invitations/password-invitee.d.ts +18 -0
- package/dist/auth/invitations/password-invitee.d.ts.map +1 -0
- package/dist/auth/invitations/passwordless-invitee.d.ts +13 -0
- package/dist/auth/invitations/passwordless-invitee.d.ts.map +1 -0
- package/dist/auth/invitations/preview.d.ts +8 -0
- package/dist/auth/invitations/preview.d.ts.map +1 -0
- package/dist/auth/invitations/read.d.ts +10 -0
- package/dist/auth/invitations/read.d.ts.map +1 -0
- package/dist/auth/invitations/resend.d.ts +12 -0
- package/dist/auth/invitations/resend.d.ts.map +1 -0
- package/dist/auth/invitations/to-invitation.d.ts +11 -0
- package/dist/auth/invitations/to-invitation.d.ts.map +1 -0
- package/dist/auth/invitations/write.d.ts +17 -0
- package/dist/auth/invitations/write.d.ts.map +1 -0
- package/dist/auth/issuers/cache.d.ts +21 -0
- package/dist/auth/issuers/cache.d.ts.map +1 -0
- package/dist/auth/issuers/create.d.ts +18 -0
- package/dist/auth/issuers/create.d.ts.map +1 -0
- package/dist/auth/issuers/index.d.ts +3 -0
- package/dist/auth/issuers/index.d.ts.map +1 -0
- package/dist/auth/issuers/types.d.ts +45 -0
- package/dist/auth/issuers/types.d.ts.map +1 -0
- package/dist/auth/janus.d.ts +39 -0
- package/dist/auth/janus.d.ts.map +1 -0
- package/dist/auth/magic-link.d.ts +25 -0
- package/dist/auth/magic-link.d.ts.map +1 -0
- package/dist/auth/mail-requests.d.ts +55 -0
- package/dist/auth/mail-requests.d.ts.map +1 -0
- package/dist/auth/one-time/codes.d.ts +46 -0
- package/dist/auth/one-time/codes.d.ts.map +1 -0
- package/dist/auth/one-time/index.d.ts +15 -0
- package/dist/auth/one-time/index.d.ts.map +1 -0
- package/dist/auth/one-time/issue.d.ts +45 -0
- package/dist/auth/one-time/issue.d.ts.map +1 -0
- package/dist/auth/one-time/refusals.d.ts +26 -0
- package/dist/auth/one-time/refusals.d.ts.map +1 -0
- package/dist/auth/one-time/spend.d.ts +24 -0
- package/dist/auth/one-time/spend.d.ts.map +1 -0
- package/dist/auth/one-time/window.d.ts +50 -0
- package/dist/auth/one-time/window.d.ts.map +1 -0
- package/dist/auth/outage.d.ts +66 -0
- package/dist/auth/outage.d.ts.map +1 -0
- package/dist/auth/parse-sealing-keys.d.ts +26 -0
- package/dist/auth/parse-sealing-keys.d.ts.map +1 -0
- package/dist/auth/passkeys/assert.d.ts +51 -0
- package/dist/auth/passkeys/assert.d.ts.map +1 -0
- package/dist/auth/passkeys/assertion-options.d.ts +9 -0
- package/dist/auth/passkeys/assertion-options.d.ts.map +1 -0
- package/dist/auth/passkeys/challenge.d.ts +19 -0
- package/dist/auth/passkeys/challenge.d.ts.map +1 -0
- package/dist/auth/passkeys/commit.d.ts +33 -0
- package/dist/auth/passkeys/commit.d.ts.map +1 -0
- package/dist/auth/passkeys/flows.d.ts +13 -0
- package/dist/auth/passkeys/flows.d.ts.map +1 -0
- package/dist/auth/passkeys/index.d.ts +12 -0
- package/dist/auth/passkeys/index.d.ts.map +1 -0
- package/dist/auth/passkeys/manage.d.ts +11 -0
- package/dist/auth/passkeys/manage.d.ts.map +1 -0
- package/dist/auth/passkeys/name.d.ts +4 -0
- package/dist/auth/passkeys/name.d.ts.map +1 -0
- package/dist/auth/passkeys/register.d.ts +20 -0
- package/dist/auth/passkeys/register.d.ts.map +1 -0
- package/dist/auth/passkeys/registration-options.d.ts +22 -0
- package/dist/auth/passkeys/registration-options.d.ts.map +1 -0
- package/dist/auth/passkeys/remove-all.d.ts +26 -0
- package/dist/auth/passkeys/remove-all.d.ts.map +1 -0
- package/dist/auth/passkeys/sign-in-options.d.ts +12 -0
- package/dist/auth/passkeys/sign-in-options.d.ts.map +1 -0
- package/dist/auth/passkeys/sign-in.d.ts +21 -0
- package/dist/auth/passkeys/sign-in.d.ts.map +1 -0
- package/dist/auth/passkeys/verifier.d.ts +113 -0
- package/dist/auth/passkeys/verifier.d.ts.map +1 -0
- package/dist/auth/passkeys/view.d.ts +5 -0
- package/dist/auth/passkeys/view.d.ts.map +1 -0
- package/dist/auth/passkeys/wiring.d.ts +24 -0
- package/dist/auth/passkeys/wiring.d.ts.map +1 -0
- package/dist/auth/password-written.d.ts +55 -0
- package/dist/auth/password-written.d.ts.map +1 -0
- package/dist/auth/port/assert-api-keys.d.ts +21 -0
- package/dist/auth/port/assert-api-keys.d.ts.map +1 -0
- package/dist/auth/port/assert-invitations.d.ts +15 -0
- package/dist/auth/port/assert-invitations.d.ts.map +1 -0
- package/dist/auth/port/assert-stores.d.ts +16 -0
- package/dist/auth/port/assert-stores.d.ts.map +1 -0
- package/dist/auth/port/memory/api-keys/capabilities.d.ts +8 -0
- package/dist/auth/port/memory/api-keys/capabilities.d.ts.map +1 -0
- package/dist/auth/port/memory/api-keys/index.d.ts +13 -0
- package/dist/auth/port/memory/api-keys/index.d.ts.map +1 -0
- package/dist/auth/port/memory/api-keys/pages.d.ts +7 -0
- package/dist/auth/port/memory/api-keys/pages.d.ts.map +1 -0
- package/dist/auth/port/memory/copy.d.ts +6 -0
- package/dist/auth/port/memory/copy.d.ts.map +1 -0
- package/dist/auth/port/memory/index.d.ts +10 -0
- package/dist/auth/port/memory/index.d.ts.map +1 -0
- package/dist/auth/port/memory/invitations-pending.d.ts +6 -0
- package/dist/auth/port/memory/invitations-pending.d.ts.map +1 -0
- package/dist/auth/port/memory/invitations.d.ts +12 -0
- package/dist/auth/port/memory/invitations.d.ts.map +1 -0
- package/dist/auth/port/memory/passkeys.d.ts +9 -0
- package/dist/auth/port/memory/passkeys.d.ts.map +1 -0
- package/dist/auth/port/memory/sessions.d.ts +4 -0
- package/dist/auth/port/memory/sessions.d.ts.map +1 -0
- package/dist/auth/port/memory/social-links.d.ts +10 -0
- package/dist/auth/port/memory/social-links.d.ts.map +1 -0
- package/dist/auth/port/memory/stores.d.ts +26 -0
- package/dist/auth/port/memory/stores.d.ts.map +1 -0
- package/dist/auth/port/memory/tokens.d.ts +4 -0
- package/dist/auth/port/memory/tokens.d.ts.map +1 -0
- package/dist/auth/port/memory/user-index.d.ts +20 -0
- package/dist/auth/port/memory/user-index.d.ts.map +1 -0
- package/dist/auth/port/memory/user-update.d.ts +10 -0
- package/dist/auth/port/memory/user-update.d.ts.map +1 -0
- package/dist/auth/port/memory/users.d.ts +4 -0
- package/dist/auth/port/memory/users.d.ts.map +1 -0
- package/dist/auth/port/types/api-keys.d.ts +199 -0
- package/dist/auth/port/types/api-keys.d.ts.map +1 -0
- package/dist/auth/port/types/credentials.d.ts +46 -0
- package/dist/auth/port/types/credentials.d.ts.map +1 -0
- package/dist/auth/port/types/index.d.ts +75 -0
- package/dist/auth/port/types/index.d.ts.map +1 -0
- package/dist/auth/port/types/invitations/index.d.ts +15 -0
- package/dist/auth/port/types/invitations/index.d.ts.map +1 -0
- package/dist/auth/port/types/invitations/page.d.ts +52 -0
- package/dist/auth/port/types/invitations/page.d.ts.map +1 -0
- package/dist/auth/port/types/invitations/records.d.ts +101 -0
- package/dist/auth/port/types/invitations/records.d.ts.map +1 -0
- package/dist/auth/port/types/invitations/store.d.ts +82 -0
- package/dist/auth/port/types/invitations/store.d.ts.map +1 -0
- package/dist/auth/port/types/json.d.ts +27 -0
- package/dist/auth/port/types/json.d.ts.map +1 -0
- package/dist/auth/port/types/passkeys.d.ts +94 -0
- package/dist/auth/port/types/passkeys.d.ts.map +1 -0
- package/dist/auth/port/types/sessions.d.ts +142 -0
- package/dist/auth/port/types/sessions.d.ts.map +1 -0
- package/dist/auth/port/types/social-links.d.ts +72 -0
- package/dist/auth/port/types/social-links.d.ts.map +1 -0
- package/dist/auth/port/types/stores.d.ts +48 -0
- package/dist/auth/port/types/stores.d.ts.map +1 -0
- package/dist/auth/port/types/tokens.d.ts +168 -0
- package/dist/auth/port/types/tokens.d.ts.map +1 -0
- package/dist/auth/port/types/users.d.ts +260 -0
- package/dist/auth/port/types/users.d.ts.map +1 -0
- package/dist/auth/prepared.d.ts +21 -0
- package/dist/auth/prepared.d.ts.map +1 -0
- package/dist/auth/proven-sign-in.d.ts +22 -0
- package/dist/auth/proven-sign-in.d.ts.map +1 -0
- package/dist/auth/sealer-for.d.ts +44 -0
- package/dist/auth/sealer-for.d.ts.map +1 -0
- package/dist/auth/sealing.d.ts +36 -0
- package/dist/auth/sealing.d.ts.map +1 -0
- package/dist/auth/second-factor/activate.d.ts +9 -0
- package/dist/auth/second-factor/activate.d.ts.map +1 -0
- package/dist/auth/second-factor/app-code-attempts.d.ts +47 -0
- package/dist/auth/second-factor/app-code-attempts.d.ts.map +1 -0
- package/dist/auth/second-factor/challenge.d.ts +15 -0
- package/dist/auth/second-factor/challenge.d.ts.map +1 -0
- package/dist/auth/second-factor/codes-left.d.ts +14 -0
- package/dist/auth/second-factor/codes-left.d.ts.map +1 -0
- package/dist/auth/second-factor/disable.d.ts +10 -0
- package/dist/auth/second-factor/disable.d.ts.map +1 -0
- package/dist/auth/second-factor/enroll.d.ts +6 -0
- package/dist/auth/second-factor/enroll.d.ts.map +1 -0
- package/dist/auth/second-factor/factor.d.ts +33 -0
- package/dist/auth/second-factor/factor.d.ts.map +1 -0
- package/dist/auth/second-factor/flows.d.ts +36 -0
- package/dist/auth/second-factor/flows.d.ts.map +1 -0
- package/dist/auth/second-factor/lifecycle.d.ts +14 -0
- package/dist/auth/second-factor/lifecycle.d.ts.map +1 -0
- package/dist/auth/second-factor/passkey-confirm.d.ts +21 -0
- package/dist/auth/second-factor/passkey-confirm.d.ts.map +1 -0
- package/dist/auth/second-factor/recovery-codes.d.ts +36 -0
- package/dist/auth/second-factor/recovery-codes.d.ts.map +1 -0
- package/dist/auth/second-factor/recovery.d.ts +20 -0
- package/dist/auth/second-factor/recovery.d.ts.map +1 -0
- package/dist/auth/second-factor/redeem.d.ts +42 -0
- package/dist/auth/second-factor/redeem.d.ts.map +1 -0
- package/dist/auth/second-factor/refusal.d.ts +6 -0
- package/dist/auth/second-factor/refusal.d.ts.map +1 -0
- package/dist/auth/second-factor/regenerate.d.ts +12 -0
- package/dist/auth/second-factor/regenerate.d.ts.map +1 -0
- package/dist/auth/second-factor/reseal.d.ts +17 -0
- package/dist/auth/second-factor/reseal.d.ts.map +1 -0
- package/dist/auth/second-factor/spend-recovery-code.d.ts +15 -0
- package/dist/auth/second-factor/spend-recovery-code.d.ts.map +1 -0
- package/dist/auth/secrets.d.ts +17 -0
- package/dist/auth/secrets.d.ts.map +1 -0
- package/dist/auth/sessions/amr.d.ts +36 -0
- package/dist/auth/sessions/amr.d.ts.map +1 -0
- package/dist/auth/sessions/authenticate.d.ts +12 -0
- package/dist/auth/sessions/authenticate.d.ts.map +1 -0
- package/dist/auth/sessions/collect-expired.d.ts +15 -0
- package/dist/auth/sessions/collect-expired.d.ts.map +1 -0
- package/dist/auth/sessions/cookie.d.ts +9 -0
- package/dist/auth/sessions/cookie.d.ts.map +1 -0
- package/dist/auth/sessions/fresh.d.ts +35 -0
- package/dist/auth/sessions/fresh.d.ts.map +1 -0
- package/dist/auth/sessions/index.d.ts +12 -0
- package/dist/auth/sessions/index.d.ts.map +1 -0
- package/dist/auth/sessions/open-session.d.ts +22 -0
- package/dist/auth/sessions/open-session.d.ts.map +1 -0
- package/dist/auth/sessions/presented-token.d.ts +25 -0
- package/dist/auth/sessions/presented-token.d.ts.map +1 -0
- package/dist/auth/sessions/shared-api.d.ts +17 -0
- package/dist/auth/sessions/shared-api.d.ts.map +1 -0
- package/dist/auth/sessions/standing.d.ts +32 -0
- package/dist/auth/sessions/standing.d.ts.map +1 -0
- package/dist/auth/shared-api.d.ts +142 -0
- package/dist/auth/shared-api.d.ts.map +1 -0
- package/dist/auth/sign-in-attempts.d.ts +45 -0
- package/dist/auth/sign-in-attempts.d.ts.map +1 -0
- package/dist/auth/sign-in-code.d.ts +26 -0
- package/dist/auth/sign-in-code.d.ts.map +1 -0
- package/dist/auth/social/attach.d.ts +31 -0
- package/dist/auth/social/attach.d.ts.map +1 -0
- package/dist/auth/social/begin.d.ts +30 -0
- package/dist/auth/social/begin.d.ts.map +1 -0
- package/dist/auth/social/complete-link.d.ts +17 -0
- package/dist/auth/social/complete-link.d.ts.map +1 -0
- package/dist/auth/social/complete.d.ts +54 -0
- package/dist/auth/social/complete.d.ts.map +1 -0
- package/dist/auth/social/cookie.d.ts +16 -0
- package/dist/auth/social/cookie.d.ts.map +1 -0
- package/dist/auth/social/find-provider.d.ts +23 -0
- package/dist/auth/social/find-provider.d.ts.map +1 -0
- package/dist/auth/social/finish.d.ts +60 -0
- package/dist/auth/social/finish.d.ts.map +1 -0
- package/dist/auth/social/flow-cookie-value.d.ts +26 -0
- package/dist/auth/social/flow-cookie-value.d.ts.map +1 -0
- package/dist/auth/social/flow-secret.d.ts +40 -0
- package/dist/auth/social/flow-secret.d.ts.map +1 -0
- package/dist/auth/social/index.d.ts +19 -0
- package/dist/auth/social/index.d.ts.map +1 -0
- package/dist/auth/social/link-holder.d.ts +33 -0
- package/dist/auth/social/link-holder.d.ts.map +1 -0
- package/dist/auth/social/provider-call.d.ts +31 -0
- package/dist/auth/social/provider-call.d.ts.map +1 -0
- package/dist/auth/social/redeem.d.ts +45 -0
- package/dist/auth/social/redeem.d.ts.map +1 -0
- package/dist/auth/social/return-to.d.ts +18 -0
- package/dist/auth/social/return-to.d.ts.map +1 -0
- package/dist/auth/social/sign-in.d.ts +41 -0
- package/dist/auth/social/sign-in.d.ts.map +1 -0
- package/dist/auth/social/sign-up.d.ts +37 -0
- package/dist/auth/social/sign-up.d.ts.map +1 -0
- package/dist/auth/social/start.d.ts +21 -0
- package/dist/auth/social/start.d.ts.map +1 -0
- package/dist/auth/social/step-up-proof.d.ts +26 -0
- package/dist/auth/social/step-up-proof.d.ts.map +1 -0
- package/dist/auth/social/step-up-request.d.ts +28 -0
- package/dist/auth/social/step-up-request.d.ts.map +1 -0
- package/dist/auth/social/step-up.d.ts +19 -0
- package/dist/auth/social/step-up.d.ts.map +1 -0
- package/dist/auth/social/types-of.d.ts +12 -0
- package/dist/auth/social/types-of.d.ts.map +1 -0
- package/dist/auth/social/unlink.d.ts +23 -0
- package/dist/auth/social/unlink.d.ts.map +1 -0
- package/dist/auth/social/wiring.d.ts +10 -0
- package/dist/auth/social/wiring.d.ts.map +1 -0
- package/dist/auth/standard-schema.d.ts +41 -0
- package/dist/auth/standard-schema.d.ts.map +1 -0
- package/dist/auth/step-up/codes.d.ts +35 -0
- package/dist/auth/step-up/codes.d.ts.map +1 -0
- package/dist/auth/step-up/flows.d.ts +18 -0
- package/dist/auth/step-up/flows.d.ts.map +1 -0
- package/dist/auth/step-up/open.d.ts +23 -0
- package/dist/auth/step-up/open.d.ts.map +1 -0
- package/dist/auth/step-up/passkey.d.ts +31 -0
- package/dist/auth/step-up/passkey.d.ts.map +1 -0
- package/dist/auth/step-up/request.d.ts +15 -0
- package/dist/auth/step-up/request.d.ts.map +1 -0
- package/dist/auth/step-up/spend.d.ts +4 -0
- package/dist/auth/step-up/spend.d.ts.map +1 -0
- package/dist/auth/totp.d.ts +36 -0
- package/dist/auth/totp.d.ts.map +1 -0
- package/dist/auth/types/api-keys-of.d.ts +19 -0
- package/dist/auth/types/api-keys-of.d.ts.map +1 -0
- package/dist/auth/types/api-keys.d.ts +164 -0
- package/dist/auth/types/api-keys.d.ts.map +1 -0
- package/dist/auth/types/avatar.d.ts +72 -0
- package/dist/auth/types/avatar.d.ts.map +1 -0
- package/dist/auth/types/change-email.d.ts +82 -0
- package/dist/auth/types/change-email.d.ts.map +1 -0
- package/dist/auth/types/checks.d.ts +147 -0
- package/dist/auth/types/checks.d.ts.map +1 -0
- package/dist/auth/types/email-flows.d.ts +117 -0
- package/dist/auth/types/email-flows.d.ts.map +1 -0
- package/dist/auth/types/find-by-email.d.ts +31 -0
- package/dist/auth/types/find-by-email.d.ts.map +1 -0
- package/dist/auth/types/find-or-create.d.ts +59 -0
- package/dist/auth/types/find-or-create.d.ts.map +1 -0
- package/dist/auth/types/index.d.ts +38 -0
- package/dist/auth/types/index.d.ts.map +1 -0
- package/dist/auth/types/inference.d.ts +62 -0
- package/dist/auth/types/inference.d.ts.map +1 -0
- package/dist/auth/types/invitations/api.d.ts +203 -0
- package/dist/auth/types/invitations/api.d.ts.map +1 -0
- package/dist/auth/types/invitations/history.d.ts +87 -0
- package/dist/auth/types/invitations/history.d.ts.map +1 -0
- package/dist/auth/types/invitations/index.d.ts +10 -0
- package/dist/auth/types/invitations/index.d.ts.map +1 -0
- package/dist/auth/types/invitations/invitation.d.ts +76 -0
- package/dist/auth/types/invitations/invitation.d.ts.map +1 -0
- package/dist/auth/types/invitations/issue-type.d.ts +15 -0
- package/dist/auth/types/invitations/issue-type.d.ts.map +1 -0
- package/dist/auth/types/invitations-of.d.ts +26 -0
- package/dist/auth/types/invitations-of.d.ts.map +1 -0
- package/dist/auth/types/janus.d.ts +51 -0
- package/dist/auth/types/janus.d.ts.map +1 -0
- package/dist/auth/types/magic-link.d.ts +69 -0
- package/dist/auth/types/magic-link.d.ts.map +1 -0
- package/dist/auth/types/passkeys.d.ts +183 -0
- package/dist/auth/types/passkeys.d.ts.map +1 -0
- package/dist/auth/types/password.d.ts +113 -0
- package/dist/auth/types/password.d.ts.map +1 -0
- package/dist/auth/types/prepared.d.ts +68 -0
- package/dist/auth/types/prepared.d.ts.map +1 -0
- package/dist/auth/types/proven-sign-in.d.ts +43 -0
- package/dist/auth/types/proven-sign-in.d.ts.map +1 -0
- package/dist/auth/types/reset-password.d.ts +46 -0
- package/dist/auth/types/reset-password.d.ts.map +1 -0
- package/dist/auth/types/second-factor.d.ts +164 -0
- package/dist/auth/types/second-factor.d.ts.map +1 -0
- package/dist/auth/types/session.d.ts +68 -0
- package/dist/auth/types/session.d.ts.map +1 -0
- package/dist/auth/types/shared-api.d.ts +96 -0
- package/dist/auth/types/shared-api.d.ts.map +1 -0
- package/dist/auth/types/sign-in.d.ts +102 -0
- package/dist/auth/types/sign-in.d.ts.map +1 -0
- package/dist/auth/types/social-flow.d.ts +28 -0
- package/dist/auth/types/social-flow.d.ts.map +1 -0
- package/dist/auth/types/social-step-up.d.ts +38 -0
- package/dist/auth/types/social-step-up.d.ts.map +1 -0
- package/dist/auth/types/social.d.ts +201 -0
- package/dist/auth/types/social.d.ts.map +1 -0
- package/dist/auth/types/step-up.d.ts +133 -0
- package/dist/auth/types/step-up.d.ts.map +1 -0
- package/dist/auth/types/type-api.d.ts +29 -0
- package/dist/auth/types/type-api.d.ts.map +1 -0
- package/dist/auth/types/user-type.d.ts +106 -0
- package/dist/auth/types/user-type.d.ts.map +1 -0
- package/dist/auth/types/user.d.ts +62 -0
- package/dist/auth/types/user.d.ts.map +1 -0
- package/dist/auth/types/verify-email.d.ts +190 -0
- package/dist/auth/types/verify-email.d.ts.map +1 -0
- package/dist/auth/users/any-type-api.d.ts +6 -0
- package/dist/auth/users/any-type-api.d.ts.map +1 -0
- package/dist/auth/users/by-login.d.ts +10 -0
- package/dist/auth/users/by-login.d.ts.map +1 -0
- package/dist/auth/users/change-password.d.ts +26 -0
- package/dist/auth/users/change-password.d.ts.map +1 -0
- package/dist/auth/users/delete.d.ts +10 -0
- package/dist/auth/users/delete.d.ts.map +1 -0
- package/dist/auth/users/email-move-guard.d.ts +20 -0
- package/dist/auth/users/email-move-guard.d.ts.map +1 -0
- package/dist/auth/users/email-prefix.d.ts +23 -0
- package/dist/auth/users/email-prefix.d.ts.map +1 -0
- package/dist/auth/users/fields-patch.d.ts +21 -0
- package/dist/auth/users/fields-patch.d.ts.map +1 -0
- package/dist/auth/users/find-by-email.d.ts +11 -0
- package/dist/auth/users/find-by-email.d.ts.map +1 -0
- package/dist/auth/users/find-many.d.ts +29 -0
- package/dist/auth/users/find-many.d.ts.map +1 -0
- package/dist/auth/users/find-or-create.d.ts +12 -0
- package/dist/auth/users/find-or-create.d.ts.map +1 -0
- package/dist/auth/users/flow-types.d.ts +15 -0
- package/dist/auth/users/flow-types.d.ts.map +1 -0
- package/dist/auth/users/index.d.ts +9 -0
- package/dist/auth/users/index.d.ts.map +1 -0
- package/dist/auth/users/insert.d.ts +15 -0
- package/dist/auth/users/insert.d.ts.map +1 -0
- package/dist/auth/users/name-prefix.d.ts +19 -0
- package/dist/auth/users/name-prefix.d.ts.map +1 -0
- package/dist/auth/users/password-flows.d.ts +11 -0
- package/dist/auth/users/password-flows.d.ts.map +1 -0
- package/dist/auth/users/record-flows.d.ts +11 -0
- package/dist/auth/users/record-flows.d.ts.map +1 -0
- package/dist/auth/users/sign-in.d.ts +24 -0
- package/dist/auth/users/sign-in.d.ts.map +1 -0
- package/dist/auth/users/sign-up.d.ts +13 -0
- package/dist/auth/users/sign-up.d.ts.map +1 -0
- package/dist/auth/users/type-api.d.ts +10 -0
- package/dist/auth/users/type-api.d.ts.map +1 -0
- package/dist/auth/users/update.d.ts +16 -0
- package/dist/auth/users/update.d.ts.map +1 -0
- package/dist/background/background.d.ts +22 -0
- package/dist/background/background.d.ts.map +1 -0
- package/dist/chunks/index-2ttdcz7n.js +354 -0
- package/dist/chunks/index-2ttdcz7n.js.map +16 -0
- package/dist/chunks/index-5dxynm32.js +85 -0
- package/dist/chunks/index-5dxynm32.js.map +10 -0
- package/dist/chunks/index-7h34nqrm.js +732 -0
- package/dist/chunks/index-7h34nqrm.js.map +24 -0
- package/dist/chunks/index-ftz0ne6j.js +127 -0
- package/dist/chunks/index-ftz0ne6j.js.map +11 -0
- package/dist/chunks/index-n8jxmxeg.js +64 -0
- package/dist/chunks/index-n8jxmxeg.js.map +11 -0
- package/dist/conformance/api-keys/cases/bound.d.ts +3 -0
- package/dist/conformance/api-keys/cases/bound.d.ts.map +1 -0
- package/dist/conformance/api-keys/cases/expiry.d.ts +3 -0
- package/dist/conformance/api-keys/cases/expiry.d.ts.map +1 -0
- package/dist/conformance/api-keys/cases/index.d.ts +4 -0
- package/dist/conformance/api-keys/cases/index.d.ts.map +1 -0
- package/dist/conformance/api-keys/cases/insert.d.ts +3 -0
- package/dist/conformance/api-keys/cases/insert.d.ts.map +1 -0
- package/dist/conformance/api-keys/cases/outage.d.ts +3 -0
- package/dist/conformance/api-keys/cases/outage.d.ts.map +1 -0
- package/dist/conformance/api-keys/cases/revoke.d.ts +3 -0
- package/dist/conformance/api-keys/cases/revoke.d.ts.map +1 -0
- package/dist/conformance/api-keys/cases/touch.d.ts +3 -0
- package/dist/conformance/api-keys/cases/touch.d.ts.map +1 -0
- package/dist/conformance/api-keys/cases/user-bound.d.ts +3 -0
- package/dist/conformance/api-keys/cases/user-bound.d.ts.map +1 -0
- package/dist/conformance/api-keys/describe.d.ts +20 -0
- package/dist/conformance/api-keys/describe.d.ts.map +1 -0
- package/dist/conformance/api-keys/fixtures.d.ts +4 -0
- package/dist/conformance/api-keys/fixtures.d.ts.map +1 -0
- package/dist/conformance/api-keys/index.d.ts +18 -0
- package/dist/conformance/api-keys/index.d.ts.map +1 -0
- package/dist/conformance/api-keys/reference.d.ts +4 -0
- package/dist/conformance/api-keys/reference.d.ts.map +1 -0
- package/dist/conformance/api-keys/types.d.ts +42 -0
- package/dist/conformance/api-keys/types.d.ts.map +1 -0
- package/dist/conformance/assert.d.ts +40 -0
- package/dist/conformance/assert.d.ts.map +1 -0
- package/dist/conformance/cases/outage.d.ts +3 -0
- package/dist/conformance/cases/outage.d.ts.map +1 -0
- package/dist/conformance/cases/outage.passkeys.d.ts +12 -0
- package/dist/conformance/cases/outage.passkeys.d.ts.map +1 -0
- package/dist/conformance/cases/passkeys/deletion.d.ts +4 -0
- package/dist/conformance/cases/passkeys/deletion.d.ts.map +1 -0
- package/dist/conformance/cases/passkeys/index.d.ts +8 -0
- package/dist/conformance/cases/passkeys/index.d.ts.map +1 -0
- package/dist/conformance/cases/passkeys/inserts.d.ts +4 -0
- package/dist/conformance/cases/passkeys/inserts.d.ts.map +1 -0
- package/dist/conformance/cases/passkeys/reads.d.ts +4 -0
- package/dist/conformance/cases/passkeys/reads.d.ts.map +1 -0
- package/dist/conformance/cases/passkeys/uses.d.ts +4 -0
- package/dist/conformance/cases/passkeys/uses.d.ts.map +1 -0
- package/dist/conformance/cases/sessions/deletion.d.ts +4 -0
- package/dist/conformance/cases/sessions/deletion.d.ts.map +1 -0
- package/dist/conformance/cases/sessions/extension.d.ts +4 -0
- package/dist/conformance/cases/sessions/extension.d.ts.map +1 -0
- package/dist/conformance/cases/sessions/index.d.ts +4 -0
- package/dist/conformance/cases/sessions/index.d.ts.map +1 -0
- package/dist/conformance/cases/sessions/inserts.d.ts +4 -0
- package/dist/conformance/cases/sessions/inserts.d.ts.map +1 -0
- package/dist/conformance/cases/sessions/list.d.ts +4 -0
- package/dist/conformance/cases/sessions/list.d.ts.map +1 -0
- package/dist/conformance/cases/sessions/reads.d.ts +4 -0
- package/dist/conformance/cases/sessions/reads.d.ts.map +1 -0
- package/dist/conformance/cases/sessions/reauthentication.d.ts +4 -0
- package/dist/conformance/cases/sessions/reauthentication.d.ts.map +1 -0
- package/dist/conformance/cases/sessions/revocation.d.ts +4 -0
- package/dist/conformance/cases/sessions/revocation.d.ts.map +1 -0
- package/dist/conformance/cases/social-links/deletion.d.ts +4 -0
- package/dist/conformance/cases/social-links/deletion.d.ts.map +1 -0
- package/dist/conformance/cases/social-links/index.d.ts +8 -0
- package/dist/conformance/cases/social-links/index.d.ts.map +1 -0
- package/dist/conformance/cases/social-links/inserts.d.ts +4 -0
- package/dist/conformance/cases/social-links/inserts.d.ts.map +1 -0
- package/dist/conformance/cases/social-links/reads.d.ts +4 -0
- package/dist/conformance/cases/social-links/reads.d.ts.map +1 -0
- package/dist/conformance/cases/tokens/attempts.d.ts +7 -0
- package/dist/conformance/cases/tokens/attempts.d.ts.map +1 -0
- package/dist/conformance/cases/tokens/change-email.d.ts +8 -0
- package/dist/conformance/cases/tokens/change-email.d.ts.map +1 -0
- package/dist/conformance/cases/tokens/deletion.d.ts +4 -0
- package/dist/conformance/cases/tokens/deletion.d.ts.map +1 -0
- package/dist/conformance/cases/tokens/index.d.ts +4 -0
- package/dist/conformance/cases/tokens/index.d.ts.map +1 -0
- package/dist/conformance/cases/tokens/inserts.d.ts +7 -0
- package/dist/conformance/cases/tokens/inserts.d.ts.map +1 -0
- package/dist/conformance/cases/tokens/kinds.d.ts +7 -0
- package/dist/conformance/cases/tokens/kinds.d.ts.map +1 -0
- package/dist/conformance/cases/tokens/redemption.d.ts +7 -0
- package/dist/conformance/cases/tokens/redemption.d.ts.map +1 -0
- package/dist/conformance/cases/tokens/social-flow.d.ts +8 -0
- package/dist/conformance/cases/tokens/social-flow.d.ts.map +1 -0
- package/dist/conformance/cases/tokens/spending.d.ts +7 -0
- package/dist/conformance/cases/tokens/spending.d.ts.map +1 -0
- package/dist/conformance/cases/users/avatar.d.ts +8 -0
- package/dist/conformance/cases/users/avatar.d.ts.map +1 -0
- package/dist/conformance/cases/users/batch.d.ts +8 -0
- package/dist/conformance/cases/users/batch.d.ts.map +1 -0
- package/dist/conformance/cases/users/deletion.d.ts +4 -0
- package/dist/conformance/cases/users/deletion.d.ts.map +1 -0
- package/dist/conformance/cases/users/index.d.ts +4 -0
- package/dist/conformance/cases/users/index.d.ts.map +1 -0
- package/dist/conformance/cases/users/inserts.d.ts +4 -0
- package/dist/conformance/cases/users/inserts.d.ts.map +1 -0
- package/dist/conformance/cases/users/listing.d.ts +4 -0
- package/dist/conformance/cases/users/listing.d.ts.map +1 -0
- package/dist/conformance/cases/users/patches.d.ts +7 -0
- package/dist/conformance/cases/users/patches.d.ts.map +1 -0
- package/dist/conformance/cases/users/reads.d.ts +7 -0
- package/dist/conformance/cases/users/reads.d.ts.map +1 -0
- package/dist/conformance/cases/users/second-factor.d.ts +16 -0
- package/dist/conformance/cases/users/second-factor.d.ts.map +1 -0
- package/dist/conformance/cases/users/versions.d.ts +7 -0
- package/dist/conformance/cases/users/versions.d.ts.map +1 -0
- package/dist/conformance/describe.d.ts +82 -0
- package/dist/conformance/describe.d.ts.map +1 -0
- package/dist/conformance/fixtures.d.ts +31 -0
- package/dist/conformance/fixtures.d.ts.map +1 -0
- package/dist/conformance/index.d.ts +46 -0
- package/dist/conformance/index.d.ts.map +1 -0
- package/dist/conformance/index.js +4442 -0
- package/dist/conformance/index.js.map +86 -0
- package/dist/conformance/invitations/cases/actors.d.ts +3 -0
- package/dist/conformance/invitations/cases/actors.d.ts.map +1 -0
- package/dist/conformance/invitations/cases/find-pending.d.ts +3 -0
- package/dist/conformance/invitations/cases/find-pending.d.ts.map +1 -0
- package/dist/conformance/invitations/cases/imported.d.ts +3 -0
- package/dist/conformance/invitations/cases/imported.d.ts.map +1 -0
- package/dist/conformance/invitations/cases/index.d.ts +4 -0
- package/dist/conformance/invitations/cases/index.d.ts.map +1 -0
- package/dist/conformance/invitations/cases/insert.d.ts +3 -0
- package/dist/conformance/invitations/cases/insert.d.ts.map +1 -0
- package/dist/conformance/invitations/cases/list-lapsed.d.ts +3 -0
- package/dist/conformance/invitations/cases/list-lapsed.d.ts.map +1 -0
- package/dist/conformance/invitations/cases/list-status.d.ts +3 -0
- package/dist/conformance/invitations/cases/list-status.d.ts.map +1 -0
- package/dist/conformance/invitations/cases/list.d.ts +3 -0
- package/dist/conformance/invitations/cases/list.d.ts.map +1 -0
- package/dist/conformance/invitations/cases/outage.d.ts +3 -0
- package/dist/conformance/invitations/cases/outage.d.ts.map +1 -0
- package/dist/conformance/invitations/cases/scope.d.ts +3 -0
- package/dist/conformance/invitations/cases/scope.d.ts.map +1 -0
- package/dist/conformance/invitations/cases/update.d.ts +3 -0
- package/dist/conformance/invitations/cases/update.d.ts.map +1 -0
- package/dist/conformance/invitations/describe.d.ts +20 -0
- package/dist/conformance/invitations/describe.d.ts.map +1 -0
- package/dist/conformance/invitations/fixtures.d.ts +4 -0
- package/dist/conformance/invitations/fixtures.d.ts.map +1 -0
- package/dist/conformance/invitations/index.d.ts +18 -0
- package/dist/conformance/invitations/index.d.ts.map +1 -0
- package/dist/conformance/invitations/reference.d.ts +4 -0
- package/dist/conformance/invitations/reference.d.ts.map +1 -0
- package/dist/conformance/invitations/types.d.ts +34 -0
- package/dist/conformance/invitations/types.d.ts.map +1 -0
- package/dist/conformance/reference.d.ts +13 -0
- package/dist/conformance/reference.d.ts.map +1 -0
- package/dist/conformance/relations/cases/deletion.d.ts +4 -0
- package/dist/conformance/relations/cases/deletion.d.ts.map +1 -0
- package/dist/conformance/relations/cases/holders.d.ts +9 -0
- package/dist/conformance/relations/cases/holders.d.ts.map +1 -0
- package/dist/conformance/relations/cases/index.d.ts +4 -0
- package/dist/conformance/relations/cases/index.d.ts.map +1 -0
- package/dist/conformance/relations/cases/outage.d.ts +3 -0
- package/dist/conformance/relations/cases/outage.d.ts.map +1 -0
- package/dist/conformance/relations/cases/reads.d.ts +8 -0
- package/dist/conformance/relations/cases/reads.d.ts.map +1 -0
- package/dist/conformance/relations/cases/traversal.d.ts +7 -0
- package/dist/conformance/relations/cases/traversal.d.ts.map +1 -0
- package/dist/conformance/relations/cases/writes.d.ts +4 -0
- package/dist/conformance/relations/cases/writes.d.ts.map +1 -0
- package/dist/conformance/relations/describe.d.ts +20 -0
- package/dist/conformance/relations/describe.d.ts.map +1 -0
- package/dist/conformance/relations/fixtures.d.ts +8 -0
- package/dist/conformance/relations/fixtures.d.ts.map +1 -0
- package/dist/conformance/relations/index.d.ts +18 -0
- package/dist/conformance/relations/index.d.ts.map +1 -0
- package/dist/conformance/relations/reference.d.ts +4 -0
- package/dist/conformance/relations/reference.d.ts.map +1 -0
- package/dist/conformance/relations/types.d.ts +34 -0
- package/dist/conformance/relations/types.d.ts.map +1 -0
- package/dist/conformance/types.d.ts +79 -0
- package/dist/conformance/types.d.ts.map +1 -0
- package/dist/errors/janus-error/base.d.ts +47 -0
- package/dist/errors/janus-error/base.d.ts.map +1 -0
- package/dist/errors/janus-error/codes.credentials.d.ts +36 -0
- package/dist/errors/janus-error/codes.credentials.d.ts.map +1 -0
- package/dist/errors/janus-error/codes.d.ts +23 -0
- package/dist/errors/janus-error/codes.d.ts.map +1 -0
- package/dist/errors/janus-error/codes.invitations.d.ts +52 -0
- package/dist/errors/janus-error/codes.invitations.d.ts.map +1 -0
- package/dist/errors/janus-error/codes.one-time.d.ts +63 -0
- package/dist/errors/janus-error/codes.one-time.d.ts.map +1 -0
- package/dist/errors/janus-error/codes.records.d.ts +86 -0
- package/dist/errors/janus-error/codes.records.d.ts.map +1 -0
- package/dist/errors/janus-error/codes.social.d.ts +88 -0
- package/dist/errors/janus-error/codes.social.d.ts.map +1 -0
- package/dist/errors/janus-error/index.d.ts +17 -0
- package/dist/errors/janus-error/index.d.ts.map +1 -0
- package/dist/errors/janus-error/options.d.ts +105 -0
- package/dist/errors/janus-error/options.d.ts.map +1 -0
- package/dist/errors/janus-error/refusals.d.ts +151 -0
- package/dist/errors/janus-error/refusals.d.ts.map +1 -0
- package/dist/errors/janus-error/status.d.ts +21 -0
- package/dist/errors/janus-error/status.d.ts.map +1 -0
- package/dist/errors/janus-error/store.d.ts +36 -0
- package/dist/errors/janus-error/store.d.ts.map +1 -0
- package/dist/ids/derived.d.ts +25 -0
- package/dist/ids/derived.d.ts.map +1 -0
- package/dist/ids/id.d.ts +55 -0
- package/dist/ids/id.d.ts.map +1 -0
- package/dist/index.d.ts +32 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +6948 -0
- package/dist/index.js.map +208 -0
- package/dist/pagination/cursor-page.d.ts +53 -0
- package/dist/pagination/cursor-page.d.ts.map +1 -0
- package/dist/permissions/bound-model.d.ts +10 -0
- package/dist/permissions/bound-model.d.ts.map +1 -0
- package/dist/permissions/can.d.ts +13 -0
- package/dist/permissions/can.d.ts.map +1 -0
- package/dist/permissions/engine.d.ts +49 -0
- package/dist/permissions/engine.d.ts.map +1 -0
- package/dist/permissions/holders.d.ts +12 -0
- package/dist/permissions/holders.d.ts.map +1 -0
- package/dist/permissions/index.d.ts +36 -0
- package/dist/permissions/index.d.ts.map +1 -0
- package/dist/permissions/index.js +924 -0
- package/dist/permissions/index.js.map +28 -0
- package/dist/permissions/input.d.ts +43 -0
- package/dist/permissions/input.d.ts.map +1 -0
- package/dist/permissions/list.d.ts +16 -0
- package/dist/permissions/list.d.ts.map +1 -0
- package/dist/permissions/model/can.d.ts +41 -0
- package/dist/permissions/model/can.d.ts.map +1 -0
- package/dist/permissions/model/config.d.ts +36 -0
- package/dist/permissions/model/config.d.ts.map +1 -0
- package/dist/permissions/model/constraint.d.ts +37 -0
- package/dist/permissions/model/constraint.d.ts.map +1 -0
- package/dist/permissions/model/ctx.d.ts +23 -0
- package/dist/permissions/model/ctx.d.ts.map +1 -0
- package/dist/permissions/model/define.d.ts +78 -0
- package/dist/permissions/model/define.d.ts.map +1 -0
- package/dist/permissions/model/from-field.d.ts +31 -0
- package/dist/permissions/model/from-field.d.ts.map +1 -0
- package/dist/permissions/model/grant.d.ts +81 -0
- package/dist/permissions/model/grant.d.ts.map +1 -0
- package/dist/permissions/model/list.d.ts +48 -0
- package/dist/permissions/model/list.d.ts.map +1 -0
- package/dist/permissions/model/names.d.ts +51 -0
- package/dist/permissions/model/names.d.ts.map +1 -0
- package/dist/permissions/model/permissions.d.ts +48 -0
- package/dist/permissions/model/permissions.d.ts.map +1 -0
- package/dist/permissions/model/refs.d.ts +36 -0
- package/dist/permissions/model/refs.d.ts.map +1 -0
- package/dist/permissions/model/refusal.d.ts +13 -0
- package/dist/permissions/model/refusal.d.ts.map +1 -0
- package/dist/permissions/model/unions.d.ts +3 -0
- package/dist/permissions/model/unions.d.ts.map +1 -0
- package/dist/permissions/model/when.d.ts +16 -0
- package/dist/permissions/model/when.d.ts.map +1 -0
- package/dist/permissions/port/holders.d.ts +38 -0
- package/dist/permissions/port/holders.d.ts.map +1 -0
- package/dist/permissions/port/memory.d.ts +17 -0
- package/dist/permissions/port/memory.d.ts.map +1 -0
- package/dist/permissions/port/types.d.ts +101 -0
- package/dist/permissions/port/types.d.ts.map +1 -0
- package/dist/permissions/replace.d.ts +25 -0
- package/dist/permissions/replace.d.ts.map +1 -0
- package/dist/permissions/resolve/declared-names.d.ts +24 -0
- package/dist/permissions/resolve/declared-names.d.ts.map +1 -0
- package/dist/permissions/resolve/refuse-data-beyond-root.d.ts +11 -0
- package/dist/permissions/resolve/refuse-data-beyond-root.d.ts.map +1 -0
- package/dist/permissions/resolve/refuse-loops.d.ts +10 -0
- package/dist/permissions/resolve/refuse-loops.d.ts.map +1 -0
- package/dist/permissions/resolve/resolve-model.d.ts +13 -0
- package/dist/permissions/resolve/resolve-model.d.ts.map +1 -0
- package/dist/permissions/resolve/resolve-relation.d.ts +9 -0
- package/dist/permissions/resolve/resolve-relation.d.ts.map +1 -0
- package/dist/permissions/resolve/resolve-rule.d.ts +12 -0
- package/dist/permissions/resolve/resolve-rule.d.ts.map +1 -0
- package/dist/permissions/resolve/resolved.d.ts +52 -0
- package/dist/permissions/resolve/resolved.d.ts.map +1 -0
- package/dist/permissions/resolve/step.d.ts +4 -0
- package/dist/permissions/resolve/step.d.ts.map +1 -0
- package/dist/permissions/reverse.d.ts +53 -0
- package/dist/permissions/reverse.d.ts.map +1 -0
- package/dist/permissions/walk.d.ts +29 -0
- package/dist/permissions/walk.d.ts.map +1 -0
- package/dist/stores/guard.d.ts +24 -0
- package/dist/stores/guard.d.ts.map +1 -0
- package/dist/stores/storable.d.ts +15 -0
- package/dist/stores/storable.d.ts.map +1 -0
- package/dist/subjects/notation.d.ts +39 -0
- package/dist/subjects/notation.d.ts.map +1 -0
- package/dist/subjects/subject.d.ts +128 -0
- package/dist/subjects/subject.d.ts.map +1 -0
- package/dist/testing/index.d.ts +12 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +26 -0
- package/dist/testing/index.js.map +10 -0
- package/dist/time/clock.d.ts +31 -0
- package/dist/time/clock.d.ts.map +1 -0
- package/dist/time/duration.d.ts +23 -0
- package/dist/time/duration.d.ts.map +1 -0
- package/docs/README.md +46 -0
- package/docs/guide/adapters.md +861 -0
- package/docs/guide/api-keys.md +316 -0
- package/docs/guide/avatars.md +334 -0
- package/docs/guide/devices.md +441 -0
- package/docs/guide/email-flows.md +880 -0
- package/docs/guide/errors.md +180 -0
- package/docs/guide/events.md +467 -0
- package/docs/guide/invitations.md +465 -0
- package/docs/guide/issuers.md +107 -0
- package/docs/guide/magic-link.md +580 -0
- package/docs/guide/migrating-invitations.md +142 -0
- package/docs/guide/passkeys.md +425 -0
- package/docs/guide/passwords.md +325 -0
- package/docs/guide/permissions.md +719 -0
- package/docs/guide/second-factor.md +1124 -0
- package/docs/guide/sessions.md +521 -0
- package/docs/guide/sign-in-code.md +631 -0
- package/docs/guide/social.md +648 -0
- package/docs/guide/step-up.md +262 -0
- package/docs/guide/users.md +557 -0
- package/docs/guide/vocabulary.md +316 -0
- package/docs/roadmap.md +102 -0
- package/docs/troubleshooting.md +3318 -0
- package/package.json +77 -5
|
@@ -0,0 +1,1124 @@
|
|
|
1
|
+
# The second factor
|
|
2
|
+
|
|
3
|
+
This page is for turning on a TOTP second factor — the six-digit codes of an
|
|
4
|
+
authenticator app — and wiring its flows: enroll, activate, confirm at
|
|
5
|
+
sign-in, recovery codes for a lost phone, disable.
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { z } from 'zod';
|
|
9
|
+
import { createMemoryStores, janus, scryptHasher } from '@softistx/janus';
|
|
10
|
+
|
|
11
|
+
const auth = janus({
|
|
12
|
+
user: z.object({ email: z.email() }),
|
|
13
|
+
password: { login: 'email' },
|
|
14
|
+
store: createMemoryStores(),
|
|
15
|
+
hasher: scryptHasher(),
|
|
16
|
+
secondFactor: {
|
|
17
|
+
issuer: 'Example', // shown in the authenticator app beside the account
|
|
18
|
+
keys: [{ id: '2026-09', key: process.env.TOTP_KEY ?? '' }], // openssl rand -base64 32; unset, janus() refuses
|
|
19
|
+
},
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
const { user } = await auth.signUp({ email: 'ada@example.com', password: 'correct horse' });
|
|
23
|
+
const { uri } = await auth.secondFactor.enroll(user); // render uri as a QR code
|
|
24
|
+
const { recoveryCodes } = await auth.secondFactor.activate(user, '123456'); // the first code the app shows
|
|
25
|
+
// recoveryCodes: ten codes, shown to the user now and never again
|
|
26
|
+
|
|
27
|
+
const result = await auth.signIn({ email: 'ada@example.com', password: 'correct horse' });
|
|
28
|
+
if (result.status === 'secondFactor') {
|
|
29
|
+
// no session yet: ask for a code, then
|
|
30
|
+
const signedIn = await auth.secondFactor.confirm(result.challenge, '654321');
|
|
31
|
+
// or, with the phone gone: await auth.secondFactor.recover(result.challenge, '7k2mq-x9d4c')
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The words — **enrolled**, **active**, **challenge**, **attempt**, **step**,
|
|
36
|
+
**seal**, **recovery code** — are defined in [the vocabulary](vocabulary.md#identities).
|
|
37
|
+
|
|
38
|
+
## Configuration
|
|
39
|
+
|
|
40
|
+
| Option | Type | Default | Effect |
|
|
41
|
+
| --- | --- | --- | --- |
|
|
42
|
+
| `secondFactor.issuer` | string | — required | Your product's name. The authenticator app shows it beside the account, and it is the first half of the QR code's label |
|
|
43
|
+
| `secondFactor.keys` | `[SealingKey, ...SealingKey[]]` | — required | The **sealing keys**. Every TOTP secret is sealed with the first before a store sees it; every key opens. See [Rotating the keys](#rotating-the-keys) |
|
|
44
|
+
| `secondFactor.challenge` | `Duration` | `'5m'` | How long the challenge `signIn` answers waits for a code |
|
|
45
|
+
| `secondFactor.throttle` | `SecondFactorThrottleConfig \| false` | `{ attempts: 10, window: '15m' }` | The codes one account may try at `confirm` and `recover`, across all its challenges. `false` counts nothing. See [Attempts](#attempts) |
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
interface SecondFactorConfig {
|
|
49
|
+
readonly issuer: string;
|
|
50
|
+
readonly keys: readonly [SealingKey, ...SealingKey[]];
|
|
51
|
+
readonly challenge?: Duration;
|
|
52
|
+
readonly throttle?: SecondFactorThrottleConfig | false;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
interface SecondFactorThrottleConfig {
|
|
56
|
+
readonly attempts?: number; // 10
|
|
57
|
+
readonly window?: Duration; // '15m'
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
interface SealingKey {
|
|
61
|
+
readonly id: string; // letters, digits, _ and -, at most 64: written into every secret it seals
|
|
62
|
+
readonly key: string; // 32 random bytes, in base64 or base64url
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Making a key
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
openssl rand -base64 32
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
That prints 44 characters: 32 random bytes in base64, which is what `key`
|
|
73
|
+
takes. Keep it where your other secrets are — an environment variable, a
|
|
74
|
+
secret manager — and **never in the database it protects**: a dump that holds
|
|
75
|
+
the key holds every secret it sealed.
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
import type { SealingKey } from '@softistx/janus';
|
|
79
|
+
|
|
80
|
+
function sealingKey(id: string, variable: string): SealingKey {
|
|
81
|
+
const key = process.env[variable];
|
|
82
|
+
if (key === undefined) throw new Error(`${variable} is not set`);
|
|
83
|
+
return { id, key };
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const auth = janus({
|
|
87
|
+
user: z.object({ email: z.email() }),
|
|
88
|
+
password: { login: 'email' },
|
|
89
|
+
store,
|
|
90
|
+
hasher: scryptHasher(),
|
|
91
|
+
secondFactor: {
|
|
92
|
+
issuer: 'Example',
|
|
93
|
+
keys: [sealingKey('2026-09', 'TOTP_KEY_2026_09')],
|
|
94
|
+
challenge: '3m',
|
|
95
|
+
// throttle: { attempts: 10, window: '15m' }, // the default; false counts nothing
|
|
96
|
+
},
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Name a key after when it was made, and never give two keys the same `id`: the
|
|
101
|
+
id is written into every secret the key seals, and it is how the right key is
|
|
102
|
+
found to open it.
|
|
103
|
+
|
|
104
|
+
### Keeping the list in one variable
|
|
105
|
+
|
|
106
|
+
`parseSealingKeys` reads the `"id:key,id:key"` form a rotation is easiest to
|
|
107
|
+
deploy in — one variable, the first key seals, every key opens — into the
|
|
108
|
+
`keys` above:
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
import { parseSealingKeys } from '@softistx/janus';
|
|
112
|
+
|
|
113
|
+
// TOTP_KEYS="2026-10:<base64>,2026-09:<base64>"
|
|
114
|
+
const keys = parseSealingKeys(process.env.TOTP_KEYS ?? '', {
|
|
115
|
+
where: 'TOTP_KEYS', // names the variable in a refusal
|
|
116
|
+
refuse: process.env.NODE_ENV === 'production' ? ['dev'] : [], // a development key committed to the repository
|
|
117
|
+
});
|
|
118
|
+
|
|
119
|
+
const auth = janus({ /* … */ secondFactor: { issuer: 'Example', keys } });
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
It refuses, with a `TypeError` that never echoes a key: an empty list, an entry
|
|
123
|
+
that is not `id:key`, an id outside letters, digits, `_` and `-`, a duplicate
|
|
124
|
+
id, a key that is not 32 bytes in base64 or base64url, and every id in
|
|
125
|
+
`refuse` — matched exactly, case-sensitive, on any entry, the one that seals or one
|
|
126
|
+
that only opens. `parseSealingKeys` takes ids of up to 42 characters (`janus()` takes 64): a longer one is a `key:id` written the wrong way round, refused by position (`entry 2 has an id that looks like key material`), never echoed. `janus()` itself names such an entry by position too. A list it accepts is one `janus()` accepts, so a malformed variable
|
|
127
|
+
stops the process at start instead of at the first enrolment.
|
|
128
|
+
|
|
129
|
+
### Sealing your own secrets: `sealerFor`
|
|
130
|
+
|
|
131
|
+
The same keys can seal a secret of your own at rest, such as an integration
|
|
132
|
+
key stored per organisation. `sealerFor(keys, purpose)` returns a sealer whose
|
|
133
|
+
keys are derived for `purpose`, so what it seals never opens under the second
|
|
134
|
+
factor's keys or under another purpose:
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
import { parseSealingKeys, sealerFor } from '@softistx/janus';
|
|
138
|
+
|
|
139
|
+
const keys = parseSealingKeys(process.env.TOTP_KEYS ?? '');
|
|
140
|
+
const sealer = sealerFor(keys, 'integration-keys');
|
|
141
|
+
|
|
142
|
+
const sealed = sealer.seal('org-1', 'sk_live_example'); // v1.<key id>.<iv>.<ciphertext and tag>
|
|
143
|
+
sealer.unseal('org-1', sealed); // 'sk_live_example'
|
|
144
|
+
sealer.unseal('org-2', sealed); // null: the id is bound to the value
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
- `sealWith` is the id of the key that seals new values (the first).
|
|
148
|
+
- `seal(id, plaintext)` seals under the first key (AES-256-GCM); `id`, the
|
|
149
|
+
record the value belongs to, is the additional data.
|
|
150
|
+
- `unseal(id, sealed)` answers `null` on any failure (another id, a changed
|
|
151
|
+
value, a key no longer held, text that is not a sealed value) and never throws.
|
|
152
|
+
- Rotation is by key id: put the new key first and keep the old one until no
|
|
153
|
+
value is sealed with it. `needsReseal(sealed)` is `true` for a value sealed
|
|
154
|
+
under another key than the first; `unseal` then `seal` moves it.
|
|
155
|
+
- Keep `purpose` stable: renamed, what was sealed no longer opens. A key
|
|
156
|
+
dropped before its values were sealed again does the same, and `unseal`
|
|
157
|
+
then emits a `JANUS_SEALER_UNKNOWN_KEY` warning once per key id (the id
|
|
158
|
+
only, never a value; an id of 43 characters or more is named by its
|
|
159
|
+
length). Build the sealer once, at start: the warning cap is per sealer.
|
|
160
|
+
- `TypeError`s: an empty, longer than 256 characters or badly formed
|
|
161
|
+
`purpose` (a NUL or a lone surrogate), a list `parseSealingKeys` refuses,
|
|
162
|
+
and, from `seal`, arguments that are not two strings, an empty plaintext, or
|
|
163
|
+
a badly formed id or plaintext. `unseal` answers `null` for a badly formed id.
|
|
164
|
+
|
|
165
|
+
### What `janus()` refuses
|
|
166
|
+
|
|
167
|
+
A configuration that cannot seal is refused when `janus()` is called, with a
|
|
168
|
+
bare `TypeError` — a wiring mistake, never an answer to a request:
|
|
169
|
+
|
|
170
|
+
| Message | Cause |
|
|
171
|
+
| --- | --- |
|
|
172
|
+
| `janus: secondFactor.issuer must name your application — the authenticator app shows it beside the account` | `issuer` missing or blank |
|
|
173
|
+
| `janus: secondFactor.keys: expected at least one key — [{ id, key }], the first seals` | `keys` missing or empty |
|
|
174
|
+
| `janus: secondFactor.keys: every key needs an id of letters, digits, _ and -, at most 64 of them` | an `id` with a `.`, a space, or over 64 characters |
|
|
175
|
+
| `janus: secondFactor.keys: two keys have the id "<id>"` | a repeated `id` |
|
|
176
|
+
| `janus: secondFactor.keys: the key "<id>" is not 32 bytes in base64 — make one with openssl rand -base64 32` | a key of another length, or not base64 |
|
|
177
|
+
| `janus: secondFactor.keys: entry <n> has the id of an earlier entry` | a repeated `id` of 43 characters or more, named by position so a `key:id` written the wrong way round is never echoed |
|
|
178
|
+
| `janus: secondFactor.keys: entry <n> is not 32 bytes in base64 …` | a key of another length, or not base64, on an `id` of 43 characters or more |
|
|
179
|
+
| `janus: secondFactor.challenge: …` | a `challenge` that is not a duration |
|
|
180
|
+
| `janus: secondFactor.throttle must be { attempts, window }, or false to count nothing` | a `throttle` that is not an object or `false` |
|
|
181
|
+
| `janus: secondFactor.throttle.attempts must be a whole number above zero` | `attempts` that is zero, negative or fractional |
|
|
182
|
+
|
|
183
|
+
### What turning it on changes
|
|
184
|
+
|
|
185
|
+
- **`signIn` answers `SignInResult`**, a union you switch on `status` — see
|
|
186
|
+
[Signing in](#signing-in-switch-on-status). This is the one change that
|
|
187
|
+
breaks a caller: `const { token } = await auth.signIn(…)` no longer
|
|
188
|
+
compiles.
|
|
189
|
+
- **`secondFactor` exists on every user type with a password, and on every
|
|
190
|
+
passwordless type that has an e-mail** — `auth.secondFactor` with one type,
|
|
191
|
+
`clinic.staff.secondFactor` with several. The authenticator app's entry is
|
|
192
|
+
named after the login, or after the e-mail when the type has no password.
|
|
193
|
+
A type with neither a password nor an e-mail has none; neither does an
|
|
194
|
+
instance given no `secondFactor`. Both are compile errors.
|
|
195
|
+
- **On a passwordless type, the sign-in code, the magic link, `signInProven`
|
|
196
|
+
and the social completion answer `SignInResult` too**: once the user's factor
|
|
197
|
+
is active they answer a challenge for `secondFactor.confirm` or `recover`,
|
|
198
|
+
as the password sign-in does. A passkey first-factor sign-in
|
|
199
|
+
(`passkeys.signIn`, which requires user verification) opens a session and
|
|
200
|
+
asks for no code.
|
|
201
|
+
- **Every user carries `hasSecondFactor`**: `true` once the factor is active.
|
|
202
|
+
A schema may not declare that field.
|
|
203
|
+
|
|
204
|
+
Without `secondFactor`, `signIn` answers a session as before, typed
|
|
205
|
+
`SignedIn`, which now carries `status: 'signedIn'` too.
|
|
206
|
+
|
|
207
|
+
## The states of a factor
|
|
208
|
+
|
|
209
|
+
| State | `hasSecondFactor` | `signIn` answers | Recovery codes | Reached by |
|
|
210
|
+
| --- | --- | --- | --- | --- |
|
|
211
|
+
| none | `false` | a session | none | a new user; `disable`, which removes the codes with the factor; the [first proof of the e-mail](#a-first-sign-in-by-e-mail-removes-it-too) by a sign-in code or link |
|
|
212
|
+
| **enrolled** — waiting for a first code | `false` | a session | none | `enroll` |
|
|
213
|
+
| **active** | `true` | a challenge | ten from `activate`; one fewer per `recover`; ten new from `regenerateRecoveryCodes` | `activate`, with a code that matches |
|
|
214
|
+
|
|
215
|
+
Only an active factor is asked for. A user who scanned the QR code and never
|
|
216
|
+
typed a code signs in with their password alone.
|
|
217
|
+
|
|
218
|
+
## Enrolling: the QR code
|
|
219
|
+
|
|
220
|
+
```ts
|
|
221
|
+
const { secret, uri } = await auth.secondFactor.enroll(user);
|
|
222
|
+
// secret: 'JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP' — base32, for a user who types it in
|
|
223
|
+
// uri: 'otpauth://totp/Example:ada%40example.com?secret=…&issuer=Example&algorithm=SHA1&digits=6&period=30'
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
`enroll` mints a secret, seals it onto the user, and answers it once. **Show
|
|
227
|
+
both, keep neither**: render `uri` as a QR code — with any QR library, in the
|
|
228
|
+
browser or on the server — and show `secret` beside it for a user who cannot
|
|
229
|
+
scan. No call answers the secret again. Send the answer with
|
|
230
|
+
`Cache-Control: no-store`, so no cache keeps it either.
|
|
231
|
+
|
|
232
|
+
```ts
|
|
233
|
+
interface SecondFactorEnrolment {
|
|
234
|
+
readonly secret: string; // base32
|
|
235
|
+
readonly uri: string; // otpauth://totp/<issuer>:<login>?…
|
|
236
|
+
}
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
The label is `issuer:login` — the login the user signs in with, so the app
|
|
240
|
+
shows `Example (ada@example.com)`. The codes are RFC 6238 as every
|
|
241
|
+
authenticator app reads them — HMAC-SHA-1, six digits, a thirty-second
|
|
242
|
+
**step** — and none of the three is configurable: several apps ignore
|
|
243
|
+
`algorithm` and `digits` in the URI, and would show codes the server never
|
|
244
|
+
accepts.
|
|
245
|
+
|
|
246
|
+
| Call | Answers | Rejects with |
|
|
247
|
+
| --- | --- | --- |
|
|
248
|
+
| `enroll(user)` on a user with no factor | `{ secret, uri }`; the factor is enrolled | |
|
|
249
|
+
| `enroll(user)` on an enrolled factor | a new secret: **it replaces the waiting one**, and the last QR code shown is the one that works | |
|
|
250
|
+
| `enroll(user)` on an active factor | | `SECOND_FACTOR_ACTIVE` — `disable` it first: enrolling again must not quietly switch it off |
|
|
251
|
+
| `enroll(user)` or `activate` on a user whose e-mail was never verified (a type that holds an e-mail) | | `EMAIL_UNVERIFIED` — [verify the e-mail first](#a-first-sign-in-by-e-mail-removes-it-too) |
|
|
252
|
+
|
|
253
|
+
`enroll` takes `{ ifVersion }` like every write.
|
|
254
|
+
|
|
255
|
+
## Activating: the first code
|
|
256
|
+
|
|
257
|
+
```ts
|
|
258
|
+
const { user: active, recoveryCodes } = await auth.secondFactor.activate(user, code); // the code the app shows now
|
|
259
|
+
active.hasSecondFactor; // true: from now on, signIn asks for a code
|
|
260
|
+
recoveryCodes; // ['7k2mq-x9d4c', …]: ten, shown once — see Recovery codes
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
`activate` proves the user's app holds the secret before anything depends on
|
|
264
|
+
it. Until it succeeds, the factor waits and `signIn` asks for nothing. Once it
|
|
265
|
+
does, it answers the user **and ten [recovery codes](#recovery-codes)**, and
|
|
266
|
+
sends a [`user.secondFactorEnabled` event](events.md) — `enroll` sends none.
|
|
267
|
+
|
|
268
|
+
**Since 0.10, `activate` answers `{ user, recoveryCodes }`, not the user.**
|
|
269
|
+
Code that read the user straight off it — `(await activate(…)).hasSecondFactor`
|
|
270
|
+
— no longer compiles: read `.user`, and show the codes.
|
|
271
|
+
|
|
272
|
+
```ts
|
|
273
|
+
interface RecoveryCodesIssued<U> {
|
|
274
|
+
readonly user: U;
|
|
275
|
+
readonly recoveryCodes: readonly string[]; // ten, `xxxxx-xxxxx`
|
|
276
|
+
}
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
| Rejects with | When |
|
|
280
|
+
| --- | --- |
|
|
281
|
+
| `CODE_INVALID` | the code does not match, or is not six digits. The factor stays enrolled, and the user tries again. **No `attemptsLeft`**: `activate` is not a challenge, so it counts nothing — rate-limit it as you would any authenticated form |
|
|
282
|
+
| `SECOND_FACTOR_NOT_ENROLLED` | `enroll` was never called, or `disable` was called since |
|
|
283
|
+
| `SECOND_FACTOR_ACTIVE` | the factor is already active |
|
|
284
|
+
|
|
285
|
+
A code is accepted once. The one that activated the factor is spent, so the
|
|
286
|
+
user's next sign-in waits for the app's next code.
|
|
287
|
+
|
|
288
|
+
## Signing in: switch on `status`
|
|
289
|
+
|
|
290
|
+
```ts
|
|
291
|
+
type SignInResult<U> = SignedIn<U> | SecondFactorRequired;
|
|
292
|
+
|
|
293
|
+
interface SignedIn<U> {
|
|
294
|
+
readonly status: 'signedIn';
|
|
295
|
+
readonly user: U;
|
|
296
|
+
readonly session: Session;
|
|
297
|
+
readonly token: string;
|
|
298
|
+
readonly newDevice: boolean; // with janus({ devices }): see devices.md
|
|
299
|
+
readonly deviceToken: string | null;
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
interface SecondFactorRequired {
|
|
303
|
+
readonly status: 'secondFactor';
|
|
304
|
+
readonly challenge: string; // a secret, like a session token
|
|
305
|
+
readonly expiresAt: Date; // five minutes from now, by default
|
|
306
|
+
readonly userId: Id; // for your logs and rate limits — not for the visitor
|
|
307
|
+
readonly methods: readonly ('totp' | 'passkey')[]; // always has 'totp'; 'passkey' too when the user holds a passkey
|
|
308
|
+
readonly passkeyOptions?: Readonly<Record<string, unknown>>; // navigator.credentials.get options, with 'passkey'
|
|
309
|
+
}
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
`methods` and `passkeyOptions` are additive: without `passkeys` in `janus()`,
|
|
313
|
+
`methods` is `['totp']` and there are no options. With a passkey, the page can
|
|
314
|
+
answer with `secondFactor.confirmPasskey(challenge, assertion)` instead of a
|
|
315
|
+
code — see [passkeys](passkeys.md#signing-in-with-a-passkey).
|
|
316
|
+
|
|
317
|
+
A user whose factor is active gets **no session from their password** — nor
|
|
318
|
+
from a [code sent by e-mail](sign-in-code.md#a-second-factor-is-still-asked-for),
|
|
319
|
+
whose `confirm` answers the same union: they get a **challenge**, which `secondFactor.confirm` redeems with a code. Anyone
|
|
320
|
+
else gets a session, as before. `signIn`'s refusals — `CREDENTIALS_INVALID`,
|
|
321
|
+
`USER_INACTIVE` — are unchanged, and come before any challenge: a wrong
|
|
322
|
+
password never tells anyone that a second factor exists.
|
|
323
|
+
|
|
324
|
+
```ts
|
|
325
|
+
const result = await auth.signIn({ email, password });
|
|
326
|
+
switch (result.status) {
|
|
327
|
+
case 'signedIn':
|
|
328
|
+
// result.token, result.session: set the cookie, as before
|
|
329
|
+
break;
|
|
330
|
+
case 'secondFactor':
|
|
331
|
+
// result.challenge: keep it for the next request, and ask for a code
|
|
332
|
+
break;
|
|
333
|
+
}
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
### Where to keep the challenge
|
|
337
|
+
|
|
338
|
+
**The challenge is a secret.** With a password already proved, it is half of
|
|
339
|
+
a sign-in: whoever holds it needs only a code. Keep it where the visitor's
|
|
340
|
+
next request presents it, and nowhere else:
|
|
341
|
+
|
|
342
|
+
- **a short-lived cookie** — `HttpOnly`, `Secure`, `SameSite=Strict`, a
|
|
343
|
+
`Path` covering only the code route, and a `Max-Age` ending at `expiresAt`;
|
|
344
|
+
- or **the body of your code form** — a hidden field of the page that asks
|
|
345
|
+
for the code;
|
|
346
|
+
- or, for a bearer client, the body of the answer, which it sends back with
|
|
347
|
+
the code.
|
|
348
|
+
|
|
349
|
+
**Never in a URL** — a query string reaches server logs, proxies, the
|
|
350
|
+
browser's history and the `Referer` header — **and never in a log**. Log the
|
|
351
|
+
user's id if you need to; the challenge is stored only as its hash, like a
|
|
352
|
+
session token, so it cannot be recovered from the store either.
|
|
353
|
+
|
|
354
|
+
A challenge belongs to the user type that issued it: in a multi-type
|
|
355
|
+
application, confirm a staff member's challenge with
|
|
356
|
+
`clinic.staff.secondFactor.confirm`. Another type's `confirm` answers
|
|
357
|
+
`TOKEN_UNKNOWN`.
|
|
358
|
+
|
|
359
|
+
## Confirming: the code at sign-in
|
|
360
|
+
|
|
361
|
+
```ts
|
|
362
|
+
const signedIn = await auth.secondFactor.confirm(challenge, code);
|
|
363
|
+
// { status: 'signedIn', user, session, token }: the session is open
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
`confirm` redeems the challenge with a code and opens the session — the same
|
|
367
|
+
`SignedIn` a sign-in without a second factor answers.
|
|
368
|
+
|
|
369
|
+
| Rejects with | When | What to do |
|
|
370
|
+
| --- | --- | --- |
|
|
371
|
+
| `CODE_INVALID`, with `attemptsLeft` | the code does not match, is not six digits, or was already accepted | ask again while `attemptsLeft > 0`; at `0` the challenge is spent: sign in again |
|
|
372
|
+
| `TOKEN_UNKNOWN` | no such challenge — a typo, another user type's, or one a store's TTL already dropped. Another type's challenge still loses one of its attempts, and its fifth spends it | sign in again |
|
|
373
|
+
| `TOKEN_SPENT` | the challenge already opened a session, its attempts ran out, or a password reset spent it | sign in again |
|
|
374
|
+
| `TOKEN_EXPIRED` | `expiresAt` has passed | sign in again |
|
|
375
|
+
| `USER_INACTIVE` | the user was deactivated since `signIn`. The challenge is spent | answer 403, as `signIn` would |
|
|
376
|
+
| `SECOND_FACTOR_NOT_ENROLLED` | the factor was disabled since `signIn`. The challenge is spent | sign in again: the password alone now opens a session |
|
|
377
|
+
|
|
378
|
+
### Giving the device again
|
|
379
|
+
|
|
380
|
+
With [`janus({ devices })`](devices.md), the challenge carries **no
|
|
381
|
+
device**: whatever `signIn` was given, `confirm` — and `recover` — decide
|
|
382
|
+
whether the device is new only from what they are given themselves. Pass
|
|
383
|
+
the same `{ device }` again, from the same cookie:
|
|
384
|
+
|
|
385
|
+
```ts
|
|
386
|
+
const result = await auth.signIn({ email, password }, { device: cookie ?? null });
|
|
387
|
+
if (result.status === 'secondFactor') {
|
|
388
|
+
// the next request, with the code — and the device cookie again
|
|
389
|
+
const signedIn = await auth.secondFactor.confirm(challenge, code, { device: cookie ?? null });
|
|
390
|
+
// { status: 'signedIn', …, newDevice, deviceToken }: user.newDeviceSignedIn sent for a new one
|
|
391
|
+
}
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
A confirmation given no device is untracked: `newDevice: false`,
|
|
395
|
+
`deviceToken: null`, no event. The challenge answer itself has neither
|
|
396
|
+
field, and sends nothing.
|
|
397
|
+
|
|
398
|
+
### Attempts
|
|
399
|
+
|
|
400
|
+
A challenge takes **five attempts**. Every call to `confirm` counts one, in
|
|
401
|
+
one write to the store, **before anything is checked** — a malformed code, a
|
|
402
|
+
code that races another: each costs an attempt. `attemptsLeft` counts down
|
|
403
|
+
`4, 3, 2, 1, 0`; the fifth wrong code spends the challenge, and the next call
|
|
404
|
+
is `TOKEN_SPENT`, even with the right code.
|
|
405
|
+
|
|
406
|
+
```ts
|
|
407
|
+
import { TokenError } from '@softistx/janus';
|
|
408
|
+
|
|
409
|
+
try {
|
|
410
|
+
await auth.secondFactor.confirm(challenge, code);
|
|
411
|
+
} catch (error) {
|
|
412
|
+
if (error instanceof TokenError && error.code === 'CODE_INVALID') {
|
|
413
|
+
error.attemptsLeft; // 4 after the first wrong code; 0 once the challenge is spent
|
|
414
|
+
}
|
|
415
|
+
throw error;
|
|
416
|
+
}
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
Five attempts at a million values is a one-in-200,000 chance per password
|
|
420
|
+
guessed right. A new challenge takes a new sign-in, with the password, and
|
|
421
|
+
`signIn`'s throttle allows ten per login per 15-minute window — so the
|
|
422
|
+
password alone buys at most ten challenges a window; a limit per client is
|
|
423
|
+
yours to add.
|
|
424
|
+
|
|
425
|
+
**The account has its own limit.** A challenge's five attempts bound that
|
|
426
|
+
challenge only, and a new one costs a first-factor sign-in, not a guess. So
|
|
427
|
+
`confirm` and `recover` also count every code tried, on **any** challenge, in a
|
|
428
|
+
per-account window: `secondFactor.throttle`, **ten per account per 15 minutes**
|
|
429
|
+
by default, `false` to count nothing.
|
|
430
|
+
|
|
431
|
+
```ts
|
|
432
|
+
secondFactor: { issuer: 'Example', keys, throttle: { attempts: 10, window: '15m' } },
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
The count is made after the challenge's own, before the code is compared: a
|
|
436
|
+
challenge spends one attempt, then the account's window refuses with
|
|
437
|
+
`CODE_INVALID`, `attemptsLeft: 0`, `reason: 'throttled'` and `retryAfter` (the
|
|
438
|
+
shape `regenerateRecoveryCodes` answers), the right code included, and nothing
|
|
439
|
+
is spent or written — the challenge is neither used nor burned. A new
|
|
440
|
+
challenge does not help until the window ends. A passkey assertion
|
|
441
|
+
(`confirmPasskey`) is neither counted nor refused: it cannot be guessed. The window is **the account's
|
|
442
|
+
own, apart from the app-code one** that `regenerateRecoveryCodes`,
|
|
443
|
+
`spendRecoveryCode` and a step-up share: a signed-in session guessing there
|
|
444
|
+
cannot lock the account out of signing in, nor the other way round. Counted
|
|
445
|
+
in fixed windows of the clock by the store, so every process shares it. A code
|
|
446
|
+
the app accepts starts it again, as for the app-code window; a recovery code
|
|
447
|
+
or a password written does not. Someone who keeps trying keeps that account's
|
|
448
|
+
second step shut, window after window, as `signIn.throttle` does for passwords;
|
|
449
|
+
an application that wants a notice listens for the `CODE_INVALID` throttled
|
|
450
|
+
refusals it answers.
|
|
451
|
+
|
|
452
|
+
A call made through **another user type's** API — `auth.staff.secondFactor.confirm`
|
|
453
|
+
for a patient's challenge — answers `TOKEN_UNKNOWN` and compares nothing, but
|
|
454
|
+
its attempt counts all the same: the fifth spends the challenge, as a wrong
|
|
455
|
+
code would.
|
|
456
|
+
|
|
457
|
+
**Writing a password ends the sign-ins left waiting.** `resetPassword.confirm`,
|
|
458
|
+
`setPassword` and `changePassword` spend every challenge of the user still
|
|
459
|
+
open, so whoever had the old password cannot finish a sign-in they started
|
|
460
|
+
with it:
|
|
461
|
+
|
|
462
|
+
```ts
|
|
463
|
+
const result = await auth.signIn({ email, password: oldPassword }); // a challenge
|
|
464
|
+
await auth.resetPassword.confirm(resetToken, newPassword);
|
|
465
|
+
await auth.secondFactor.confirm(result.challenge, code); // TOKEN_SPENT
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
A sign-in still running when the password is written is refused too.
|
|
469
|
+
`signIn` reads the user again once it answered: if the password it verified
|
|
470
|
+
is no longer theirs, it spends its own challenge — or revokes the session it
|
|
471
|
+
opened — and throws `CREDENTIALS_INVALID`. The writer spends after writing,
|
|
472
|
+
the sign-in reads after issuing, so however the two interleave one of them
|
|
473
|
+
sees the other. A hash rewritten for the same password — another sign-in
|
|
474
|
+
rehashing it — is not a change.
|
|
475
|
+
|
|
476
|
+
### Lifetime
|
|
477
|
+
|
|
478
|
+
A challenge lives `'5m'` unless `secondFactor.challenge` says otherwise, and
|
|
479
|
+
is `TOKEN_EXPIRED` after that. Five minutes is time to unlock a phone and
|
|
480
|
+
open an app; a longer window is a longer life for a stolen challenge.
|
|
481
|
+
|
|
482
|
+
### Replay
|
|
483
|
+
|
|
484
|
+
A code is accepted **once**. Each accepted code records its step, and only a
|
|
485
|
+
later step counts after that — so a code seen over a shoulder, or replayed
|
|
486
|
+
against a new challenge, is `CODE_INVALID`. Of two `confirm` calls with the
|
|
487
|
+
same code at the same moment, one opens a session and the other is refused.
|
|
488
|
+
|
|
489
|
+
The app's code changes every thirty seconds, and the code of the step before
|
|
490
|
+
or after the current one is accepted too, for a phone whose clock drifted.
|
|
491
|
+
|
|
492
|
+
## Recovery codes
|
|
493
|
+
|
|
494
|
+
A user whose phone is lost, reset or stolen cannot produce a TOTP code. Their
|
|
495
|
+
**recovery codes** sign them in instead, once each, with no operator
|
|
496
|
+
resetting anything:
|
|
497
|
+
|
|
498
|
+
```ts
|
|
499
|
+
const { recoveryCodes } = await auth.secondFactor.activate(user, code);
|
|
500
|
+
// show them now; later, at sign-in, with the phone gone:
|
|
501
|
+
const signedIn = await auth.secondFactor.recover(challenge, recoveryCodes[0] ?? '');
|
|
502
|
+
signedIn.recoveryCodesLeft; // 9
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
### Showing them
|
|
506
|
+
|
|
507
|
+
`activate` answers **ten codes**, each ten characters shown `xxxxx-xxxxx` —
|
|
508
|
+
digits and lower-case letters without `i`, `l`, `o` and `u`, fifty random
|
|
509
|
+
bits a code. **They are shown once**: only their keyed hashes are stored, so
|
|
510
|
+
no call answers them again. Show them on the page that confirms activation,
|
|
511
|
+
with a way to copy, download or print them, and send that answer with
|
|
512
|
+
`Cache-Control: no-store`, like `enroll`'s secret:
|
|
513
|
+
|
|
514
|
+
```ts
|
|
515
|
+
const { user: active, recoveryCodes } = await auth.secondFactor.activate(current.user, code);
|
|
516
|
+
return Response.json({ id: active.id, recoveryCodes }, { headers: { 'Cache-Control': 'no-store' } });
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
Never log them, never mail them, never keep them yourself: a recovery code
|
|
520
|
+
is as good as the user's phone.
|
|
521
|
+
|
|
522
|
+
### Signing in with one
|
|
523
|
+
|
|
524
|
+
`recover(challenge, code)` redeems the challenge `signIn` answered — or
|
|
525
|
+
`signInCode.confirm`'s, `magicLink.confirm`'s or `signInProven`'s — with a recovery code instead of the app's code, and
|
|
526
|
+
opens the session. The recovery code is **spent**: its hash leaves the store,
|
|
527
|
+
and `recoveryCodesLeft` says how many remain.
|
|
528
|
+
|
|
529
|
+
```ts
|
|
530
|
+
type RecoveredSignIn<U> = SignedIn<U> & { readonly recoveryCodesLeft: number };
|
|
531
|
+
|
|
532
|
+
const signedIn = await auth.secondFactor.recover(challenge, ' 7K2MQ X9D4C ');
|
|
533
|
+
// { status: 'signedIn', user, session, token, newDevice, deviceToken, recoveryCodesLeft: 9 }
|
|
534
|
+
```
|
|
535
|
+
|
|
536
|
+
- **Read as the user may type it**: case, spaces and dashes are ignored, `o`
|
|
537
|
+
is read as `0`, and `i` and `l` as `1`.
|
|
538
|
+
- **One challenge, one count of attempts.** `recover` and `confirm` share the
|
|
539
|
+
challenge's five: a wrong code in either costs one, and the fifth spends
|
|
540
|
+
the challenge. A form may offer both on one page.
|
|
541
|
+
- **Each takes its own kind.** A TOTP code is never accepted by `recover`, and
|
|
542
|
+
a recovery code never by `confirm`: either is `CODE_INVALID`.
|
|
543
|
+
- **At `recoveryCodesLeft: 0`**, the user has no way back in without their
|
|
544
|
+
phone: tell them, and send them to [regenerate](#regenerating-them) — with
|
|
545
|
+
a new phone, if that is why they are here.
|
|
546
|
+
|
|
547
|
+
| Rejects with | When | What to do |
|
|
548
|
+
| --- | --- | --- |
|
|
549
|
+
| `CODE_INVALID`, with `attemptsLeft` | the recovery code is not one of the user's, or was already used | ask again while `attemptsLeft > 0`; at `0` the challenge is spent: sign in again |
|
|
550
|
+
| `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED` | as for [`confirm`](#confirming-the-code-at-sign-in) | sign in again |
|
|
551
|
+
| `USER_INACTIVE` | the user was deactivated since `signIn`. The challenge is spent; the recovery code is not | answer 403 |
|
|
552
|
+
| `SECOND_FACTOR_NOT_ENROLLED` | the factor was disabled since `signIn`. The challenge is spent | sign in again: the password alone now opens a session |
|
|
553
|
+
| `VERSION_CONFLICT` | the same recovery code, used by two sign-ins at once: the other one opened a session, this one opened nothing | sign in again |
|
|
554
|
+
|
|
555
|
+
The recovery code is removed in one write under the user's version, as
|
|
556
|
+
`confirm` writes the step it accepted — so of two sign-ins spending one code
|
|
557
|
+
at the same moment, exactly one gets a session.
|
|
558
|
+
|
|
559
|
+
`recover` sends a [`user.recoveryCodeUsed` event](events.md) once the code is
|
|
560
|
+
spent — even if opening the session then fails. It is the one to tell the
|
|
561
|
+
user about: a recovery code used by someone else is a sign-in without their
|
|
562
|
+
phone. Given a [`device`](devices.md) that is new, it sends
|
|
563
|
+
`user.newDeviceSignedIn` after it.
|
|
564
|
+
|
|
565
|
+
### Counting what is left
|
|
566
|
+
|
|
567
|
+
`recoveryCodesLeft(user)` reads the count `recover` answered, for whoever
|
|
568
|
+
did not see that answer: a `user.recoveryCodeUsed` listener, which carries
|
|
569
|
+
the user's id only, or a security settings page that says "3 recovery codes
|
|
570
|
+
left".
|
|
571
|
+
|
|
572
|
+
```ts
|
|
573
|
+
await auth.secondFactor.recoveryCodesLeft(user); // 9 — or null, with no active factor
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
- **`null` without an active factor**: a user with none, or one still
|
|
577
|
+
waiting for its first code, holds no codes to count. `0` is an active
|
|
578
|
+
factor whose codes are all spent: send them to
|
|
579
|
+
[regenerate](#regenerating-them).
|
|
580
|
+
- **An unknown id is `NOT_FOUND`**, as for `get`; a store that fails throws
|
|
581
|
+
`STORE_FAILED`. It writes nothing, and takes no key: it counts hashes.
|
|
582
|
+
- **Read after the write**: in a `user.recoveryCodeUsed` listener it counts
|
|
583
|
+
the code just spent out.
|
|
584
|
+
[`@softistx/janus-mail`](https://github.com/softistx/nxgt-janus/tree/develop/packages/janus-mail)'s
|
|
585
|
+
`recoveryCodeUsed` says it in the e-mail — see [User events](events.md#telling-the-user-a-recovery-code-was-used).
|
|
586
|
+
|
|
587
|
+
### Spending one outside a sign-in
|
|
588
|
+
|
|
589
|
+
```ts
|
|
590
|
+
// A user already signed in turns the factor off with a recovery code: their phone is gone.
|
|
591
|
+
const { recoveryCodesLeft } = await auth.secondFactor.spendRecoveryCode(user, code);
|
|
592
|
+
await auth.secondFactor.disable(user);
|
|
593
|
+
```
|
|
594
|
+
|
|
595
|
+
`spendRecoveryCode(user, code)` checks one of the user's recovery codes
|
|
596
|
+
**without a sign-in**: no challenge, no session, no `user.recoveryCodeUsed`
|
|
597
|
+
and no `user.newDeviceSignedIn` event, so nothing a mailer would read as a
|
|
598
|
+
sign-in. The code is removed in one write under the user's version, as
|
|
599
|
+
`recover` removes it, and the call answers `{ user, recoveryCodesLeft }`.
|
|
600
|
+
|
|
601
|
+
It takes the **same five attempts per user per 15-minute window** as
|
|
602
|
+
`regenerateRecoveryCodes`, in the same count (see
|
|
603
|
+
[regenerating them](#regenerating-them)): a code that does not match, or was
|
|
604
|
+
already used, is `CODE_INVALID` with `attemptsLeft`; past the fifth every call
|
|
605
|
+
is `CODE_INVALID` with `attemptsLeft: 0`, `reason: 'throttled'` and
|
|
606
|
+
`retryAfter`, the right code included. Calling `signInProven` then `recover`
|
|
607
|
+
for the same need is no substitute: each challenge brings five fresh tries.
|
|
608
|
+
|
|
609
|
+
| Error | When | What to do |
|
|
610
|
+
| --- | --- | --- |
|
|
611
|
+
| `CODE_INVALID`, with `attemptsLeft` | the code is not one of the user's, or was already used | ask again while `attemptsLeft > 0` |
|
|
612
|
+
| `CODE_INVALID`, `reason: 'throttled'` | five attempts spent in the window | answer 429 with `retryAfter`; wait |
|
|
613
|
+
| `SECOND_FACTOR_NOT_ENROLLED` | the user has no active factor | nothing to spend |
|
|
614
|
+
| `NOT_FOUND` | unknown user | answer 404 |
|
|
615
|
+
|
|
616
|
+
The call spends the code: decide whether the action it unlocks (`disable`)
|
|
617
|
+
follows at once. It is your policy to ask for it from a standing session only.
|
|
618
|
+
|
|
619
|
+
### Regenerating them
|
|
620
|
+
|
|
621
|
+
```ts
|
|
622
|
+
const { recoveryCodes } = await auth.secondFactor.regenerateRecoveryCodes(current.user, code); // a code the app shows now
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
`regenerateRecoveryCodes(user, code)` replaces **all** the user's recovery
|
|
626
|
+
codes with ten new ones, answered once like `activate`'s: the old ones, used
|
|
627
|
+
or not, stop working. It takes a **fresh code from the app** — whoever holds a
|
|
628
|
+
stolen session alone cannot mint codes that outlive it — and spends that code
|
|
629
|
+
as a sign-in would: the same code cannot regenerate twice, nor then confirm a
|
|
630
|
+
sign-in. It sends a [`user.recoveryCodesRegenerated` event](events.md).
|
|
631
|
+
|
|
632
|
+
**It takes five attempts per user per 15-minute window**, the same five a
|
|
633
|
+
challenge takes, counted by the store before the code is compared — so a
|
|
634
|
+
stolen session cannot guess the app's code one call at a time. A code that
|
|
635
|
+
does not match is `CODE_INVALID` with `attemptsLeft`; past the fifth, every
|
|
636
|
+
call in the window is `CODE_INVALID` with `attemptsLeft: 0`,
|
|
637
|
+
`reason: 'throttled'` and `retryAfter` — the seconds until the window frees —
|
|
638
|
+
**the right code included**, and writes nothing:
|
|
639
|
+
|
|
640
|
+
```text
|
|
641
|
+
secondFactor.regenerateRecoveryCodes: too many codes tried — wait for the next 15-minute window
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
The windows are fixed slices of the clock — 00:00, 00:15, 00:30 — so the wait
|
|
645
|
+
is 15 minutes at most. A code accepted starts the count again: a regenerate
|
|
646
|
+
that succeeded, or a sign-in finished with the app. Writing a password does
|
|
647
|
+
not: the attempts already spent in the window stay spent. The count lives in
|
|
648
|
+
the tokens store as a token of kind `secondFactor` whose secret is never
|
|
649
|
+
given out — no store method and no migration of its own — so every process
|
|
650
|
+
over the same store shares it, and a store that fails throws `STORE_FAILED`,
|
|
651
|
+
never a refusal. The count is keyed with the first of `secondFactor.keys`:
|
|
652
|
+
putting a new key first starts every user's count of the current window
|
|
653
|
+
again.
|
|
654
|
+
|
|
655
|
+
A factor activated before 0.10 holds no recovery codes; this is how it gets
|
|
656
|
+
its first ten.
|
|
657
|
+
|
|
658
|
+
| Rejects with | When |
|
|
659
|
+
| --- | --- |
|
|
660
|
+
| `CODE_INVALID` | the app's code does not match, or was already accepted — with `attemptsLeft`, what the window has left: `0` on the fifth wrong code, and the next call is refused. `attemptsLeft: 0` with `reason: 'throttled'`, `retryAfter` and *too many codes tried*: five were already tried in this window, and the code was not compared — wait `retryAfter` seconds |
|
|
661
|
+
| `SECOND_FACTOR_NOT_ENROLLED` | the user has no active factor — none, or one still waiting for its first code |
|
|
662
|
+
| `VERSION_CONFLICT` | `{ ifVersion }` no longer matches, or another call changed the user meanwhile — the same code tried twice at once regenerates once |
|
|
663
|
+
|
|
664
|
+
Like `enroll` and `disable`, `regenerateRecoveryCodes` does not know who is
|
|
665
|
+
calling: pass the user from `auth.authenticate(request)`, and ask for a
|
|
666
|
+
[recent proof](#asking-before-enroll-and-disable-is-your-policy) first. The app's code is the one check `janus` makes itself.
|
|
667
|
+
|
|
668
|
+
```ts
|
|
669
|
+
import { TokenError, assertFresh } from '@softistx/janus';
|
|
670
|
+
|
|
671
|
+
export async function regenerateRecoveryCodes(request: Request): Promise<Response> {
|
|
672
|
+
const current = await auth.authenticate(request);
|
|
673
|
+
if (current === null) return new Response(null, { status: 401 });
|
|
674
|
+
assertFresh(current.session, '5m'); // STEP_UP_REQUIRED: your error handler answers 403, and the client steps up
|
|
675
|
+
const { code } = (await request.json()) as { code: string };
|
|
676
|
+
try {
|
|
677
|
+
const { recoveryCodes } = await auth.secondFactor.regenerateRecoveryCodes(current.user, code);
|
|
678
|
+
return Response.json({ recoveryCodes }, { headers: { 'Cache-Control': 'no-store' } });
|
|
679
|
+
} catch (error) {
|
|
680
|
+
if (error instanceof TokenError && error.code === 'CODE_INVALID') {
|
|
681
|
+
// The window is spent: no code is compared until it frees, `retryAfter` seconds from now.
|
|
682
|
+
if (error.reason === 'throttled') {
|
|
683
|
+
return Response.json(
|
|
684
|
+
{ code: error.code, retryAfter: error.retryAfter },
|
|
685
|
+
{ status: 429, headers: { 'Retry-After': String(error.retryAfter) } },
|
|
686
|
+
);
|
|
687
|
+
}
|
|
688
|
+
return Response.json({ code: error.code, attemptsLeft: error.attemptsLeft }, { status: 401 });
|
|
689
|
+
}
|
|
690
|
+
throw error;
|
|
691
|
+
}
|
|
692
|
+
}
|
|
693
|
+
```
|
|
694
|
+
|
|
695
|
+
### Disabling removes them
|
|
696
|
+
|
|
697
|
+
`disable` removes the factor **and its recovery codes**. A later `enroll` and
|
|
698
|
+
`activate` answer ten new ones; the old ones never work again.
|
|
699
|
+
|
|
700
|
+
### How they are stored
|
|
701
|
+
|
|
702
|
+
Each recovery code is stored as an HMAC-SHA-256 under a key derived (HKDF)
|
|
703
|
+
from the first [sealing key](#rotating-the-keys), with the user's id bound
|
|
704
|
+
in, written `v1.<key id>.<mac>` in `secondFactor.recoveryCodes`. A dump of
|
|
705
|
+
the users, without the keys, cannot check a guess; a hash copied onto another
|
|
706
|
+
user matches nothing. A rotation keeps them readable — see
|
|
707
|
+
[Rotating the keys](#rotating-the-keys) — and what a store keeps of them is
|
|
708
|
+
in [Writing an adapter](adapters.md#a-users-password-and-second-factor).
|
|
709
|
+
|
|
710
|
+
## Disabling
|
|
711
|
+
|
|
712
|
+
```ts
|
|
713
|
+
const user = await auth.secondFactor.disable(current.user);
|
|
714
|
+
user.hasSecondFactor; // false: signIn answers a session again
|
|
715
|
+
```
|
|
716
|
+
|
|
717
|
+
`disable` removes the factor, active or enrolled, with its recovery codes,
|
|
718
|
+
and answers the user. A user without one is answered as they are. A challenge issued before is
|
|
719
|
+
refused afterwards, with `SECOND_FACTOR_NOT_ENROLLED`.
|
|
720
|
+
|
|
721
|
+
When the factor it removed was **active**, `disable` sends a
|
|
722
|
+
[`user.secondFactorDisabled` event](events.md) — the one to tell the user
|
|
723
|
+
about, since a stolen session may have done it. A user who had no factor, or
|
|
724
|
+
one still waiting for its first code, was never asked for one: no event.
|
|
725
|
+
|
|
726
|
+
```ts
|
|
727
|
+
// `mail` is janusMail({ … }), and the user schema holds a name and a locale.
|
|
728
|
+
const auth = janus({
|
|
729
|
+
...config,
|
|
730
|
+
async events(event) {
|
|
731
|
+
if (event.type === 'user.secondFactorDisabled') {
|
|
732
|
+
const user = await auth.get(event.userId);
|
|
733
|
+
await mail.twoFactorDisabled({ name: user.name, locale: user.locale, email: user.email }); // @softistx/janus-mail
|
|
734
|
+
}
|
|
735
|
+
},
|
|
736
|
+
});
|
|
737
|
+
```
|
|
738
|
+
|
|
739
|
+
### A first sign-in by e-mail removes it too
|
|
740
|
+
|
|
741
|
+
When [`signInCode.confirm`](sign-in-code.md) or
|
|
742
|
+
[`magicLink.confirm`](magic-link.md#an-account-someone-else-registered)
|
|
743
|
+
proves an e-mail **never verified**, the write that proves it also removes
|
|
744
|
+
the factor, active or enrolled, with its recovery codes — and drops the
|
|
745
|
+
password, and signs out every session. Whoever registered the address never
|
|
746
|
+
proved they held its inbox, so a factor stored before `enroll` required a
|
|
747
|
+
proved e-mail is not theirs to keep:
|
|
748
|
+
the inbox's owner signs in with no challenge.
|
|
749
|
+
|
|
750
|
+
```ts
|
|
751
|
+
const signedIn = await auth.magicLink.confirm(token); // an e-mail never verified
|
|
752
|
+
if (signedIn.status === 'signedIn' && !signedIn.user.hasSecondFactor) {
|
|
753
|
+
// offer setPassword, then enroll again
|
|
754
|
+
}
|
|
755
|
+
```
|
|
756
|
+
|
|
757
|
+
`user.secondFactorDisabled` is sent when the factor removed was active, after
|
|
758
|
+
`user.emailVerified` and any `user.passwordChanged`, so the listener above
|
|
759
|
+
tells the inbox's owner. An e-mail already verified keeps the factor, and
|
|
760
|
+
`confirm` answers a challenge as `signIn` does. **`enroll` and `activate`
|
|
761
|
+
refuse a user whose e-mail is never verified** with `EMAIL_UNVERIFIED` (403),
|
|
762
|
+
so a factor a real member set up never vanishes on their first sign-in by
|
|
763
|
+
code or link: send `verifyEmail` before offering `enroll`. A type with no
|
|
764
|
+
e-mail has nothing to prove and is not asked. **`update` refuses to move the
|
|
765
|
+
e-mail of a user who holds a factor** (active or waiting) or a passkey, with
|
|
766
|
+
`EMAIL_CHANGE_NEEDS_PROOF` and nothing written: the new address would be
|
|
767
|
+
unproved and its first proof would drop the factor. Use `changeEmail`, which
|
|
768
|
+
proves the new address and keeps it. The removal above stays for a factor
|
|
769
|
+
stored before these rules.
|
|
770
|
+
|
|
771
|
+
### Asking before `enroll` and `disable` is your policy
|
|
772
|
+
|
|
773
|
+
`janus` checks nothing before `enroll` or `disable`: it does not know who is
|
|
774
|
+
calling, only which user is meant. **Whether the user must prove themselves
|
|
775
|
+
again first is the application's decision** — a support tool may disable a
|
|
776
|
+
factor for a user who lost their phone, while a user's own settings page
|
|
777
|
+
should not let a stolen session switch it off.
|
|
778
|
+
|
|
779
|
+
A common rule is a **recent proof**: the session signed in, or was
|
|
780
|
+
confirmed by a [step-up](step-up.md), a few minutes ago — so its holder just
|
|
781
|
+
gave the password, the code, or both. `assertFresh` reads
|
|
782
|
+
`session.authenticatedAt`, which renewal never moves, and throws
|
|
783
|
+
`STEP_UP_REQUIRED` (403) for an older session:
|
|
784
|
+
|
|
785
|
+
```ts
|
|
786
|
+
import { JanusError, assertFresh, statusOf } from '@softistx/janus';
|
|
787
|
+
|
|
788
|
+
export async function disableSecondFactor(request: Request): Promise<Response> {
|
|
789
|
+
const current = await auth.authenticate(request);
|
|
790
|
+
if (current === null) return new Response(null, { status: 401 });
|
|
791
|
+
try {
|
|
792
|
+
assertFresh(current.session, '5m');
|
|
793
|
+
} catch (error) {
|
|
794
|
+
// STEP_UP_REQUIRED: the client asks for auth.stepUp, then sends this again
|
|
795
|
+
if (error instanceof JanusError) {
|
|
796
|
+
return Response.json({ code: error.code }, { status: statusOf(error.code) });
|
|
797
|
+
}
|
|
798
|
+
throw error;
|
|
799
|
+
}
|
|
800
|
+
await auth.secondFactor.disable(current.user);
|
|
801
|
+
return new Response(null, { status: 204 });
|
|
802
|
+
}
|
|
803
|
+
```
|
|
804
|
+
|
|
805
|
+
For a user whose factor is active, `stepUp.request` asks for their app's
|
|
806
|
+
code, never an e-mailed one: a stolen session and a read inbox together still
|
|
807
|
+
cannot switch the factor off.
|
|
808
|
+
|
|
809
|
+
Use the same check before `enroll`, before `regenerateRecoveryCodes` — which
|
|
810
|
+
asks for the app's code besides — before `changePassword`, and before
|
|
811
|
+
anything else a stolen session should not be able to do.
|
|
812
|
+
|
|
813
|
+
## Rotating the keys
|
|
814
|
+
|
|
815
|
+
**The first key seals; every key opens.** A secret names the key that sealed
|
|
816
|
+
it (`v1.<key id>.…`), and so does a [recovery code](#how-they-are-stored)'s
|
|
817
|
+
hash, so a rotation is a change of order, not a migration:
|
|
818
|
+
|
|
819
|
+
1. Make a new key, and add it **last**: every instance can now open what it
|
|
820
|
+
will seal, and none seals with it yet. Deploy that everywhere.
|
|
821
|
+
|
|
822
|
+
```ts
|
|
823
|
+
keys: [sealingKey('2026-09', 'TOTP_KEY_2026_09'), sealingKey('2026-10', 'TOTP_KEY_2026_10')],
|
|
824
|
+
```
|
|
825
|
+
|
|
826
|
+
2. Move it **first**, and deploy again. It seals every new secret; the old
|
|
827
|
+
key still opens the others:
|
|
828
|
+
|
|
829
|
+
```ts
|
|
830
|
+
keys: [sealingKey('2026-10', 'TOTP_KEY_2026_10'), sealingKey('2026-09', 'TOTP_KEY_2026_09')],
|
|
831
|
+
```
|
|
832
|
+
|
|
833
|
+
Two deployments, because during a rolling one an instance still on the
|
|
834
|
+
old list would meet a secret sealed with a key it does not hold. With a
|
|
835
|
+
single instance, or one that stops before the next starts, step 1 can be
|
|
836
|
+
skipped.
|
|
837
|
+
3. Seal the rest again. Every secret sealed under the old key is sealed again
|
|
838
|
+
under the new one **the next time a code is accepted** for it — at `activate`,
|
|
839
|
+
`confirm` or `regenerateRecoveryCodes`. A user who does not sign in keeps
|
|
840
|
+
the old sealing. **Recovery codes cannot be hashed again** — only their
|
|
841
|
+
hashes are kept: new ones, from `activate` or
|
|
842
|
+
`regenerateRecoveryCodes`, are hashed under the first key, and the old ones
|
|
843
|
+
keep working while their key is in `keys`.
|
|
844
|
+
|
|
845
|
+
For the users who do not sign in, `secondFactor.reseal` does it in batches
|
|
846
|
+
(an `after` from the previous call's `nextCursor` resumes; no event is
|
|
847
|
+
sent and no field changes but the secret, `updatedAt` and `version`):
|
|
848
|
+
|
|
849
|
+
```ts
|
|
850
|
+
let after: string | null = null;
|
|
851
|
+
do {
|
|
852
|
+
const run = await auth.secondFactor.reseal({ batch: 100, after });
|
|
853
|
+
// { scanned, resealed, current, skipped, unreadable, nextCursor }
|
|
854
|
+
after = run.nextCursor;
|
|
855
|
+
} while (after !== null);
|
|
856
|
+
```
|
|
857
|
+
|
|
858
|
+
It is idempotent (a secret already under the first key is left alone) and
|
|
859
|
+
safe beside sign-ins or a second run: every write is conditional on the
|
|
860
|
+
version read, and a user who changed meanwhile is counted `skipped`. Run
|
|
861
|
+
the loop again until `resealed`, `skipped` and `unreadable` are all 0 over
|
|
862
|
+
a whole pass. `unreadable` counts a secret no key in `keys` opens (a key
|
|
863
|
+
dropped too early): it is left as it is, never stops the run. Pending
|
|
864
|
+
enrolments are sealed again too.
|
|
865
|
+
4. Remove the old key only when **no secret is sealed with it and no recovery
|
|
866
|
+
code is hashed with it**. Ask your database, since the key's id is the
|
|
867
|
+
second part of both:
|
|
868
|
+
|
|
869
|
+
```ts
|
|
870
|
+
// MongoDB, with @softistx/janus-mongo — the second query matches any code in the array
|
|
871
|
+
await db.collection('users').countDocuments({ 'secondFactor.secret': { $regex: '^v1\\.2026-09\\.' } });
|
|
872
|
+
await db.collection('users').countDocuments({ 'secondFactor.recoveryCodes': { $regex: '^v1\\.2026-09\\.' } });
|
|
873
|
+
```
|
|
874
|
+
|
|
875
|
+
```sql
|
|
876
|
+
-- PostgreSQL, with @softistx/janus-drizzle
|
|
877
|
+
select count(*) from users where second_factor_secret like 'v1.2026-09.%';
|
|
878
|
+
select count(*) from users
|
|
879
|
+
where exists (select 1 from unnest(second_factor_recovery_codes) c where c like 'v1.2026-09.%');
|
|
880
|
+
```
|
|
881
|
+
|
|
882
|
+
Those users have not signed in, or regenerated their recovery codes, since
|
|
883
|
+
the rotation. Wait longer; have them regenerate their codes, which leaves
|
|
884
|
+
only the secret; or `disable` their factor and have them enroll again.
|
|
885
|
+
|
|
886
|
+
A key removed too early, or changed under the same id, is a wiring mistake,
|
|
887
|
+
and it surfaces the next time one of those users signs in — as a bare
|
|
888
|
+
`TypeError`, a 500, never a `CODE_INVALID` that would blame the user:
|
|
889
|
+
|
|
890
|
+
```
|
|
891
|
+
secondFactor.confirm: the secret is sealed with the key "2026-09", which secondFactor.keys no longer holds — keep a key until no secret is sealed with it
|
|
892
|
+
secondFactor.confirm: the secret does not open with the key "2026-09" — was that key changed under the same id, or the secret copied from another user?
|
|
893
|
+
secondFactor.recover: a recovery code is hashed with the key "2026-09", which secondFactor.keys no longer holds — keep a key until no secret or recovery code uses it
|
|
894
|
+
```
|
|
895
|
+
|
|
896
|
+
A key changed under the same id raises nothing on a recovery code: its hash
|
|
897
|
+
simply matches no more, and `recover` answers `CODE_INVALID`. Never change a
|
|
898
|
+
key under its id.
|
|
899
|
+
|
|
900
|
+
**What sealing protects.** A secret is sealed with AES-256-GCM, and the
|
|
901
|
+
user's id is bound into it: a dump of the users, without the keys, produces
|
|
902
|
+
no code, and a sealed secret copied onto another user does not open. It does
|
|
903
|
+
not protect a store whose application is compromised — that process holds
|
|
904
|
+
the keys.
|
|
905
|
+
|
|
906
|
+
## Failing closed without keys
|
|
907
|
+
|
|
908
|
+
A user whose factor is active is **never signed in by a `janus()` given no
|
|
909
|
+
`secondFactor`**. The password is right, a code is due, and that instance
|
|
910
|
+
cannot check one — so `signIn` throws a bare `TypeError` rather than open a
|
|
911
|
+
session on the password alone:
|
|
912
|
+
|
|
913
|
+
```
|
|
914
|
+
signIn: the user's second factor is active, and janus() was given no secondFactor — pass secondFactor: { issuer, keys }
|
|
915
|
+
```
|
|
916
|
+
|
|
917
|
+
This bites an application that builds more than one `janus()` — a web server
|
|
918
|
+
and an admin tool, a worker, a script — and gives the keys to one of them.
|
|
919
|
+
**Give every instance that signs users in the same `secondFactor`**, built
|
|
920
|
+
once:
|
|
921
|
+
|
|
922
|
+
```ts
|
|
923
|
+
// auth.ts: the one configuration every entry point imports
|
|
924
|
+
export const secondFactor = {
|
|
925
|
+
issuer: 'Example',
|
|
926
|
+
keys: [sealingKey('2026-10', 'TOTP_KEY_2026_10'), sealingKey('2026-09', 'TOTP_KEY_2026_09')],
|
|
927
|
+
} as const;
|
|
928
|
+
```
|
|
929
|
+
|
|
930
|
+
The same holds for `enroll`, `activate`, `confirm`, `recover` and
|
|
931
|
+
`regenerateRecoveryCodes`, which an instance with no keys cannot call — for TypeScript they do not exist on it, and for a
|
|
932
|
+
JavaScript caller they throw the same `TypeError`.
|
|
933
|
+
|
|
934
|
+
## A sign-in with a code, as routes
|
|
935
|
+
|
|
936
|
+
A fetch-style pair of handlers — the shape Bun and most frameworks hand you.
|
|
937
|
+
The challenge travels in a cookie scoped to the sign-in routes;
|
|
938
|
+
[`@softistx/janus-hono`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-hono/docs/guide/routes.md#a-second-factor)
|
|
939
|
+
has the same in Hono.
|
|
940
|
+
|
|
941
|
+
```ts
|
|
942
|
+
import { JanusError, TokenError } from '@softistx/janus';
|
|
943
|
+
|
|
944
|
+
const CHALLENGE = 'sign-in-challenge';
|
|
945
|
+
const scope = 'Path=/sign-in; HttpOnly; Secure; SameSite=Strict';
|
|
946
|
+
|
|
947
|
+
export async function signIn(request: Request): Promise<Response> {
|
|
948
|
+
const { email, password } = (await request.json()) as { email: string; password: string };
|
|
949
|
+
const result = await auth.signIn({ email, password });
|
|
950
|
+
|
|
951
|
+
if (result.status === 'secondFactor') {
|
|
952
|
+
const maxAge = Math.floor((result.expiresAt.getTime() - Date.now()) / 1000);
|
|
953
|
+
return Response.json(
|
|
954
|
+
{ next: 'code' },
|
|
955
|
+
{ headers: { 'Set-Cookie': `${CHALLENGE}=${result.challenge}; Max-Age=${maxAge}; ${scope}` } },
|
|
956
|
+
);
|
|
957
|
+
}
|
|
958
|
+
return Response.json(
|
|
959
|
+
{ id: result.user.id },
|
|
960
|
+
{ headers: { 'Set-Cookie': auth.cookie.serialize(result.token, result.session) } },
|
|
961
|
+
);
|
|
962
|
+
}
|
|
963
|
+
|
|
964
|
+
export async function confirmSecondFactor(request: Request): Promise<Response> {
|
|
965
|
+
const { code } = (await request.json()) as { code: string };
|
|
966
|
+
const challenge = request.headers
|
|
967
|
+
.get('cookie')
|
|
968
|
+
?.match(new RegExp(`(?:^|;\\s*)${CHALLENGE}=([^;]+)`))?.[1];
|
|
969
|
+
if (challenge === undefined) return Response.json({ code: 'TOKEN_UNKNOWN' }, { status: 400 });
|
|
970
|
+
|
|
971
|
+
try {
|
|
972
|
+
const signedIn = await auth.secondFactor.confirm(challenge, code);
|
|
973
|
+
const headers = new Headers();
|
|
974
|
+
headers.append('Set-Cookie', auth.cookie.serialize(signedIn.token, signedIn.session));
|
|
975
|
+
headers.append('Set-Cookie', `${CHALLENGE}=; Max-Age=0; ${scope}`);
|
|
976
|
+
return Response.json({ id: signedIn.user.id }, { headers });
|
|
977
|
+
} catch (error) {
|
|
978
|
+
if (error instanceof TokenError && error.code === 'CODE_INVALID') {
|
|
979
|
+
return Response.json({ code: error.code, attemptsLeft: error.attemptsLeft }, { status: 401 });
|
|
980
|
+
}
|
|
981
|
+
if (error instanceof JanusError && error.code !== 'STORE_FAILED') {
|
|
982
|
+
return Response.json({ code: error.code }, { status: 400 }); // sign in again
|
|
983
|
+
}
|
|
984
|
+
throw error; // STORE_FAILED: your 503
|
|
985
|
+
}
|
|
986
|
+
}
|
|
987
|
+
```
|
|
988
|
+
|
|
989
|
+
The recovery code route is the same, calling `recover`, and answers what is
|
|
990
|
+
left besides — a form that offers both kinds posts each kind to its own route:
|
|
991
|
+
|
|
992
|
+
```ts
|
|
993
|
+
export async function recoverSignIn(request: Request): Promise<Response> {
|
|
994
|
+
const { recoveryCode } = (await request.json()) as { recoveryCode: string };
|
|
995
|
+
const challenge = request.headers
|
|
996
|
+
.get('cookie')
|
|
997
|
+
?.match(new RegExp(`(?:^|;\\s*)${CHALLENGE}=([^;]+)`))?.[1];
|
|
998
|
+
if (challenge === undefined) return Response.json({ code: 'TOKEN_UNKNOWN' }, { status: 400 });
|
|
999
|
+
|
|
1000
|
+
try {
|
|
1001
|
+
const signedIn = await auth.secondFactor.recover(challenge, recoveryCode);
|
|
1002
|
+
const headers = new Headers();
|
|
1003
|
+
headers.append('Set-Cookie', auth.cookie.serialize(signedIn.token, signedIn.session));
|
|
1004
|
+
headers.append('Set-Cookie', `${CHALLENGE}=; Max-Age=0; ${scope}`);
|
|
1005
|
+
// 0 left: have the user regenerate them once signed in
|
|
1006
|
+
return Response.json({ id: signedIn.user.id, recoveryCodesLeft: signedIn.recoveryCodesLeft }, { headers });
|
|
1007
|
+
} catch (error) {
|
|
1008
|
+
if (error instanceof TokenError && error.code === 'CODE_INVALID') {
|
|
1009
|
+
return Response.json({ code: error.code, attemptsLeft: error.attemptsLeft }, { status: 401 });
|
|
1010
|
+
}
|
|
1011
|
+
if (error instanceof JanusError && error.code !== 'STORE_FAILED') {
|
|
1012
|
+
return Response.json({ code: error.code }, { status: 400 }); // sign in again — VERSION_CONFLICT included
|
|
1013
|
+
}
|
|
1014
|
+
throw error;
|
|
1015
|
+
}
|
|
1016
|
+
}
|
|
1017
|
+
```
|
|
1018
|
+
|
|
1019
|
+
The code route answers `attemptsLeft` so the form can say how many attempts are
|
|
1020
|
+
left, and nothing else: which of the causes of `CODE_INVALID` it was — a wrong
|
|
1021
|
+
code, a reused one — is not the visitor's business.
|
|
1022
|
+
|
|
1023
|
+
## In a test
|
|
1024
|
+
|
|
1025
|
+
The codes come from the secret `enroll` answered and the clock. Pass
|
|
1026
|
+
`fixedClock` to `janus()`, and compute each code with `totpCode(secret, at?)`
|
|
1027
|
+
from `@softistx/janus/testing`: RFC 6238, as an authenticator app does. A
|
|
1028
|
+
secret that is not base32, or an invalid `at`, throws a `TypeError` that names
|
|
1029
|
+
`totpCode`.
|
|
1030
|
+
|
|
1031
|
+
```ts
|
|
1032
|
+
import { expect, it } from 'bun:test';
|
|
1033
|
+
import { z } from 'zod';
|
|
1034
|
+
import { createMemoryStores, fixedClock, janus, scryptHasher } from '@softistx/janus';
|
|
1035
|
+
import { totpCode } from '@softistx/janus/testing';
|
|
1036
|
+
|
|
1037
|
+
it('asks for a code once the factor is active', async () => {
|
|
1038
|
+
const clock = fixedClock(Date.UTC(2026, 0, 1));
|
|
1039
|
+
const auth = janus({
|
|
1040
|
+
user: z.object({ email: z.email() }),
|
|
1041
|
+
password: { login: 'email' },
|
|
1042
|
+
store: createMemoryStores(),
|
|
1043
|
+
hasher: scryptHasher({ cost: 10 }), // fast in tests; keep the default in production
|
|
1044
|
+
clock,
|
|
1045
|
+
secondFactor: {
|
|
1046
|
+
issuer: 'Test',
|
|
1047
|
+
keys: [{ id: 'test', key: Buffer.alloc(32, 1).toString('base64') }],
|
|
1048
|
+
},
|
|
1049
|
+
});
|
|
1050
|
+
const credentials = { email: 'ada@example.com', password: 'correct horse' };
|
|
1051
|
+
const { user } = await auth.signUp(credentials);
|
|
1052
|
+
const { secret } = await auth.secondFactor.enroll(user);
|
|
1053
|
+
await auth.secondFactor.activate(user, totpCode(secret, clock.now()));
|
|
1054
|
+
clock.advance(30_000); // activation spent this step's code
|
|
1055
|
+
|
|
1056
|
+
const result = await auth.signIn(credentials);
|
|
1057
|
+
if (result.status !== 'secondFactor') throw new Error('expected a challenge');
|
|
1058
|
+
const signedIn = await auth.secondFactor.confirm(result.challenge, totpCode(secret, clock.now()));
|
|
1059
|
+
|
|
1060
|
+
expect(signedIn.user.hasSecondFactor).toBe(true);
|
|
1061
|
+
});
|
|
1062
|
+
```
|
|
1063
|
+
|
|
1064
|
+
## Signatures
|
|
1065
|
+
|
|
1066
|
+
```ts
|
|
1067
|
+
interface SecondFactorApi<U> {
|
|
1068
|
+
readonly secondFactor: {
|
|
1069
|
+
enroll(user: UserRef, options?: WriteOptions): Promise<SecondFactorEnrolment>;
|
|
1070
|
+
activate(user: UserRef, code: string, options?: WriteOptions): Promise<RecoveryCodesIssued<U>>;
|
|
1071
|
+
regenerateRecoveryCodes(user: UserRef, code: string, options?: WriteOptions): Promise<RecoveryCodesIssued<U>>;
|
|
1072
|
+
disable(user: UserRef, options?: WriteOptions): Promise<U>;
|
|
1073
|
+
confirm(challenge: string, code: string, options?: SignInOptions): Promise<SignedIn<U>>;
|
|
1074
|
+
recover(challenge: string, code: string, options?: SignInOptions): Promise<RecoveredSignIn<U>>; // code: a recovery code
|
|
1075
|
+
recoveryCodesLeft(user: UserRef): Promise<number | null>; // null: no active factor
|
|
1076
|
+
// batch: default and at most 100; an `after` not minted by the store is INVALID_CURSOR
|
|
1077
|
+
reseal(input?: { batch?: number; after?: string | null }): Promise<SecondFactorResealed>;
|
|
1078
|
+
};
|
|
1079
|
+
}
|
|
1080
|
+
|
|
1081
|
+
// With janus({ passkeys }) — see passkeys.md
|
|
1082
|
+
interface PasskeySignInApi<U> {
|
|
1083
|
+
readonly secondFactor: {
|
|
1084
|
+
confirmPasskey(challenge: string, assertion: unknown, options?: SignInOptions): Promise<SignedIn<U>>;
|
|
1085
|
+
};
|
|
1086
|
+
}
|
|
1087
|
+
|
|
1088
|
+
interface RecoveryCodesIssued<U> {
|
|
1089
|
+
readonly user: U;
|
|
1090
|
+
readonly recoveryCodes: readonly string[]; // ten, `xxxxx-xxxxx`, shown once
|
|
1091
|
+
}
|
|
1092
|
+
|
|
1093
|
+
type RecoveredSignIn<U> = SignedIn<U> & { readonly recoveryCodesLeft: number };
|
|
1094
|
+
|
|
1095
|
+
interface SecondFactorResealed {
|
|
1096
|
+
readonly scanned: number; // users visited
|
|
1097
|
+
readonly resealed: number; // now under the first key
|
|
1098
|
+
readonly current: number; // already under it
|
|
1099
|
+
readonly skipped: number; // changed meanwhile: run again
|
|
1100
|
+
readonly unreadable: number; // no held key opens them: left alone
|
|
1101
|
+
readonly nextCursor: string | null; // `after` of the next call; null at the end
|
|
1102
|
+
}
|
|
1103
|
+
```
|
|
1104
|
+
|
|
1105
|
+
`RecoveryCodesIssued`, `RecoveredSignIn` and `SecondFactorResealed` are exported types of
|
|
1106
|
+
`@softistx/janus`. `SignInOptions` is `{ device?: string | null }` — see
|
|
1107
|
+
[devices](devices.md#giving-a-sign-in-the-device).
|
|
1108
|
+
|
|
1109
|
+
`UserRef` is a user or its id; `WriteOptions` is `{ ifVersion? }`, as on
|
|
1110
|
+
every write — see [Users](users.md#ifversion). Every call may also reject
|
|
1111
|
+
with `STORE_FAILED`.
|
|
1112
|
+
|
|
1113
|
+
## See also
|
|
1114
|
+
|
|
1115
|
+
- [Sign-in codes](sign-in-code.md) — a sign-in by e-mailed code, which still asks for an active factor, with the same challenge
|
|
1116
|
+
- [Sign-in links](magic-link.md) — a sign-in by e-mailed link, which does the same
|
|
1117
|
+
- [Passkeys](passkeys.md) — a passkey as the second factor at sign-in (`confirmPasskey`) and in a step-up
|
|
1118
|
+
- [Sessions](sessions.md) — the cookie `confirm`'s session is sent in, and `authenticatedAt`
|
|
1119
|
+
- [Devices](devices.md) — the `device` `confirm` and `recover` are given again, and the notice of a new one
|
|
1120
|
+
- [User events](events.md) — `user.secondFactorEnabled`, `user.secondFactorDisabled`, `user.recoveryCodesRegenerated` and `user.recoveryCodeUsed`
|
|
1121
|
+
- [Errors](errors.md) — `CODE_INVALID`, `SECOND_FACTOR_NOT_ENROLLED`, `SECOND_FACTOR_ACTIVE` and their statuses
|
|
1122
|
+
- [Writing an adapter](adapters.md#a-users-password-and-second-factor) — what a store keeps of a factor and its recovery codes
|
|
1123
|
+
- [`@softistx/janus-telemetry`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-telemetry/docs/guide/tracing.md) — the events a second factor writes
|
|
1124
|
+
- [Troubleshooting](../troubleshooting.md) — by the message you see
|