@softistx/janus 0.0.0-stage → 0.73.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +2928 -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 +64 -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 +139 -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 +16 -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 +193 -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-ftz0ne6j.js +127 -0
- package/dist/chunks/index-ftz0ne6j.js.map +11 -0
- package/dist/chunks/index-k6y18nx9.js +724 -0
- package/dist/chunks/index-k6y18nx9.js.map +24 -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 +4411 -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 +6933 -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 +858 -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 +639 -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 +101 -0
- package/docs/troubleshooting.md +3305 -0
- package/package.json +77 -5
|
@@ -0,0 +1,3305 @@
|
|
|
1
|
+
# Troubleshooting `@softistx/janus`
|
|
2
|
+
|
|
3
|
+
Each entry is headed by the text you see: a compiler error, a message, or an
|
|
4
|
+
error `code`. Search this page for the words of your message.
|
|
5
|
+
|
|
6
|
+
How the messages are shaped:
|
|
7
|
+
|
|
8
|
+
- **Every message starts with the call you wrote**: `signIn: …`,
|
|
9
|
+
`resetPassword.confirm: …`, `can: …`. With several user types, that call is
|
|
10
|
+
prefixed by the type: `staff.signIn: …`. Below, `<call>` stands for it.
|
|
11
|
+
- **A `TypeError` is a wiring mistake**: it comes from how the application was
|
|
12
|
+
put together — a configuration, a store, a model, a prepared request sent
|
|
13
|
+
twice — and never from a request. Fix the code; no handler should answer
|
|
14
|
+
one.
|
|
15
|
+
- **A `JanusError` is a refusal at call time**, on a value that could have come
|
|
16
|
+
from a request. It carries a `code` you can `switch` on; the heading of each
|
|
17
|
+
entry below names it.
|
|
18
|
+
|
|
19
|
+
## Index
|
|
20
|
+
|
|
21
|
+
**Sessions**
|
|
22
|
+
- [`session.amr` is `[]`](#sessionamr-is---or-ismultifactor-is-false)
|
|
23
|
+
|
|
24
|
+
**Background work**
|
|
25
|
+
- [`<name> failed in the background: <error>`](#name-failed-in-the-background-error)
|
|
26
|
+
|
|
27
|
+
**Installing @softistx packages**
|
|
28
|
+
- [`401` / `404` on `bun add @softistx/janus*`](#installing-softistx-packages)
|
|
29
|
+
|
|
30
|
+
**Install and types**
|
|
31
|
+
- [`TS2834: Relative import paths need explicit file extensions …`](#ts2834-relative-import-paths-need-explicit-file-extensions-in-ecmascript-imports-when---moduleresolution-is-node16-or-nodenext)
|
|
32
|
+
- [`TS2305: Module '"@softistx/janus"' has no exported member '<name>'.`](#ts2305-module-nxgtjanus-has-no-exported-member-name)
|
|
33
|
+
- [`error instanceof StoreFailure` is `false` for an outage](#error-instanceof-storefailure-is-false-for-an-outage)
|
|
34
|
+
|
|
35
|
+
**Configuring `janus()`**
|
|
36
|
+
- [`createJanusIssuers: …` wiring messages](#createjanusissuers--wiring-messages)
|
|
37
|
+
- [`janus: pass either user … or users …, and exactly one of them`](#janus-pass-either-user-one-user-type-or-users-several-user-types-and-exactly-one-of-them)
|
|
38
|
+
- [`janus: user must be a Standard Schema …`](#janus-user-must-be-a-standard-schema--a-zod-4-valibot-or-arktype-schema)
|
|
39
|
+
- [`janus: a user type signs in with a password and no hasher is wired …`](#janus-a-user-type-signs-in-with-a-password-and-no-hasher-is-wired--pass-hasher-scrypthasher-or-bunhasher-on-bun-there-is-no-silent-fallback)
|
|
40
|
+
- [`bunHasher: Bun.password is not available …`](#bunhasher-bunpassword-is-not-available--this-runtime-is-not-bun-wire-scrypthasher-instead)
|
|
41
|
+
- [`scryptHasher: cost is log2(N), an integer from 10 to 20 …`](#scrypthasher-cost-is-log2n-an-integer-from-10-to-20--17-is-the-recommended-value)
|
|
42
|
+
- [`scryptHasher: concurrency is …` / `bunHasher: concurrency is …`](#scrypthasher-concurrency-is-how-many-hashes-may-run-at-once-an-integer-from-1-to-64--2-is-the-default)
|
|
43
|
+
- [`janus: two hashers claim the prefix "<prefix>" …`](#janus-two-hashers-claim-the-prefix-prefix--which-one-verifies-would-depend-on-their-order)
|
|
44
|
+
- [`janus: store.<slot> has no method <method>, which the port requires`](#janus-storeslot-has-no-method-method-which-the-port-requires)
|
|
45
|
+
- [`janus: relations must be a relation store — relations.deleteEntity is missing`](#janus-relations-must-be-a-relation-store--relationsdeleteentity-is-missing)
|
|
46
|
+
- [`janus: password.login must name a top-level field of the schema, such as "email"`](#janus-passwordlogin-must-name-a-top-level-field-of-the-schema-such-as-email)
|
|
47
|
+
- [`janus: password.login "<field>" did not name a string in validated <type> fields …`](#janus-passwordlogin-field-did-not-name-a-string-in-validated-type-fields--it-must-name-a-required-string-field)
|
|
48
|
+
- [`janus: the user type "<name>" must be a camelCase name …`](#janus-the-user-type-name-must-be-a-camelcase-name--letters-and-digits-starting-with-a-letter)
|
|
49
|
+
- [`janus: session.lifespan: "<value>" is not a duration …`](#janus-sessionlifespan-value-is-not-a-duration-write-a-number-followed-by-ms-s-m-h-or-d--for-example-15m-or-720h)
|
|
50
|
+
- [`janus: cookie.sameSite "none" requires cookie.secure …`](#janus-cookiesamesite-none-requires-cookiesecure--browsers-refuse-the-cookie-otherwise)
|
|
51
|
+
- [`janus: secondFactor.issuer must name your application …`](#janus-secondfactorissuer-must-name-your-application--the-authenticator-app-shows-it-beside-the-account)
|
|
52
|
+
- [`janus: secondFactor.keys: the key "<id>" is not 32 bytes in base64 …`](#janus-secondfactorkeys-the-key-id-is-not-32-bytes-in-base64--make-one-with-openssl-rand--base64-32)
|
|
53
|
+
- [`list` with a `namePrefix` finds nobody, or not everybody](#list-with-a-nameprefix-finds-nobody-or-not-everybody)
|
|
54
|
+
- [`"hasSecondFactor" is a field janus sets itself; rename it`](#hassecondfactor-is-a-field-janus-sets-itself-rename-it)
|
|
55
|
+
- [`"avatar" is a field janus sets itself; rename it`](#avatar-is-a-field-janus-sets-itself-rename-it)
|
|
56
|
+
- [`janus: devices.keys: …`](#janus-deviceskeys-expected-at-least-one-key---id-key--the-first-seals)
|
|
57
|
+
- [`janus: events must be a function that takes a user event …`](#janus-events-must-be-a-function-that-takes-a-user-event--webhooks---from-nxgtjanus-webhooks-or-your-own)
|
|
58
|
+
- [`janus: signIn.throttle …` wiring messages](#janus-signinthrottle-wiring-messages)
|
|
59
|
+
- [`janus: mail.throttle …` wiring messages](#janus-mailthrottle-wiring-messages)
|
|
60
|
+
- [`janus: secondFactor.throttle must be { attempts, window }, or false to count nothing`](#janus-secondfactorthrottle-must-be--attempts-window--or-false-to-count-nothing)
|
|
61
|
+
- [`janus: secondFactor.throttle.attempts must be a whole number above zero`](#janus-secondfactorthrottleattempts-must-be-a-whole-number-above-zero)
|
|
62
|
+
- [`janus: tokens.<flow> is 5m, shorter than mail.throttle.window, 10m …`](#janus-tokensflow-is-5m-shorter-than-mailthrottlewindow-10m-)
|
|
63
|
+
- [Other `janus:` wiring messages](#other-janus-wiring-messages)
|
|
64
|
+
|
|
65
|
+
**API keys**
|
|
66
|
+
- [`API_KEY_LIMIT` — `apiKeys.create: the user already holds <n> API keys — revoke one first`](#api_key_limit--apikeyscreate-the-user-already-holds-n-api-keys--revoke-one-first)
|
|
67
|
+
- [`API_KEY_INVALID` — `apiKeys.create: name must be 1 to 100 characters once trimmed` / `lifetime is not one of the configured lifetimes`](#api_key_invalid--apikeyscreate-name-must-be-1-to-100-characters-once-trimmed--lifetime-is-not-one-of-the-configured-lifetimes)
|
|
68
|
+
- [`STEP_UP_REQUIRED` with `reason: 'apiKey'`](#step_up_required-with-reason-apikey)
|
|
69
|
+
- [`TS2769: No overload matches this call` on `authenticate(request, { apiKey })`](#ts2769-no-overload-matches-this-call-on-authenticaterequest--apikey-)
|
|
70
|
+
- [A valid API key answers `null` (anonymous)](#a-valid-api-key-answers-null-anonymous)
|
|
71
|
+
- [`API_KEY_INVALID` with `field: 'scopes'` or `'bound'`](#api_key_invalid-with-field-scopes-or-bound)
|
|
72
|
+
- [`TypeError: apiKeys.create: the API key store does not implement listBoundApiKeys and revokeBoundApiKeys`](#typeerror-apikeyscreate-the-api-key-store-does-not-implement-listboundapikeys-and-revokeboundapikeys)
|
|
73
|
+
- [`TypeError: … does not implement listExpiringApiKeys and markApiKeyExpiryNotified`](#typeerror--does-not-implement-listexpiringapikeys-and-markapikeyexpirynotified)
|
|
74
|
+
- [`assertApiKeyStore`: `has listUserBoundApiKeys without the bound capability`](#assertapikeystore-has-listuserboundapikeys-without-the-bound-capability-listboundapikeys-and-revokeboundapikeys-the-userbound-capability-needs-it)
|
|
75
|
+
- [`assertApiKeyStore`: `has listBoundApiKeys without revokeBoundApiKeys: the bound capability needs both`](#assertapikeystore-has-listboundapikeys-without-revokeboundapikeys-the-bound-capability-needs-both)
|
|
76
|
+
|
|
77
|
+
**Invitations**
|
|
78
|
+
- [`INVITATION_INVALID` — `invitations.preview: this code names no pending invitation`](#invitation_invalid--invitationspreview-this-code-names-no-pending-invitation)
|
|
79
|
+
- [`INVITATION_INVALID` — `invitations.issue: email must be an address with one "@"` (and the other fields)](#invitation_invalid--invitationsissue-email-must-be-an-address-with-one--and-the-other-fields)
|
|
80
|
+
- [`TypeError` — `invitations.issue: the invitation store did not keep the invitation's type`](#typeerror--invitationsissue-the-invitation-store-did-not-keep-the-invitations-type)
|
|
81
|
+
- [`PASSWORD_REQUIRED` — `invitations.accept: choose a password to accept this invitation`](#password_required--invitationsaccept-choose-a-password-to-accept-this-invitation)
|
|
82
|
+
- [`PASSWORD_TOO_SHORT` on `invitations.accept`](#password_too_short-on-invitationsaccept)
|
|
83
|
+
- [`INVITATION_PENDING` — `invitations.issue: another pending invitation holds this scope and address`](#invitation_pending--invitationsissue-another-pending-invitation-holds-this-scope-and-address)
|
|
84
|
+
- [`INVITATION_LIMIT` — `invitations.issue: the scope already holds <n> pending invitations — revoke one first`](#invitation_limit--invitationsissue-the-scope-already-holds-n-pending-invitations--revoke-one-first)
|
|
85
|
+
- [`TypeError` — `invitations.importHistory: records must be an array` (and the other call shapes)](#typeerror--invitationsimporthistory-records-must-be-an-array-and-the-other-call-shapes)
|
|
86
|
+
- [`importHistory` refuses a record: `invalid`, `unknown-type`, `live-pending`, `pending-held`, `duplicate-key`, `key-taken`](#importhistory-refuses-a-record-invalid-unknown-type-live-pending-pending-held-duplicate-key-key-taken)
|
|
87
|
+
- [`INVITATION_NOT_PENDING` — `invitations.resend: the invitation is accepted`](#invitation_not_pending--invitationsresend-the-invitation-is-accepted)
|
|
88
|
+
- [`INVITATION_REFUSED` — `invitations.accept: the application refused this acceptance`](#invitation_refused--invitationsaccept-the-application-refused-this-acceptance)
|
|
89
|
+
- [A retry after a failed `onAccepted` answers `signIn`](#a-retry-after-a-failed-onaccepted-answers-signin)
|
|
90
|
+
- [`JANUS_INVITATION_RELEASE_FAILED` process warning](#janus_invitation_release_failed-process-warning)
|
|
91
|
+
- [`janus: invitations …` wiring messages](#janus-invitations--wiring-messages)
|
|
92
|
+
|
|
93
|
+
**Users, sessions and tokens**
|
|
94
|
+
- [`STORE_FAILED` — `<slot>.<method>: the store could not answer`](#store_failed--slotmethod-the-store-could-not-answer)
|
|
95
|
+
- [`STORE_FAILED` — `tokens.insertToken: the store could not answer`, on `changeEmail.send` alone](#store_failed--tokensinserttoken-the-store-could-not-answer-on-changeemailsend-alone)
|
|
96
|
+
- [`STORE_FAILED` — `<slot>.<method> answered undefined …`](#store_failed--slotmethod-answered-undefined-an-absence-is-null-so-this-store-forgot-to-answer)
|
|
97
|
+
- [`STORE_FAILED` — `users.findUsers answered no list …`](#store_failed--usersfindusers-answered-no-list-an-absence-is-a-shorter-list-so-this-store-forgot-to-answer)
|
|
98
|
+
- [`signOutEverywhere: issuedBefore is not a valid Date`](#signouteverywhere-issuedbefore-is-not-a-valid-date)
|
|
99
|
+
- [`<call>: ids must be an array of user ids`](#call-ids-must-be-an-array-of-user-ids)
|
|
100
|
+
- [`findMany` answers fewer users than ids](#findmany-answers-fewer-users-than-ids)
|
|
101
|
+
- [`findByEmail` answers `null` for an address somebody holds](#findbyemail-answers-null-for-an-address-somebody-holds)
|
|
102
|
+
- [`NOT_FOUND` — `<call>: no <type> has this id`](#not_found--call-no-type-has-this-id)
|
|
103
|
+
- [`AVATAR_ID_INVALID` — `<call>: the avatar id must be a non-empty string of at most 512 characters that every store can keep`](#avatar_id_invalid--call-the-avatar-id-must-be-a-non-empty-string-of-at-most-512-characters-that-every-store-can-keep)
|
|
104
|
+
- [`LOGIN_TAKEN` — `<call>: the login is taken by another <type>`](#login_taken--call-the-login-is-taken-by-another-type)
|
|
105
|
+
- [`EMAIL_CHANGE_NEEDS_PROOF` — `<call>: the user holds a <second factor|passkey> — moving the e-mail with update would leave the new address unproved and the first proof would drop it; use changeEmail, which proves the new address`](#email_change_needs_proof--call-the-user-holds-a-second-factorpasskey--moving-the-e-mail-with-update-would-leave-the-new-address-unproved-and-the-first-proof-would-drop-it-use-changeemail-which-proves-the-new-address)
|
|
106
|
+
- [`VERSION_CONFLICT` — `<call>: expected version <n>, found <m>`](#version_conflict--call-expected-version-n-found-m)
|
|
107
|
+
- [`USER_INVALID` — `<call>: the fields do not match the <type> schema …`](#user_invalid--call-the-fields-do-not-match-the-type-schema-n-issues-at-paths)
|
|
108
|
+
- [`PASSWORD_TOO_SHORT` — `<call>: the password is shorter than the policy's <n> characters`](#password_too_short--call-the-password-is-shorter-than-the-policys-n-characters)
|
|
109
|
+
- [`CREDENTIALS_INVALID` — `<call>: the login and the password do not match`](#credentials_invalid--call-the-login-and-the-password-do-not-match)
|
|
110
|
+
- [`CREDENTIALS_INVALID` — `<call>: too many passwords tried at this login …`](#credentials_invalid--call-too-many-passwords-tried-at-this-login--wait-for-the-next-window)
|
|
111
|
+
- [`MAGIC_LINK_DISABLED` — `<call>: magic-link sign-in is disabled`](#magic_link_disabled--call-magic-link-sign-in-is-disabled)
|
|
112
|
+
- [`MAIL_THROTTLED` — `<call>: too many e-mails asked for this address …`, or `… for this user …`](#mail_throttled--call-too-many-e-mails-asked-for-this-address--the-last-one-sent-still-works-use-it-or-wait-for-the-next-window)
|
|
113
|
+
- [Accepting an invitation answers `MAIL_THROTTLED`](#accepting-an-invitation-answers-mail_throttled)
|
|
114
|
+
- [The password chosen when accepting an invitation answers `CREDENTIALS_INVALID` (`noPassword`)](#the-password-chosen-when-accepting-an-invitation-answers-credentials_invalid-nopassword)
|
|
115
|
+
- [`MAIL_THROTTLED` never reaches the visitor: `request` runs in the background](#mail_throttled-never-reaches-the-visitor-request-runs-in-the-background)
|
|
116
|
+
- [`<flow>.prepare(…).send: already called — …`](#flowpreparesend-already-called--a-prepared-request-sends-once-call-flowprepare-again-for-another)
|
|
117
|
+
- [`STORE_FAILED` — `<call>: the store dropped the attempts it had just stored`](#store_failed--call-the-store-dropped-the-attempts-it-had-just-stored)
|
|
118
|
+
- [`HASH_UNSUPPORTED` — `<call>: no wired verifier claims the prefix "<prefix>"`](#hash_unsupported--call-no-wired-verifier-claims-the-prefix-prefix)
|
|
119
|
+
- [`scryptHasher: the stored hash has the $scrypt$ prefix and not its format`](#scrypthasher-the-stored-hash-has-the-scrypt-prefix-and-not-its-format)
|
|
120
|
+
- [`USER_INACTIVE` — `<call>: the user is inactive`](#user_inactive--call-the-user-is-inactive)
|
|
121
|
+
- [`EMAIL_UNVERIFIED` — `<call>: the e-mail is not verified`](#email_unverified--call-the-e-mail-is-not-verified)
|
|
122
|
+
- [`EMAIL_UNVERIFIED` — `<call>: the e-mail stopped being verified while the passkey was registered — nothing was kept`](#email_unverified--call-the-e-mail-stopped-being-verified-while-the-passkey-was-registered--nothing-was-kept)
|
|
123
|
+
- [`EMAIL_UNVERIFIED` — `<call>: the e-mail changed or was proved again while the passkey was registered — nothing was kept`](#email_unverified--call-the-e-mail-changed-or-was-proved-again-while-the-passkey-was-registered--nothing-was-kept)
|
|
124
|
+
- [`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired)
|
|
125
|
+
- [`TOKEN_STALE` — `<call>: the token was sent to an e-mail the user no longer has`](#token_stale--call-the-token-was-sent-to-an-e-mail-the-user-no-longer-has)
|
|
126
|
+
- [`INVALID_CURSOR` — `<call>: this cursor was not minted by this store …`](#invalid_cursor--call-this-cursor-was-not-minted-by-this-store-or-was-minted-for-another-ordering-n-characters)
|
|
127
|
+
- [`CURSOR_FILTER_MISMATCH` — `<call>: this cursor was issued for another scope, status, role, ref, lapsed or order …`](#cursor_filter_mismatch--call-this-cursor-was-issued-for-another-scope-status-role-ref-lapsed-or-order-than-the-one-given)
|
|
128
|
+
- [`UNSUPPORTED` — `sessions.list: store.sessions does not implement listUserSessions`](#unsupported--sessionslist-storesessions-does-not-implement-listusersessions)
|
|
129
|
+
- [`<where>: options.deviceLabel must be a string`](#where-optionsdevicelabel-must-be-a-string)
|
|
130
|
+
- [`<call>: limit must be an integer of at least 1, or absent`](#call-limit-must-be-an-integer-of-at-least-1-or-absent)
|
|
131
|
+
- [`UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions, nor store.tokens deleteExpiredTokens …`](#unsupported--collectexpired-storesessions-does-not-implement-deleteexpiredsessions-nor-storetokens-deleteexpiredtokens--their-stores-expire-records-on-their-own-or-implement-the-methods)
|
|
132
|
+
- [`<call>: the <type> type does not sign in with a password …`](#call-the-type-type-does-not-sign-in-with-a-password--add-password--login--to-it)
|
|
133
|
+
- [`authenticate()` answers `null` although a valid cookie was sent](#authenticate-answers-null-although-a-valid-cookie-was-sent)
|
|
134
|
+
|
|
135
|
+
**Second factor**
|
|
136
|
+
- [`TS2339: Property 'token' does not exist on type 'SignInResult<…>'.`](#ts2339-property-token-does-not-exist-on-type-signinresult)
|
|
137
|
+
- [`TS2339: Property 'hasSecondFactor' does not exist on type 'RecoveryCodesIssued<…>'.`](#ts2339-property-hassecondfactor-does-not-exist-on-type-recoverycodesissued)
|
|
138
|
+
- [`CODE_INVALID` — `<call>: the code does not match, or was already used`](#code_invalid--call-the-code-does-not-match-or-was-already-used)
|
|
139
|
+
- [`totpCode: the secret is not base32` / `totpCode: at is not a valid Date`](#totpcode-the-secret-is-not-base32--totpcode-at-is-not-a-valid-date)
|
|
140
|
+
- [`CODE_INVALID` — `secondFactor.confirm: too many codes tried …` (and `recover`)](#code_invalid--secondfactorconfirm-too-many-codes-tried--wait-for-the-next-15-minute-window)
|
|
141
|
+
- [`CODE_INVALID` — `secondFactor.regenerateRecoveryCodes: too many codes tried …`](#code_invalid--secondfactorregeneraterecoverycodes-too-many-codes-tried--wait-for-the-next-15-minute-window)
|
|
142
|
+
- [The code the authenticator app shows is refused with `CODE_INVALID`](#the-code-the-authenticator-app-shows-is-refused-with-code_invalid)
|
|
143
|
+
- [A recovery code the user kept is refused with `CODE_INVALID`](#a-recovery-code-the-user-kept-is-refused-with-code_invalid)
|
|
144
|
+
- [`SECOND_FACTOR_NOT_ENROLLED` — `secondFactor.regenerateRecoveryCodes: the user has no active second factor …`](#second_factor_not_enrolled--secondfactorregeneraterecoverycodes-the-user-has-no-active-second-factor--recovery-codes-come-with-one)
|
|
145
|
+
- [`SECOND_FACTOR_NOT_ENROLLED` — `secondFactor.activate: the user has no second factor waiting …`](#second_factor_not_enrolled--secondfactoractivate-the-user-has-no-second-factor-waiting--call-enroll-first)
|
|
146
|
+
- [`SECOND_FACTOR_ACTIVE` — `secondFactor.enroll: the user's second factor is active …`](#second_factor_active--secondfactorenroll-the-users-second-factor-is-active--disable-it-first)
|
|
147
|
+
- [`<call>: …, and janus() was given no secondFactor …`](#call--and-janus-was-given-no-secondfactor--pass-secondfactor--issuer-keys-)
|
|
148
|
+
- [`<call>: the secret is sealed with the key "<id>", which secondFactor.keys no longer holds …`](#call-the-secret-is-sealed-with-the-key-id-which-secondfactorkeys-no-longer-holds--keep-a-key-until-no-secret-is-sealed-with-it)
|
|
149
|
+
- [`<call>: the secret does not open with the key "<id>" — was that key changed under the same id, or the secret copied from another user?`](#call-the-secret-does-not-open-with-the-key-id--was-that-key-changed-under-the-same-id-or-the-secret-copied-from-another-user)
|
|
150
|
+
- [`<call>: the stored secret is not a sealed one`](#call-the-stored-secret-is-not-a-sealed-one)
|
|
151
|
+
- [`<call>: a recovery code is hashed with the key "<id>", which secondFactor.keys no longer holds …`](#call-a-recovery-code-is-hashed-with-the-key-id-which-secondfactorkeys-no-longer-holds--keep-a-key-until-no-secret-or-recovery-code-uses-it)
|
|
152
|
+
- [`<call>: a stored recovery code is not a keyed hash`](#call-a-stored-recovery-code-is-not-a-keyed-hash)
|
|
153
|
+
- [`<call>: the <type> type has no password and the user has no e-mail, so a second factor has no account name`](#call-the-type-type-has-no-password-and-the-user-has-no-e-mail-so-a-second-factor-has-no-account-name)
|
|
154
|
+
- `TOKEN_*`, `USER_INACTIVE` and `VERSION_CONFLICT` from `secondFactor.confirm` and `secondFactor.recover`: in their entries above.
|
|
155
|
+
|
|
156
|
+
**Sign-in codes**
|
|
157
|
+
- [`TOKEN_STALE` — `<call>: the code was sent to an e-mail the user no longer has`](#token_stale--call-the-code-was-sent-to-an-e-mail-the-user-no-longer-has)
|
|
158
|
+
- [The code from an earlier e-mail is refused with `CODE_INVALID`](#the-code-from-an-earlier-e-mail-is-refused-with-code_invalid)
|
|
159
|
+
- [`signInCode.request` answers `null` for a user who exists](#signincoderequest-answers-null-for-a-user-who-exists)
|
|
160
|
+
- [`TS2339: Property 'signInCode' does not exist on type 'TypeApi<…>'.`](#ts2339-property-signincode-does-not-exist-on-type-typeapi)
|
|
161
|
+
- `CODE_INVALID`, `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `USER_INACTIVE` and `VERSION_CONFLICT` from `signInCode.confirm`, and `TS2339` on its `token`: in their entries above.
|
|
162
|
+
|
|
163
|
+
**Sign-in links**
|
|
164
|
+
- [A sign-in link answers `TOKEN_SPENT` on the user's first click](#a-sign-in-link-answers-token_spent-on-the-users-first-click)
|
|
165
|
+
- [The link's own button answers `403`](#the-links-own-button-answers-403)
|
|
166
|
+
- [The link signed in another device than the one that asked](#the-link-signed-in-another-device-than-the-one-that-asked)
|
|
167
|
+
- [`magicLink.request` answers `null` for a user who exists](#magiclinkrequest-answers-null-for-a-user-who-exists)
|
|
168
|
+
- [`TS2339: Property 'magicLink' does not exist on type 'TypeApi<…>'.`](#ts2339-property-magiclink-does-not-exist-on-type-typeapi)
|
|
169
|
+
- [`TS2559: Type 'string' has no properties in common with type 'SignInOptions'.`, on `magicLink.confirm`](#ts2559-type-string-has-no-properties-in-common-with-type-signinoptions-on-magiclinkconfirm)
|
|
170
|
+
- `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE`, `USER_INACTIVE` and `VERSION_CONFLICT` from `magicLink.confirm`, and `TS2339` on its `token`: in their entries above.
|
|
171
|
+
|
|
172
|
+
**Step-up**
|
|
173
|
+
- [`STEP_UP_REQUIRED` — `assertFresh: the session proved who it is longer ago than maxAge …`](#step_up_required--assertfresh-the-session-proved-who-it-is-longer-ago-than-maxage--confirm-with-a-step-up)
|
|
174
|
+
- [`TOKEN_UNKNOWN` — `stepUp.confirm: no such challenge`, with a challenge just issued](#token_unknown--stepupconfirm-no-such-challenge-with-a-challenge-just-issued)
|
|
175
|
+
- [`TOKEN_UNKNOWN` — `stepUp.confirm: the session was signed out while the code was checked`](#token_unknown--stepupconfirm-the-session-was-signed-out-while-the-code-was-checked)
|
|
176
|
+
- [`SECOND_FACTOR_ACTIVE` — `stepUp.confirm: the user's second factor became active since the code was sent …`](#second_factor_active--stepupconfirm-the-users-second-factor-became-active-since-the-code-was-sent--request-a-step-up-again)
|
|
177
|
+
- [`SECOND_FACTOR_NOT_ENROLLED` — `stepUp.confirm: the user no longer has a second factor …`](#second_factor_not_enrolled--stepupconfirm-the-user-no-longer-has-a-second-factor--request-a-step-up-again)
|
|
178
|
+
- [`CODE_INVALID` — `stepUp.confirm: too many codes tried …`](#code_invalid--stepupconfirm-too-many-codes-tried--wait-for-the-next-15-minute-window)
|
|
179
|
+
- [`NOT_FOUND` — `stepUp.request: the user has no e-mail`](#not_found--stepuprequest-the-user-has-no-e-mail)
|
|
180
|
+
- [`TS2339: Property 'code' does not exist on type 'StepUpByEmail<…> | StepUpByApp<…>'.`](#ts2339-property-code-does-not-exist-on-type-stepupbyemail--stepupbyapp)
|
|
181
|
+
- [`TS2339: Property 'stepUp' does not exist on type 'TypeApi<…>'.`](#ts2339-property-stepup-does-not-exist-on-type-typeapi)
|
|
182
|
+
|
|
183
|
+
**Devices**
|
|
184
|
+
- [`RangeError: deviceCookie(): maxAge must be a number of seconds from 0 to 34560000 (400 days), got …`](#rangeerror-devicecookie-maxage-must-be-a-number-of-seconds-from-0-to-34560000-400-days-got-)
|
|
185
|
+
- [`TypeError: deviceCookie(): …` (a name, prefix or attribute the browser would refuse)](#typeerror-devicecookie--a-name-prefix-or-attribute-the-browser-would-refuse)
|
|
186
|
+
- [`<call>: a device was given, but janus() has no devices — pass devices: { keys }`](#call-a-device-was-given-but-janus-has-no-devices--pass-devices--keys-)
|
|
187
|
+
- [`<call>: options must be { device }, or left out — the token goes under device`](#call-options-must-be--device--or-left-out--the-token-goes-under-device)
|
|
188
|
+
- [`<call>: options.device must be the device token the client holds, or null when it holds none`](#call-optionsdevice-must-be-the-device-token-the-client-holds-or-null-when-it-holds-none)
|
|
189
|
+
- [Every sign-in reports a new device](#every-sign-in-reports-a-new-device)
|
|
190
|
+
- [A new device is never reported: `newDevice` is always `false`](#a-new-device-is-never-reported-newdevice-is-always-false)
|
|
191
|
+
- [`TS2379: Argument of type '{ device: string | undefined; }' is not assignable to parameter of type 'SignInOptions' …`](#ts2379-argument-of-type--device-string--undefined--is-not-assignable-to-parameter-of-type-signinoptions-with-exactoptionalpropertytypes-true)
|
|
192
|
+
- [`TS2739: Type '{ … }' is missing the following properties from type 'SignedIn<…>': newDevice, deviceToken`](#ts2739-type----is-missing-the-following-properties-from-type-signedin-newdevice-devicetoken)
|
|
193
|
+
- [`TS2559: Type 'string' has no properties in common with type 'SignInOptions'.`, on `secondFactor.confirm` or `signInCode.confirm`](#ts2559-type-string-has-no-properties-in-common-with-type-signinoptions-on-secondfactorconfirm-or-signincodeconfirm)
|
|
194
|
+
- [`TS2322: Type 'string | null' is not assignable to type 'string'.`, on `deviceToken`](#ts2322-type-string--null-is-not-assignable-to-type-string-on-devicetoken)
|
|
195
|
+
- `janus: devices.keys: …`: under [Configuring `janus()`](#configuring-janus).
|
|
196
|
+
|
|
197
|
+
**Social sign-in**
|
|
198
|
+
- [`FLOW_EXPIRED` — `social.complete: the flow is unknown, used or lapsed — start it again`](#flow_expired--socialcomplete-the-flow-is-unknown-used-or-lapsed--start-it-again)
|
|
199
|
+
- [`FLOW_MISMATCH` — `social.complete: the flow cookie is missing or malformed` / …](#flow_mismatch--socialcomplete-the-flow-cookie-is-missing-or-malformed--the-callbacks-state-is-not-this-flows--the-flow-cookies-contents-were-changed--this-link-was-started-by-another-user)
|
|
200
|
+
- [`FLOW_PURPOSE_MISMATCH` — `social.complete: this is a sign-in flow, and a link flow was expected` / …](#flow_purpose_mismatch--socialcomplete-this-is-a-sign-in-flow-and-a-link-flow-was-expected--this-is-a-link-flow-and-a-sign-in-flow-was-expected)
|
|
201
|
+
- [`RETURN_TO_INVALID` — `social.start: returnTo must be a path of this site …`](#return_to_invalid--socialstart-returnto-must-be-a-path-of-this-site--starting-with-a-single---with-no--no-empty-or--segment-and-no-scheme)
|
|
202
|
+
- [`PROVIDER_ERROR` — `social.complete: the provider "<name>" failed`](#provider_error--socialcomplete-the-provider-name-failed)
|
|
203
|
+
- [`SOCIAL_PROVIDER_UNKNOWN` — `social.start: the user type configures no such social provider`](#social_provider_unknown--socialstart-the-user-type-configures-no-such-social-provider)
|
|
204
|
+
- [`janus: social.providers must name at least one provider, or social.resolveProvider must be given`](#janus-socialproviders-must-name-at-least-one-provider-or-socialresolveprovider-must-be-given)
|
|
205
|
+
- [`janus: social.resolveProvider must be a function …`](#janus-socialresolveprovider-must-be-a-function-)
|
|
206
|
+
- [`social.resolveProvider("<name>") must answer a provider …`](#socialresolveprovidername-must-answer-a-provider-)
|
|
207
|
+
- [`SIGN_UP_DISABLED` — `social.complete: nobody holds this account's e-mail, and the user type does not sign strangers up`](#sign_up_disabled--socialcomplete-nobody-holds-this-accounts-e-mail-and-the-user-type-does-not-sign-strangers-up)
|
|
208
|
+
- [`EMAIL_NOT_VERIFIED_FOR_LINK` — `social.complete: a user holds this e-mail, and the provider or the account does not vouch for it …`](#email_not_verified_for_link--socialcomplete-a-user-holds-this-e-mail-and-the-provider-or-the-account-does-not-vouch-for-it--sign-in-another-way-then-link-the-account)
|
|
209
|
+
- [`SOCIAL_ACCOUNT_TAKEN` — `social.complete: this social account is already linked to another user`](#social_account_taken--socialcomplete-this-social-account-is-already-linked-to-another-user)
|
|
210
|
+
- [`SOCIAL_STEP_UP_UNMET` — `social.complete: the provider's answer does not prove the step-up the flow asked for`](#social_step_up_unmet--socialcomplete-the-providers-answer-does-not-prove-the-step-up-the-flow-asked-for)
|
|
211
|
+
- [`LAST_SIGN_IN_METHOD` — `social.unlink: this is the user's only way to sign in …`](#last_sign_in_method--socialunlink-this-is-the-users-only-way-to-sign-in--set-a-password-or-link-another-account-first)
|
|
212
|
+
- [`EMAIL_UNVERIFIED` — `social.complete: the provider does not vouch for an e-mail, so no account is created`](#email_unverified--socialcomplete-the-provider-does-not-vouch-for-an-e-mail-so-no-account-is-created)
|
|
213
|
+
- [`janus: the user type "<name>" configures social and store.socialLinks is missing …`](#janus-the-user-type-name-configures-social-and-storesociallinks-is-missing-)
|
|
214
|
+
- [`janus: social.signUp needs a type whose login is its e-mail …`](#janus-socialsignup-needs-a-type-whose-login-is-its-e-mail-)
|
|
215
|
+
|
|
216
|
+
**Passkeys**
|
|
217
|
+
- [`PASSKEY_INVALID` — `passkeys.register: the browser's response did not verify (<reason>) …`](#passkey_invalid--passkeysregister-the-browsers-response-did-not-verify-reason--ask-for-new-options)
|
|
218
|
+
- [`PASSKEY_INVALID` — `<call>: name must be 1 to 100 characters once trimmed`](#passkey_invalid--call-name-must-be-1-to-100-characters-once-trimmed)
|
|
219
|
+
- [`PASSKEY_TAKEN` — `passkeys.register: this credential is already registered`](#passkey_taken--passkeysregister-this-credential-is-already-registered)
|
|
220
|
+
- [`PASSKEY_LIMIT` — `passkeys.register: the user already holds <n> passkeys …`](#passkey_limit--passkeysregister-the-user-already-holds-n-passkeys--remove-one-first)
|
|
221
|
+
- [`SECOND_FACTOR_NOT_ENROLLED` — `passkeys.registrationOptions: the user has no active TOTP …`](#second_factor_not_enrolled--passkeysregistrationoptions-the-user-has-no-active-totp--a-passkey-is-only-registered-beside-one)
|
|
222
|
+
- [`CODE_INVALID` — `secondFactor.confirmPasskey` / `stepUp.confirmPasskey` refused an assertion](#code_invalid--secondfactorconfirmpasskey--stepupconfirmpasskey-refused-an-assertion)
|
|
223
|
+
- [`SECOND_FACTOR_NOT_ENROLLED` — `stepUp.request: the user holds no passkey …`](#second_factor_not_enrolled--stepuprequest-the-user-holds-no-passkey-)
|
|
224
|
+
- [`CREDENTIALS_INVALID` with `reason: 'passkey'`, and `passkeys.signIn` / `signInOptions` needs `passkeys.firstFactor`](#credentials_invalid-with-reason-passkey-and-the-typeerror-naming-passkeysfirstfactor)
|
|
225
|
+
- [`janus: passkeys needs secondFactor …`, `store.passkeys is missing`, `passkeys.rpId` / `origins` / `verifier` …](#janus-passkeys-needs-secondfactor--storepasskeys-is-missing-passkeysrpid--origins--verifier-)
|
|
226
|
+
|
|
227
|
+
**User events**
|
|
228
|
+
- [`[JANUS_EVENT_FAILED] Warning: janus: the events listener failed on <type> <event id> for user <user id>: <name>`](#janus_event_failed-warning-janus-the-events-listener-failed-on-type-event-id-for-user-user-id-name)
|
|
229
|
+
- [An event you expected never arrived](#an-event-you-expected-never-arrived)
|
|
230
|
+
|
|
231
|
+
**Permissions**
|
|
232
|
+
- [`PERMISSION_DEPTH` — `can: checking <type>#<permission> crossed more than <n> relations without an answer`](#permission_depth--can-checking-typepermission-crossed-more-than-n-relations-without-an-answer)
|
|
233
|
+
- [`permissions: this model was not made by defineModel() …`](#permissions-this-model-was-not-made-by-definemodel--pass-what-definemodel-answered)
|
|
234
|
+
- [`permissions: store.<method> is missing`](#permissions-storemethod-is-missing)
|
|
235
|
+
- [`can: <type>.<relation> reads <field>, which the object does not carry …`](#can-typerelation-reads-field-which-the-object-does-not-carry--pass-the-loaded-object-spread)
|
|
236
|
+
- [`can: <type>.<name> reaches a condition, and no ctx was passed — pass { ctx }`](#can-typename-reaches-a-condition-and-no-ctx-was-passed--pass--ctx-)
|
|
237
|
+
- [`list: <type>.<relation> is read from a field, and has no lookup …`](#list-typerelation-is-read-from-a-field-and-has-no-lookup-to-find-the-types-naming-a-subject-of-type-subject-type--)
|
|
238
|
+
- [`list: the lookup of <type>.<relation> must answer an array of ids`](#list-the-lookup-of-typerelation-must-answer-an-array-of-ids)
|
|
239
|
+
- [`grant: <type>.<relation> is read from <field>; there is nothing to store …`](#grant-typerelation-is-read-from-field-there-is-nothing-to-store--change-the-type-instead)
|
|
240
|
+
- [`grant: <type>.<relation> is not held by <holder>`](#grant-typerelation-is-not-held-by-holder)
|
|
241
|
+
- [`replace: the subjects must be an array`](#replace-the-subjects-must-be-an-array)
|
|
242
|
+
- [Two `replace` calls at once leave the union of their adds](#two-replace-calls-at-once-leave-the-union-of-their-adds)
|
|
243
|
+
- [`replace` leaves extra holders on a capped relation store](#replace-leaves-extra-holders-on-a-capped-relation-store)
|
|
244
|
+
- [`holders` answers a short or empty page that has a `nextCursor`](#holders-answers-a-short-or-empty-page-that-has-a-nextcursor)
|
|
245
|
+
- [Other `can:`, `list:`, `grant:`, `revoke:` and `replace:` messages](#other-can-list-grant-revoke-and-replace-messages)
|
|
246
|
+
- [`defineModel: …`](#definemodel-)
|
|
247
|
+
|
|
248
|
+
**Subjects**
|
|
249
|
+
- [`parseTuple: "<text>" is not a relation tuple; expected type:id#relation@subject`](#parsetuple-text-is-not-a-relation-tuple-expected-typeidrelationsubject)
|
|
250
|
+
- [`setOf: pass a user or { type, id }, then a relation`](#setof-pass-a-user-or--type-id--then-a-relation)
|
|
251
|
+
|
|
252
|
+
**Conformance (adapter authors)**
|
|
253
|
+
- [`describeJanusStores: no test runner on globalThis …`](#describejanusstores-no-test-runner-on-globalthis--pass-runner--describe-it--under-bun-test-import-them-from-buntest)
|
|
254
|
+
- [`[JANUS_TOKEN_STORE_IGNORES_USER_ID] Warning`](#janus_token_store_ignores_user_id-warning-tokensconsumetoken-answered-a-token-of-another-user-although-a-userid-was-given-the-store-ignores-its-fourth-argument-the-call-was-refused-but-the-token-was-spent-put-userid-in-the-consumetoken-condition-and-run-describejanusstores-tokensconsumebound)
|
|
255
|
+
- [`tokens.consumeBound` fails](#tokensconsumebound-fails--consumetoken-bound-to-another-user-consumetoken-bound-to-an-empty-id-or-consumetoken-bound-to-the-tokens-own-user)
|
|
256
|
+
- [`JANUS_CONFORMANCE_SKIPPED` — `faults not provided: the outage invariant is not proven for this adapter`](#janus_conformance_skipped--faults-not-provided-the-outage-invariant-is-not-proven-for-this-adapter)
|
|
257
|
+
- [`the error is named <Class> but is not @softistx/janus's <Class>: two copies of @softistx/janus are installed …`](#the-error-is-named-class-but-is-not-nxgtjanuss-class-two-copies-of-nxgtjanus-are-installed-the-adapter-must-list-it-as-a-peer-dependency-never-a-dependency)
|
|
258
|
+
- [`expected <Class>, got <value>`](#expected-class-got-value)
|
|
259
|
+
- [`expected null, got undefined — an absence is null; undefined is a store that forgot to answer`](#expected-null-got-undefined--an-absence-is-null-undefined-is-a-store-that-forgot-to-answer)
|
|
260
|
+
- [`findUser should answer recoveryCodes [] as [] — never null, never undefined`](#finduser-should-answer-recoverycodes--as---never-null-never-undefined)
|
|
261
|
+
- [`reauthenticateSession racing revokeSession: the session should stay revoked — one conditional write, never a read then a write`](#reauthenticatesession-racing-revokesession-the-session-should-stay-revoked--one-conditional-write-never-a-read-then-a-write)
|
|
262
|
+
- [`tokens.insertToken: the store could not answer`, in `tokens.everyKind`](#tokensinserttoken-the-store-could-not-answer-in-tokenseverykind)
|
|
263
|
+
- [`consumeToken for a signInCode token redeemed as magicLink`, in `tokens.magicLinkKind`](#consumetoken-for-a-signincode-token-redeemed-as-magiclink-in-tokensmagiclinkkind)
|
|
264
|
+
- [`consumeToken for a verifyEmail token redeemed as changeEmail`, in `tokens.changeEmailKind`](#consumetoken-for-a-verifyemail-token-redeemed-as-changeemail-in-tokenschangeemailkind)
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## Sessions
|
|
269
|
+
|
|
270
|
+
### `session.amr` is `[]` or `isMultiFactor` is false
|
|
271
|
+
|
|
272
|
+
A session stored before `amr` existed reads `amr: []`, and `signInProven` records
|
|
273
|
+
nothing (the proof is the application's). A step-up adds its methods, so the
|
|
274
|
+
session reads right after the user proves again. A custom store must write and
|
|
275
|
+
read `SessionRecord.amr` and honour the third argument of `reauthenticateSession`
|
|
276
|
+
(the conformance case `sessions.amr` checks it).
|
|
277
|
+
|
|
278
|
+
## Background work
|
|
279
|
+
|
|
280
|
+
### `<name> failed in the background: <error>`
|
|
281
|
+
|
|
282
|
+
**When:** a task given to `background().run` reads something tied to the request (a body stream, a transaction, a scoped connection, a `Request`) and logs `<name> failed in the background: …` with a closed or already-read message.
|
|
283
|
+
**Why:** `run` starts the task after the response is on its way, so a resource the framework closes with the response is gone when the task reads it. Janus only logs the failure; it cannot tell it from any other.
|
|
284
|
+
**Fix:** read what the task needs before the response, and capture plain values; open long-lived resources (a client, a pool) in the task or share them.
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
const to = user.email; // read now
|
|
288
|
+
jobs.run('reset mail', () => sendResetMail(to, token)); // not request.json() or tx.query() inside
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
A runner lives for the process: do not create one per request, or `settled()` waits only for that request's tasks.
|
|
292
|
+
|
|
293
|
+
## Installing @softistx packages
|
|
294
|
+
|
|
295
|
+
### `error: GET https://registry.npmjs.org/@softistx%2fjanus - 401` (or `404 Not Found`) on `bun add` / `bun install`
|
|
296
|
+
|
|
297
|
+
The `@softistx/janus*` packages are public on registry.npmjs.org: installing
|
|
298
|
+
them needs no token and no scope mapping. A 401 or 404 means something still
|
|
299
|
+
sends the request elsewhere. The causes, in the order to check them:
|
|
300
|
+
|
|
301
|
+
- **A stale `@softistx` scope.** A `bunfig.toml` `[install.scopes]` entry or an
|
|
302
|
+
`.npmrc` line mapping `@softistx` to another registry (with a token that is
|
|
303
|
+
unset or expired) sends every `@softistx` request there. Remove the entry
|
|
304
|
+
and the packages resolve from registry.npmjs.org:
|
|
305
|
+
|
|
306
|
+
```toml
|
|
307
|
+
# delete this from bunfig.toml
|
|
308
|
+
[install.scopes]
|
|
309
|
+
"@softistx" = { url = "https://npm.softistx.com/", token = "$NPM_REGISTRY_TOKEN" }
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
- **The lockfile still names another registry.** A `bun.lock` entry whose
|
|
313
|
+
tarball URL is `https://npm.pkg.github.com/download/…` or
|
|
314
|
+
`https://npm.softistx.com/…` keeps installing from there. Check
|
|
315
|
+
`grep -c "npm.pkg.github.com\|npm.softistx.com" bun.lock`; when it is not 0,
|
|
316
|
+
delete those entries (or the lockfile) and run `bun install` again so they
|
|
317
|
+
re-resolve from registry.npmjs.org.
|
|
318
|
+
- **The version is not on npmjs.** `npm view @softistx/janus versions` lists
|
|
319
|
+
what is published; a 404 on a version older than the first npmjs one means
|
|
320
|
+
the range must move up to a version that is.
|
|
321
|
+
|
|
322
|
+
## Install and types
|
|
323
|
+
|
|
324
|
+
### `TS2834: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'.`
|
|
325
|
+
|
|
326
|
+
**When:** `tsc` on your project, reported inside `node_modules/@softistx/janus/dist/*.d.ts`, once per import line.
|
|
327
|
+
**Why:** the declarations import their siblings without an extension (`'./auth/index'`), the way a bundler resolves them. `moduleResolution: "nodenext"` (or `"node16"`) demands an extension on every relative import and is **not supported** by this package.
|
|
328
|
+
**Fix:** resolve as a bundler does — Bun, Vite, esbuild and every other bundler already do:
|
|
329
|
+
|
|
330
|
+
```jsonc
|
|
331
|
+
// tsconfig.json
|
|
332
|
+
{
|
|
333
|
+
"compilerOptions": {
|
|
334
|
+
"module": "preserve", // or "esnext"
|
|
335
|
+
"moduleResolution": "bundler"
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
Do not patch the declarations to add `.js` extensions: that support is out of
|
|
341
|
+
scope, and a patched copy breaks on the next install.
|
|
342
|
+
|
|
343
|
+
### `TS2305: Module '"@softistx/janus"' has no exported member '<name>'.`
|
|
344
|
+
|
|
345
|
+
**When:** `tsc` on your own file, for an export the README shows — typically `janus`, `createMemoryStores` or `scryptHasher`.
|
|
346
|
+
**Why:** the same `moduleResolution: "nodenext"` as above, with `skipLibCheck: true` hiding the `TS2834` errors in the declarations. The `export * from './auth/index'` in the package's entry declaration does not resolve, so everything it re-exports is missing.
|
|
347
|
+
**Fix:** `"moduleResolution": "bundler"`, as in the entry above.
|
|
348
|
+
|
|
349
|
+
### `error instanceof StoreFailure` is `false` for an outage
|
|
350
|
+
|
|
351
|
+
**When:** at run time, with an adapter from another package (`@softistx/janus-mongo`, or your own). An outage is then handled as an unknown error, and a taken login can be reported as an outage.
|
|
352
|
+
**Why:** two copies of `@softistx/janus` are installed — the adapter depends on it instead of peering it, or the versions it accepts do not include yours. The adapter throws its copy's `StoreFailure`, and your code tests against the other.
|
|
353
|
+
**Fix:** one copy. An adapter lists `@softistx/janus` in `peerDependencies`, never `dependencies`; then check that only one is installed:
|
|
354
|
+
|
|
355
|
+
```sh
|
|
356
|
+
bun pm ls --all | grep @softistx/janus
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
---
|
|
360
|
+
|
|
361
|
+
## Configuring `janus()`
|
|
362
|
+
|
|
363
|
+
Every entry here is a `TypeError` thrown by `janus(...)` itself, before any
|
|
364
|
+
request. With several user types, the option is prefixed by the type:
|
|
365
|
+
`janus: users.staff: password.login …`.
|
|
366
|
+
|
|
367
|
+
### `createJanusIssuers: …` wiring messages
|
|
368
|
+
|
|
369
|
+
`createJanusIssuers: resolve must be a function`, `createJanusIssuers: build must be a function`, `createJanusIssuers: cache.max must be a positive integer`, and `createJanusIssuers: resolve must answer null or { issuer, version } with two strings`. All are a `TypeError`. A bad `cache.idle` fails with `cache.idle: …`, the duration message.
|
|
370
|
+
|
|
371
|
+
**When:** the options are wrong at wiring time, or `resolve` answered something other than `null` or an object with a non-empty string `issuer` and a string `version` (a numeric `updatedAt` is the usual one).
|
|
372
|
+
|
|
373
|
+
**Fix:** answer the two strings.
|
|
374
|
+
|
|
375
|
+
```ts
|
|
376
|
+
resolve: async (request) => {
|
|
377
|
+
const tenant = await tenants.byHost(new URL(request.url).host);
|
|
378
|
+
return tenant === null ? null : { issuer: tenant.id, version: String(tenant.updatedAt) };
|
|
379
|
+
},
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
An instance that keeps answering with an old configuration is a `version` that did not change: bump it whenever the tenant changes, or call `issuers.evict(issuer)`. See [Several issuers](guide/issuers.md).
|
|
383
|
+
|
|
384
|
+
### `janus: pass either user (one user type) or users (several user types), and exactly one of them`
|
|
385
|
+
|
|
386
|
+
**When:** `janus({...})`, with both `user` and `users`, or neither.
|
|
387
|
+
**Why:** `user` is the shorthand for one user type; `users` declares several, each with its own schema and options. The two cannot be mixed.
|
|
388
|
+
**Fix:**
|
|
389
|
+
|
|
390
|
+
```ts
|
|
391
|
+
// One user type
|
|
392
|
+
janus({ user: User, password: { login: 'email' }, store, hasher });
|
|
393
|
+
|
|
394
|
+
// Several
|
|
395
|
+
janus({
|
|
396
|
+
users: {
|
|
397
|
+
patient: { schema: Patient, password: { login: 'email' } },
|
|
398
|
+
staff: { schema: Staff, password: { login: 'username' } },
|
|
399
|
+
},
|
|
400
|
+
store,
|
|
401
|
+
hasher,
|
|
402
|
+
});
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
### `janus: user must be a Standard Schema — a Zod 4, Valibot or ArkType schema`
|
|
406
|
+
|
|
407
|
+
With several types: `janus: users.<type>: schema must be a Standard Schema — a Zod 4, Valibot or ArkType schema`.
|
|
408
|
+
|
|
409
|
+
**When:** `janus({...})`.
|
|
410
|
+
**Why:** the value has no `['~standard'].validate`. It is a plain object, a TypeScript type used as a value, or a schema from a library version that does not implement [Standard Schema](https://standardschema.dev).
|
|
411
|
+
**Fix:** pass the schema object itself:
|
|
412
|
+
|
|
413
|
+
```ts
|
|
414
|
+
import { z } from 'zod'; // Zod 4
|
|
415
|
+
const User = z.object({ email: z.email(), name: z.string() });
|
|
416
|
+
janus({ user: User, password: { login: 'email' }, store, hasher });
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
### `janus: a user type signs in with a password and no hasher is wired — pass hasher: scryptHasher(), or bunHasher() on Bun. There is no silent fallback`
|
|
420
|
+
|
|
421
|
+
**When:** `janus({...})`, when a type has `password` and the configuration has no `hasher`.
|
|
422
|
+
**Why:** picking a hashing algorithm for you would be a silent choice about your users' passwords.
|
|
423
|
+
**Fix:**
|
|
424
|
+
|
|
425
|
+
```ts
|
|
426
|
+
import { janus, scryptHasher } from '@softistx/janus';
|
|
427
|
+
|
|
428
|
+
janus({ user: User, password: { login: 'email' }, store, hasher: scryptHasher() });
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
### `bunHasher: Bun.password is not available — this runtime is not Bun; wire scryptHasher() instead`
|
|
432
|
+
|
|
433
|
+
**When:** calling `bunHasher()` under Node, or in a test runner that is not Bun.
|
|
434
|
+
**Why:** `bunHasher()` is argon2id through `Bun.password`, which only Bun provides.
|
|
435
|
+
**Fix:** `scryptHasher()` runs on both. To keep verifying argon2id hashes written under Bun while running on Node, you need a verifier for the `$argon2id$` prefix of your own in `verifiers`.
|
|
436
|
+
|
|
437
|
+
```ts
|
|
438
|
+
const hasher = typeof Bun === 'undefined' ? scryptHasher() : bunHasher();
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
### `scryptHasher: cost is log2(N), an integer from 10 to 20 — 17 is the recommended value`
|
|
442
|
+
|
|
443
|
+
**When:** `scryptHasher({ cost })`.
|
|
444
|
+
**Why:** `cost` is the exponent, not N: `cost: 131072` asks for 2^131072.
|
|
445
|
+
**Fix:** leave it out in production (17). In tests, `scryptHasher({ cost: 10 })` is fast and still runs every line.
|
|
446
|
+
|
|
447
|
+
### `scryptHasher: concurrency is how many hashes may run at once, an integer from 1 to 64 — 2 is the default`
|
|
448
|
+
|
|
449
|
+
Also: `bunHasher: concurrency is how many hashes may run at once, an integer from 1 to 64 — 4 is the default`.
|
|
450
|
+
|
|
451
|
+
**When:** `scryptHasher({ concurrency })` or `bunHasher({ concurrency })`.
|
|
452
|
+
**Why:** each `hash` and `verify` holds memory while it runs (about 128 MiB for scrypt, 64 MiB for argon2id), so the hasher runs at most `concurrency` at once and queues the rest. The value must be an integer from 1 to 64.
|
|
453
|
+
**Fix:** leave it out (2 for scrypt, 4 for argon2id, about 256 MiB at most), or pass an integer in range.
|
|
454
|
+
|
|
455
|
+
### `janus: two hashers claim the prefix "<prefix>" — which one verifies would depend on their order`
|
|
456
|
+
|
|
457
|
+
Also: `janus: every hasher needs a non-empty prefix`.
|
|
458
|
+
|
|
459
|
+
**When:** `janus({...})` with `verifiers`.
|
|
460
|
+
**Why:** a stored hash is verified by the hasher whose `prefix` it starts with. Two hashers with one prefix — typically `hasher` repeated in `verifiers` — would make that depend on list order.
|
|
461
|
+
**Fix:** `hasher` already verifies its own hashes; `verifiers` only lists the *other* formats your database holds.
|
|
462
|
+
|
|
463
|
+
```ts
|
|
464
|
+
janus({ ..., hasher: scryptHasher(), verifiers: [legacyBcrypt] }); // not [scryptHasher(), legacyBcrypt]
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
### `janus: store.<slot> has no method <method>, which the port requires`
|
|
468
|
+
|
|
469
|
+
Also: `janus: store.<slot> is missing`, `janus: store must be an object with users, sessions and tokens`, `janus: store.sessions.deleteExpiredSessions must be a function or absent`, `janus: store.tokens.deleteExpiredTokens must be a function or absent`, `janus: store.users.findUsers must be a function or absent`.
|
|
470
|
+
|
|
471
|
+
**When:** `janus({...})`, from JavaScript or with a store typed loosely. TypeScript refuses a partial store at compile time and names the method.
|
|
472
|
+
**Why:** `store` is `{ users, sessions, tokens }`, and each slot must answer every method of the port. Three methods are optional — `sessions.deleteExpiredSessions`, `tokens.deleteExpiredTokens` and `users.findUsers` — and each is absent, or a function: a value in its place (`findUsers: true`, a property copied from a config) is a wiring mistake, not an absent capability.
|
|
473
|
+
An adapter written for an earlier `@softistx/janus` reports the method a later
|
|
474
|
+
release added to the port: `store.tokens has no method countAttempt` for one
|
|
475
|
+
written against 0.3 (the method came in 0.4), and
|
|
476
|
+
`store.tokens has no method spendUserTokens` for one written against 0.6 (the
|
|
477
|
+
method came in 0.7), and `store.sessions has no method reauthenticateSession`
|
|
478
|
+
for one written against 0.11 (the method came in 0.12).
|
|
479
|
+
|
|
480
|
+
**Fix:** pass the three stores, whole:
|
|
481
|
+
|
|
482
|
+
```ts
|
|
483
|
+
import { createMemoryStores, janus } from '@softistx/janus';
|
|
484
|
+
|
|
485
|
+
janus({ ..., store: createMemoryStores() });
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
Upgrade the published adapter to the release that implements all three —
|
|
489
|
+
`@softistx/janus-drizzle` 0.5, `@softistx/janus-mongo` 0.6, `@softistx/janus-redis` 0.4:
|
|
490
|
+
|
|
491
|
+
```bash
|
|
492
|
+
bun add @softistx/janus@^0.12 @softistx/janus-drizzle@^0.5 # or @softistx/janus-mongo@^0.6, @softistx/janus-redis@^0.4
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
Your own adapter implements them as
|
|
496
|
+
[`TokenStore.countAttempt`](guide/adapters.md#tokenstorecountattempt),
|
|
497
|
+
[`TokenStore.spendUserTokens`](guide/adapters.md#tokenstorespendusertokens) and
|
|
498
|
+
[`SessionStore.reauthenticateSession`](guide/adapters.md#sessionstorereauthenticatesession)
|
|
499
|
+
set out, then runs the conformance suite.
|
|
500
|
+
|
|
501
|
+
### `janus: relations must be a relation store — relations.deleteEntity is missing`
|
|
502
|
+
|
|
503
|
+
**When:** `janus({ ..., relations })`.
|
|
504
|
+
**Why:** `relations` takes the **relation store** — the same one `permissions()` takes as `store` — not what `permissions()` answers, nor the model.
|
|
505
|
+
**Fix:**
|
|
506
|
+
|
|
507
|
+
```ts
|
|
508
|
+
import { createMemoryRelations, permissions } from '@softistx/janus/permissions';
|
|
509
|
+
|
|
510
|
+
const relations = createMemoryRelations();
|
|
511
|
+
const auth = janus({ ..., relations }); // deleting a user deletes their tuples
|
|
512
|
+
const access = permissions({ model, store: relations });
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
### `janus: password.login must name a top-level field of the schema, such as "email"`
|
|
516
|
+
|
|
517
|
+
Also `janus: email must name a top-level field of the schema, such as "email"`, and `janus: password.login: "<field>" is a field janus sets itself`.
|
|
518
|
+
|
|
519
|
+
**When:** `janus({...})`, from JavaScript; TypeScript refuses these on the `login` or `email` key first.
|
|
520
|
+
**Why:** a login and an e-mail are top-level fields of your schema, by name — not a path (`'contact.email'`), and not a field janus sets (`id`, `type`, `active`, `version`, …).
|
|
521
|
+
**Fix:**
|
|
522
|
+
|
|
523
|
+
```ts
|
|
524
|
+
janus({ user: z.object({ username: z.string() }), password: { login: 'username' }, ... });
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
### `janus: password.login "<field>" did not name a string in validated <type> fields — it must name a required string field`
|
|
528
|
+
|
|
529
|
+
**When:** `signUp`, `create` or `update`, when the validated fields have no string at the login field.
|
|
530
|
+
**Why:** the login field is optional or not a string in the schema. TypeScript refuses that shape at compile time; a schema typed loosely gets here.
|
|
531
|
+
**Fix:** make the login a required string: `username: z.string()`, not `z.string().optional()`.
|
|
532
|
+
|
|
533
|
+
### `janus: the user type "<name>" must be a camelCase name — letters and digits, starting with a letter`
|
|
534
|
+
|
|
535
|
+
Also `janus: "<name>" cannot name a user type — janus() answers a method of that name` and `janus: users declares no user type`.
|
|
536
|
+
|
|
537
|
+
**When:** `janus({ users: {...} })`.
|
|
538
|
+
**Why:** each type becomes a property of what `janus()` answers — `auth.staff` — so it must be a name, and not one of the shared methods (`authenticate`, `signOut`, `signOutEverywhere`, `findUser`, `getUser`, `cookie`, `collectExpired`, `types`, `avatar`, `changeEmail`, `verifyEmail`, `resetPassword`).
|
|
539
|
+
**Fix:** `users: { staffMember: {...} }`, not `'staff-member'`, `cookie` or `changeEmail`.
|
|
540
|
+
|
|
541
|
+
### `janus: session.lifespan: "<value>" is not a duration; write a number followed by ms, s, m, h or d — for example "15m" or "720h"`
|
|
542
|
+
|
|
543
|
+
The same for `session.renewAfter`, `session.absolute`, `tokens.verifyEmail`, `tokens.resetPassword`, `tokens.signInCode`, `tokens.magicLink`, `tokens.stepUp`, `tokens.changeEmail`, `secondFactor.challenge` and `signIn.throttle.window` — and, at call time rather than in `janus()`, `assertFresh: maxAge: "<value>" is not a duration; …`, from a `maxAge` written wrong. Also `<option>: a duration must be above zero` and `<option>: a duration in milliseconds must be a finite number above zero`.
|
|
544
|
+
|
|
545
|
+
**When:** `janus({...})`.
|
|
546
|
+
**Why:** a duration is a number of milliseconds, or a number followed by one unit. `'30 m'` compiles — TypeScript's `${number}` accepts the space — and is refused here.
|
|
547
|
+
**Fix:**
|
|
548
|
+
|
|
549
|
+
```ts
|
|
550
|
+
janus({ ..., session: { lifespan: '8h', renewAfter: '30m' }, tokens: { resetPassword: '1h' } });
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
### `janus: cookie.sameSite "none" requires cookie.secure — browsers refuse the cookie otherwise`
|
|
554
|
+
|
|
555
|
+
Also `janus: cookie.name must be a cookie-name token — letters, digits and !#$%&'*+-.^_\`|~, with no space, ";" or "="`.
|
|
556
|
+
|
|
557
|
+
**When:** `janus({ ..., cookie })`.
|
|
558
|
+
**Why:** browsers drop a `SameSite=None` cookie that is not `Secure`, so every sign-in would silently fail to stick.
|
|
559
|
+
**Fix:** keep `secure: true` with `sameSite: 'none'`, or use the default `sameSite: 'lax'` when the site and the API share a site.
|
|
560
|
+
|
|
561
|
+
### `janus: secondFactor.issuer must name your application — the authenticator app shows it beside the account`
|
|
562
|
+
|
|
563
|
+
**When:** `janus({ ..., secondFactor })`, when `issuer` is missing, is not a string, or is blank.
|
|
564
|
+
**Why:** the issuer is the label the authenticator app shows beside the account. Without it, a user with several accounts in the app cannot tell which code is yours.
|
|
565
|
+
**Fix:**
|
|
566
|
+
|
|
567
|
+
```ts
|
|
568
|
+
janus({ ..., secondFactor: { issuer: 'Acme', keys } });
|
|
569
|
+
```
|
|
570
|
+
|
|
571
|
+
### `janus: secondFactor.keys: the key "<id>" is not 32 bytes in base64 — make one with openssl rand -base64 32`
|
|
572
|
+
|
|
573
|
+
Also:
|
|
574
|
+
|
|
575
|
+
- `janus: secondFactor.keys: expected at least one key — [{ id, key }], the first seals`
|
|
576
|
+
- `janus: secondFactor.keys: every key needs an id of letters, digits, _ and -, at most 64 of them`
|
|
577
|
+
- `janus: secondFactor.keys: two keys have the id "<id>"`
|
|
578
|
+
- `janus: secondFactor.keys: entry <n> is not 32 bytes in base64 …` and `entry <n> has the id of an earlier entry`: an id of 43 characters or more may be a key written first (`key:id`), so the message names the entry by position and never echoes it. The same holds for `janus: devices.keys`.
|
|
579
|
+
- `parseSealingKeys` alone: `<where>: entry <n> has an id that looks like key material — write id:key, the id first` (its ids stop at 42 characters; `janus()` takes 64)
|
|
580
|
+
- From `parseSealingKeys`, prefixed with its `where` option (`parseSealingKeys` when none is given), in place of `janus: secondFactor.keys`:
|
|
581
|
+
- `<where>: entry <n> is not id:key — "id:key,id:key", the first seals`
|
|
582
|
+
- `<where>: the key "<id>" is refused here — make a real one with openssl rand -base64 32` (the id is in its `refuse` list)
|
|
583
|
+
- `<where>: expected a string — "id:key,id:key"`
|
|
584
|
+
- `sealerFor: …`: the same key-list messages as above, prefixed `sealerFor:` in place of `janus: secondFactor.keys:`
|
|
585
|
+
- `sealerFor: purpose must be a well-formed string of 1 to 256 characters`: an empty, longer or badly formed (NUL, lone surrogate) purpose
|
|
586
|
+
- `sealerFor: seal(id, plaintext) takes two strings`: `seal` was called with a non-string
|
|
587
|
+
- `sealerFor: seal(id, plaintext) takes a well-formed id and a non-empty, well-formed plaintext`
|
|
588
|
+
- Warning `JANUS_SEALER_UNKNOWN_KEY` (not an error): `unseal` was given a value sealed with a key id the sealer no longer holds, and answered `null`. Put the key back until every value is sealed again (`needsReseal`). For TOTP secrets, `secondFactor.reseal` seals them again in batches (see Rotating the keys in the second-factor guide).
|
|
589
|
+
|
|
590
|
+
**When:** `janus({ ..., secondFactor })`, or `sealerFor(keys, purpose)`.
|
|
591
|
+
**Why:** every TOTP secret is sealed with AES-256-GCM before a store sees it, and that takes a 32-byte key: 43 characters of base64 or base64url, with or without the trailing `=`. A hex key (64 characters), a passphrase, or an environment variable that is not set is refused. The id is written into every secret the key seals, so it is short, plain, and names one key only.
|
|
592
|
+
**Fix:** make each key once and keep it with your other secrets:
|
|
593
|
+
|
|
594
|
+
```sh
|
|
595
|
+
openssl rand -base64 32
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
When the keys live in one variable, `"id:key,id:key"`, read them with `parseSealingKeys` instead of splitting by hand: it applies the same rules at start, names the variable with `where`, and never echoes a key.
|
|
599
|
+
|
|
600
|
+
```ts
|
|
601
|
+
import { parseSealingKeys } from '@softistx/janus';
|
|
602
|
+
|
|
603
|
+
const keys = parseSealingKeys(process.env.TOTP_KEYS ?? '', { where: 'TOTP_KEYS', refuse: ['dev'] });
|
|
604
|
+
```
|
|
605
|
+
|
|
606
|
+
```ts
|
|
607
|
+
janus({
|
|
608
|
+
...,
|
|
609
|
+
secondFactor: {
|
|
610
|
+
issuer: 'Acme',
|
|
611
|
+
keys: [{ id: 'k2026a', key: process.env.TOTP_KEY_K2026A ?? '' }], // the first key seals
|
|
612
|
+
},
|
|
613
|
+
});
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
### `janus: devices.keys: expected at least one key — [{ id, key }], the first seals`
|
|
617
|
+
|
|
618
|
+
Also:
|
|
619
|
+
|
|
620
|
+
- `janus: devices.keys: every key needs an id of letters, digits, _ and -, at most 64 of them`
|
|
621
|
+
- `janus: devices.keys: two keys have the id "<id>"`, and `entry <n> …` by position for an id of 43 characters or more (a swapped `key:id`; never echoed)
|
|
622
|
+
- `janus: devices.keys: the key "<id>" is not 32 bytes in base64 — make one with openssl rand -base64 32`
|
|
623
|
+
|
|
624
|
+
**When:** `janus({ ..., devices })`.
|
|
625
|
+
**Why:** device tokens are signed with these keys, in the format of
|
|
626
|
+
`secondFactor.keys`: a list of at least one `{ id, key }`, the key 32 random
|
|
627
|
+
bytes in base64. An empty list, a key from an environment variable that is
|
|
628
|
+
not set, a hex key or a passphrase is refused.
|
|
629
|
+
**Fix:** make a key of its own — not a sealing key of the second factor's —
|
|
630
|
+
and keep it with your other secrets:
|
|
631
|
+
|
|
632
|
+
```sh
|
|
633
|
+
openssl rand -base64 32
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
```ts
|
|
637
|
+
janus({
|
|
638
|
+
...,
|
|
639
|
+
devices: { keys: [{ id: '2026-09', key: process.env.DEVICES_KEY_2026_09 ?? '' }] }, // the first signs
|
|
640
|
+
});
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
### `list` with a `namePrefix` finds nobody, or not everybody
|
|
644
|
+
|
|
645
|
+
**When:** `auth.list({ namePrefix })` answers an empty page, or misses users you can see.
|
|
646
|
+
|
|
647
|
+
**Why:** the prefix is compared with the user's folded display name, the field `displayName` names (`name` when absent). Three causes: the schema calls the field something else (`fullName`) and `displayName` is not set; the name is not a string; or the user was written before `nameKey` existed (0.66 for `@softistx/janus`) and has not been written since. A prefix is the start of the whole name, not of a word.
|
|
648
|
+
|
|
649
|
+
**Fix:** set `displayName: 'fullName'`, and backfill the older users once ([PostgreSQL](../../janus-drizzle/docs/guide/migrations.md#to-024-a-name-key-on-users), [MongoDB](../../janus-mongo/docs/guide/sync.md#backfilling-name-keys)). A store of your own that ignores `UserFilter.namePrefix` lists everyone instead: run the conformance suite.
|
|
650
|
+
|
|
651
|
+
### `"hasSecondFactor" is a field janus sets itself; rename it`
|
|
652
|
+
|
|
653
|
+
**When:** `tsc`, on the `janus({...})` call, when your schema declares a `hasSecondFactor` field. This version added it to the fields janus sets on every user.
|
|
654
|
+
**Why:** `user.hasSecondFactor` is janus's own answer: whether the user's second factor is active. A field of yours with that name would be shadowed. From JavaScript, a validated input holding it is refused with `USER_INVALID` and the issue `set by janus, not by a request`.
|
|
655
|
+
**Fix:** rename the field in your schema, and read `user.hasSecondFactor` for janus's answer.
|
|
656
|
+
|
|
657
|
+
### `"avatar" is a field janus sets itself; rename it`
|
|
658
|
+
|
|
659
|
+
**When:** `tsc`, on the `janus({...})` call, when your schema declares an `avatar` field. 0.29 added it to the fields janus sets on every user.
|
|
660
|
+
**Why:** `user.avatar` is janus's own answer: `{ id, updatedAt }` for the image the application chose, or `null`. A field of yours with that name would be shadowed. From JavaScript, a validated input holding it is refused with `USER_INVALID` and the issue `set by janus, not by a request`.
|
|
661
|
+
**Fix:** rename the field in your schema (`photoUrl`, say), and read `user.avatar` for janus's answer. `avatar` is also a reserved **user type** name, since the root answers `auth.avatar.set`: a type called `avatar` is refused the same way as one named like a method.
|
|
662
|
+
|
|
663
|
+
Values already stored under the old name stop being read, since `user.avatar` is janus's now. Move them **before** deploying, and deploy `@softistx/janus` with its store adapter together (an older adapter returns no avatar slot):
|
|
664
|
+
|
|
665
|
+
```js
|
|
666
|
+
// MongoDB
|
|
667
|
+
db.users.updateMany(
|
|
668
|
+
{ 'fields.avatar': { $exists: true } },
|
|
669
|
+
{ $rename: { 'fields.avatar': 'fields.photoUrl' } },
|
|
670
|
+
);
|
|
671
|
+
```
|
|
672
|
+
|
|
673
|
+
```sql
|
|
674
|
+
-- PostgreSQL, @softistx/janus-drizzle: the fields are the jsonb column "users"."fields"
|
|
675
|
+
UPDATE "users"
|
|
676
|
+
SET "fields" = ("fields" - 'avatar') || jsonb_build_object('photoUrl', "fields" -> 'avatar')
|
|
677
|
+
WHERE jsonb_exists("fields", 'avatar');
|
|
678
|
+
```
|
|
679
|
+
|
|
680
|
+
The move overwrites a target key a row already holds: pick a name no row uses, or check first.
|
|
681
|
+
|
|
682
|
+
### `janus: events must be a function that takes a user event — webhooks({ … }) from @softistx/janus-webhooks, or your own`
|
|
683
|
+
|
|
684
|
+
**When:** `janus({ events })` with something other than a function — most often an object of functions, one per event type.
|
|
685
|
+
**Why:** `events` is one listener, called with every user event; the event's `type` says which.
|
|
686
|
+
**Fix:** pass one function, and switch on `type`:
|
|
687
|
+
|
|
688
|
+
```ts
|
|
689
|
+
janus({
|
|
690
|
+
...config,
|
|
691
|
+
events(event) {
|
|
692
|
+
if (event.type === 'user.created') return welcome(event.userId);
|
|
693
|
+
},
|
|
694
|
+
});
|
|
695
|
+
```
|
|
696
|
+
|
|
697
|
+
### `janus: signIn.throttle` wiring messages
|
|
698
|
+
|
|
699
|
+
`TypeError`, at `janus()`: `janus: signIn must be an object — { throttle }`,
|
|
700
|
+
`janus: signIn.throttle must be { attempts, window }, or false to count
|
|
701
|
+
nothing`, `janus: signIn.throttle.attempts must be a whole number above
|
|
702
|
+
zero`, and a `janus: signIn.throttle.window` that is not a duration.
|
|
703
|
+
**Fix:** `signIn: { throttle: { attempts: 10, window: '15m' } }` — the
|
|
704
|
+
defaults — or `signIn: { throttle: false }` to count nothing.
|
|
705
|
+
|
|
706
|
+
### `janus: mail.throttle` wiring messages
|
|
707
|
+
|
|
708
|
+
`TypeError`, at `janus()`: `janus: mail must be an object — { throttle }`,
|
|
709
|
+
`janus: mail.throttle must be { attempts, window }, or false to count
|
|
710
|
+
nothing`, `janus: mail.throttle.attempts must be a whole number above zero`,
|
|
711
|
+
and a `janus: mail.throttle.window` that is not a duration.
|
|
712
|
+
**Fix:** `mail: { throttle: { attempts: 5, window: '10m' } }` — the defaults —
|
|
713
|
+
or `mail: { throttle: false }` to count nothing.
|
|
714
|
+
|
|
715
|
+
### `janus: secondFactor.throttle must be { attempts, window }, or false to count nothing`
|
|
716
|
+
|
|
717
|
+
`TypeError`, at `janus()`.
|
|
718
|
+
|
|
719
|
+
**When:** `secondFactor.throttle` is set to something that is neither an object nor `false` — `true`, a number, a string.
|
|
720
|
+
**Why:** the option bounds the codes one account may try at the second step of a sign-in, across all its challenges. It takes its limits as an object, or `false` to count nothing; `true` says nothing about how many.
|
|
721
|
+
**Fix:**
|
|
722
|
+
|
|
723
|
+
```ts
|
|
724
|
+
janus({
|
|
725
|
+
// ...
|
|
726
|
+
secondFactor: {
|
|
727
|
+
issuer: 'My App',
|
|
728
|
+
keys,
|
|
729
|
+
throttle: { attempts: 10, window: '15m' }, // the defaults; `false` counts nothing
|
|
730
|
+
},
|
|
731
|
+
});
|
|
732
|
+
```
|
|
733
|
+
|
|
734
|
+
The window is separate from the one `regenerateRecoveryCodes` uses. A `secondFactor.throttle.window` that is not a duration is refused with the duration messages (see the `maxAge` entries above).
|
|
735
|
+
|
|
736
|
+
### `janus: secondFactor.throttle.attempts must be a whole number above zero`
|
|
737
|
+
|
|
738
|
+
`TypeError`, at `janus()`.
|
|
739
|
+
|
|
740
|
+
**When:** `secondFactor.throttle.attempts` is `0`, negative, fractional, `NaN`, or a string such as `'10'`.
|
|
741
|
+
**Why:** the count is compared with a whole number of codes tried; anything else could never trip or never reset.
|
|
742
|
+
**Fix:**
|
|
743
|
+
|
|
744
|
+
```ts
|
|
745
|
+
janus({
|
|
746
|
+
// ...
|
|
747
|
+
secondFactor: { issuer: 'My App', keys, throttle: { attempts: 10 } },
|
|
748
|
+
});
|
|
749
|
+
```
|
|
750
|
+
|
|
751
|
+
To remove the limit, use `throttle: false` and rate-limit the account yourself; `attempts: 0` is refused.
|
|
752
|
+
|
|
753
|
+
### `janus: tokens.<flow> is 5m, shorter than mail.throttle.window, 10m …`
|
|
754
|
+
|
|
755
|
+
A warning, not an error: `janus()` returns, and emits through
|
|
756
|
+
`process.emitWarning` with the code `JANUS_THROTTLE_WINDOW`, once per call. The
|
|
757
|
+
text, here for `tokens.signInCode: '5m'` with the default window:
|
|
758
|
+
|
|
759
|
+
```
|
|
760
|
+
janus: tokens.signInCode is 5m, shorter than mail.throttle.window, 10m — past the limit the last token sent can expire before the refusal ends. Set mail.throttle.window to 5m or less, or raise tokens.signInCode to 10m or more.
|
|
761
|
+
```
|
|
762
|
+
|
|
763
|
+
With several flows shorter than the window, one warning lists each
|
|
764
|
+
(`tokens.magicLink is 2m, … ; tokens.stepUp is 30s, …`). **Why:** a request the
|
|
765
|
+
mail throttle refuses spends nothing, so the last link or code sent still works,
|
|
766
|
+
but only until it expires; with a lifetime shorter than the window it can lapse
|
|
767
|
+
while the visitor is still refused. **Fix:** make the window no longer than the
|
|
768
|
+
shortest lifetime, or raise the lifetime:
|
|
769
|
+
|
|
770
|
+
```ts
|
|
771
|
+
janus({ user, store, tokens: { signInCode: '5m' }, mail: { throttle: { window: '5m' } } });
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
A runtime without `process.emitWarning` stays silent. Silence it with
|
|
775
|
+
`node --disable-warning=JANUS_THROTTLE_WINDOW`.
|
|
776
|
+
|
|
777
|
+
### Other `janus:` wiring messages
|
|
778
|
+
|
|
779
|
+
| Message | Fix |
|
|
780
|
+
| --- | --- |
|
|
781
|
+
| `janus: expected a configuration object` | Pass an object to `janus()`. |
|
|
782
|
+
| `janus: password.minLength must be an integer of at least 1` | `password: { login: 'email', minLength: 12 }`. |
|
|
783
|
+
| `janus: apiKeys.prefix must be lowercase letters and digits, starting with a letter, at most 16 characters, ending in "_"` | `apiKeys: { prefix: 'sl_', … }`. |
|
|
784
|
+
| `janus: apiKeys.lifetimes must list at least one lifetime …` | List the lifetimes a key may have: `lifetimes: ['30d', '90d']`. There is no default and no unlimited key. |
|
|
785
|
+
| `janus: apiKeys.lifetimes: "<value>" is under one day …` | Each lifetime is at least `'1d'`. |
|
|
786
|
+
| `janus: apiKeys.maxActive must be an integer from 1 to 100` | `maxActive: 10`. |
|
|
787
|
+
| `janus: apiKeys.types: "<name>" is not a user type of this instance` | Name types declared in `user`/`users`, or leave `types` out for every type. |
|
|
788
|
+
| `janus: apiKeys.store: the API key store has no method <method> …` | Pass `createMemoryApiKeys()` or an adapter's `ApiKeyStore`; it is not a slot of `store`. |
|
|
789
|
+
| `janus: password.normalize must be "none", "lowercase", "lowercaseTrim", "nfkcLowercaseTrim" or a function` | One of those names, or `(login) => string`. |
|
|
790
|
+
|
|
791
|
+
---
|
|
792
|
+
|
|
793
|
+
## API keys
|
|
794
|
+
|
|
795
|
+
### `API_KEY_LIMIT` — `apiKeys.create: the user already holds <n> API keys — revoke one first`
|
|
796
|
+
|
|
797
|
+
`ApiKeyLimitError`, 409, carrying `maxActive`.
|
|
798
|
+
|
|
799
|
+
**When:** `apiKeys.create` for a user with `maxActive` standing keys (not revoked, not lapsed).
|
|
800
|
+
**Why:** the user's standing keys were counted before anything was written and already reached the limit. (Two creations racing at the limit are both refused too: each key is inserted, the keys are counted again, and the new one is revoked.)
|
|
801
|
+
**Fix:** answer 409 with `maxActive`; the user revokes a key (`apiKeys.revoke(id, { owner })`) or waits for one to lapse, or raise `apiKeys.maxActive` (at most 100).
|
|
802
|
+
|
|
803
|
+
### `API_KEY_INVALID` — `apiKeys.create: name must be 1 to 100 characters once trimmed` / `lifetime is not one of the configured lifetimes`
|
|
804
|
+
|
|
805
|
+
`ApiKeyInvalidError`, 400, carrying `field`: `'name'` or `'lifetime'` (and `'scopes'` or `'bound'`, [below](#api_key_invalid-with-field-scopes-or-bound)).
|
|
806
|
+
|
|
807
|
+
**When:** `apiKeys.create` with a blank or over-long name, or one holding a NUL or a lone surrogate, or a lifetime not among `apiKeys.lifetimes` (compared as a duration: `'720h'` is `'30d'`).
|
|
808
|
+
**Fix:** answer 400 with `field`; offer the user the configured lifetimes only.
|
|
809
|
+
|
|
810
|
+
### `STEP_UP_REQUIRED` with `reason: 'apiKey'`
|
|
811
|
+
|
|
812
|
+
**When:** `apiKeys.create` or `assertFresh(principal, …)` was given a principal that came in by an API key.
|
|
813
|
+
**Why:** a key never proves who anyone is, so it is never fresh and cannot create a key; a step-up does not help it. `apiKeys.create` can also answer `STEP_UP_REQUIRED` to a session without `reason`: the password was written after that session proved who it is (a reset or `changePassword`), or the session ended meanwhile (a reset or a first proof of the e-mail), and the key just made was revoked. Sign in again or confirm a step-up, then create the key.
|
|
814
|
+
**Fix:** create keys from a signed-in session. Without `reason: 'apiKey'`, the session is merely stale: ask for a [step-up](guide/step-up.md).
|
|
815
|
+
|
|
816
|
+
### `TS2769: No overload matches this call` on `authenticate(request, { apiKey })`
|
|
817
|
+
|
|
818
|
+
**When:** the option is not the literal `true`, for example `authenticate(request, { apiKey: wantsKey })` with `wantsKey: boolean`. TypeScript reports `Type 'boolean' is not assignable to type 'true'` (and `'false'` for the first overload).
|
|
819
|
+
**Why:** `authenticate` has two overloads. Without the option, or with `apiKey: false`, it answers `Authenticated | null`; with `apiKey: true` it answers `Principal | null`, whose `via` tells a session from a key. A `boolean` is neither, so the type of the answer would be a guess.
|
|
820
|
+
**Fix:** branch on the condition and call with a literal each way:
|
|
821
|
+
|
|
822
|
+
```ts
|
|
823
|
+
const principal = wantsKey
|
|
824
|
+
? await auth.authenticate(request, { apiKey: true })
|
|
825
|
+
: await auth.authenticate(request);
|
|
826
|
+
```
|
|
827
|
+
|
|
828
|
+
### A valid API key answers `null` (anonymous)
|
|
829
|
+
|
|
830
|
+
**When:** a script sends `Authorization: Bearer sl_…` and `authenticate` answers `null`.
|
|
831
|
+
**Why:** keys are opt-in per call. Without `apiKey: true`, a key-shaped bearer is anonymous. A key is read from `Authorization: Bearer` and nowhere else: one sent in the session cookie or in `X-Session-Token` is not a key, and is anonymous. Otherwise the key is revoked or lapsed, its user is inactive, of a type outside `apiKeys.types` or other than `options.type`, or the token was cut or altered (it must be the prefix, 32 hex characters, `_`, 43 characters).
|
|
832
|
+
**Fix:** `await auth.authenticate(request, { apiKey: true })` on the routes meant for scripts, and send the key as `Authorization: Bearer sl_…`; check the key with `apiKeys.list(user)`. A store outage is not `null`: it rejects with `STORE_FAILED`. `apiKey: true` on an instance wired without `apiKeys` is a `TypeError`.
|
|
833
|
+
|
|
834
|
+
### `JANUS_API_KEY_REVOKE_FAILED` process warning
|
|
835
|
+
|
|
836
|
+
**When:** `apiKeys.create` stored a key, then one of its checks after the insert failed (a refusal, such as a race at `maxActive`, or a store outage), and revoking the key failed too. Node prints `janus: an API key could not be revoked after its creation failed: <error name>` with the code `JANUS_API_KEY_REVOKE_FAILED`; the original error is still thrown.
|
|
837
|
+
**Why:** the token is only answered when the checks pass, so nobody holds it. The key may still stand, though, and holds one of the user's `maxActive` slots until it lapses.
|
|
838
|
+
**Fix:** revoke it through `apiKeys.revoke` (find it with `apiKeys.list(user)`; a key never used and not named by the user is the one), and look at the store outage behind the warning:
|
|
839
|
+
|
|
840
|
+
```ts
|
|
841
|
+
const { items } = await auth.apiKeys.list(user); // oldest first
|
|
842
|
+
const stuck = items.findLast((key) => key.lastUsedAt === null && key.revokedAt === null);
|
|
843
|
+
if (stuck) await auth.apiKeys.revoke(stuck.id, { owner: user });
|
|
844
|
+
```
|
|
845
|
+
|
|
846
|
+
### `API_KEY_INVALID` with `field: 'scopes'` or `'bound'`
|
|
847
|
+
|
|
848
|
+
`apiKeys.create: scopes must be 1 to 32 distinct tokens of 1 to 100 printable characters, with no space, quote or backslash` / `apiKeys.create: bound must be { type, id }, a type of 1 to 64 characters and an id of 1 to 200`.
|
|
849
|
+
|
|
850
|
+
**When:** `apiKeys.create` with `scopes` that is not an array of 1 to 32 scope tokens (an empty array included), or a `bound` that is not an object with string `type` and `id` of those lengths, or holds a NUL or a lone surrogate. Nothing is written.
|
|
851
|
+
**Why:** both come from a request and are stored with the key, so they are checked like `name`.
|
|
852
|
+
**Fix:** answer 400 with `field`. Leave `scopes` out for a key that may do everything its user may; do not send `[]`.
|
|
853
|
+
|
|
854
|
+
### `TypeError: apiKeys.create: the API key store does not implement listBoundApiKeys and revokeBoundApiKeys`
|
|
855
|
+
|
|
856
|
+
`…, so it cannot keep scopes or a bound object`; the same message prefixed `apiKeys.listBound`, `apiKeys.revokeAllBound` or `apiKeys.list`.
|
|
857
|
+
|
|
858
|
+
**When:** `create` with `scopes` or `bound`, `listBound` / `revokeAllBound`, or `list(user, { bound })` (an object or `null`), on an instance whose key store lacks the optional `bound` capability.
|
|
859
|
+
**Why:** a store without it would drop the fields, and a restricted key would come back as a full one. It is a wiring mistake, so a `TypeError` before anything is written.
|
|
860
|
+
**Fix:** use a store that has it (`createMemoryApiKeys()`, `createMongoApiKeys(db)` of `@softistx/janus-mongo`), or add both methods to yours and run `describeApiKeyStores` on it.
|
|
861
|
+
|
|
862
|
+
### `TypeError: … does not implement listExpiringApiKeys and markApiKeyExpiryNotified`
|
|
863
|
+
|
|
864
|
+
**When:** `apiKeys.expiring` or `apiKeys.markExpiryNotified` on an instance whose key store lacks the optional `expiryNotice` capability. A `within` that is not a duration (`apiKeys.expiring: within: …`) is a `TypeError` too.
|
|
865
|
+
**Fix:** use a store that has it, or add both methods; pass `within` as `'7d'` or a number of milliseconds above zero.
|
|
866
|
+
|
|
867
|
+
### `assertApiKeyStore`: `has listBoundApiKeys without revokeBoundApiKeys: the bound capability needs both`
|
|
868
|
+
|
|
869
|
+
The same for `expiryNotice` (`listExpiringApiKeys`, `markApiKeyExpiryNotified`), and `… must be a function or absent` for a method that is set to something else.
|
|
870
|
+
|
|
871
|
+
**When:** `janus({ apiKeys: { store } })` or `assertApiKeyStore` on a store with half of an optional capability.
|
|
872
|
+
**Why:** the core would use the half that is there and fail on the other at the first call.
|
|
873
|
+
**Fix:** implement both methods of the pair, or neither.
|
|
874
|
+
|
|
875
|
+
### `assertApiKeyStore`: `has listUserBoundApiKeys without the bound capability (listBoundApiKeys and revokeBoundApiKeys): the userBound capability needs it`
|
|
876
|
+
|
|
877
|
+
**When:** `janus({ apiKeys: { store } })` or `assertApiKeyStore` on a store with `listUserBoundApiKeys` but not both methods of `bound`.
|
|
878
|
+
**Why:** `userBound` is a filter over the keys `bound` stores; a store that does not keep `bound` has nothing to filter.
|
|
879
|
+
**Fix:** implement `listBoundApiKeys` and `revokeBoundApiKeys` too, or drop `listUserBoundApiKeys`: without it `apiKeys.list(user, { bound })` reads the user's keys and filters them.
|
|
880
|
+
|
|
881
|
+
### `authenticate: apiKey: true needs janus({ apiKeys }) — no API keys are configured`
|
|
882
|
+
|
|
883
|
+
**When:** `authenticate(request, { apiKey: true })` on an instance wired without `apiKeys`.
|
|
884
|
+
**Why:** a wiring mistake, so a `TypeError` rather than anonymous.
|
|
885
|
+
**Fix:** add `apiKeys: { store, prefix, lifetimes }` to `janus()`, or drop `apiKey: true`.
|
|
886
|
+
|
|
887
|
+
---
|
|
888
|
+
|
|
889
|
+
## Invitations
|
|
890
|
+
|
|
891
|
+
### `INVITATION_INVALID` — `invitations.preview: this code names no pending invitation`
|
|
892
|
+
|
|
893
|
+
`InvitationInvalidError`, 400, with `field: 'code'`. The same message comes from `invitations.accept`, with the prefix `invitations.accept:` (`invitations.accept: this code names no pending invitation`).
|
|
894
|
+
|
|
895
|
+
**When:** `preview` or `accept` was given a code that names no pending, unlapsed invitation. `accept` also answers it for a deactivated user, when the invitation's version moved under it (a write outside Janus: `revoke` and `resend` refuse a claimed invitation), and when creating the user met a login another user holds (`LOGIN_TAKEN`).
|
|
896
|
+
**Why:** the code is unknown or malformed (a link cut by a mail client, a code copied with its trailing characters missing), or the invitation was accepted, revoked, replaced by a newer `issue` (the old link stops working) or has lapsed (`lifetime`, `'7d'` by default). One code covers all of them, but `error.reason` says which: `'unknown'`, `'expired'`, `'accepted'` or `'revoked'` (a code is its holder's own secret, so naming the reason discloses nothing). A deactivated user, a taken login and a lost race stay `'unknown'`, so a response cannot tell which accounts exist. Of two concurrent `accept`s on one code, the loser gets it too. A deactivated user's invitation is refused alike, so the response does not say an account exists; the claim is released.
|
|
897
|
+
**Fix:** switch on `error.reason` for a precise message (`expired`: ask for a new link; `accepted`: sign in; `revoked`: contact the inviter; `unknown`: check the link), or answer 400 with a message that fits every cause: "this invitation is no longer valid — ask whoever invited you to send it again". The inviter uses `list(scope)` to see its status and `resend({ id, scope })` for a new code (it also revives a lapsed one). Check the link carries the whole code: `encodeURIComponent(code)` when building it, `searchParams.get('code')` when reading it.
|
|
898
|
+
|
|
899
|
+
### `INVITATION_INVALID` — `invitations.issue: email must be an address with one "@"` (and the other fields)
|
|
900
|
+
|
|
901
|
+
`InvitationInvalidError`, 400, with `field`: `'email'`, `'name'`, `'role'`, `'scope'`, `'locale'`, `'ref'`, `'type'` or `'invitedBy'`. For `'type'` the message is `invitations.issue: type must be one of "staff", "guardian"`: with several `invitations.type` listed, `issue` needs one of them.
|
|
902
|
+
|
|
903
|
+
**When:** `invitations.issue` was given a field it cannot keep: an address without exactly one `@`, a blank or over-long `scope`, `name`, `role`, `locale` or `ref` (1 to 100 characters), or an `invitedBy` that is neither a user, a user id nor `null` (`null` is a system issue; leaving the key out is refused). Nothing was written.
|
|
904
|
+
**Why:** the values come from a request and were not checked on the way in.
|
|
905
|
+
**Fix:** answer 400 naming `field`, and validate the form before calling `issue`.
|
|
906
|
+
|
|
907
|
+
### `TypeError` — `invitations.issue: the invitation store did not keep the invitation's type`
|
|
908
|
+
|
|
909
|
+
A bare `TypeError`, thrown at call time. The full message ends `with several invitation types, the store must keep \`type\` — update the adapter`.
|
|
910
|
+
|
|
911
|
+
**When:** `invitations.issue` on an instance whose `invitations.type` lists several user types.
|
|
912
|
+
**Why:** the `InvitationStore` dropped `InvitationRecord.type` (or changed it) when it kept the invitation: `issue` reads the record back once and finds a different type. Left alone, every invitation would read as the first type listed. This is a defect of the adapter, not of the request.
|
|
913
|
+
**Fix:** make `insertInvitation` store `type` as given, `null` included, and return it from `findInvitation` and `findInvitationByCodeHash`. Run `describeInvitationStores` from `@softistx/janus/conformance`: the case `invitations.insert.type` fails on such a store. `@softistx/janus-mongo` and `@softistx/janus-drizzle` keep it from the release that adds it (the Mongo sync and the Drizzle migration come first).
|
|
914
|
+
|
|
915
|
+
### `PASSWORD_REQUIRED` — `invitations.accept: choose a password to accept this invitation`
|
|
916
|
+
|
|
917
|
+
`PasswordRequiredError`, 400.
|
|
918
|
+
|
|
919
|
+
**When:** `invitations.accept` for an invitee who has no usable account yet — nobody holds the address, or a user holds it with an e-mail never proved — and no `password` was given.
|
|
920
|
+
**Why:** the password they choose is what they sign in with from now on. An invitee whose address belongs to a proved account that has a password needs none; `preview(code).needsPassword` says which case it is, so the page can show the field before it calls `accept`.
|
|
921
|
+
**Fix:** nothing was written and the invitation is still pending: show the password field and call `accept` again with it. Send `password` whenever the form has one; it is ignored for a proved account.
|
|
922
|
+
|
|
923
|
+
```ts
|
|
924
|
+
try {
|
|
925
|
+
return await auth.invitations.accept({ code, password });
|
|
926
|
+
} catch (error) {
|
|
927
|
+
if (error instanceof PasswordRequiredError) return Response.json({ code: error.code }, { status: 400 });
|
|
928
|
+
throw error;
|
|
929
|
+
}
|
|
930
|
+
```
|
|
931
|
+
|
|
932
|
+
### `PASSWORD_TOO_SHORT` on `invitations.accept`
|
|
933
|
+
|
|
934
|
+
`CredentialError`, 400, with `minLength`.
|
|
935
|
+
|
|
936
|
+
**When:** `invitations.accept` with a `password` under the user type's `password.minLength`.
|
|
937
|
+
**Why:** the password is checked against the type's policy before any user is made, as `signUp` would. The invitation was claimed first, so it is released on this failure.
|
|
938
|
+
**Fix:** no user was made and the invitation is pending again. Answer 400 with `minLength` and let the invitee try again; check the length in the form first.
|
|
939
|
+
|
|
940
|
+
### `INVITATION_PENDING` — `invitations.issue: another pending invitation holds this scope and address`
|
|
941
|
+
|
|
942
|
+
`StoreConflict` (`on: 'pending'`), 409.
|
|
943
|
+
|
|
944
|
+
**When:** `invitations.issue` (or a call to the store) could not take the place of the pending invitation for this scope and address.
|
|
945
|
+
**Why:** a scope and address hold one pending invitation, and the store enforces it. `issue` revokes the invitation that was pending when it began and tries again. It surfaces when another `issue` for the same address won the place meanwhile (the loser never revokes that winner, so exactly one invitation stays pending), or when a store is called directly with a write that would make a second one pending.
|
|
946
|
+
**Fix:** answer 409 and let the inviter try again; the invitation that won the place stands. Do not call `issue` in a loop for one address.
|
|
947
|
+
|
|
948
|
+
### `INVITATION_LIMIT` — `invitations.issue: the scope already holds <n> pending invitations — revoke one first`
|
|
949
|
+
|
|
950
|
+
`InvitationLimitError`, 409, carrying `maxActive`. The message starts `invitations.resend:` for a resend.
|
|
951
|
+
|
|
952
|
+
**When:** `invitations.issue`, or `resend` of a lapsed invitation, into a scope with `maxPending` invitations that are pending and not lapsed, none of them this address's own.
|
|
953
|
+
**Why:** `maxPending` counts pending invitations that have not lapsed, per scope. Re-inviting an address that already has one never hits it: that replaces the old invitation.
|
|
954
|
+
**Fix:** answer 409 with `maxActive`; revoke one (`revoke({ id, scope })`), wait for one to lapse, or raise `invitations.maxPending` (at most 10000).
|
|
955
|
+
|
|
956
|
+
### `TypeError` — `invitations.importHistory: records must be an array` (and the other call shapes)
|
|
957
|
+
|
|
958
|
+
Also `invitations.importHistory: at most 1000 records per call`, `invitations.importHistory: options must be an object` and `invitations.importHistory: options.dryRun must be a boolean`.
|
|
959
|
+
|
|
960
|
+
**When:** `invitations.importHistory(records, options)`, before anything is read or written.
|
|
961
|
+
**Why:** `records` was not an array (a single record, `null`), held more than 1000 records, or `options` was not `{ dryRun?: boolean }`.
|
|
962
|
+
**Fix:** pass an array, cut a bigger import into calls of at most 1000, and pass a real boolean:
|
|
963
|
+
|
|
964
|
+
```ts
|
|
965
|
+
for (let from = 0; from < records.length; from += 1000) {
|
|
966
|
+
await auth.invitations.importHistory(records.slice(from, from + 1000), { dryRun: false });
|
|
967
|
+
}
|
|
968
|
+
```
|
|
969
|
+
|
|
970
|
+
### `importHistory` refuses a record: `invalid`, `unknown-type`, `live-pending`, `pending-held`, `duplicate-key`, `key-taken`
|
|
971
|
+
|
|
972
|
+
Not thrown: the report's item says `outcome: 'refused'` with a `reason`, and the other records go on.
|
|
973
|
+
|
|
974
|
+
**When:** `invitations.importHistory`, for that record.
|
|
975
|
+
**Why:** by `reason`:
|
|
976
|
+
- `invalid`: a field is not valid; `field` names it (`key`, `scope`, `email`, `createdAt` outside the years 1970 to 10889, `acceptedAt`, `acceptedBy` that is no Janus user id, …). The value is never echoed.
|
|
977
|
+
- `unknown-type`: `type` is not one of `invitations.type`.
|
|
978
|
+
- `live-pending`: a `pending` record whose `expiresAt` is still ahead; the invitee may hold a working link. Issue it with `issue`.
|
|
979
|
+
- `pending-held`: a `pending` record whose scope and address already hold a pending invitation.
|
|
980
|
+
- `duplicate-key`: the scope and `key` appear twice in the call.
|
|
981
|
+
- `key-taken`: the scope and `key` were imported before with another `createdAt`; `id` is the stored record's.
|
|
982
|
+
**Fix:** correct the field in your data and run again (records already imported are `present`); for `key-taken`, give the same `createdAt` as the first import.
|
|
983
|
+
|
|
984
|
+
### `INVITATION_NOT_PENDING` — `invitations.resend: the invitation is accepted`
|
|
985
|
+
|
|
986
|
+
`InvitationNotPendingError`, 409. The message ends with the status (`accepted` or `revoked`) and names `resend` or `revoke`.
|
|
987
|
+
|
|
988
|
+
**When:** `invitations.resend` or `revoke` on an invitation that has been accepted or revoked. Nothing was written.
|
|
989
|
+
**Why:** only a pending invitation — lapsed or not — can be sent again or taken back. A revoked one is final; the invitee is invited with a new `issue`.
|
|
990
|
+
**Fix:** answer 409; to invite the person again, `issue` for the same address.
|
|
991
|
+
|
|
992
|
+
### `INVITATION_REFUSED` — `invitations.accept: the application refused this acceptance`
|
|
993
|
+
|
|
994
|
+
`InvitationRefusedError`, 403.
|
|
995
|
+
|
|
996
|
+
**When:** `invitations.accept` with a valid code, and the `invitations.beforeAccept` hook returned `false`.
|
|
997
|
+
**Why:** `beforeAccept` runs before the claim, the user, the proof of the e-mail and the password, so nothing was written: the invitation is still pending, no user was made or changed, `onAccepted` did not run.
|
|
998
|
+
**Fix:** answer 403 and tell the person what the application checks (the invited person no longer exists, the address is linked elsewhere…). The same code can be accepted once the condition changes. A hook that throws is not a refusal: its error surfaces as it is.
|
|
999
|
+
|
|
1000
|
+
### A retry after a failed `onAccepted` answers `signIn`
|
|
1001
|
+
|
|
1002
|
+
**When:** `invitations.accept` threw because `onAccepted` threw (the database was down while adding the member, say). The page showed an error, the invitee submitted again with the same code, and the second `accept` answers `{ status: 'signIn' }` — no session, no password asked.
|
|
1003
|
+
**Why:** the first try did what comes before `onAccepted`: it created the user, proved their e-mail and set the password they chose. Then `onAccepted` threw and the invitation was released, so the code works again. The retry finds a user whose e-mail is proved and, as for any proved account, signs nobody in: an invitation proves the inbox, not who holds the account. `onAccepted` runs again on the retry.
|
|
1004
|
+
**Fix:** the accept page handles `signIn` after an error as it does at any time: send the person to the sign-in page, where the password they just chose works. Make `onAccepted` safe to run twice for one user.
|
|
1005
|
+
|
|
1006
|
+
```ts
|
|
1007
|
+
const accepted = await auth.invitations.accept({ code, password });
|
|
1008
|
+
if (accepted.status === 'signIn') return redirect('/sign-in?invited=1'); // the account exists; sign in with your password
|
|
1009
|
+
```
|
|
1010
|
+
|
|
1011
|
+
A retry after the first try failed on `setPassword` itself is different: the user was proved and holds no password, so the retry sets the `password` it is given and answers `signedIn`. Send `password` on every try.
|
|
1012
|
+
|
|
1013
|
+
### `JANUS_INVITATION_RELEASE_FAILED` process warning
|
|
1014
|
+
|
|
1015
|
+
**When:** `invitations.accept` failed after claiming the invitation, and giving the claim back failed too (a store outage).
|
|
1016
|
+
**Why:** the invitation is left `accepted` although nobody was added to the scope (or, if a newer pending invitation for the same address took the place meanwhile, the old one cannot go back to pending). The error you caught is the first failure; the warning names the second.
|
|
1017
|
+
**Fix:** look at the store outage behind the warning. Then `issue` the invitation again for the same address: the accepted one is final, and the new invitation has a new code. If a user was created and their e-mail proved, they can also just sign in.
|
|
1018
|
+
|
|
1019
|
+
### `janus: invitations …` wiring messages
|
|
1020
|
+
|
|
1021
|
+
| Message | Fix |
|
|
1022
|
+
| --- | --- |
|
|
1023
|
+
| `janus: invitations must be an object` | `invitations: { store, create, onAccepted }`. |
|
|
1024
|
+
| `janus: invitations.create must be a function that returns the fields of the user an invitation makes` | `create: (invitation) => ({ email: invitation.email, name: invitation.name })`. |
|
|
1025
|
+
| `janus: invitations.onAccepted must be a function: where the application adds the new user to the scope` | Pass the function that adds the user to the scope with the invitation's role. |
|
|
1026
|
+
| `janus: invitations.beforeAccept must be a function that may refuse an acceptance` | `beforeAccept: ({ invitation, user }) => boolean | Promise<boolean>`, or leave it out. |
|
|
1027
|
+
| `janus: invitations.events must be a function that takes an invitation event` | A function, called once per `invitation.*` event. |
|
|
1028
|
+
| `janus: invitations.maxPending must be an integer from 1 to 10000` | Or leave it out for no limit. |
|
|
1029
|
+
| `janus: invitations.type must name the user type an invitation makes: this instance has several` | With `users`, name the type: `type: 'member'`. |
|
|
1030
|
+
| `janus: invitations.type: "<name>" is not a user type of this instance` | Name a type declared in `user`/`users`. |
|
|
1031
|
+
| `janus: invitations.type: "<name>" must have no password, or sign in with a password whose login is its e-mail …` | The type needs `password: { login: 'email' }` (an invitee chooses a password for the address they were invited at), or no `password` at all. |
|
|
1032
|
+
| `janus: invitations.type must be a user type, or a non-empty list of distinct user types` | `type: 'staff'` or `type: ['staff', 'guardian']`, never `[]`. |
|
|
1033
|
+
| `janus: invitations.type: "<name>" is listed twice` | Each type once. |
|
|
1034
|
+
| `janus: invitations.store: the invitation store has no method <method> …` | Pass `createMemoryInvitations()` or an adapter's `InvitationStore`; it is not a slot of `store`. |
|
|
1035
|
+
|
|
1036
|
+
## Users, sessions and tokens
|
|
1037
|
+
|
|
1038
|
+
### A signed-in user is sent to sign in again although the session was used a minute ago
|
|
1039
|
+
|
|
1040
|
+
**When:** `session.absolute` is set, and the sign-in is older than the cap.
|
|
1041
|
+
**Why:** the cap counts from when the session was opened and no use extends it; `authenticate` answers `null` and `stepUp.confirm` rejects with `TOKEN_UNKNOWN`. It also applies to sessions opened before the option was added.
|
|
1042
|
+
**Fix:** this is the cap working. Send the user to sign in; raise `session.absolute`, or remove it for a sliding-only session.
|
|
1043
|
+
|
|
1044
|
+
### `STORE_FAILED` — `<slot>.<method>: the store could not answer`
|
|
1045
|
+
|
|
1046
|
+
`StoreFailure`, for example `users.findUserByLogin: the store could not answer`.
|
|
1047
|
+
|
|
1048
|
+
**When:** any call that reaches the store — `authenticate`, `signIn`, `get`, `can` — while the database is down, times out, or the adapter throws.
|
|
1049
|
+
**Why:** a store that cannot answer throws; it never answers `null`. The driver's own error is on `error.cause` — not in the message, because a driver message can hold a connection string, and a connection string holds a password.
|
|
1050
|
+
**Fix:** answer **503**, and log `cause`. Never map it to 401, 404, `null` or `false`: that turns an outage into a silent lockout, where every user is told they do not exist.
|
|
1051
|
+
|
|
1052
|
+
**After a password write** — `resetPassword.confirm`, `changePassword`, `setPassword` — the failure may come from spending the user's reset links and second-factor challenges, which runs after the password is written: the new password is then in place. A `STORE_FAILED` from `changePassword` may therefore follow a written change: check with `signIn` using `next` before retrying. A retried `changePassword` with the old `current` answers `CREDENTIALS_INVALID`; the next `resetPassword.request` spends any link left live.
|
|
1053
|
+
|
|
1054
|
+
```ts
|
|
1055
|
+
import { JanusError } from '@softistx/janus';
|
|
1056
|
+
|
|
1057
|
+
try {
|
|
1058
|
+
return await auth.authenticate(request);
|
|
1059
|
+
} catch (error) {
|
|
1060
|
+
if (error instanceof JanusError && error.code === 'STORE_FAILED') {
|
|
1061
|
+
console.error(error.cause);
|
|
1062
|
+
return new Response('Try again shortly', { status: 503 });
|
|
1063
|
+
}
|
|
1064
|
+
throw error;
|
|
1065
|
+
}
|
|
1066
|
+
```
|
|
1067
|
+
|
|
1068
|
+
### `STORE_FAILED` — `tokens.insertToken: the store could not answer`, on `changeEmail.send` alone
|
|
1069
|
+
|
|
1070
|
+
`StoreFailure`, whose `error.cause` reads `new row for relation "tokens" violates check constraint "tokens_kind"` with `@softistx/janus-drizzle`, or `Document failed validation` with `@softistx/janus-mongo`.
|
|
1071
|
+
|
|
1072
|
+
**When:** `changeEmail.send`, on a database not yet migrated for the `changeEmail` token kind; every other call works.
|
|
1073
|
+
**Why:** `changeEmail` is a token kind of its own, and the adapter's table (drizzle's `tokens_kind` check) or collection validator (mongo's `kind` enum) does not list it yet.
|
|
1074
|
+
**Fix:** `@softistx/janus-drizzle` 0.8: apply its migration (`drizzle-kit migrate`). `@softistx/janus-mongo` 0.9: run `syncMongoAdapter` once at start-up (`syncMongoStores` for an application that only authenticates, as the sync guide says). Until then answer 503, as for any outage.
|
|
1075
|
+
|
|
1076
|
+
### `STORE_FAILED` — `<slot>.<method> answered undefined: an absence is null, so this store forgot to answer`
|
|
1077
|
+
|
|
1078
|
+
**When:** with a store you wrote, on the first call to that method.
|
|
1079
|
+
**Why:** a method that can find nothing must answer `null`. `undefined` is also what a missing `return` produces, so it is treated as a bug in the store, not as "not found".
|
|
1080
|
+
**Fix:** `return doc ?? null;` — and run `@softistx/janus/conformance` against the store.
|
|
1081
|
+
|
|
1082
|
+
### `STORE_FAILED` — `users.findUsers answered no list: an absence is a shorter list, so this store forgot to answer`
|
|
1083
|
+
|
|
1084
|
+
**When:** `findMany`, over a users store you wrote that implements the optional `findUsers`.
|
|
1085
|
+
**Why:** `findUsers` answered `null`, `undefined` or something else than an array. An id nobody holds is left out of the list, and nobody at all is `[]`; anything else is a store that forgot to answer, so it fails rather than read as "nobody".
|
|
1086
|
+
**Fix:** answer the rows you found, mapped to records — or leave `findUsers` out, and `findMany` reads with `findUser`:
|
|
1087
|
+
|
|
1088
|
+
```ts
|
|
1089
|
+
findUsers: async (ids) => (await db.users.where('id', 'in', ids)).map(toUser), // [] when none
|
|
1090
|
+
```
|
|
1091
|
+
|
|
1092
|
+
### `<call>: ids must be an array of user ids`
|
|
1093
|
+
|
|
1094
|
+
A bare `TypeError` — `findMany: …`, or `staff.findMany: …` with several user types.
|
|
1095
|
+
|
|
1096
|
+
**When:** `findMany` was given something other than an array: one id, a `Set`, a comma-separated string.
|
|
1097
|
+
**Why:** `findMany` takes a list; one id is `find`. Only your code passes the wrong shape, and TypeScript refuses it.
|
|
1098
|
+
**Fix:** pass an array, or use `find` for one id:
|
|
1099
|
+
|
|
1100
|
+
```ts
|
|
1101
|
+
await auth.staff.findMany([...selectedIds]); // from a Set
|
|
1102
|
+
await auth.staff.find(id); // one id
|
|
1103
|
+
```
|
|
1104
|
+
|
|
1105
|
+
### `findMany` answers fewer users than ids
|
|
1106
|
+
|
|
1107
|
+
**When:** always, when an id is malformed, unknown, held by a user of another type, or repeated.
|
|
1108
|
+
**Why:** `findMany` leaves out what `find` answers `null` for, and answers a repeated id once — it never puts `null` in a place. Reading `users[i]` as the user of `ids[i]` then shows one row's account on another.
|
|
1109
|
+
**Fix:** match by id:
|
|
1110
|
+
|
|
1111
|
+
```ts
|
|
1112
|
+
const byId = new Map((await auth.staff.findMany(ids)).map((user) => [user.id, user]));
|
|
1113
|
+
const member = byId.get(row.staffId); // undefined: nobody of this type holds it
|
|
1114
|
+
```
|
|
1115
|
+
|
|
1116
|
+
### `findByEmail` answers `null` for an address somebody holds
|
|
1117
|
+
|
|
1118
|
+
**When:** `auth.<type>.findByEmail(email)` on an address you can see on a user.
|
|
1119
|
+
**Why:** one of three. The user is of **another type**: each type answers its own users, and the same address may hold one of each. The address is the type's **login, not its e-mail**: on a type that signs in with a username, only the field `email` names is looked up, and a username that looks like an address is nobody's. Or the value is **no address**: not a string — a `{ email }` object from JavaScript, an `undefined` read off a record — empty once trimmed, or holding a NUL or a lone surrogate; it answers `null` without asking the store, as `find` answers a malformed id.
|
|
1120
|
+
**Fix:** ask the type the user is of, pass the e-mail itself, and for a username use `findByLogin`:
|
|
1121
|
+
|
|
1122
|
+
```ts
|
|
1123
|
+
const member = await clinic.member.findByEmail(invitation.email); // a string: the address the invitation holds
|
|
1124
|
+
const staff = await clinic.staff.findByLogin('grace'); // a username is a login, not an e-mail
|
|
1125
|
+
```
|
|
1126
|
+
|
|
1127
|
+
An outage is never `null` here: it rejects with `STORE_FAILED`.
|
|
1128
|
+
|
|
1129
|
+
### `NOT_FOUND` — `<call>: no <type> has this id`
|
|
1130
|
+
|
|
1131
|
+
`NotFoundError`, from `get`, `getUser`, `update`, `setActive`, `setPassword`, `signInProven`, `verifyEmail.send`, `verifyEmail.proveFirst`, `setEmailVerified`, `secondFactor.recoveryCodesLeft`. Also `<call>: the user has no e-mail`.
|
|
1132
|
+
|
|
1133
|
+
**When:** the id names nobody, names a user of another type (`auth.staff.get(patientId)`), or is not an id at all.
|
|
1134
|
+
**Why:** `get*` calls turn an absence into `NOT_FOUND`; `find*` calls answer `null` instead. `signInProven` is a `get`: a sign-in that found nobody throws, and on it `NOT_FOUND` means the proof you verified names a user deleted since, or you passed the id of another type's user — or a value that is not the proof's id at all.
|
|
1135
|
+
**Fix:** answer 404, or use `find` when absence is an ordinary outcome:
|
|
1136
|
+
|
|
1137
|
+
```ts
|
|
1138
|
+
const user = await auth.find(id); // null when there is nobody
|
|
1139
|
+
```
|
|
1140
|
+
|
|
1141
|
+
### `AVATAR_ID_INVALID` — `<call>: the avatar id must be a non-empty string of at most 512 characters that every store can keep`
|
|
1142
|
+
|
|
1143
|
+
**When:** `avatar.set`, as `avatar.set` or `<type>.avatar.set` — before the user is read. Most often an id the upload step did not produce: `undefined` from a failed storage call, an empty string, a whole URL longer than 512 characters, or a string with a NUL or a lone surrogate.
|
|
1144
|
+
**Why:** the id is what the application finds its image by, and janus only has to store it: a non-empty string of at most 512 characters that every store can keep, never parsed. The message names the shape and never the id.
|
|
1145
|
+
**Fix:** pass the fresh id you stored the image under — and set it only after the upload succeeded:
|
|
1146
|
+
|
|
1147
|
+
```ts
|
|
1148
|
+
const id = crypto.randomUUID();
|
|
1149
|
+
await store.replace({ imageId: id }, bytes);
|
|
1150
|
+
await auth.avatar.set(userId, { id }); // auth.<type>.avatar.set with several types
|
|
1151
|
+
```
|
|
1152
|
+
|
|
1153
|
+
### `LOGIN_TAKEN` — `<call>: the login is taken by another <type>`
|
|
1154
|
+
|
|
1155
|
+
`StoreConflict` with `on: 'login'`, carrying `login` and `userType`. The login is not in the message, which never carries a value: an e-mail in a log line is personal data. Read it from `error.login`.
|
|
1156
|
+
|
|
1157
|
+
**When:** `signUp`, `create`, or an `update` that changes the login, when another user of **the same type** holds it after normalisation (`Ada@Example.com` and `ada@example.com` collide by default). `findOrCreate` rethrows it only when its re-read of the key still finds nobody — another login of the new user (its e-mail, beside a username) is taken; a race lost on the key itself answers `{ user, created: false }` instead.
|
|
1158
|
+
**Why:** the store's unique constraint refused the write. A login is unique per user type: one e-mail may hold a patient user and a staff user.
|
|
1159
|
+
**On `changeEmail.confirm`** the address was free when `changeEmail.send` asked — `send` never checks — and somebody took it before the link was used. The link is already spent and nothing was written: the user keeps their e-mail.
|
|
1160
|
+
**Fix:** answer 409. On `changeEmail.confirm`, tell the user the address is taken and ask for another with a new `changeEmail.send`. If two concurrent sign-ups with one login both succeed, the unique index is missing — with `@softistx/janus-mongo`, run `syncMongoStores(db)`.
|
|
1161
|
+
|
|
1162
|
+
### `EMAIL_CHANGE_NEEDS_PROOF` — `<call>: the user holds a <second factor|passkey> — moving the e-mail with update would leave the new address unproved and the first proof would drop it; use changeEmail, which proves the new address`
|
|
1163
|
+
|
|
1164
|
+
`EmailChangeNeedsProofError`, status 409, carrying `userId` and `userType`. The message says `passkey` instead of `second factor` for a user who holds a passkey and no factor. A user with **no e-mail yet** gets `<call>: the user holds a <second factor|passkey> and has no e-mail — setting one with update would leave it unproved and the first proof would drop it; remove the second factor and the passkeys first`.
|
|
1165
|
+
|
|
1166
|
+
**When:** `update` with a patch that moves the e-mail of a user who holds a second factor, active or waiting, or at least one passkey. A change of case only, another field, clearing the e-mail, or a user who holds neither, is not refused. For a user with no e-mail yet there is nothing to move with `changeEmail`: remove the factor (`secondFactor.disable`) and the passkeys (`passkeys.remove`), then set the e-mail and prove it.
|
|
1167
|
+
**Why:** a new e-mail is unproved, and the first proof of an e-mail by code or link drops the password, the second factor and the passkeys. `update` would have left a factor set up while the old address was proved beside an address nobody proved, to be wiped at the next sign-in by e-mail. Nothing was written.
|
|
1168
|
+
**Fix:** answer 409 and move the address with `changeEmail`, which sends a link to the new address and keeps the factor once it is confirmed:
|
|
1169
|
+
|
|
1170
|
+
```ts
|
|
1171
|
+
const { token } = await auth.changeEmail.send(user, 'new@example.test');
|
|
1172
|
+
// e-mail the token to the new address, then, from the page it opens:
|
|
1173
|
+
await auth.changeEmail.confirm(token);
|
|
1174
|
+
```
|
|
1175
|
+
|
|
1176
|
+
### `VERSION_CONFLICT` — `<call>: expected version <n>, found <m>`
|
|
1177
|
+
|
|
1178
|
+
`StoreConflict` with `on: 'version'`, carrying `expectedVersion` and `actualVersion`.
|
|
1179
|
+
|
|
1180
|
+
**When:** a write with `ifVersion`, after someone else changed the user.
|
|
1181
|
+
**Why:** nothing was written. A sign-in moves `version` too, when it rewrites a stale password hash — so a user read before somebody signed in, then passed as `ifVersion`, conflicts.
|
|
1182
|
+
**Fix:** read the user again and retry, or answer 409:
|
|
1183
|
+
|
|
1184
|
+
```ts
|
|
1185
|
+
const user = await auth.get(id);
|
|
1186
|
+
await auth.update(user, { name }, { ifVersion: user.version });
|
|
1187
|
+
```
|
|
1188
|
+
|
|
1189
|
+
**From `verifyEmail.confirm(token, { firstProof: true })`**: the user was written between the read that found the e-mail never proved and the proof. Nothing was proved and the token is spent; send a new link.
|
|
1190
|
+
|
|
1191
|
+
**From `verifyEmail.proveFirst`**, with no `ifVersion` of yours: either the
|
|
1192
|
+
`User` you passed carries an address that is no longer the user's (nothing is
|
|
1193
|
+
proved, on the first read already; a bare id skips this check and proves the
|
|
1194
|
+
current address), or the user was written between the read that found the e-mail never proved and the
|
|
1195
|
+
write that proves it — by the user, or by a second acceptance of the same
|
|
1196
|
+
invitation. `proveFirst` already retried once on a fresh read, so you see
|
|
1197
|
+
this error only when the user was written **again** during the retry, or when
|
|
1198
|
+
the write **changed the e-mail address** since the first read (or it is not
|
|
1199
|
+
the one the `User` you passed carries): the proof you hold is for the
|
|
1200
|
+
address you read. Nothing was proved, though
|
|
1201
|
+
the sessions may already be revoked. Read the user and check that their
|
|
1202
|
+
e-mail is still the invitation's address; if it is, call it again — it
|
|
1203
|
+
answers `proved: false` when another write proved the e-mail.
|
|
1204
|
+
|
|
1205
|
+
**From `secondFactor.confirm`**, the message is the store's:
|
|
1206
|
+
`updateUser: expected version <n>, found <m>`.
|
|
1207
|
+
|
|
1208
|
+
**When:** two `confirm` calls for one user run at once with the same code — a
|
|
1209
|
+
double-submitted form, two tabs, a client that retries before the first answer.
|
|
1210
|
+
**Why:** of two codes accepted at once, the first write wins and opens a
|
|
1211
|
+
session. The second finds the user's version moved and writes nothing: no
|
|
1212
|
+
session. Its challenge is not spent, and has lost one attempt.
|
|
1213
|
+
**Fix:** submit the code form once. The session already exists, from the call
|
|
1214
|
+
that won; if the visitor still needs one, the next code works on the same
|
|
1215
|
+
challenge — the same code will not, it was used.
|
|
1216
|
+
|
|
1217
|
+
```ts
|
|
1218
|
+
// in the browser: one submit per code
|
|
1219
|
+
form.addEventListener('submit', () => form.querySelector('button')?.setAttribute('disabled', ''));
|
|
1220
|
+
```
|
|
1221
|
+
|
|
1222
|
+
**From `signInCode.confirm` and `magicLink.confirm`**, the message names the
|
|
1223
|
+
call: `magicLink.confirm: expected version <n>, found <m>`.
|
|
1224
|
+
|
|
1225
|
+
**When:** the user was written — an `update`, a sign-in that rehashed the
|
|
1226
|
+
password — between `confirm` reading them and writing the e-mail as
|
|
1227
|
+
verified. Rare: the window is one read.
|
|
1228
|
+
**Why:** the proof is written under the version read, so an address changed
|
|
1229
|
+
meanwhile is never the one marked verified. Nothing was written and no
|
|
1230
|
+
session opened, but the code's challenge or the link is already spent.
|
|
1231
|
+
**Fix:** answer it as a spent link or code: ask for a new one.
|
|
1232
|
+
|
|
1233
|
+
**From `secondFactor.recover`**, the same store message.
|
|
1234
|
+
|
|
1235
|
+
**When:** one recovery code used by two sign-ins at once — the same
|
|
1236
|
+
double-submitted form, or two people holding the same printed sheet.
|
|
1237
|
+
**Why:** the recovery code is removed in one write under the version read.
|
|
1238
|
+
The first write wins and opens a session; the second writes nothing and opens
|
|
1239
|
+
nothing. Its challenge is not spent, and has lost one attempt.
|
|
1240
|
+
**Fix:** answer it as "sign in again" — that recovery code is gone either
|
|
1241
|
+
way — and submit the form once, as above. The route in
|
|
1242
|
+
[the second factor guide](guide/second-factor.md#a-sign-in-with-a-code-as-routes)
|
|
1243
|
+
does the first.
|
|
1244
|
+
|
|
1245
|
+
### `USER_INVALID` — `<call>: the fields do not match the <type> schema (<n> issues, at <paths>)`
|
|
1246
|
+
|
|
1247
|
+
`UserInvalidError`, carrying `issues` — each a `path` and a `message`.
|
|
1248
|
+
|
|
1249
|
+
**When:** `signUp`, `create`, `update`, `changeEmail.send`, and `findOrCreate`.
|
|
1250
|
+
**Why:** your schema refused the fields. `changeEmail.send` also answers it, with one issue at the e-mail field (`is the current e-mail of the user`), for an address equal to the user's current one once normalised: nothing is counted or issued; answer 400, or offer `verifyEmail.send` to prove the current one. `update` merges the patch over the stored fields and validates the whole, so the refusal can name a field the patch did not touch. An issue whose message is `set by janus, not by a request` means the input carried a field janus sets (`id`, `active`, `version`, …) and your schema let it through. An issue whose message is `holds a NUL character or a lone surrogate, which no store can keep` means a string — or, with `a key holds …`, an object key — carried `\u0000` or half of a surrogate pair: PostgreSQL refuses both, so janus refuses them on every adapter rather than answer `STORE_FAILED` on one. A key is reported by the path of the object holding it, never by the key itself — in janus's issues and in your schema's alike. An issue at your login field whose message is `normalises to a login that holds …` means your own `password.normalize` function produced such a login from a valid field: fix the function. On MongoDB or the memory store, a user written before janus refused these characters may already hold one: every `update` of that user is refused, whatever it patches, until the field is cleaned — patch it with a clean value in the same `update`.
|
|
1251
|
+
**`findOrCreate`** also answers it, with one issue at the login field (the e-mail field on a type with no password) and the message `is not the key findOrCreate was given`, when the validated input names another key than the one asked for; nothing is written. A username type given an e-mail nobody holds always meets it, since the input's username cannot be that e-mail. Fix: build the input from the same value as the key. A key that is not a string is answered before `input()` runs, with one issue at the empty path and the message `is not a string`: pass the login or the e-mail as a string.
|
|
1252
|
+
**Fix:** answer 400, field by field:
|
|
1253
|
+
|
|
1254
|
+
```ts
|
|
1255
|
+
if (error instanceof UserInvalidError) {
|
|
1256
|
+
return Response.json({ issues: error.issues }, { status: 400 });
|
|
1257
|
+
}
|
|
1258
|
+
```
|
|
1259
|
+
|
|
1260
|
+
### `PASSWORD_TOO_SHORT` — `<call>: the password is shorter than the policy's <n> characters`
|
|
1261
|
+
|
|
1262
|
+
**When:** `signUp`, `setPassword`, `changePassword`, `resetPassword.confirm`.
|
|
1263
|
+
**Why:** the type's `password.minLength` (8 by default). `resetPassword.confirm` checks this **before** spending the token, so the visitor can retry with the same link.
|
|
1264
|
+
At the root of several user types, `auth.resetPassword.confirm` checks the **strictest** `minLength` among the types with a password (one with no e-mail counts too, since the root cannot tell: it can never be reset, but its rule still applies at the root), since the type is only known after the token is spent: `error.minLength` is that one and `error.userType` the type that set it, and a password a more lenient type would accept can be refused there. The token is still not spent.
|
|
1265
|
+
**Fix:** answer 400 with `error.minLength`, or change the policy: `password: { login: 'email', minLength: 12 }`.
|
|
1266
|
+
|
|
1267
|
+
### `CREDENTIALS_INVALID` — `<call>: the login and the password do not match`
|
|
1268
|
+
|
|
1269
|
+
Also `changePassword: the current password does not match`.
|
|
1270
|
+
|
|
1271
|
+
**When:** `signIn`, `changePassword`.
|
|
1272
|
+
**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. Also a sign-in that verified a password written over while it ran (`reason: 'wrongPassword'`): its session is revoked, or its challenge spent, before the refusal. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter; a login past its attempts has its own message, below. A login holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one. A user who signed up with a password and then signed in by `signInCode` or `magicLink` before verifying the e-mail has no password any more (`noPassword`): that first proof drops it, and the second factor, and signs out every session, so an address registered by someone else keeps nothing of theirs — [the sign-in link guide](guide/magic-link.md#an-account-someone-else-registered) has why.
|
|
1273
|
+
**Fix:** answer 401 with the same body whatever the reason — and, for a user who signed in by code or link before verifying, offer `setPassword` after that sign-in, or send `verifyEmail` at sign-up:
|
|
1274
|
+
|
|
1275
|
+
```ts
|
|
1276
|
+
// Never: { reason: error.reason } — `unknownLogin` tells an attacker which users exist.
|
|
1277
|
+
return new Response('Wrong e-mail or password', { status: 401 });
|
|
1278
|
+
```
|
|
1279
|
+
|
|
1280
|
+
### `CREDENTIALS_INVALID` — `<call>: too many passwords tried at this login — wait for the next window`
|
|
1281
|
+
|
|
1282
|
+
`CredentialError`, with `reason: 'throttled'` and `retryAfter`.
|
|
1283
|
+
|
|
1284
|
+
**When:** `signIn` or `changePassword`, after ten passwords were tried at
|
|
1285
|
+
this login in the current 15-minute window. The two share one count. Whatever
|
|
1286
|
+
the password is, **the right one included**, and whether or not anybody holds
|
|
1287
|
+
the login, it is refused. Nothing is compared.
|
|
1288
|
+
**Why:** `signIn` throttles password guessing per login, on by default:
|
|
1289
|
+
counted by the store, in fixed windows of the clock, shared by every process
|
|
1290
|
+
over the same store. Nothing locks: the next window signs in, and a sign-in
|
|
1291
|
+
that succeeds, or a `changePassword` that is written, starts the count
|
|
1292
|
+
again. In tests with `fixedClock`, the window never ends: advance the clock
|
|
1293
|
+
past `retryAfter`, or wire `signIn: { throttle: false }`.
|
|
1294
|
+
**Fix:** tell the visitor to wait `retryAfter` seconds — not that the
|
|
1295
|
+
password is wrong — and answer 401, as `@softistx/janus-hono`'s `janusErrors()`
|
|
1296
|
+
does, with a `Retry-After` header. If nobody you know tried ten passwords,
|
|
1297
|
+
somebody is guessing: count the `CredentialError`s with `reason: 'throttled'` your handler sees. To
|
|
1298
|
+
change the limit or turn it off:
|
|
1299
|
+
|
|
1300
|
+
```ts
|
|
1301
|
+
if (error instanceof JanusError && error.retryAfter !== undefined) {
|
|
1302
|
+
const headers = { 'retry-after': String(error.retryAfter) };
|
|
1303
|
+
return Response.json({ code: error.code, retryAfter: error.retryAfter }, { status: 401, headers });
|
|
1304
|
+
}
|
|
1305
|
+
|
|
1306
|
+
janus({ ..., signIn: { throttle: { attempts: 20, window: '15m' } } });
|
|
1307
|
+
```
|
|
1308
|
+
|
|
1309
|
+
### `MAGIC_LINK_DISABLED` — `<call>: magic-link sign-in is disabled`
|
|
1310
|
+
|
|
1311
|
+
`MagicLinkDisabledError`, status 404.
|
|
1312
|
+
|
|
1313
|
+
**When:** `magicLink.request`, `prepare` or `confirm` on an instance built with
|
|
1314
|
+
`janus({ magicLink: { enabled: false } })`.
|
|
1315
|
+
**Why:** the switch is off. The call refuses before any store access: no
|
|
1316
|
+
address is counted, no token issued or spent, no e-mail to send. A link
|
|
1317
|
+
e-mailed earlier is not spent either; it works again if the switch goes back on.
|
|
1318
|
+
**Fix:** turn it on (`magicLink: { enabled: true }`, or leave the option out),
|
|
1319
|
+
or stop offering the flow: read `auth.magicLink.enabled` to hide the button,
|
|
1320
|
+
and answer the code with a 404.
|
|
1321
|
+
|
|
1322
|
+
```ts
|
|
1323
|
+
const auth = janus({ /* … */ magicLink: { enabled: process.env.MAGIC_LINK === '1' } });
|
|
1324
|
+
if (auth.magicLink.enabled) showMagicLinkButton();
|
|
1325
|
+
```
|
|
1326
|
+
|
|
1327
|
+
### `MAIL_THROTTLED` — `<call>: too many e-mails asked for this address — the last one sent still works; use it, or wait for the next window`
|
|
1328
|
+
|
|
1329
|
+
`MailThrottledError`, with `retryAfter` and `userType`. The per-user flows say
|
|
1330
|
+
`… too many e-mails asked for this user — the last one sent still works; use
|
|
1331
|
+
it, or wait for the next window` and carry `userId`.
|
|
1332
|
+
|
|
1333
|
+
**When:** `magicLink.request`, `signInCode.request` or
|
|
1334
|
+
`resetPassword.request` (per address), or `verifyEmail.send`,
|
|
1335
|
+
`changeEmail.send` (per user, and per new address) and an e-mailed
|
|
1336
|
+
`stepUp.request` (per user), past five requests of that flow in the current
|
|
1337
|
+
10-minute window — whether or not anybody holds the address. `<call>` is the
|
|
1338
|
+
call, such as `magicLink.request` or `patient.signInCode.request`.
|
|
1339
|
+
**Why:** requests that send e-mail are throttled, on by default, so a loop
|
|
1340
|
+
cannot fill an inbox or cancel its owner's link or code. Each flow counts on
|
|
1341
|
+
its own, in fixed windows of the clock, by the store. **A refused request
|
|
1342
|
+
spends, invalidates and rotates nothing**: no token, code or challenge is
|
|
1343
|
+
issued, and the last link or code sent — by anyone's request, an attacker's
|
|
1344
|
+
included — still confirms until it expires, so a loop on a victim's address
|
|
1345
|
+
cannot lock them out. Nothing locks: the next window answers again. In tests with `fixedClock`, the window never
|
|
1346
|
+
ends.
|
|
1347
|
+
**Fix:** answer 429 with a `Retry-After` header, and tell the visitor to use
|
|
1348
|
+
the last e-mail they received (it still works), or to wait `retryAfter`
|
|
1349
|
+
seconds: "Check your inbox: the last e-mail we sent still works. You can ask for
|
|
1350
|
+
a new one in N minutes." It reveals nothing about accounts, so it is safe to
|
|
1351
|
+
show.
|
|
1352
|
+
In tests, advance the clock past `retryAfter`, or wire `mail: { throttle:
|
|
1353
|
+
false }`. If nobody you know asked five times, somebody is looping on the
|
|
1354
|
+
route: `janus` never sees IP addresses, so limit it per client, which the
|
|
1355
|
+
throttle does not — with `@softistx/redis` rate limits (`defineRateLimit`,
|
|
1356
|
+
`bindRateLimit`; `enforce()` throws `GuardError` `RATE_LIMITED` whose
|
|
1357
|
+
`retryAfter` is in milliseconds), as in the
|
|
1358
|
+
[e-mail flows guide](guide/email-flows.md#requests-that-send-e-mail-are-throttled).
|
|
1359
|
+
If you set a token lifetime shorter than the window (`tokens.signInCode: '5m'`
|
|
1360
|
+
with the default), the last code can expire before the window ends: keep
|
|
1361
|
+
`mail.throttle.window` no longer than the shortest `tokens.*` you use.
|
|
1362
|
+
|
|
1363
|
+
```ts
|
|
1364
|
+
import { MailThrottledError } from '@softistx/janus';
|
|
1365
|
+
|
|
1366
|
+
if (error instanceof MailThrottledError) {
|
|
1367
|
+
const headers = { 'retry-after': String(error.retryAfter) };
|
|
1368
|
+
return Response.json({ code: error.code, retryAfter: error.retryAfter }, { status: 429, headers });
|
|
1369
|
+
}
|
|
1370
|
+
|
|
1371
|
+
janus({ ..., mail: { throttle: { attempts: 10, window: '10m' } } });
|
|
1372
|
+
```
|
|
1373
|
+
|
|
1374
|
+
### Accepting an invitation answers `MAIL_THROTTLED`
|
|
1375
|
+
|
|
1376
|
+
**When:** the application signs an invitee in by calling
|
|
1377
|
+
`magicLink.request(email)` and confirming the token at once, and somebody
|
|
1378
|
+
asked for links to that address five times in the window — the default mail
|
|
1379
|
+
throttle. The acceptance answers 429, and the message says the last link
|
|
1380
|
+
sent still works, though the invitee was sent none.
|
|
1381
|
+
**Why:** `request` is counted per address, whoever asks: that is what stops a
|
|
1382
|
+
loop from filling an inbox. A sign-in your server already proved — the
|
|
1383
|
+
invitation token it issued — does not need an e-mailed link, and should not
|
|
1384
|
+
share its count.
|
|
1385
|
+
**Fix:** call `signInProven` with the user from the invitation's record, after
|
|
1386
|
+
verifying the token yourself. It counts nothing, sends nothing, spends no
|
|
1387
|
+
link already sent, and answers what `signIn` answers. An invitation that
|
|
1388
|
+
holds an address rather than an id finds the account with `findByEmail`,
|
|
1389
|
+
which counts nothing either — on any type with an e-mail, password or not.
|
|
1390
|
+
|
|
1391
|
+
```ts
|
|
1392
|
+
const invitation = await invitations.spend(hash(token), new Date()); // yours: once, unexpired
|
|
1393
|
+
if (invitation === null) return new Response(null, { status: 404 });
|
|
1394
|
+
const user = await auth.findByEmail(invitation.email); // or invitation.userId, when you stored the id
|
|
1395
|
+
if (user === null) return new Response(null, { status: 404 });
|
|
1396
|
+
await auth.verifyEmail.proveFirst(user); // the invitation reached the inbox — before signInProven
|
|
1397
|
+
const result = await auth.signInProven(user, { device: deviceOf(request) });
|
|
1398
|
+
```
|
|
1399
|
+
|
|
1400
|
+
Never pass it an id the request carries: it checks no credential. See
|
|
1401
|
+
[sessions](guide/sessions.md#signing-in-on-your-own-proof--signinproven).
|
|
1402
|
+
|
|
1403
|
+
### The password chosen when accepting an invitation answers `CREDENTIALS_INVALID` (`noPassword`)
|
|
1404
|
+
|
|
1405
|
+
**When:** the acceptance route calls `setPassword` with the password the
|
|
1406
|
+
invitee chose, then `verifyEmail.proveFirst`; the invitee is signed in, and
|
|
1407
|
+
their next `signIn` with that password answers `CREDENTIALS_INVALID` with
|
|
1408
|
+
`reason: 'noPassword'`. Or the route calls `signInProven` before
|
|
1409
|
+
`proveFirst`, and the session it just opened is anonymous on the next
|
|
1410
|
+
request.
|
|
1411
|
+
**Why:** on an e-mail never proved, `proveFirst` drops the password and the
|
|
1412
|
+
second factor and revokes every session — whatever was set before it is
|
|
1413
|
+
taken for what somebody who signed up with the address left there. It
|
|
1414
|
+
cannot tell the invitee's fresh password from a squatter's.
|
|
1415
|
+
**Fix:** prove first, then set the password, then sign in:
|
|
1416
|
+
|
|
1417
|
+
```ts
|
|
1418
|
+
const user = (await auth.findByEmail(invitation.email)) ?? (await auth.create({ email: invitation.email, name }));
|
|
1419
|
+
await auth.verifyEmail.proveFirst(user); // 1. drops what was there before
|
|
1420
|
+
await auth.setPassword(user, body.password); // 2. the invitee's own
|
|
1421
|
+
const result = await auth.signInProven(user, { device: deviceOf(request) }); // 3. last
|
|
1422
|
+
```
|
|
1423
|
+
|
|
1424
|
+
See [e-mail flows](guide/email-flows.md#proving-an-e-mail-on-your-own-proof--provefirst).
|
|
1425
|
+
|
|
1426
|
+
### `MAIL_THROTTLED` never reaches the visitor: `request` runs in the background
|
|
1427
|
+
|
|
1428
|
+
**When:** the application runs `magicLink.request`, `signInCode.request` or
|
|
1429
|
+
`resetPassword.request` off the visitor's request — a queue, a promise it
|
|
1430
|
+
does not await — so that the time of the answer does not tell whether the
|
|
1431
|
+
address has an account. Past the limit, the refusal is thrown there, and
|
|
1432
|
+
nobody tells the visitor to use the last e-mail they received.
|
|
1433
|
+
**Why:** `request` counts, then looks the address up and issues: its
|
|
1434
|
+
`MAIL_THROTTLED` comes from the same call whose time must be hidden.
|
|
1435
|
+
**Fix:** call `prepare(email)` in the visitor's request — validated and
|
|
1436
|
+
counted, nobody looked up, the same store calls for any address — and
|
|
1437
|
+
answer its `MAIL_THROTTLED` with 429; call `send()` on what it answered in the
|
|
1438
|
+
background. `send()` counts nothing and answers what `request` would have.
|
|
1439
|
+
|
|
1440
|
+
```ts
|
|
1441
|
+
const pending = await auth.magicLink.prepare(email); // MAIL_THROTTLED here, in the visitor's request
|
|
1442
|
+
void pending.send().then(mailIt).catch(reportError); // looked up and issued off it
|
|
1443
|
+
return new Response(null, { status: 202 });
|
|
1444
|
+
```
|
|
1445
|
+
|
|
1446
|
+
See [requests in two steps](guide/email-flows.md#requests-in-two-steps).
|
|
1447
|
+
|
|
1448
|
+
### `<flow>.prepare(…).send: already called — a prepared request sends once; call <flow>.prepare again for another`
|
|
1449
|
+
|
|
1450
|
+
A `TypeError`, such as `magicLink.prepare(…).send: already called — a
|
|
1451
|
+
prepared request sends once; call magicLink.prepare again for another`, or
|
|
1452
|
+
`patient.signInCode.prepare(…)…` with several user types.
|
|
1453
|
+
**When:** `send()` was called a second time on what one `prepare` answered —
|
|
1454
|
+
after it issued, after it answered `null`, after it threw (`STORE_FAILED`),
|
|
1455
|
+
or while the first call was still running.
|
|
1456
|
+
**Why:** `prepare` counted one request against the mail throttle, and that
|
|
1457
|
+
count pays for one issue. A `send()` that could run again would issue
|
|
1458
|
+
uncounted, so a loop could mail an address past the limit; nothing a caller
|
|
1459
|
+
passes skips the count. It is a bug in the calling code, never a value from
|
|
1460
|
+
a request, so it is a `TypeError` with no `code`.
|
|
1461
|
+
**Fix:** call `send()` once per `prepare`. To retry — after a failure, in a
|
|
1462
|
+
queue that retries — `prepare` again, which counts again (and, for a sign-in
|
|
1463
|
+
code, mints another challenge: give the visitor the new one):
|
|
1464
|
+
|
|
1465
|
+
```ts
|
|
1466
|
+
async function sendLink(email: string): Promise<void> {
|
|
1467
|
+
const pending = await auth.magicLink.prepare(email); // one count…
|
|
1468
|
+
const issued = await pending.send(); // …one issue
|
|
1469
|
+
if (issued !== null) await mailer.send(issued.email, linkTo(issued.token));
|
|
1470
|
+
}
|
|
1471
|
+
// a retry calls sendLink again: never pending.send() twice
|
|
1472
|
+
```
|
|
1473
|
+
|
|
1474
|
+
### `STORE_FAILED` — `<call>: the store dropped the attempts it had just stored`
|
|
1475
|
+
|
|
1476
|
+
`StoreFailure`, with `slot: 'tokens'` and `operation: 'countAttempt'`.
|
|
1477
|
+
|
|
1478
|
+
**When:** `signIn`, when the tokens store answers `countAttempt` with `null`
|
|
1479
|
+
for the count it stored an instant before.
|
|
1480
|
+
**Why:** the store lost it — a Redis evicting keys under memory pressure, a
|
|
1481
|
+
flush between the two calls, or an adapter whose `countAttempt` does not
|
|
1482
|
+
find what `insertToken` wrote. The throttle cannot count, so the sign-in
|
|
1483
|
+
fails rather than pass uncounted.
|
|
1484
|
+
**Fix:** answer 503. Run the conformance suite against the adapter, and give
|
|
1485
|
+
a Redis tokens store `maxmemory-policy noeviction`.
|
|
1486
|
+
|
|
1487
|
+
### `HASH_UNSUPPORTED` — `<call>: no wired verifier claims the prefix "<prefix>"`
|
|
1488
|
+
|
|
1489
|
+
**When:** `signIn` or `changePassword`, for a user whose stored hash was written by another system — typically after an import.
|
|
1490
|
+
**Why:** the hash starts with a prefix (`$2b$`, `$argon2id$`, …) that neither `hasher` nor any of `verifiers` claims.
|
|
1491
|
+
**Fix:** wire a verifier for that format; the next successful sign-in rewrites the hash with `hasher`:
|
|
1492
|
+
|
|
1493
|
+
```ts
|
|
1494
|
+
janus({ ..., hasher: scryptHasher(), verifiers: [bcryptVerifier] }); // a PasswordHasher whose prefix is '$2b$'
|
|
1495
|
+
```
|
|
1496
|
+
|
|
1497
|
+
### `scryptHasher: the stored hash has the $scrypt$ prefix and not its format`
|
|
1498
|
+
|
|
1499
|
+
**When:** `signIn` or `changePassword`, a `TypeError`.
|
|
1500
|
+
**Why:** the stored hash starts with `$scrypt$` but is not `$scrypt$ln=…,r=…,p=…$<salt>$<key>`: it was truncated or written by another scrypt implementation.
|
|
1501
|
+
**Fix:** repair the record, or `setPassword` for that user. It is not treated as a wrong password on purpose.
|
|
1502
|
+
|
|
1503
|
+
### `USER_INACTIVE` — `<call>: the user is inactive`
|
|
1504
|
+
|
|
1505
|
+
**When:** `signIn`, with the **right** password, for a user set inactive. Also `changeEmail.send` and `changeEmail.confirm` (the link is spent), and `secondFactor.confirm` and `secondFactor.recover`, for a user set inactive after `signIn` asked for a code, `signInCode.confirm`, for a user set inactive after the code was sent, and `magicLink.confirm`, for one set inactive after the link was sent. And `signInProven` and `verifyEmail.proveFirst`, for an inactive user: the application's proof does not reactivate anybody, and proves nothing on an inactive one.
|
|
1506
|
+
**Why:** an inactive user keeps their record and password, and every sign-in is refused. It is checked after the password, so only somebody who knows the password learns the user is inactive — and after the code, so only somebody who read the e-mail does: `signInCode.request` answers `null` for an inactive user, as for nobody. On either `confirm`, the challenge is spent: reactivating the user does not revive it. `magicLink.confirm` checks after spending the link, which is spent too, and `magicLink.request` answers `null` for an inactive user.
|
|
1507
|
+
**Fix:** answer 403, or reactivate, then sign in again: `await auth.setActive(user, true)`.
|
|
1508
|
+
|
|
1509
|
+
### `EMAIL_UNVERIFIED` — `<call>: the e-mail is not verified`
|
|
1510
|
+
|
|
1511
|
+
**When:** `signIn`, with the **right** password, on a user type configured with `password: { requireVerifiedEmail: true }`, for a user whose address was never verified; or `secondFactor.enroll`, `secondFactor.activate`, `passkeys.registrationOptions` or `passkeys.register` for such a user (see the last *Also* lines).
|
|
1512
|
+
**Why:** the option refuses a session until `verifyEmail.confirm` (or a sign-in code or link, or `verifyEmail.proveFirst`) proved the address. It is checked after the password, so only somebody who knows it learns the address is unverified; a wrong password is still `CREDENTIALS_INVALID`. No session was opened.
|
|
1513
|
+
**Also:** `social.complete` creating a user from a provider that does not vouch for its e-mail — see [below](#email_unverified--socialcomplete-the-provider-does-not-vouch-for-an-e-mail-so-no-account-is-created).
|
|
1514
|
+
**Also:** `passkeys.registrationOptions` and `passkeys.register`, for a user of a type that holds an e-mail that was never verified: the first proof of the address removes every passkey, so one is registered after it. Verify it first (`verifyEmail.confirm`).
|
|
1515
|
+
**Also:** `secondFactor.enroll` and `secondFactor.activate`, for a user of a type that holds an e-mail that was never verified: the first proof of the address removes the factor, so one is enrolled after it. Verify it first (`verifyEmail.confirm`), then enroll.
|
|
1516
|
+
**Also:** `apiKeys.create` for a user whose address was never verified, whatever the type's options, when the type holds an e-mail: nothing is written. A type that signs in by username holds none, so it is not asked. A key outlives the session that made it, and there is no option to allow it. Verify the address first.
|
|
1517
|
+
**Fix:** answer 403 and offer a resend: `const pending = await auth.verifyEmail.prepare(email)` in the request, `pending.send()` off it. A new sign-up goes through `signUp.prepare`, which opens no session.
|
|
1518
|
+
|
|
1519
|
+
### `EMAIL_UNVERIFIED` — `<call>: the e-mail stopped being verified while the passkey was registered — nothing was kept`
|
|
1520
|
+
|
|
1521
|
+
`EmailUnverifiedError`, status 403, carrying `userId` and `userType`.
|
|
1522
|
+
|
|
1523
|
+
**When:** `passkeys.register`, when the user's e-mail stopped being verified between the checks at the start of the call and the insert of the passkey (an `update` that moved the e-mail, or a store write).
|
|
1524
|
+
**Why:** the first proof of an unproved address removes every passkey, so none is kept beside one. The passkey just inserted was deleted, and no `user.passkeyAdded` was sent.
|
|
1525
|
+
**Fix:** answer 403, verify the new address (`changeEmail`, or `verifyEmail.confirm`), then register the passkey again with new options.
|
|
1526
|
+
|
|
1527
|
+
### `EMAIL_UNVERIFIED` — `<call>: the e-mail changed or was proved again while the passkey was registered — nothing was kept`
|
|
1528
|
+
|
|
1529
|
+
`EmailUnverifiedError`, status 403, carrying `userId` and `userType`.
|
|
1530
|
+
|
|
1531
|
+
**When:** `passkeys.register`, when the user's e-mail, or the date it was verified, is no longer what the call checked at its start, though it is proved: it was moved and proved again between the check and the insert (an `update` then a first proof of the new address).
|
|
1532
|
+
**Why:** that first proof wiped the user's factors and passkeys before this passkey existed, so it would have survived for whoever held the session before. The passkey just inserted was deleted, and no `user.passkeyAdded` was sent. It fails closed: a legitimate `changeEmail.confirm`, or a `verifyEmail` re-proof of the same address, landing in the same instant is withdrawn the same way.
|
|
1533
|
+
**Fix:** answer 403 and ask for new options, then register the passkey again.
|
|
1534
|
+
|
|
1535
|
+
### `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`
|
|
1536
|
+
|
|
1537
|
+
`TokenError`: `<call>: no such token`, `<call>: the token was already used`, `<call>: the token has expired`.
|
|
1538
|
+
|
|
1539
|
+
**When:** `verifyEmail.confirm`, `resetPassword.confirm`, `changeEmail.confirm`.
|
|
1540
|
+
**Why:** a token is spent by its first use, and an expired one is spent too. `TOKEN_UNKNOWN` also covers a token whose user was deleted, and a link confirmed through another user type's `verifyEmail`, `resetPassword` or `changeEmail` `confirm` (which spends it, so the right type then answers `TOKEN_SPENT`) or passed to another flow. `verifyEmail.confirm(token, { user })` also answers `TOKEN_UNKNOWN` for a link issued to a different user than `user`, and **does not spend it**: the right user can still confirm it. A `user` key that is present but `undefined` or `null` is refused the same way (nothing is confirmed unbound); it has no message of its own. The defaults are 24 h for `verifyEmail`, 1 h for `resetPassword` and for `changeEmail`. A change link is also spent by a newer `changeEmail.send` for the same user (only the last one works), and by an `update` that changes the user's e-mail.
|
|
1541
|
+
A reset link answers `resetPassword.confirm: the token was already used` in
|
|
1542
|
+
two more cases: a newer `resetPassword.request` for the same user spent it —
|
|
1543
|
+
only the last link sent works, so a visitor who asked twice and clicked the
|
|
1544
|
+
first e-mail gets `TOKEN_SPENT` — or the password was written since it was
|
|
1545
|
+
sent, by another link's `confirm`, `changePassword` or `setPassword`. When two
|
|
1546
|
+
requests race, even the last link can be spent: at most one survives,
|
|
1547
|
+
sometimes none.
|
|
1548
|
+
**Fix:** answer 400 and offer to send a new link — and tell the visitor to use
|
|
1549
|
+
the latest e-mail. With several user types, confirm a link from a page that
|
|
1550
|
+
does not know the type with the root's `auth.verifyEmail.confirm(token)`,
|
|
1551
|
+
`auth.resetPassword.confirm(token, password)` or `auth.changeEmail.confirm(token)`,
|
|
1552
|
+
never through a guessed type. To change the lifetimes:
|
|
1553
|
+
|
|
1554
|
+
```ts
|
|
1555
|
+
janus({ ..., tokens: { verifyEmail: '72h', resetPassword: '2h' } });
|
|
1556
|
+
```
|
|
1557
|
+
|
|
1558
|
+
**On `secondFactor.confirm` and `secondFactor.recover`**, the messages name
|
|
1559
|
+
the challenge `signIn` answered: `secondFactor.confirm: no such challenge`,
|
|
1560
|
+
`secondFactor.confirm: the challenge was already used`,
|
|
1561
|
+
`secondFactor.confirm: the challenge has expired` — and the same three from
|
|
1562
|
+
`secondFactor.recover`, such as `secondFactor.recover: no such challenge`.
|
|
1563
|
+
|
|
1564
|
+
**When:** `secondFactor.confirm(challenge, code)` or
|
|
1565
|
+
`secondFactor.recover(challenge, code)`.
|
|
1566
|
+
**Why:** a challenge lives five minutes and takes five codes. It is spent by
|
|
1567
|
+
the code that opens the session, by the fifth wrong code, by a refusal
|
|
1568
|
+
that ends it (`USER_INACTIVE`, `SECOND_FACTOR_NOT_ENROLLED`), and by a
|
|
1569
|
+
password written — `resetPassword.confirm`, `setPassword`, `changePassword` —
|
|
1570
|
+
which ends every sign-in left waiting on its code.
|
|
1571
|
+
`TOKEN_UNKNOWN` also covers a challenge whose user was deleted, one
|
|
1572
|
+
confirmed through another user type's `secondFactor`, and a challenge passed
|
|
1573
|
+
where a code was expected — the two arguments swapped. Another type's
|
|
1574
|
+
`confirm` still costs an attempt, and the fifth spends the challenge.
|
|
1575
|
+
**Fix:** answer 400 and send the visitor back to sign in, which asks for a new
|
|
1576
|
+
code. To give slower visitors more time:
|
|
1577
|
+
|
|
1578
|
+
```ts
|
|
1579
|
+
janus({ ..., secondFactor: { issuer: 'Acme', keys, challenge: '10m' } });
|
|
1580
|
+
```
|
|
1581
|
+
|
|
1582
|
+
**On `signInCode.confirm`**, the messages name the challenge
|
|
1583
|
+
`signInCode.request` answered: `signInCode.confirm: no such challenge`,
|
|
1584
|
+
`signInCode.confirm: the challenge was already used`,
|
|
1585
|
+
`signInCode.confirm: the challenge has expired`.
|
|
1586
|
+
|
|
1587
|
+
**When:** `signInCode.confirm(challenge, code)`.
|
|
1588
|
+
**Why:** a challenge lives ten minutes and takes five codes. It is spent by
|
|
1589
|
+
the code that signs the user in, by the fifth wrong code, by a refusal
|
|
1590
|
+
that ends it (`TOKEN_STALE`, `USER_INACTIVE`), and by the next `request` for
|
|
1591
|
+
the same user: only the last code sent works, so a visitor who asked twice
|
|
1592
|
+
and typed the first code gets `TOKEN_SPENT` — and when two requests race,
|
|
1593
|
+
even the last code can be spent: at most one survives, sometimes none. `TOKEN_UNKNOWN` also covers a
|
|
1594
|
+
challenge whose user was deleted, one confirmed through another user type's
|
|
1595
|
+
`signInCode`, the decoy challenge of a `request` that answered `null`, and
|
|
1596
|
+
the two arguments swapped. Another type's `confirm` compares no code, but it
|
|
1597
|
+
has already cost one of the challenge's five
|
|
1598
|
+
attempts: the attempt is counted before the type is known. The challenge is
|
|
1599
|
+
left for its own type, with one attempt fewer — and the fifth such call
|
|
1600
|
+
spends it, as a fifth wrong code would.
|
|
1601
|
+
**Fix:** answer 400 and offer to send a new code — and tell the visitor to
|
|
1602
|
+
use the latest e-mail. To give slower inboxes
|
|
1603
|
+
more time:
|
|
1604
|
+
|
|
1605
|
+
```ts
|
|
1606
|
+
janus({ ..., tokens: { signInCode: '15m' } });
|
|
1607
|
+
```
|
|
1608
|
+
|
|
1609
|
+
**On `magicLink.confirm`**, the messages name the token, as for the other
|
|
1610
|
+
links: `magicLink.confirm: no such token`, `magicLink.confirm: the token was
|
|
1611
|
+
already used`, `magicLink.confirm: the token has expired`.
|
|
1612
|
+
|
|
1613
|
+
**When:** `magicLink.confirm(token)`.
|
|
1614
|
+
**Why:** a sign-in link lives fifteen minutes and is spent by its first
|
|
1615
|
+
`confirm`, whether that call signs in or is refused — so a second click, a
|
|
1616
|
+
refresh that posts again, or a link [a mail scanner opened](#a-sign-in-link-answers-token_spent-on-the-users-first-click)
|
|
1617
|
+
first answers `TOKEN_SPENT`. The next `request` for the same user spends it
|
|
1618
|
+
too: only the last link sent works. `TOKEN_UNKNOWN` also covers a link
|
|
1619
|
+
whose user was deleted, one confirmed through another user type's
|
|
1620
|
+
`magicLink` — which spends it — a sign-in code's challenge, and a token cut
|
|
1621
|
+
short by the mail client wrapping the URL.
|
|
1622
|
+
**Fix:** send the visitor back to ask for a new link — every `TOKEN_*`
|
|
1623
|
+
means that to them — and tell them to use the latest e-mail.
|
|
1624
|
+
|
|
1625
|
+
```ts
|
|
1626
|
+
janus({ ..., tokens: { magicLink: '30m' } });
|
|
1627
|
+
```
|
|
1628
|
+
|
|
1629
|
+
### `TOKEN_STALE` — `<call>: the token was sent to an e-mail the user no longer has`
|
|
1630
|
+
|
|
1631
|
+
**When:** `verifyEmail.confirm`, `resetPassword.confirm`, `magicLink.confirm` or `changeEmail.confirm`, after the user changed their e-mail — even while the link was being redeemed: the address is checked again on the very record the write replaces. A change link is `TOKEN_SPENT`, not stale, after an `update` that moved the e-mail; it is stale after a write outside janus, or a `send` racing an `update`.
|
|
1632
|
+
**Why:** confirming it would verify an address nobody holds any more, or reset a password through one. The token is spent, and nothing is written.
|
|
1633
|
+
**Fix:** send a new token to the current address: `await auth.verifyEmail.send(user)` — or, for a sign-in link, ask for a new one: `magicLink.request` sends it to the current address — or, for a change link, send a new one: `await auth.changeEmail.send(user, newEmail)`.
|
|
1634
|
+
|
|
1635
|
+
### `INVALID_CURSOR` — `<call>: this cursor was not minted by this store, or was minted for another ordering (<n> characters)`
|
|
1636
|
+
|
|
1637
|
+
**When:** `list({ after })`.
|
|
1638
|
+
**Why:** `after` is not a `nextCursor` this store answered — edited, truncated, or from another store. (A cursor that `invitations.list` issued, replayed with other filters, is [`CURSOR_FILTER_MISMATCH`](#cursor_filter_mismatch--call-this-cursor-was-issued-for-another-scope-status-role-ref-lapsed-or-order-than-the-one-given).) It is never read as "first page", which would make a paging loop run forever. A cursor that `invitations.list` handed out before the upgrade that bound cursors to their list is refused as `INVALID_CURSOR`; the client restarts from the first page.
|
|
1639
|
+
**Fix:** pass `nextCursor` back as it came; `null` means the last page:
|
|
1640
|
+
|
|
1641
|
+
```ts
|
|
1642
|
+
let after: string | null = null;
|
|
1643
|
+
do {
|
|
1644
|
+
const page = await auth.list({ after, limit: 100 });
|
|
1645
|
+
after = page.nextCursor;
|
|
1646
|
+
} while (after);
|
|
1647
|
+
```
|
|
1648
|
+
|
|
1649
|
+
### `CURSOR_FILTER_MISMATCH` — `<call>: this cursor was issued for another scope, status, role, ref, lapsed or order than the one given`
|
|
1650
|
+
|
|
1651
|
+
**When:** `invitations.list(scope, { after })`.
|
|
1652
|
+
**Why:** a `nextCursor` is bound to the list that issued it. It was passed back with a different scope, `status`, `role`, `ref`, `lapsed` or `order`; it is refused rather than paging through the other list from that position. (`@softistx/janus-graphql` answers it `BAD_USER_INPUT`.)
|
|
1653
|
+
**Fix:** page with the same filters from the first page to the last, and start again from `after: null` when a filter changes:
|
|
1654
|
+
|
|
1655
|
+
```ts
|
|
1656
|
+
const filters = { status: 'pending', order: 'asc' } as const;
|
|
1657
|
+
let after: string | null = null;
|
|
1658
|
+
do {
|
|
1659
|
+
const page = await auth.invitations.list(scope, { ...filters, after });
|
|
1660
|
+
after = page.nextCursor;
|
|
1661
|
+
} while (after);
|
|
1662
|
+
```
|
|
1663
|
+
|
|
1664
|
+
### `<call>: limit must be an integer of at least 1, or absent`
|
|
1665
|
+
|
|
1666
|
+
**When:** `list({ limit })` of users, or `access.list(..., { limit })`, a `TypeError`. Most often a limit read from a request: `Number(query.limit)` is `NaN` for `?limit=abc`, and the route answers 500.
|
|
1667
|
+
**Why:** `limit` is a positive integer. Above 100 it is capped at 100, not refused. It is a `TypeError`, not a coded error, because the value is your code's to decide: parse a limit from a request before passing it.
|
|
1668
|
+
**Fix:** leave it out (20), or pass `1`–`100`. From a query string, drop what is not a positive integer:
|
|
1669
|
+
|
|
1670
|
+
```ts
|
|
1671
|
+
const asked = Number(query.limit); // c.req.query('limit') in Hono
|
|
1672
|
+
const page = await access.list(user, 'view', 'record', {
|
|
1673
|
+
after: query.after ?? null,
|
|
1674
|
+
...(Number.isInteger(asked) && asked >= 1 ? { limit: asked } : {}), // 20 otherwise, 100 at most
|
|
1675
|
+
});
|
|
1676
|
+
```
|
|
1677
|
+
|
|
1678
|
+
### `UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions, nor store.tokens deleteExpiredTokens — their stores expire records on their own, or implement the methods`
|
|
1679
|
+
|
|
1680
|
+
**When:** `auth.collectExpired()`.
|
|
1681
|
+
**Why:** neither the sessions store implements the optional `deleteExpiredSessions` nor the tokens store the optional `deleteExpiredTokens` — usually because they expire records themselves (a MongoDB TTL index, a Redis `EXPIRE`). With one of the two, `collectExpired` collects that one and does not throw.
|
|
1682
|
+
**Fix:** do not schedule `collectExpired` for those stores. Expiry does not depend on it: the core compares `expiresAt` on every `authenticate` and on every redemption. If your database has no TTL, implement the methods ([adapters](guide/adapters.md#tokenstoredeleteexpiredtokens-optional)).
|
|
1683
|
+
|
|
1684
|
+
### `UNSUPPORTED` — `sessions.list: store.sessions does not implement listUserSessions`
|
|
1685
|
+
|
|
1686
|
+
**When:** `auth.sessions.list(user)` or `auth.sessions.revoke(user, sessionId)`.
|
|
1687
|
+
**Why:** the sessions store does not implement the optional `listUserSessions`, so one user's sessions cannot be listed (and `revoke` checks ownership through that list). A store written before this method existed does not have it.
|
|
1688
|
+
**Fix:** implement `listUserSessions(userId, now)` on the store ([adapters](guide/adapters.md)), or use one of the shipped stores, which all have it. `signOutEverywhere` and `signOut` do not depend on it.
|
|
1689
|
+
|
|
1690
|
+
### `<where>: options.deviceLabel must be a string`
|
|
1691
|
+
|
|
1692
|
+
**When:** `signIn` (or any sign-in flow) with a `deviceLabel` that is not a string. A `TypeError`, thrown before any store is asked.
|
|
1693
|
+
**Why:** the label is recorded on the session as `device`; it is the user agent or a name, never a number or an object. It is cut at 256 characters.
|
|
1694
|
+
**Fix:** pass a string, for example `request.headers.get('user-agent') ?? undefined`.
|
|
1695
|
+
|
|
1696
|
+
### `signOutEverywhere: issuedBefore is not a valid Date`
|
|
1697
|
+
|
|
1698
|
+
**When:** `auth.signOutEverywhere(user, { issuedBefore })` with an `issuedBefore` that is not a `Date`, or a `Date` with no time (`new Date('garbage')`). A `TypeError`, thrown before any store is asked.
|
|
1699
|
+
**Why:** there is no cut-off to apply, and the stores would disagree on what it means (a number, a string). Nothing is revoked.
|
|
1700
|
+
**Fix:** hand over a valid `Date`: the moment the credential changed, read back from your own record.
|
|
1701
|
+
|
|
1702
|
+
```ts
|
|
1703
|
+
const changedAt = new Date(record.changedAt);
|
|
1704
|
+
await auth.signOutEverywhere(user, { except: current.id, issuedBefore: changedAt });
|
|
1705
|
+
```
|
|
1706
|
+
|
|
1707
|
+
Only sessions created **strictly before** it end; one created at that very instant stands.
|
|
1708
|
+
|
|
1709
|
+
### `<call>: the <type> type does not sign in with a password — add password: { login } to it`
|
|
1710
|
+
|
|
1711
|
+
**When:** `signIn`, `findByLogin`, `setPassword`, `changePassword`, `resetPassword.*`, from JavaScript. In TypeScript, these methods are absent from a type without `password`.
|
|
1712
|
+
**Why:** the user type has no `password` option.
|
|
1713
|
+
**Fix:** `users: { staff: { schema: Staff, password: { login: 'email' } } }` — when the type should sign in with a password. To **find** a user of a type with no password, call `findByEmail(email)` instead of `findByLogin`: declaring a password only to look users up opens `signIn` and `resetPassword` on a type that has none by design.
|
|
1714
|
+
|
|
1715
|
+
### `authenticate()` answers `null` although a valid cookie was sent
|
|
1716
|
+
|
|
1717
|
+
**When:** `auth.authenticate(request)` on a request that also carries an `Authorization: Bearer` or an `X-Session-Token` header.
|
|
1718
|
+
**Why:** the **first credential present** wins, not the first valid one: `Authorization: Bearer`, then `X-Session-Token`, then the cookie. A lapsed bearer beside a live cookie is anonymous.
|
|
1719
|
+
**Fix:** stop the client sending the stale header. A `null` is never an outage: when the store cannot answer, `authenticate` rejects with `STORE_FAILED` — answer 503, not 401.
|
|
1720
|
+
|
|
1721
|
+
---
|
|
1722
|
+
|
|
1723
|
+
## Second factor
|
|
1724
|
+
|
|
1725
|
+
Every entry here needs `janus({ ..., secondFactor })`, but for the
|
|
1726
|
+
`signInCode.confirm` paragraph of `CODE_INVALID`. The messages start with
|
|
1727
|
+
`secondFactor.enroll`, `secondFactor.activate`, `secondFactor.confirm`,
|
|
1728
|
+
`secondFactor.recover`, `secondFactor.regenerateRecoveryCodes` or `signIn` —
|
|
1729
|
+
prefixed by the type with several user types:
|
|
1730
|
+
`staff.secondFactor.confirm: …`. `secondFactor.confirm` and
|
|
1731
|
+
`secondFactor.recover` also reject with
|
|
1732
|
+
[`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
|
|
1733
|
+
[`USER_INACTIVE`](#user_inactive--call-the-user-is-inactive) and
|
|
1734
|
+
[`VERSION_CONFLICT`](#version_conflict--call-expected-version-n-found-m);
|
|
1735
|
+
each of those entries has a paragraph for it.
|
|
1736
|
+
|
|
1737
|
+
### `TS2339: Property 'token' does not exist on type 'SignInResult<…>'.`
|
|
1738
|
+
|
|
1739
|
+
The same for `session` and `user`.
|
|
1740
|
+
|
|
1741
|
+
**When:** `tsc`, wherever `signIn`'s answer is read, once `janus()` is given a `secondFactor` — and `signInCode.confirm`'s and `magicLink.confirm`'s, on a user type with a password or an e-mail.
|
|
1742
|
+
**Why:** `signIn` then answers one of two shapes: `{ status: 'signedIn', user, session, token }`, or `{ status: 'secondFactor', challenge, expiresAt, userId }` for a user whose second factor is active — the password alone opens no session for them. Without `secondFactor`, `signIn` still answers a session.
|
|
1743
|
+
**Fix:** switch on `status`:
|
|
1744
|
+
|
|
1745
|
+
```ts
|
|
1746
|
+
const result = await auth.signIn({ email, password });
|
|
1747
|
+
if (result.status === 'secondFactor') {
|
|
1748
|
+
// Keep the challenge for the next request — never in a URL — and ask for a code.
|
|
1749
|
+
return Response.json({ challenge: result.challenge, expiresAt: result.expiresAt });
|
|
1750
|
+
}
|
|
1751
|
+
return Response.json({ token: result.token });
|
|
1752
|
+
|
|
1753
|
+
// the next request, with the code the app shows
|
|
1754
|
+
const signedIn = await auth.secondFactor.confirm(challenge, code); // { status: 'signedIn', token, … }
|
|
1755
|
+
```
|
|
1756
|
+
|
|
1757
|
+
### `TS2339: Property 'hasSecondFactor' does not exist on type 'RecoveryCodesIssued<…>'.`
|
|
1758
|
+
|
|
1759
|
+
The same for any field of your user — `id`, `email`, `version`.
|
|
1760
|
+
|
|
1761
|
+
**When:** `tsc`, after upgrading to 0.10, wherever `secondFactor.activate`'s answer is read as the user.
|
|
1762
|
+
**Why:** `activate` now answers `{ user, recoveryCodes }`: the user, and the ten recovery codes it minted — shown once, never answered again. Reading the answer as the user would drop them unseen.
|
|
1763
|
+
**Fix:** read `.user`, and show the codes:
|
|
1764
|
+
|
|
1765
|
+
```ts
|
|
1766
|
+
const { user, recoveryCodes } = await auth.secondFactor.activate(current.user, code);
|
|
1767
|
+
user.hasSecondFactor; // true
|
|
1768
|
+
return Response.json({ recoveryCodes }, { headers: { 'Cache-Control': 'no-store' } });
|
|
1769
|
+
```
|
|
1770
|
+
|
|
1771
|
+
### `CODE_INVALID` — `<call>: the code does not match, or was already used`
|
|
1772
|
+
|
|
1773
|
+
`TokenError`. The same message answers five calls; there is a paragraph
|
|
1774
|
+
for each below.
|
|
1775
|
+
|
|
1776
|
+
**When:** `secondFactor.activate`, `secondFactor.confirm`,
|
|
1777
|
+
`secondFactor.regenerateRecoveryCodes`, `secondFactor.recover` or
|
|
1778
|
+
`signInCode.confirm`, with a code that does not match.
|
|
1779
|
+
|
|
1780
|
+
**`secondFactor.activate(user, code)`**
|
|
1781
|
+
**Why:** the code is wrong, or it was accepted before: a code is accepted
|
|
1782
|
+
once. There is no challenge here: no `attemptsLeft`, and nothing is spent.
|
|
1783
|
+
**Fix:** let the user try the next code the app shows. If it is the one on
|
|
1784
|
+
screen, see [the next entry](#the-code-the-authenticator-app-shows-is-refused-with-code_invalid).
|
|
1785
|
+
|
|
1786
|
+
**`secondFactor.confirm(challenge, code)`**
|
|
1787
|
+
**Why:** the code is wrong, or it was accepted before. Every call costs one of
|
|
1788
|
+
the challenge's five attempts, counted before anything is checked. The error
|
|
1789
|
+
carries `attemptsLeft`, what remains; at `0`, the challenge is spent and the
|
|
1790
|
+
next `confirm` is `TOKEN_SPENT`.
|
|
1791
|
+
**Fix:** answer 401 with `attemptsLeft`, and send the visitor back to sign in
|
|
1792
|
+
once it is `0`:
|
|
1793
|
+
|
|
1794
|
+
```ts
|
|
1795
|
+
import { TokenError } from '@softistx/janus';
|
|
1796
|
+
|
|
1797
|
+
try {
|
|
1798
|
+
return await auth.secondFactor.confirm(challenge, code);
|
|
1799
|
+
} catch (error) {
|
|
1800
|
+
if (error instanceof TokenError && error.code === 'CODE_INVALID') {
|
|
1801
|
+
return Response.json({ code: error.code, attemptsLeft: error.attemptsLeft }, { status: 401 });
|
|
1802
|
+
}
|
|
1803
|
+
throw error;
|
|
1804
|
+
}
|
|
1805
|
+
```
|
|
1806
|
+
|
|
1807
|
+
**`secondFactor.regenerateRecoveryCodes(user, code)`** — the app's code.
|
|
1808
|
+
**Why:** as for `activate`: the code is wrong, or was accepted before — by a
|
|
1809
|
+
sign-in or by an earlier regeneration. The user's recovery codes are
|
|
1810
|
+
unchanged. Every call costs one of the user's five attempts in the current
|
|
1811
|
+
15-minute window, counted before the code is compared, and the error carries
|
|
1812
|
+
`attemptsLeft` — `0` on the fifth wrong code; past the fifth, the message is
|
|
1813
|
+
[*too many codes tried*](#code_invalid--secondfactorregeneraterecoverycodes-too-many-codes-tried--wait-for-the-next-15-minute-window).
|
|
1814
|
+
**Fix:** ask for the next code the app shows, and answer 401 with
|
|
1815
|
+
`attemptsLeft`; past the fifth, wait `retryAfter` seconds.
|
|
1816
|
+
|
|
1817
|
+
**`secondFactor.recover(challenge, code)`** — a recovery code.
|
|
1818
|
+
**Why:** the recovery code is not one of the user's — a typo past what is
|
|
1819
|
+
forgiven, a TOTP code typed in the wrong field, a code from before a
|
|
1820
|
+
regeneration — or it was already used. Each call costs one of the
|
|
1821
|
+
challenge's five attempts, the same five `confirm` counts, and the error
|
|
1822
|
+
carries `attemptsLeft`.
|
|
1823
|
+
**Fix:** answer 401 with `attemptsLeft`, exactly as for `confirm`. If the user
|
|
1824
|
+
is sure of the code, see
|
|
1825
|
+
[a recovery code refused](#a-recovery-code-the-user-kept-is-refused-with-code_invalid).
|
|
1826
|
+
|
|
1827
|
+
**`signInCode.confirm(challenge, code)`** — the e-mailed code.
|
|
1828
|
+
**Why:** the code is not the one sent with this challenge, or is not six
|
|
1829
|
+
digits — a space, a dash, a code pasted with its label. The error carries
|
|
1830
|
+
`attemptsLeft` and the `userId` of the user the code was sent to. Every call
|
|
1831
|
+
costs one of the challenge's five attempts, counted before the code is
|
|
1832
|
+
compared — a call through another user type's `signInCode` too, although it
|
|
1833
|
+
answers `TOKEN_UNKNOWN`. At `0` the challenge is spent, and the next
|
|
1834
|
+
`confirm` is `TOKEN_SPENT`, even with the right code. Codes sent at once past
|
|
1835
|
+
the fifth attempt are all refused, the right one included.
|
|
1836
|
+
**Fix:** answer 401 with `attemptsLeft`, and request a new code once it is
|
|
1837
|
+
`0`. Strip what the visitor may have typed around the digits before calling
|
|
1838
|
+
`confirm`:
|
|
1839
|
+
|
|
1840
|
+
```ts
|
|
1841
|
+
import { TokenError } from '@softistx/janus';
|
|
1842
|
+
|
|
1843
|
+
try {
|
|
1844
|
+
return await auth.signInCode.confirm(challenge, code.replace(/\D/g, ''));
|
|
1845
|
+
} catch (error) {
|
|
1846
|
+
if (error instanceof TokenError && error.code === 'CODE_INVALID') {
|
|
1847
|
+
return Response.json({ code: error.code, attemptsLeft: error.attemptsLeft }, { status: 401 });
|
|
1848
|
+
}
|
|
1849
|
+
throw error;
|
|
1850
|
+
}
|
|
1851
|
+
```
|
|
1852
|
+
|
|
1853
|
+
If the visitor typed the code from the e-mail correctly, see
|
|
1854
|
+
[the code from an earlier e-mail](#the-code-from-an-earlier-e-mail-is-refused-with-code_invalid).
|
|
1855
|
+
|
|
1856
|
+
### `CODE_INVALID` — `secondFactor.confirm: too many codes tried — wait for the next 15-minute window`
|
|
1857
|
+
|
|
1858
|
+
`TokenError`, with `attemptsLeft: 0`, `reason: 'throttled'` and `retryAfter`, the seconds until the window frees. The same for `secondFactor.recover`.
|
|
1859
|
+
|
|
1860
|
+
**When:** `secondFactor.confirm` or `recover` on a challenge that still has
|
|
1861
|
+
attempts, after ten codes were already tried for that account (default) across
|
|
1862
|
+
all its challenges in the current window — the right code included. Nothing
|
|
1863
|
+
is compared or written, and the challenge is not spent.
|
|
1864
|
+
**Why:** a challenge's five attempts bound that challenge only; a new one
|
|
1865
|
+
costs only a first-factor sign-in. `confirmPasskey` is not counted. The account's own window bounds the guesses
|
|
1866
|
+
of someone who knows the password. It is separate from the one
|
|
1867
|
+
`regenerateRecoveryCodes` uses.
|
|
1868
|
+
**Fix:** tell the user to wait `retryAfter` seconds — 15 minutes at most — and
|
|
1869
|
+
answer 429 with `Retry-After`. If the user did not try that many codes,
|
|
1870
|
+
somebody knows their password and is guessing: reset it. Tune or switch off
|
|
1871
|
+
with `secondFactor.throttle: { attempts, window }` or `false`.
|
|
1872
|
+
|
|
1873
|
+
### `CODE_INVALID` — `secondFactor.regenerateRecoveryCodes: too many codes tried — wait for the next 15-minute window`
|
|
1874
|
+
|
|
1875
|
+
`TokenError`, with `attemptsLeft: 0`, `reason: 'throttled'` and `retryAfter`, the seconds until the window frees.
|
|
1876
|
+
|
|
1877
|
+
**When:** `secondFactor.regenerateRecoveryCodes(user, code)` — or
|
|
1878
|
+
`secondFactor.spendRecoveryCode(user, code)`, which shares the count, with
|
|
1879
|
+
the message `secondFactor.spendRecoveryCode: too many codes tried …` — after five codes
|
|
1880
|
+
were already tried for that user in the current window — whatever this code
|
|
1881
|
+
is, **the right one included**. Nothing is compared and nothing is written.
|
|
1882
|
+
**Why:** the call's code is the only thing between a stolen session and new
|
|
1883
|
+
recovery codes, so its attempts are bounded as a challenge's are: five per
|
|
1884
|
+
user, counted by the store, in fixed 15-minute windows of the clock. Every
|
|
1885
|
+
process over the same store shares the count. A code accepted — a
|
|
1886
|
+
regenerate, or a sign-in finished with the app — starts it again; a password
|
|
1887
|
+
written does not.
|
|
1888
|
+
**Fix:** tell the user to wait `retryAfter` seconds — 15 minutes at most —
|
|
1889
|
+
and answer 429 with a `Retry-After` header, or 401 as
|
|
1890
|
+
`@softistx/janus-hono`'s `janusErrors()` does — `retryAfter` and the
|
|
1891
|
+
`Retry-After` header either way. If nobody tried five codes, somebody else
|
|
1892
|
+
holds a session of theirs: revoke them with `signOutEverywhere(user)`.
|
|
1893
|
+
|
|
1894
|
+
```ts
|
|
1895
|
+
if (error instanceof TokenError && error.code === 'CODE_INVALID') {
|
|
1896
|
+
if (error.reason === 'throttled') {
|
|
1897
|
+
return Response.json(
|
|
1898
|
+
{ code: error.code, retryAfter: error.retryAfter },
|
|
1899
|
+
{ status: 429, headers: { 'Retry-After': String(error.retryAfter) } },
|
|
1900
|
+
);
|
|
1901
|
+
}
|
|
1902
|
+
return Response.json({ code: error.code, attemptsLeft: error.attemptsLeft }, { status: 401 });
|
|
1903
|
+
}
|
|
1904
|
+
```
|
|
1905
|
+
|
|
1906
|
+
### The code the authenticator app shows is refused with `CODE_INVALID`
|
|
1907
|
+
|
|
1908
|
+
**When:** `activate` or `confirm`, with the code on screen, typed correctly.
|
|
1909
|
+
**Why**, in the order to check:
|
|
1910
|
+
|
|
1911
|
+
1. **A clock is off.** A code is accepted in its own 30-second step and one step either side. A phone or a server whose clock is more than about 30 seconds away from the real time produces codes outside those three steps. How many steps are accepted is not configurable.
|
|
1912
|
+
2. **The code was already used** — and so were the codes before it. Once a code is accepted, that code and every earlier one are refused: the user who activates and then signs in within the same 30 seconds, or who signs in twice in a row, must wait for the next code.
|
|
1913
|
+
3. **The app holds an older secret.** `enroll` called again before `activate` replaces the secret: an entry scanned from the first `enroll` shows codes for a secret nobody holds any more.
|
|
1914
|
+
|
|
1915
|
+
**Fix:** for 1, keep the server's clock synchronised and ask the user to set their phone's time automatically. For 2, wait for the next code. For 3, delete the entry from the app and scan the `uri` of the last `enroll`.
|
|
1916
|
+
|
|
1917
|
+
```sh
|
|
1918
|
+
timedatectl show -p NTPSynchronized # NTPSynchronized=yes on the server
|
|
1919
|
+
```
|
|
1920
|
+
|
|
1921
|
+
### A recovery code the user kept is refused with `CODE_INVALID`
|
|
1922
|
+
|
|
1923
|
+
**When:** `secondFactor.recover`, with a code copied from the sheet the user was shown.
|
|
1924
|
+
**Why**, in the order to check:
|
|
1925
|
+
|
|
1926
|
+
1. **It was used already.** Each recovery code signs in once; `recoveryCodesLeft` told the user how many were left.
|
|
1927
|
+
2. **The codes were replaced.** `regenerateRecoveryCodes` ends every code shown before it, and `disable` removes them all — a factor enrolled and activated again has ten new ones.
|
|
1928
|
+
3. **It is the app's code.** `recover` takes a recovery code only; a six-digit code goes to `confirm`.
|
|
1929
|
+
4. **A sealing key was changed under the same id.** The hash then matches nothing, and nothing else says so. Restore the original key under that id.
|
|
1930
|
+
|
|
1931
|
+
**Fix:** for 1 and 2, the user signs in with the app, or with an unused code of the latest sheet. With neither, the factor has to be removed for them — `disable`, by your support process — and enrolled again.
|
|
1932
|
+
|
|
1933
|
+
```ts
|
|
1934
|
+
await auth.secondFactor.disable(userId); // after your own identity check: janus asks for nothing here
|
|
1935
|
+
```
|
|
1936
|
+
|
|
1937
|
+
### `SECOND_FACTOR_NOT_ENROLLED` — `secondFactor.regenerateRecoveryCodes: the user has no active second factor — recovery codes come with one`
|
|
1938
|
+
|
|
1939
|
+
`SecondFactorError`.
|
|
1940
|
+
|
|
1941
|
+
**When:** `regenerateRecoveryCodes` for a user with no second factor, or one enrolled and still waiting for its first code.
|
|
1942
|
+
**Why:** recovery codes belong to an active factor. `activate` hands out the first ten; there is nothing to replace before that.
|
|
1943
|
+
**Fix:** offer regeneration only when `user.hasSecondFactor`; for a factor still waiting, finish `activate`, whose answer carries the codes:
|
|
1944
|
+
|
|
1945
|
+
```ts
|
|
1946
|
+
if (!current.user.hasSecondFactor) return Response.json({ error: 'noSecondFactor' }, { status: 409 });
|
|
1947
|
+
const { recoveryCodes } = await auth.secondFactor.regenerateRecoveryCodes(current.user, code);
|
|
1948
|
+
```
|
|
1949
|
+
|
|
1950
|
+
### `SECOND_FACTOR_NOT_ENROLLED` — `secondFactor.activate: the user has no second factor waiting — call enroll first`
|
|
1951
|
+
|
|
1952
|
+
`SecondFactorError`. Also `secondFactor.confirm: the user no longer has a second factor — sign in again`, and the same from `secondFactor.recover`.
|
|
1953
|
+
|
|
1954
|
+
**When:** `activate` before `enroll`, or after `disable` — or after a sign-in by `signInCode` or `magicLink` that proved the e-mail for the first time, which removes a factor enrolled before it. On `confirm` or `recover`: the factor was disabled after `signIn` asked for a code, or removed by such a first proof when an outage kept its challenges from being spent — the proof spends them otherwise, and `confirm` answers `TOKEN_SPENT`.
|
|
1955
|
+
**Why:** `activate` checks a code against the secret `enroll` wrote, and there is none. On `confirm`, the factor the challenge asked for is gone, so the challenge is spent.
|
|
1956
|
+
**Fix:** `enroll`, show the `uri` as a QR code, then `activate` with a code from the app. After `confirm`'s refusal, sign in again: `signIn` answers a session directly for a user without a factor.
|
|
1957
|
+
|
|
1958
|
+
```ts
|
|
1959
|
+
const { secret, uri } = await auth.secondFactor.enroll(user);
|
|
1960
|
+
// …the user scans uri, or types secret…
|
|
1961
|
+
const { user: active, recoveryCodes } = await auth.secondFactor.activate(user, code);
|
|
1962
|
+
// show recoveryCodes once, on this response
|
|
1963
|
+
```
|
|
1964
|
+
|
|
1965
|
+
### `SECOND_FACTOR_ACTIVE` — `secondFactor.enroll: the user's second factor is active — disable it first`
|
|
1966
|
+
|
|
1967
|
+
`SecondFactorError`. Also `secondFactor.activate: the user's second factor is already active`.
|
|
1968
|
+
|
|
1969
|
+
**When:** `enroll` or `activate` for a user whose factor is already active — often a form submitted twice, or a "set up again" button.
|
|
1970
|
+
**Why:** enrolling again would replace the secret and quietly switch the factor off until the new one is activated. It is refused so that only `disable` switches it off.
|
|
1971
|
+
**Fix:** check `user.hasSecondFactor` first. To move to a new phone, disable, then enroll:
|
|
1972
|
+
|
|
1973
|
+
```ts
|
|
1974
|
+
const cleared = await auth.secondFactor.disable(user);
|
|
1975
|
+
const { uri } = await auth.secondFactor.enroll(cleared);
|
|
1976
|
+
```
|
|
1977
|
+
|
|
1978
|
+
### `<call>: …, and janus() was given no secondFactor — pass secondFactor: { issuer, keys }`
|
|
1979
|
+
|
|
1980
|
+
Most often: `signIn: the user's second factor is active, and janus() was given no secondFactor — pass secondFactor: { issuer, keys }`. A `TypeError`.
|
|
1981
|
+
|
|
1982
|
+
**When:** `signIn` for a user whose factor is active, on a `janus()` built without `secondFactor` — a second process over the same users: a worker, a script, an admin service, an older deployment. From JavaScript, `enroll`, `activate`, `confirm`, `recover` and `regenerateRecoveryCodes` on such an instance too.
|
|
1983
|
+
**Why:** the password alone never opens a session for a user with an active factor, and an instance without keys cannot check a code. It refuses rather than sign the user in on the password alone.
|
|
1984
|
+
**Fix:** give every `janus()` over the same users the same `secondFactor`, from one module:
|
|
1985
|
+
|
|
1986
|
+
```ts
|
|
1987
|
+
// auth-config.ts, imported by every process
|
|
1988
|
+
export const secondFactor = { issuer: 'Acme', keys } as const;
|
|
1989
|
+
|
|
1990
|
+
janus({ ..., secondFactor });
|
|
1991
|
+
```
|
|
1992
|
+
|
|
1993
|
+
### `<call>: the secret is sealed with the key "<id>", which secondFactor.keys no longer holds — keep a key until no secret is sealed with it`
|
|
1994
|
+
|
|
1995
|
+
A `TypeError`.
|
|
1996
|
+
|
|
1997
|
+
**When:** `activate`, `confirm` or `regenerateRecoveryCodes`, for a user whose secret was sealed with a key since removed from `keys` — or with a key another deployment has and this one does not.
|
|
1998
|
+
**Why:** each sealed secret names its key. The first key seals, every key opens, and a secret is sealed again under the first key only the next time a code of that user is accepted. A user who has not signed in since the rotation still holds the old seal.
|
|
1999
|
+
**Fix:** put the old key back, after the new one:
|
|
2000
|
+
|
|
2001
|
+
```ts
|
|
2002
|
+
secondFactor: {
|
|
2003
|
+
issuer: 'Acme',
|
|
2004
|
+
keys: [
|
|
2005
|
+
{ id: 'k2026b', key: process.env.TOTP_KEY_K2026B ?? '' }, // seals
|
|
2006
|
+
{ id: 'k2026a', key: process.env.TOTP_KEY_K2026A ?? '' }, // still opens
|
|
2007
|
+
],
|
|
2008
|
+
},
|
|
2009
|
+
```
|
|
2010
|
+
|
|
2011
|
+
A key can go once no stored second-factor secret starts with `v1.<its id>.`,
|
|
2012
|
+
nor any recovery code — see
|
|
2013
|
+
[a recovery code hashed with a key removed](#call-a-recovery-code-is-hashed-with-the-key-id-which-secondfactorkeys-no-longer-holds--keep-a-key-until-no-secret-or-recovery-code-uses-it).
|
|
2014
|
+
|
|
2015
|
+
### `<call>: the secret does not open with the key "<id>" — was that key changed under the same id, or the secret copied from another user?`
|
|
2016
|
+
|
|
2017
|
+
A `TypeError`.
|
|
2018
|
+
|
|
2019
|
+
**When:** `activate`, `confirm` or `regenerateRecoveryCodes`.
|
|
2020
|
+
**Why:** the key held under that id is not the one that sealed the secret: its value was changed and its id kept, or two environments sharing one database hold different keys under one id. It is also the message for a sealed secret copied onto another user — a seal is bound to the user's id — for example a user record duplicated by hand.
|
|
2021
|
+
**Fix:** restore the original key under that id. A new key always takes a new id. For a copied record, disable the factor and have the user enroll again: `await auth.secondFactor.disable(user)`.
|
|
2022
|
+
|
|
2023
|
+
### `<call>: the stored secret is not a sealed one`
|
|
2024
|
+
|
|
2025
|
+
A `TypeError`.
|
|
2026
|
+
|
|
2027
|
+
**When:** `activate`, `confirm` or `regenerateRecoveryCodes`.
|
|
2028
|
+
**Why:** the stored secret is not `v1.<key id>.<iv>.<sealed>`: it was written into the store directly — a plain base32 secret imported from another system — or cut short.
|
|
2029
|
+
**Fix:** never write the second factor into the store yourself. Disable it and have the user enroll again:
|
|
2030
|
+
|
|
2031
|
+
```ts
|
|
2032
|
+
await auth.secondFactor.disable(user);
|
|
2033
|
+
```
|
|
2034
|
+
|
|
2035
|
+
### `<call>: a recovery code is hashed with the key "<id>", which secondFactor.keys no longer holds — keep a key until no secret or recovery code uses it`
|
|
2036
|
+
|
|
2037
|
+
A `TypeError`: a 500, never a `CODE_INVALID` that would blame the user.
|
|
2038
|
+
|
|
2039
|
+
**When:** `secondFactor.recover`, for a user whose recovery codes were hashed under a key since removed from `keys`.
|
|
2040
|
+
**Why:** each recovery code's hash names its key, like a sealed secret. A secret is sealed again whenever a code is accepted; a recovery code cannot be hashed again — only its hash is kept — so it needs its key for as long as it exists. A rotation that waited only for the secrets removed the key too early.
|
|
2041
|
+
**Fix:** put the key back, after the first one. Remove it once no user holds a recovery code hashed with it — or have those users regenerate their codes, which hashes the new ones under the first key:
|
|
2042
|
+
|
|
2043
|
+
```ts
|
|
2044
|
+
// MongoDB, with @softistx/janus-mongo: matches any code in the array
|
|
2045
|
+
await db.collection('users').countDocuments({ 'secondFactor.recoveryCodes': { $regex: '^v1\\.2026-09\\.' } });
|
|
2046
|
+
```
|
|
2047
|
+
|
|
2048
|
+
```sql
|
|
2049
|
+
-- PostgreSQL, with @softistx/janus-drizzle
|
|
2050
|
+
select count(*) from users
|
|
2051
|
+
where exists (select 1 from unnest(second_factor_recovery_codes) c where c like 'v1.2026-09.%');
|
|
2052
|
+
```
|
|
2053
|
+
|
|
2054
|
+
### `<call>: a stored recovery code is not a keyed hash`
|
|
2055
|
+
|
|
2056
|
+
A `TypeError`.
|
|
2057
|
+
|
|
2058
|
+
**When:** `secondFactor.recover`.
|
|
2059
|
+
**Why:** one of the user's stored recovery codes is not `v1.<key id>.<mac>`: codes written into the store directly — plain codes imported from another system — or an adapter that altered the array.
|
|
2060
|
+
**Fix:** never write recovery codes into the store yourself; codes from another system cannot be carried over. Have the user regenerate theirs with a code from the app, which replaces the whole array:
|
|
2061
|
+
|
|
2062
|
+
```ts
|
|
2063
|
+
const { recoveryCodes } = await auth.secondFactor.regenerateRecoveryCodes(current.user, code);
|
|
2064
|
+
```
|
|
2065
|
+
|
|
2066
|
+
### `<call>: the <type> type has no password and the user has no e-mail, so a second factor has no account name`
|
|
2067
|
+
|
|
2068
|
+
A `TypeError`.
|
|
2069
|
+
|
|
2070
|
+
**When:** `secondFactor.enroll` on a passwordless user whose e-mail field is absent (an optional e-mail left empty). In TypeScript, `secondFactor` is absent from a type with neither a password nor an e-mail.
|
|
2071
|
+
**Why:** the authenticator app labels its entry with the login, or with the e-mail when the type has no password; there is nothing to show.
|
|
2072
|
+
**Fix:** give the user an e-mail before enrolling, or leave a type with no e-mail without a second factor.
|
|
2073
|
+
|
|
2074
|
+
### `totpCode: the secret is not base32` / `totpCode: at is not a valid Date`
|
|
2075
|
+
|
|
2076
|
+
Both are a `TypeError`, from `totpCode` of `@softistx/janus/testing`.
|
|
2077
|
+
|
|
2078
|
+
**When:** a test calls `totpCode(secret, at?)` with something that is not the secret `secondFactor.enroll` answered, or with an invalid `Date` (`new Date('soon')`, `new Date(NaN)`).
|
|
2079
|
+
**Why:** the secret is base32 (A-Z and 2-7; spaces, `=` padding and case are ignored). A string that holds other characters, such as the `otpauth://` URI or the sealed value a store keeps, is not one. A `Date` holding `NaN` has no thirty-second step to compute.
|
|
2080
|
+
**Fix:** pass the `secret` field of the enrolment, and a real moment, such as `clock.now()` from `fixedClock`:
|
|
2081
|
+
|
|
2082
|
+
```ts
|
|
2083
|
+
const { secret } = await auth.secondFactor.enroll(user); // not enrolment.uri
|
|
2084
|
+
const code = totpCode(secret, clock.now());
|
|
2085
|
+
```
|
|
2086
|
+
|
|
2087
|
+
---
|
|
2088
|
+
|
|
2089
|
+
## Sign-in codes
|
|
2090
|
+
|
|
2091
|
+
The messages start with `signInCode.confirm` — prefixed by the type with
|
|
2092
|
+
several user types: `patient.signInCode.confirm: …`. `signInCode.request`
|
|
2093
|
+
throws nothing but `STORE_FAILED` and
|
|
2094
|
+
[`MAIL_THROTTLED`](#mail_throttled--call-too-many-e-mails-asked-for-this-address--the-last-one-sent-still-works-use-it-or-wait-for-the-next-window):
|
|
2095
|
+
an e-mail it cannot sign in is `null`.
|
|
2096
|
+
`signInCode.confirm` also rejects with
|
|
2097
|
+
[`CODE_INVALID`](#code_invalid--call-the-code-does-not-match-or-was-already-used),
|
|
2098
|
+
[`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
|
|
2099
|
+
[`USER_INACTIVE`](#user_inactive--call-the-user-is-inactive) and
|
|
2100
|
+
[`VERSION_CONFLICT`](#version_conflict--call-expected-version-n-found-m);
|
|
2101
|
+
each of those entries has a paragraph for it.
|
|
2102
|
+
[The sign-in code guide](guide/sign-in-code.md) has the whole flow.
|
|
2103
|
+
|
|
2104
|
+
### `TOKEN_STALE` — `<call>: the code was sent to an e-mail the user no longer has`
|
|
2105
|
+
|
|
2106
|
+
`TokenError`, carrying the `userId`.
|
|
2107
|
+
|
|
2108
|
+
**When:** `signInCode.confirm`, after the user's e-mail was changed — by
|
|
2109
|
+
`update`, or a patch naming the e-mail field — since the code was sent.
|
|
2110
|
+
**Why:** the code proves an address, and signing in with it would mark as
|
|
2111
|
+
verified an address the user no longer holds. The challenge is spent.
|
|
2112
|
+
**Fix:** answer 400, and request a new code: it goes to the current address.
|
|
2113
|
+
|
|
2114
|
+
```ts
|
|
2115
|
+
const issued = await auth.signInCode.request(currentEmail);
|
|
2116
|
+
```
|
|
2117
|
+
|
|
2118
|
+
### The code from an earlier e-mail is refused with `CODE_INVALID`
|
|
2119
|
+
|
|
2120
|
+
**When:** the visitor asked for a code twice — pressed "send again", or
|
|
2121
|
+
opened the form in two tabs — and typed the code of the first e-mail.
|
|
2122
|
+
**Why:** every `request` issues a new code **with its own challenge**, and a
|
|
2123
|
+
code is checked against the challenge it was sent with. The cookie or the
|
|
2124
|
+
form field now holds the second challenge, so the first code does not
|
|
2125
|
+
match it — and costs an attempt.
|
|
2126
|
+
**Fix:** tell the visitor that only the last code sent works, and put the
|
|
2127
|
+
time it was sent in the e-mail's subject or text so they can tell the
|
|
2128
|
+
e-mails apart. The earlier challenge is spent by the new `request`: the
|
|
2129
|
+
first code, even with its own challenge, answers `TOKEN_SPENT`.
|
|
2130
|
+
|
|
2131
|
+
### `signInCode.request` answers `null` for a user who exists
|
|
2132
|
+
|
|
2133
|
+
**When:** `signInCode.request(email)`, for an address you can see in the
|
|
2134
|
+
database.
|
|
2135
|
+
**Why**, in the order to check:
|
|
2136
|
+
|
|
2137
|
+
1. **The user is inactive.** An inactive user gets no code, and the answer
|
|
2138
|
+
is the same as for nobody.
|
|
2139
|
+
2. **It is another user type.** `clinic.patient.signInCode.request` looks
|
|
2140
|
+
among patients only; the same address may hold a user of another type.
|
|
2141
|
+
3. **The address is not the type's e-mail field.** A type whose `email`
|
|
2142
|
+
option names `contact` is looked up by `contact`. A login that looks like
|
|
2143
|
+
an e-mail — a `username` of `ada@example.com` — is not an e-mail, and is
|
|
2144
|
+
`null` too.
|
|
2145
|
+
|
|
2146
|
+
The e-mail is trimmed and lowercased before the lookup, so case and
|
|
2147
|
+
surrounding spaces are never the cause.
|
|
2148
|
+
**Fix:** `setActive(user, true)`; call the right type's `signInCode`; name
|
|
2149
|
+
the field with `email: 'contact'`. Do not tell the visitor which case it
|
|
2150
|
+
was — the route answers the same page either way.
|
|
2151
|
+
|
|
2152
|
+
### `TS2339: Property 'signInCode' does not exist on type 'TypeApi<…>'.`
|
|
2153
|
+
|
|
2154
|
+
Also `Property 'signInCode' does not exist on type 'Janus<…>'.`, with the
|
|
2155
|
+
single-type form, `janus({ user })`.
|
|
2156
|
+
|
|
2157
|
+
**When:** `tsc`, on `auth.signInCode` or `clinic.<type>.signInCode`.
|
|
2158
|
+
**Why:** the user type has no e-mail: no field called `email`, and no
|
|
2159
|
+
`email` option naming one. A code has nowhere to be sent, so the flow is
|
|
2160
|
+
absent from the type.
|
|
2161
|
+
**Fix:** name the field that holds the e-mail:
|
|
2162
|
+
|
|
2163
|
+
```ts
|
|
2164
|
+
janus({
|
|
2165
|
+
users: {
|
|
2166
|
+
staff: { schema: Staff, password: { login: 'username' }, email: 'workEmail' },
|
|
2167
|
+
},
|
|
2168
|
+
...
|
|
2169
|
+
});
|
|
2170
|
+
```
|
|
2171
|
+
|
|
2172
|
+
---
|
|
2173
|
+
|
|
2174
|
+
## Sign-in links
|
|
2175
|
+
|
|
2176
|
+
`magicLink.confirm`'s messages start with `magicLink.confirm` — prefixed by
|
|
2177
|
+
the type with several user types: `patient.magicLink.confirm: …`.
|
|
2178
|
+
`magicLink.request` throws nothing but `STORE_FAILED`,
|
|
2179
|
+
[`MAGIC_LINK_DISABLED`](#magic_link_disabled--call-magic-link-sign-in-is-disabled) (so do `prepare` and `confirm`, with the switch off) and
|
|
2180
|
+
[`MAIL_THROTTLED`](#mail_throttled--call-too-many-e-mails-asked-for-this-address--the-last-one-sent-still-works-use-it-or-wait-for-the-next-window):
|
|
2181
|
+
an e-mail it cannot sign in is `null`. `magicLink.confirm` rejects with
|
|
2182
|
+
[`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
|
|
2183
|
+
[`TOKEN_STALE`](#token_stale--call-the-token-was-sent-to-an-e-mail-the-user-no-longer-has),
|
|
2184
|
+
[`USER_INACTIVE`](#user_inactive--call-the-user-is-inactive) and
|
|
2185
|
+
[`VERSION_CONFLICT`](#version_conflict--call-expected-version-n-found-m);
|
|
2186
|
+
each of those entries has a paragraph for it. On a type with a password or an e-mail in
|
|
2187
|
+
an instance given a `secondFactor`, reading its `token` before narrowing on
|
|
2188
|
+
`status` is the `TS2339` of `signIn`'s. [The sign-in link guide](guide/magic-link.md)
|
|
2189
|
+
has the whole flow.
|
|
2190
|
+
|
|
2191
|
+
### A sign-in link answers `TOKEN_SPENT` on the user's first click
|
|
2192
|
+
|
|
2193
|
+
`magicLink.confirm: the token was already used`, when the user swears they
|
|
2194
|
+
clicked once.
|
|
2195
|
+
|
|
2196
|
+
**When:** a route calls `magicLink.confirm` on the `GET` of the link — and
|
|
2197
|
+
most often for users behind a corporate mail gateway, or of a webmail that
|
|
2198
|
+
checks links.
|
|
2199
|
+
**Why:** a mail scanner opened the link before the user did. Gateways,
|
|
2200
|
+
safe-browsing checks and antivirus fetch every URL in an e-mail, and some
|
|
2201
|
+
run the page's scripts; a `GET` that confirms spent the token for them.
|
|
2202
|
+
**Fix:** make the link's `GET` a page that spends nothing, and confirm from
|
|
2203
|
+
its button's `POST` — not from a script that submits by itself, which a
|
|
2204
|
+
scanner that runs scripts submits too:
|
|
2205
|
+
|
|
2206
|
+
```ts
|
|
2207
|
+
// GET /sign-in/link?token=… → a page whose <form method="post"> holds the token, and a button
|
|
2208
|
+
// POST /sign-in/link → the one place that calls confirm
|
|
2209
|
+
const token = String((await request.formData()).get('token') ?? '');
|
|
2210
|
+
const signedIn = await auth.magicLink.confirm(token);
|
|
2211
|
+
```
|
|
2212
|
+
|
|
2213
|
+
The [guide](guide/magic-link.md#confirming-from-a-post-never-from-the-links-get)
|
|
2214
|
+
has the page, with the headers it needs.
|
|
2215
|
+
|
|
2216
|
+
### The link's own button answers `403`
|
|
2217
|
+
|
|
2218
|
+
**When:** the page the e-mailed link opens posts its token, and the route
|
|
2219
|
+
that checks the `Origin` before `magicLink.confirm` refuses it — for every
|
|
2220
|
+
user, or only on plain HTTP off `localhost` and in older browsers.
|
|
2221
|
+
**Why:** the page is sent with `Referrer-Policy: no-referrer`, and under it
|
|
2222
|
+
the browser posts the form with `Origin: null`. A check on `Origin` alone
|
|
2223
|
+
refuses every such `POST`; one that tries `Sec-Fetch-Site: same-origin`
|
|
2224
|
+
first refuses it wherever the browser sends no `Sec-Fetch-Site`. A
|
|
2225
|
+
mismatched `ORIGIN` — `http` for `https`, a port, a trailing `/` — does the
|
|
2226
|
+
same.
|
|
2227
|
+
**Fix:** send the page with `Referrer-Policy: strict-origin`, and set
|
|
2228
|
+
`ORIGIN` to the scheme, host and port the address bar shows. A `Referer`
|
|
2229
|
+
then holds the origin only, never the path and its token, and the form
|
|
2230
|
+
carries its real `Origin`:
|
|
2231
|
+
|
|
2232
|
+
```ts
|
|
2233
|
+
new Response(html, { headers: { 'Referrer-Policy': 'strict-origin', 'Cache-Control': 'no-store' } }); // the GET page
|
|
2234
|
+
if (request.headers.get('Origin') !== ORIGIN) return new Response(null, { status: 403 }); // on the POST
|
|
2235
|
+
```
|
|
2236
|
+
|
|
2237
|
+
The [guide](guide/magic-link.md#confirming-from-a-post-never-from-the-links-get)
|
|
2238
|
+
has the page and the route.
|
|
2239
|
+
|
|
2240
|
+
### The link signed in another device than the one that asked
|
|
2241
|
+
|
|
2242
|
+
**When:** a user asks for a link on a laptop and opens the e-mail on their
|
|
2243
|
+
phone: the phone is signed in, the laptop still waits.
|
|
2244
|
+
**Why:** the session opens in the browser that posts the token — whoever
|
|
2245
|
+
opens the link signs in, wherever they open it. That is what a link is.
|
|
2246
|
+
**Fix:** say on the page that asked "open the link on this device", or send
|
|
2247
|
+
a [sign-in code](guide/sign-in-code.md) instead: it is typed into the page
|
|
2248
|
+
that asked for it, so the sign-in completes there.
|
|
2249
|
+
|
|
2250
|
+
### `magicLink.request` answers `null` for a user who exists
|
|
2251
|
+
|
|
2252
|
+
**When:** `magicLink.request(email)`, for an address you can see in the
|
|
2253
|
+
database.
|
|
2254
|
+
**Why:** the same three causes as a
|
|
2255
|
+
[sign-in code's `null`](#signincoderequest-answers-null-for-a-user-who-exists):
|
|
2256
|
+
the user is inactive, is of another user type, or the address is not the
|
|
2257
|
+
type's e-mail field.
|
|
2258
|
+
**Fix:** as there. Do not tell the visitor which — the route answers the
|
|
2259
|
+
same page either way.
|
|
2260
|
+
|
|
2261
|
+
### `TS2339: Property 'magicLink' does not exist on type 'TypeApi<…>'.`
|
|
2262
|
+
|
|
2263
|
+
Also `Property 'magicLink' does not exist on type 'Janus<…>'.`, with the
|
|
2264
|
+
single-type form.
|
|
2265
|
+
|
|
2266
|
+
**When:** `tsc`, on `auth.magicLink` or `clinic.<type>.magicLink`.
|
|
2267
|
+
**Why:** the user type has no e-mail, so a link has nowhere to be sent — as
|
|
2268
|
+
for [`signInCode`](#ts2339-property-signincode-does-not-exist-on-type-typeapi).
|
|
2269
|
+
Or `@softistx/janus` is older than 0.15, which brought `magicLink`.
|
|
2270
|
+
**Fix:** name the field that holds the e-mail with the type's `email`
|
|
2271
|
+
option, or upgrade `@softistx/janus`.
|
|
2272
|
+
|
|
2273
|
+
### `TS2559: Type 'string' has no properties in common with type 'SignInOptions'.`, on `magicLink.confirm`
|
|
2274
|
+
|
|
2275
|
+
Before 0.17: `TS2554: Expected 1 arguments, but got 2.`
|
|
2276
|
+
|
|
2277
|
+
**When:** `tsc`, on `magicLink.confirm(challenge, code)` — a sign-in code's
|
|
2278
|
+
route copied for a link.
|
|
2279
|
+
**Why:** a link carries no code: its token is the whole secret. The second
|
|
2280
|
+
argument is `SignInOptions`, `{ device }`, which a string is not.
|
|
2281
|
+
**Fix:** `magicLink.confirm(token)`, with the token the link's page posted —
|
|
2282
|
+
and `magicLink.confirm(token, { device: cookie ?? null })` with
|
|
2283
|
+
[devices](guide/devices.md).
|
|
2284
|
+
|
|
2285
|
+
---
|
|
2286
|
+
|
|
2287
|
+
## Step-up
|
|
2288
|
+
|
|
2289
|
+
The messages start with `stepUp.request` or `stepUp.confirm` — prefixed by
|
|
2290
|
+
the type with several user types: `patient.stepUp.confirm: …`.
|
|
2291
|
+
`stepUp.confirm` also rejects with
|
|
2292
|
+
[`CODE_INVALID`](#code_invalid--call-the-code-does-not-match-or-was-already-used),
|
|
2293
|
+
[`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
|
|
2294
|
+
[`TOKEN_STALE`](#token_stale--call-the-code-was-sent-to-an-e-mail-the-user-no-longer-has),
|
|
2295
|
+
[`USER_INACTIVE`](#user_inactive--call-the-user-is-inactive) and
|
|
2296
|
+
[`VERSION_CONFLICT`](#version_conflict--call-expected-version-n-found-m),
|
|
2297
|
+
as `signInCode.confirm` does. [The step-up guide](guide/step-up.md) has the
|
|
2298
|
+
whole flow.
|
|
2299
|
+
|
|
2300
|
+
### `STEP_UP_REQUIRED` — `assertFresh: the session proved who it is longer ago than maxAge — confirm with a step-up`
|
|
2301
|
+
|
|
2302
|
+
`StepUpRequiredError`, carrying the `userId`; `statusOf` answers 403, and
|
|
2303
|
+
so does `@softistx/janus-hono`'s `janusErrors()`.
|
|
2304
|
+
|
|
2305
|
+
**When:** `assertFresh(session, maxAge)` — or `fresh(maxAge)` in a Hono
|
|
2306
|
+
app, whose message starts `fresh():` instead — on a session that signed
|
|
2307
|
+
in, or was last confirmed by a step-up, `maxAge` ago or more.
|
|
2308
|
+
**Why:** the route asks for a recent proof of who the user is; renewal
|
|
2309
|
+
keeps a session alive but proves nothing, so it never moves
|
|
2310
|
+
`authenticatedAt`.
|
|
2311
|
+
**Fix:** this is not a denial. Answer 403 with the code, and have the
|
|
2312
|
+
client run a step-up, then send the request again:
|
|
2313
|
+
|
|
2314
|
+
```ts
|
|
2315
|
+
const issued = await auth.stepUp.request(current.user);
|
|
2316
|
+
// … the user types the code …
|
|
2317
|
+
await auth.stepUp.confirm(request, challenge, code); // authenticatedAt: now
|
|
2318
|
+
```
|
|
2319
|
+
|
|
2320
|
+
### `TOKEN_UNKNOWN` — `stepUp.confirm: no such challenge`, with a challenge just issued
|
|
2321
|
+
|
|
2322
|
+
**When:** `stepUp.confirm(request, challenge, code)`, with the challenge
|
|
2323
|
+
`stepUp.request` answered a moment ago.
|
|
2324
|
+
**Why**, in the order to check:
|
|
2325
|
+
|
|
2326
|
+
1. **The request presents no standing session.** `confirm` stamps the
|
|
2327
|
+
session the request carries: pass the request itself — the cookie or the
|
|
2328
|
+
`Authorization: Bearer` header — not a new one built without it.
|
|
2329
|
+
2. **The session is another user's.** A challenge is confirmed on its
|
|
2330
|
+
user's own session only; one carried to another browser, signed in as
|
|
2331
|
+
someone else, is unknown there.
|
|
2332
|
+
3. **The session was signed out, revoked or lapsed** since the challenge
|
|
2333
|
+
was issued — a password reset revokes every session.
|
|
2334
|
+
4. **It is a sign-in code's challenge.** A step-up is a kind of its own: a
|
|
2335
|
+
`signInCode` challenge never confirms one.
|
|
2336
|
+
|
|
2337
|
+
**Fix:** confirm on the same request that asked; after a sign-out, sign in
|
|
2338
|
+
again — which is fresh on its own.
|
|
2339
|
+
|
|
2340
|
+
### `TOKEN_UNKNOWN` — `stepUp.confirm: the session was signed out while the code was checked`
|
|
2341
|
+
|
|
2342
|
+
**When:** `stepUp.confirm`, when the session was revoked — a sign-out in
|
|
2343
|
+
another tab, a password reset — between the check of the code and the
|
|
2344
|
+
write that stamps the session.
|
|
2345
|
+
**Why:** a confirmation never brings a revoked session back: the store
|
|
2346
|
+
writes `authenticatedAt` only while `revokedAt` is empty. The challenge was
|
|
2347
|
+
spent.
|
|
2348
|
+
**Fix:** answer 401 and sign in again.
|
|
2349
|
+
|
|
2350
|
+
### `SECOND_FACTOR_ACTIVE` — `stepUp.confirm: the user's second factor became active since the code was sent — request a step-up again`
|
|
2351
|
+
|
|
2352
|
+
`SecondFactorError`, carrying the `userId`.
|
|
2353
|
+
|
|
2354
|
+
**When:** `stepUp.confirm` with an e-mailed code, for a user who activated
|
|
2355
|
+
their second factor after `stepUp.request`.
|
|
2356
|
+
**Why:** a step-up is never weaker than the sign-in the account asks for —
|
|
2357
|
+
once the factor is active, only the app's code confirms. The challenge is
|
|
2358
|
+
spent.
|
|
2359
|
+
**Fix:** call `stepUp.request` again: it answers `via: 'secondFactor'`, and
|
|
2360
|
+
the user types the code from their app.
|
|
2361
|
+
|
|
2362
|
+
### `SECOND_FACTOR_NOT_ENROLLED` — `stepUp.confirm: the user no longer has a second factor — request a step-up again`
|
|
2363
|
+
|
|
2364
|
+
`SecondFactorError`, carrying the `userId`.
|
|
2365
|
+
|
|
2366
|
+
**When:** `stepUp.confirm` on a challenge issued `via: 'secondFactor'`, for
|
|
2367
|
+
a user whose factor was disabled since.
|
|
2368
|
+
**Why:** there is no secret left to check the app's code against. The
|
|
2369
|
+
challenge is spent.
|
|
2370
|
+
**Fix:** call `stepUp.request` again: it answers `via: 'email'`, with a code
|
|
2371
|
+
to send.
|
|
2372
|
+
|
|
2373
|
+
### `CODE_INVALID` — `stepUp.confirm: too many codes tried — wait for the next 15-minute window`
|
|
2374
|
+
|
|
2375
|
+
`TokenError`, `attemptsLeft: 0`, `reason: 'throttled'` and `retryAfter`, the seconds until the window frees.
|
|
2376
|
+
|
|
2377
|
+
**When:** `stepUp.confirm` with an app's code, after five app codes for
|
|
2378
|
+
the same user in the current 15-minute window — across step-ups and
|
|
2379
|
+
`secondFactor.regenerateRecoveryCodes`, which share the count.
|
|
2380
|
+
**Why:** a challenge takes five attempts, but a stolen session could ask
|
|
2381
|
+
for challenge after challenge; the window caps its guesses per user.
|
|
2382
|
+
**Fix:** tell the user to wait `retryAfter` seconds: **a new challenge does
|
|
2383
|
+
not help**. A challenge whose own five tries are spent while the window is
|
|
2384
|
+
free is `CODE_INVALID` with `attemptsLeft: 0` and no `reason` — there, request
|
|
2385
|
+
a new challenge. It is the
|
|
2386
|
+
[same count as `regenerateRecoveryCodes`](#code_invalid--secondfactorregeneraterecoverycodes-too-many-codes-tried--wait-for-the-next-15-minute-window).
|
|
2387
|
+
|
|
2388
|
+
### `NOT_FOUND` — `stepUp.request: the user has no e-mail`
|
|
2389
|
+
|
|
2390
|
+
`NotFoundError`, carrying the `userId`.
|
|
2391
|
+
|
|
2392
|
+
**When:** `stepUp.request(user)` for a user whose e-mail field is empty —
|
|
2393
|
+
an optional field left unset — and whose second factor is not active.
|
|
2394
|
+
**Why:** the code has nowhere to be sent.
|
|
2395
|
+
**Fix:** ask for the e-mail first. A user with an active second factor
|
|
2396
|
+
never meets this: the step-up asks for their app's code.
|
|
2397
|
+
|
|
2398
|
+
### `TS2339: Property 'code' does not exist on type 'StepUpByEmail<…> | StepUpByApp<…>'.`
|
|
2399
|
+
|
|
2400
|
+
Followed by `Property 'code' does not exist on type 'StepUpByApp<…>'.`
|
|
2401
|
+
|
|
2402
|
+
**When:** `tsc`, on `issued.code` after `stepUp.request`, with
|
|
2403
|
+
`secondFactor` configured on a type with a password, or on a passwordless type with an e-mail.
|
|
2404
|
+
**Why:** a user whose factor is active is sent no code — the answer is
|
|
2405
|
+
`via: 'secondFactor'`, with a challenge only. `request(user)` without `via`
|
|
2406
|
+
answers `StepUpByEmail` or `StepUpByApp`; `request(user, { via: 'passkey' })`
|
|
2407
|
+
(with `passkeys` configured) answers `StepUpByPasskey`, which has `options`
|
|
2408
|
+
and no code either.
|
|
2409
|
+
**Fix:** narrow on `via` first:
|
|
2410
|
+
|
|
2411
|
+
```ts
|
|
2412
|
+
const issued = await auth.stepUp.request(user);
|
|
2413
|
+
if (issued.via === 'email') await sendMail(issued.email, issued.code);
|
|
2414
|
+
```
|
|
2415
|
+
|
|
2416
|
+
### `TS2339: Property 'stepUp' does not exist on type 'TypeApi<…>'.`
|
|
2417
|
+
|
|
2418
|
+
**When:** `tsc`, on `clinic.<type>.stepUp` or `auth.stepUp`.
|
|
2419
|
+
**Why:** the user type has no e-mail, as for
|
|
2420
|
+
[`signInCode`](#ts2339-property-signincode-does-not-exist-on-type-typeapi):
|
|
2421
|
+
a code has nowhere to be sent.
|
|
2422
|
+
**Fix:** name the field that holds the e-mail with the `email` option.
|
|
2423
|
+
|
|
2424
|
+
---
|
|
2425
|
+
|
|
2426
|
+
## Devices
|
|
2427
|
+
|
|
2428
|
+
The three messages below are bare `TypeError`s, thrown by a sign-in before
|
|
2429
|
+
anything is written — a `signUp` creates no user. `<call>` is the call you
|
|
2430
|
+
wrote: `signIn`, `secondFactor.recover`, `patient.magicLink.confirm`. A
|
|
2431
|
+
device token itself is never refused: one that proves nothing is a new
|
|
2432
|
+
device. [The devices guide](guide/devices.md) has the whole flow.
|
|
2433
|
+
|
|
2434
|
+
### `<call>: a device was given, but janus() has no devices — pass devices: { keys }`
|
|
2435
|
+
|
|
2436
|
+
**When:** a sign-in given `{ device }` — `{ device: null }` included — on a
|
|
2437
|
+
`janus()` wired without `devices`. Most often one instance of several: the
|
|
2438
|
+
one that serves another route — the second factor's code, a sign-in link —
|
|
2439
|
+
was built from another configuration.
|
|
2440
|
+
**Why:** a device token is signed and checked with `devices.keys`; without
|
|
2441
|
+
keys there is nothing to sign it with, and answering `newDevice: false` would
|
|
2442
|
+
hide a notice you meant to send.
|
|
2443
|
+
**Fix:** give every `janus()` that signs users in the same `devices` — build
|
|
2444
|
+
the configuration once and import it:
|
|
2445
|
+
|
|
2446
|
+
```ts
|
|
2447
|
+
export const devices = { keys: [{ id: '2026-09', key: process.env.DEVICES_KEY_2026_09 ?? '' }] } as const;
|
|
2448
|
+
janus({ ...config, devices });
|
|
2449
|
+
```
|
|
2450
|
+
|
|
2451
|
+
Or stop passing `{ device }` where devices are not wanted.
|
|
2452
|
+
|
|
2453
|
+
### `<call>: options must be { device }, or left out — the token goes under device`
|
|
2454
|
+
|
|
2455
|
+
**When:** from JavaScript, or through a cast, options that are not an
|
|
2456
|
+
object — most often the token itself, `auth.signIn(credentials, deviceOf(c))`,
|
|
2457
|
+
where `{ device: deviceOf(c) }` belongs. Left unrefused, that sign-in would
|
|
2458
|
+
be silently untracked: no token, no notice.
|
|
2459
|
+
**Why:** the last argument is `SignInOptions`, `{ device }`, or nothing.
|
|
2460
|
+
**Fix:**
|
|
2461
|
+
|
|
2462
|
+
```ts
|
|
2463
|
+
await auth.signIn(credentials, { device: token ?? null });
|
|
2464
|
+
```
|
|
2465
|
+
|
|
2466
|
+
### `<call>: options.device must be the device token the client holds, or null when it holds none`
|
|
2467
|
+
|
|
2468
|
+
**When:** from JavaScript, or through a cast, a `device` that is neither a
|
|
2469
|
+
string nor `null`: a number, an object — the cookie jar, a parsed cookie, the
|
|
2470
|
+
previous `SignedIn` instead of its `deviceToken`. `undefined` is not refused:
|
|
2471
|
+
it means "not tracked".
|
|
2472
|
+
**Why:** `device` is the token the client holds, as a string, or `null` when
|
|
2473
|
+
it holds none.
|
|
2474
|
+
**Fix:**
|
|
2475
|
+
|
|
2476
|
+
```ts
|
|
2477
|
+
await auth.signIn(credentials, { device: previous.deviceToken }); // the string, or null
|
|
2478
|
+
```
|
|
2479
|
+
|
|
2480
|
+
### Every sign-in reports a new device
|
|
2481
|
+
|
|
2482
|
+
**When:** `newDevice` is `true` — and `user.newDeviceSignedIn` sent, and a
|
|
2483
|
+
notice e-mailed — at every sign-in of a user who always uses the same
|
|
2484
|
+
browser.
|
|
2485
|
+
**Why:** the token the sign-in is given does not prove this user signed in
|
|
2486
|
+
there. In order of likelihood:
|
|
2487
|
+
|
|
2488
|
+
- **the device cookie is not kept.** It was never set from `deviceToken`;
|
|
2489
|
+
it was set without `Max-Age` or `Expires`, so the browser drops it when it
|
|
2490
|
+
closes; it is `Secure` on a plain `http://` origin other than
|
|
2491
|
+
`localhost`; its `Path` or `Domain` leaves out a sign-in route; or it is
|
|
2492
|
+
written under one name and read under another;
|
|
2493
|
+
- **a confirmation is given `null`** rather than the cookie — a
|
|
2494
|
+
`{ device: null }` written in the second factor's route — so each
|
|
2495
|
+
confirmation is a device holding no token;
|
|
2496
|
+
- **a device key was removed**, or two instances hold different keys: each
|
|
2497
|
+
device is new once after a removal, and at every sign-in that reaches the
|
|
2498
|
+
other instance;
|
|
2499
|
+
- **two people share the browser** and take turns: one cookie holds one
|
|
2500
|
+
user's token, and the other's proves nothing.
|
|
2501
|
+
|
|
2502
|
+
**Fix:** set the cookie from every answer's `deviceToken`, long-lived and
|
|
2503
|
+
sent to every sign-in route, and read it under the same name:
|
|
2504
|
+
|
|
2505
|
+
```ts
|
|
2506
|
+
headers.append('Set-Cookie', deviceCookie(signedIn.deviceToken));
|
|
2507
|
+
```
|
|
2508
|
+
|
|
2509
|
+
Give the confirmations the cookie too, and every `janus()` the same
|
|
2510
|
+
`devices`. The shared browser is not a bug: it is the price of storing
|
|
2511
|
+
nothing.
|
|
2512
|
+
|
|
2513
|
+
### `RangeError: deviceCookie(): maxAge must be a number of seconds from 0 to 34560000 (400 days), got …`
|
|
2514
|
+
|
|
2515
|
+
**When:** `deviceCookie(token, options)` is called
|
|
2516
|
+
with a `maxAge` that is not a finite number from 0 to 34560000 — `NaN`,
|
|
2517
|
+
`Infinity`, a negative value, or above 400 days — most often milliseconds
|
|
2518
|
+
given where seconds belong. It throws after the sign-in completed: the
|
|
2519
|
+
session exists, the response is not sent.
|
|
2520
|
+
**Why:** a browser keeps a cookie 400 days at most, and `deviceCookie` refuses
|
|
2521
|
+
a `maxAge` it would not keep rather than write it.
|
|
2522
|
+
**Fix:** give seconds within 0 to 34560000 — or leave `maxAge` out, which is
|
|
2523
|
+
400 days.
|
|
2524
|
+
|
|
2525
|
+
```ts
|
|
2526
|
+
headers.append('Set-Cookie', deviceCookie(signedIn.deviceToken, { maxAge: 60 * 60 * 24 * 180 })); // 180 days
|
|
2527
|
+
```
|
|
2528
|
+
|
|
2529
|
+
### `TypeError: deviceCookie(): …` (a name, prefix or attribute the browser would refuse)
|
|
2530
|
+
|
|
2531
|
+
**When:** `deviceCookie(token, options)` is called
|
|
2532
|
+
with a `name` that is not a valid cookie name, a `__Secure-` name without
|
|
2533
|
+
`secure: true`, a `__Host-` name without `secure: true`, with a `path` other
|
|
2534
|
+
than `'/'` or with a `domain`, or a `domain`, `path` or `sameSite` holding
|
|
2535
|
+
`;`, a carriage return or a line feed. The message names the option.
|
|
2536
|
+
**Why:** `deviceCookie` refuses what Hono's `setCookie` refuses: a browser
|
|
2537
|
+
would drop the cookie, and a `;` or line break in an attribute could inject
|
|
2538
|
+
another one.
|
|
2539
|
+
**Fix:** meet the prefix's terms, or drop the prefix — `__Host-` asks `Secure`,
|
|
2540
|
+
`Path=/` and no `Domain`; the adapters' `device` options are the same object.
|
|
2541
|
+
|
|
2542
|
+
```ts
|
|
2543
|
+
headers.append('Set-Cookie', deviceCookie(signedIn.deviceToken, { name: '__Host-device' })); // Secure, Path=/, no Domain
|
|
2544
|
+
```
|
|
2545
|
+
|
|
2546
|
+
### A new device is never reported: `newDevice` is always `false`
|
|
2547
|
+
|
|
2548
|
+
**When:** a user signs in from a browser that never saw them, and nothing is
|
|
2549
|
+
reported: `newDevice: false`, `deviceToken: null`, no event.
|
|
2550
|
+
**Why:**
|
|
2551
|
+
|
|
2552
|
+
- **no `device` was given** — absent, or `undefined`: a cookie read as
|
|
2553
|
+
`string | undefined` passed as it is, which compiles unless your tsconfig
|
|
2554
|
+
has `exactOptionalPropertyTypes`. Absent means *not tracked*, not *new*;
|
|
2555
|
+
- **the device was not given again** to `secondFactor.confirm` or `recover`:
|
|
2556
|
+
for a user with an active second factor, the challenge `signIn` answered
|
|
2557
|
+
carries none, and the confirmation decides alone;
|
|
2558
|
+
- `newDevice` read on `signUp`'s answer, which is never new.
|
|
2559
|
+
|
|
2560
|
+
**Fix:** pass `null` for a client with no token, and the device to every
|
|
2561
|
+
call that opens a session:
|
|
2562
|
+
|
|
2563
|
+
```ts
|
|
2564
|
+
const device = cookie ?? null;
|
|
2565
|
+
const result = await auth.signIn(credentials, { device });
|
|
2566
|
+
if (result.status === 'secondFactor') await auth.secondFactor.confirm(result.challenge, code, { device });
|
|
2567
|
+
```
|
|
2568
|
+
|
|
2569
|
+
### `TS2379: Argument of type '{ device: string | undefined; }' is not assignable to parameter of type 'SignInOptions' with 'exactOptionalPropertyTypes: true'.`
|
|
2570
|
+
|
|
2571
|
+
It goes on: `Type 'string | undefined' is not assignable to type 'string | null'.`
|
|
2572
|
+
|
|
2573
|
+
**When:** `tsc`, with `exactOptionalPropertyTypes`, on a sign-in given a
|
|
2574
|
+
cookie read as `string | undefined`.
|
|
2575
|
+
**Why:** `undefined` would mean *not tracked*: a browser without a cookie
|
|
2576
|
+
would never be given a token, and never reported. `null` says the client
|
|
2577
|
+
holds none.
|
|
2578
|
+
**Fix:** `{ device: cookie ?? null }`. Without that compiler option, the same
|
|
2579
|
+
line compiles and tracks nothing — write `?? null` there too.
|
|
2580
|
+
|
|
2581
|
+
### `TS2739: Type '{ … }' is missing the following properties from type 'SignedIn<…>': newDevice, deviceToken`
|
|
2582
|
+
|
|
2583
|
+
**When:** `tsc`, on a `SignedIn` built by hand — a test double of `signIn`,
|
|
2584
|
+
a stub of `auth` — after upgrading to 0.17.
|
|
2585
|
+
**Why:** every answer that opens a session now carries `newDevice` and
|
|
2586
|
+
`deviceToken`.
|
|
2587
|
+
**Fix:**
|
|
2588
|
+
|
|
2589
|
+
```ts
|
|
2590
|
+
const signedIn: SignedIn<User> = { status: 'signedIn', user, session, token, newDevice: false, deviceToken: null };
|
|
2591
|
+
```
|
|
2592
|
+
|
|
2593
|
+
### `TS2559: Type 'string' has no properties in common with type 'SignInOptions'.`, on `secondFactor.confirm` or `signInCode.confirm`
|
|
2594
|
+
|
|
2595
|
+
Also: `Type '"<value>"' has no properties in common with type 'SignInOptions'.`
|
|
2596
|
+
for a literal token, and `TS2345: Argument of type 'string | undefined' is
|
|
2597
|
+
not assignable to parameter of type 'SignInOptions | undefined'.` — or
|
|
2598
|
+
`'string | null'` — for a cookie or an earlier `deviceToken`, given as is.
|
|
2599
|
+
|
|
2600
|
+
**When:** `tsc`, on `secondFactor.confirm(challenge, code, token)` or
|
|
2601
|
+
`signInCode.confirm(challenge, code, token)` — the device token given as a
|
|
2602
|
+
bare string, or as a nullable one.
|
|
2603
|
+
**Why:** the options come last, as an object: `{ device }`.
|
|
2604
|
+
**Fix:** `secondFactor.confirm(challenge, code, { device: token ?? null })`.
|
|
2605
|
+
|
|
2606
|
+
### `TS2322: Type 'string | null' is not assignable to type 'string'.`, on `deviceToken`
|
|
2607
|
+
|
|
2608
|
+
**When:** `tsc`, reading `signedIn.deviceToken` as a `string` — to set a
|
|
2609
|
+
cookie.
|
|
2610
|
+
**Why:** it is `null` when the sign-in was given no `device`: nothing was
|
|
2611
|
+
minted then.
|
|
2612
|
+
**Fix:** set the cookie only for a token — `if (signedIn.deviceToken !==
|
|
2613
|
+
null) …` — or give every sign-in a `device`.
|
|
2614
|
+
|
|
2615
|
+
---
|
|
2616
|
+
|
|
2617
|
+
## Social sign-in
|
|
2618
|
+
|
|
2619
|
+
### `FLOW_EXPIRED` — `social.complete: the flow is unknown, used or lapsed — start it again`
|
|
2620
|
+
|
|
2621
|
+
`SocialError`, 400.
|
|
2622
|
+
|
|
2623
|
+
**When:** the provider's callback reaches `social.complete` a second time (the visitor reloads or presses back), after more than `tokens.socialFlow` (ten minutes), or with a cookie value nobody issued.
|
|
2624
|
+
**Why:** a flow is single-use. Once its `state` matched, every outcome — a success, `PROVIDER_ERROR`, `SIGN_UP_DISABLED` — spends it, and a lapsed one is spent too.
|
|
2625
|
+
**Fix:** answer 400 and send the visitor to `social.start` again; clear the cookie with `auth.social.cookie.clear()`. Raise `tokens: { socialFlow: '15m' }` only if visitors take longer at the provider.
|
|
2626
|
+
|
|
2627
|
+
### `FLOW_MISMATCH` — `social.complete: the flow cookie is missing or malformed` / `the callback's state is not this flow's` / `the flow cookie's contents were changed` / `this link was started by another user`
|
|
2628
|
+
|
|
2629
|
+
`SocialError`, 400.
|
|
2630
|
+
|
|
2631
|
+
**When:** the callback arrives without the flow cookie, with a `state` that is not this flow's, with a cookie that was edited, or — for a link — from a different signed-in user than the one who started it.
|
|
2632
|
+
**Why:** the cookie and the `state` bind a callback to the browser that started the flow. The usual cause is a cookie that did not travel: set on another host or path than the callback's, `Secure` on plain `http`, `SameSite=Strict` added by a proxy, or a BFF that never forwarded it. A missing cookie or a foreign `state` leaves the flow unspent; the other two spend it.
|
|
2633
|
+
|
|
2634
|
+
**A link flow also ends here when your session cookie is `sameSite: 'strict'`.** The provider's callback is a cross-site navigation, so the browser leaves a Strict cookie out, `authenticate` finds no session, the callback has no `current`, and the flow is spent. Use `sameSite: 'lax'` for the session cookie when users link accounts.
|
|
2635
|
+
|
|
2636
|
+
**Fix:** send the cookie with the callback request and give `complete` its value unchanged:
|
|
2637
|
+
|
|
2638
|
+
```ts
|
|
2639
|
+
const flow = new RegExp(`(?:^|; )${auth.social.cookie.name}=([^;]*)`).exec(request.headers.get('cookie') ?? '')?.[1] ?? '';
|
|
2640
|
+
await auth.social.complete({ callback: new URL(request.url).searchParams, flow, current }); // `current` only for a link
|
|
2641
|
+
```
|
|
2642
|
+
|
|
2643
|
+
### `FLOW_PURPOSE_MISMATCH` — `social.complete: this is a sign-in flow, and a link flow was expected` / `this is a link flow, and a sign-in flow was expected`
|
|
2644
|
+
|
|
2645
|
+
`SocialError`, 400.
|
|
2646
|
+
|
|
2647
|
+
**When:** `social.complete` was given `purpose: 'link'` and the flow came from `social.start`, or `purpose: 'signIn'` and it came from `social.link`.
|
|
2648
|
+
**Why:** `start` and `link` answer the same kind of `flow` string, and `complete` alone tells them apart. The `purpose` makes an endpoint that is only for one kind refuse the other before the provider is called, so a sign-in flow handed to a link endpoint cannot sign anybody in. The flow is spent (`flowSpent: true`); nothing was linked or signed in.
|
|
2649
|
+
**Fix:** a mismatch is a wrong endpoint or a forged request: clear the cookie, answer 400 and start the right flow. If both kinds legitimately reach the endpoint, leave `purpose` out.
|
|
2650
|
+
|
|
2651
|
+
```ts
|
|
2652
|
+
await auth.social.complete({ callback, flow, current, purpose: 'link' });
|
|
2653
|
+
```
|
|
2654
|
+
|
|
2655
|
+
### `RETURN_TO_INVALID` — `social.start: returnTo must be a path of this site — starting with a single "/", with no "\", no empty or "." segment and no scheme`
|
|
2656
|
+
|
|
2657
|
+
`SocialError`, 400. Also from `social.link`.
|
|
2658
|
+
|
|
2659
|
+
**When:** `returnTo` is a full URL, starts with `//`, has an empty, `.` or `..` segment (`/.//evil.test` reads as `//evil.test` in a browser), holds a backslash or a control character, or is over 2048 characters.
|
|
2660
|
+
**Why:** a `returnTo` the visitor is redirected to after sign-in is an open redirect unless it stays on your site. Nothing was started.
|
|
2661
|
+
**Fix:** pass a path; take it from your own state, not from a raw query string:
|
|
2662
|
+
|
|
2663
|
+
```ts
|
|
2664
|
+
await auth.social.start({ provider: 'google', returnTo: '/billing?plan=pro' });
|
|
2665
|
+
```
|
|
2666
|
+
|
|
2667
|
+
### `PROVIDER_ERROR` — `social.complete: the provider "<name>" failed`
|
|
2668
|
+
|
|
2669
|
+
`SocialError`, 502, carrying `provider` and `reason`: `'denied'`, `'refused'` or `'unreachable'`. The original failure is its `cause`. Also from `social.start`, when the provider is unreachable; and `social.complete: the provider "<name>" answered no usable identity — accountId, email and emailVerified are required` for an identity the core cannot keep.
|
|
2670
|
+
|
|
2671
|
+
**When:** the visitor refused at the provider (`denied`), the token exchange or the ID token check failed (`refused`), or the provider could not be reached, at `start` or at `complete` (`unreachable`).
|
|
2672
|
+
**Why:** `exchange` or `authorizationUrl` threw. Any failure of the provider becomes this code, so the core never answers a provider's message. An identity with an empty, over-512-character or NUL-holding `accountId`, or without a string `email` and a boolean `emailVerified`, is `refused` too.
|
|
2673
|
+
**Fix:** answer 502, show the visitor a neutral "try again", and read `reason` and `cause` in your logs. **Never put `reason` in a response body.** If it is always `refused`, check the provider's client id, secret and redirect URI:
|
|
2674
|
+
|
|
2675
|
+
```ts
|
|
2676
|
+
if (error instanceof SocialError && error.code === 'PROVIDER_ERROR') logger.warn({ provider: error.provider, reason: error.reason, cause: error.cause });
|
|
2677
|
+
```
|
|
2678
|
+
|
|
2679
|
+
### `SOCIAL_PROVIDER_UNKNOWN` — `social.start: the user type configures no such social provider`
|
|
2680
|
+
|
|
2681
|
+
`SocialError`, 404, carrying `provider`. Also `this user's type configures no social provider` when the type has none.
|
|
2682
|
+
|
|
2683
|
+
**When:** `social.start`, `social.link` or `social.complete` named a provider the user type does not have: the name is not under `social.providers`, **and** either there is no `social.resolveProvider`, the name fails the provider-name pattern (the resolver is never called for it), the resolver answered `null`, or the connection was removed between `start` and `complete` (then the error carries `flowSpent: true` and the flow's `returnTo`).
|
|
2684
|
+
**Why:** the name came from a URL or a form (`/auth/:provider`) and is not one of yours. Names are lowercase letters, digits and `-`, starting with a letter, at most 32 characters.
|
|
2685
|
+
**Not this:** a `StoreFailure` thrown by `resolveProvider` propagates as itself, it is never an unknown provider: check the resolver's database.
|
|
2686
|
+
**Fix:** answer 404 and list the providers explicitly, or make the resolver answer the connection:
|
|
2687
|
+
|
|
2688
|
+
```ts
|
|
2689
|
+
const social = { providers: { google, github } }; // a request for /auth/gitlab is SOCIAL_PROVIDER_UNKNOWN
|
|
2690
|
+
```
|
|
2691
|
+
|
|
2692
|
+
### `janus: social.providers must name at least one provider, or social.resolveProvider must be given`
|
|
2693
|
+
|
|
2694
|
+
A `TypeError` at wiring, and a compile error: `social` has neither a non-empty `providers` nor a `resolveProvider`.
|
|
2695
|
+
|
|
2696
|
+
**Fix:** list the providers, give a resolver, or both.
|
|
2697
|
+
|
|
2698
|
+
```ts
|
|
2699
|
+
social: { providers: { google } }, // or: { resolveProvider: async (name) => lookup(name) }
|
|
2700
|
+
```
|
|
2701
|
+
|
|
2702
|
+
### `janus: social.resolveProvider must be a function …`
|
|
2703
|
+
|
|
2704
|
+
A `TypeError` at wiring: `resolveProvider` is not a function (a map, a provider, a string).
|
|
2705
|
+
|
|
2706
|
+
**Fix:** give `(name) => Promise<SocialProvider | null>`; a map of providers goes under `providers`.
|
|
2707
|
+
|
|
2708
|
+
### `social.resolveProvider("<name>") must answer a provider …`
|
|
2709
|
+
|
|
2710
|
+
A `TypeError` at `start`, `link` or `complete`: the resolver answered something that is neither `null` nor an object with `authorizationUrl` and `exchange` (`undefined` from a missing `return`, a record not turned into a provider).
|
|
2711
|
+
|
|
2712
|
+
**Why:** a bug in the resolver, not a refusal. At `complete` the flow was already spent, so the user starts again.
|
|
2713
|
+
**Fix:** answer `null` for an unknown name and a built `SocialProvider` otherwise.
|
|
2714
|
+
|
|
2715
|
+
### `SIGN_UP_DISABLED` — `social.complete: nobody holds this account's e-mail, and the user type does not sign strangers up`
|
|
2716
|
+
|
|
2717
|
+
`SocialError`, 403, carrying `provider`.
|
|
2718
|
+
|
|
2719
|
+
**When:** a visitor signs in with a provider account that is not linked, and no user of the type holds its e-mail.
|
|
2720
|
+
**Why:** `social.signUp` is absent or `false`, so a stranger is refused. Nothing was created. The answer tells the visitor that no account holds that address.
|
|
2721
|
+
**Fix:** to let strangers in, give the type a `signUp`; to keep them out, tell the visitor to sign up or be invited first, then link the provider:
|
|
2722
|
+
|
|
2723
|
+
```ts
|
|
2724
|
+
social: { providers: { google }, signUp: (profile) => ({ email: profile.email ?? '', name: profile.name ?? 'Unnamed' }) },
|
|
2725
|
+
```
|
|
2726
|
+
|
|
2727
|
+
### `EMAIL_NOT_VERIFIED_FOR_LINK` — `social.complete: a user holds this e-mail, and the provider or the account does not vouch for it — sign in another way, then link the account`
|
|
2728
|
+
|
|
2729
|
+
`SocialError`, 409, carrying `provider`.
|
|
2730
|
+
|
|
2731
|
+
**When:** the provider's account is not linked, and a user of the type holds its e-mail, but the provider reports `emailVerified: false` or the local account never verified its address.
|
|
2732
|
+
**Why:** linking on an address one side has not proved would hand the account to whoever controls the unproven side. Nothing was linked. The answer tells the visitor an account exists for that address.
|
|
2733
|
+
**Fix:** the user signs in the way they have, and links from `social.link`, which needs no e-mail match. If the local address is unverified, have them prove it first (`verifyEmail.confirm`). If the account was registered by somebody else, they recover it: `resetPassword`, or `verifyEmail` with `{ firstProof: true }`, which prove the address and drop the squatter's password.
|
|
2734
|
+
|
|
2735
|
+
### `SOCIAL_ACCOUNT_TAKEN` — `social.complete: this social account is already linked to another user`
|
|
2736
|
+
|
|
2737
|
+
`SocialError`, 409, carrying `provider`.
|
|
2738
|
+
|
|
2739
|
+
**When:** a link flow completes with a provider account another user holds, or a sign-in finds the account linked to a user of another type.
|
|
2740
|
+
**Why:** a provider account links to one user per instance, so one Google account cannot be both a patient and a staff member.
|
|
2741
|
+
**Fix:** answer 409. The other user unlinks it (`social.unlink`) first, or the visitor uses another provider account.
|
|
2742
|
+
|
|
2743
|
+
### `SOCIAL_STEP_UP_UNMET` — `social.complete: the provider's answer does not prove the step-up the flow asked for`
|
|
2744
|
+
|
|
2745
|
+
`SocialError`, 403, carrying `provider`, `returnTo`, `flowSpent: true` and `reason` (`'acr'` or `'authTime'`, for logs only).
|
|
2746
|
+
|
|
2747
|
+
**When:** a flow started with `stepUp` completes and the identity has no `acr` or one that was not asked for, no `authTime` or one older than `maxAge` plus 60 s, or the provider stopped setting `supportsStepUp` since `start`.
|
|
2748
|
+
**Why:** `acr_values` and `max_age` are requests, and the provider may ignore them; the core trusts only the evidence the identity carries, on its own clock, and a missing one is unmet. The flow is spent and nobody signed in or linked.
|
|
2749
|
+
**Fix:** answer 403 or send the visitor back with `?socialError=SOCIAL_STEP_UP_UNMET` and offer to try again; log `reason`. If every attempt fails, check that the provider honours `acr_values` (some, such as Google, do not) and reports `acr` / `auth_time`.
|
|
2750
|
+
|
|
2751
|
+
### `LAST_SIGN_IN_METHOD` — `social.unlink: this is the user's only way to sign in — set a password or link another account first`
|
|
2752
|
+
|
|
2753
|
+
`SocialError`, 409, carrying `provider`.
|
|
2754
|
+
|
|
2755
|
+
**When:** `social.unlink` for a user with no password, no other link and, on a type with no password, no verified e-mail.
|
|
2756
|
+
**Why:** deleting the link would lock the user out. The check counts a password, the other links and — on a type with no password — a verified e-mail. Nothing was deleted.
|
|
2757
|
+
**Fix:** answer 409; ask the user to add a way in, then unlink:
|
|
2758
|
+
|
|
2759
|
+
```ts
|
|
2760
|
+
await auth.setPassword(user, newPassword); // or link another account, then:
|
|
2761
|
+
await auth.social.unlink(user, { provider: 'google', accountId });
|
|
2762
|
+
```
|
|
2763
|
+
|
|
2764
|
+
### `EMAIL_UNVERIFIED` — `social.complete: the provider does not vouch for an e-mail, so no account is created`
|
|
2765
|
+
|
|
2766
|
+
`EmailUnverifiedError`, 403, carrying `provider`.
|
|
2767
|
+
|
|
2768
|
+
**When:** a stranger signs in with a provider that reports `emailVerified: false` or no e-mail, on a type with `social.signUp`.
|
|
2769
|
+
**Why:** a user is created only for an e-mail the provider vouches for. Nothing was created.
|
|
2770
|
+
**Fix:** answer 403 and ask the visitor to use a provider account with a verified address, or to sign up another way. If your provider package knows the address is verified, make it report `emailVerified: true` — never by default.
|
|
2771
|
+
|
|
2772
|
+
### `janus: the user type "<name>" configures social and store.socialLinks is missing …`
|
|
2773
|
+
|
|
2774
|
+
A `TypeError` at wiring: `<where>: the user type "<name>" configures social and store.socialLinks is missing — createMemoryStores() has it; an adapter's stores need its social links table or collection`.
|
|
2775
|
+
|
|
2776
|
+
**When:** `janus()` with a user type that configures `social`, on stores that lack the `socialLinks` slot.
|
|
2777
|
+
**Why:** the links between users and provider accounts have nowhere to live. Stores written before social sign-in have no such slot.
|
|
2778
|
+
**Fix:** use `createMemoryStores()`, or upgrade the adapter and run its migration (the links table or collection, and the `socialFlow` token kind):
|
|
2779
|
+
|
|
2780
|
+
```ts
|
|
2781
|
+
const store = { ...createMemoryStores(), ...adapterStores, socialLinks: adapterSocialLinks };
|
|
2782
|
+
```
|
|
2783
|
+
|
|
2784
|
+
### `janus: social.signUp needs a type whose login is its e-mail …`
|
|
2785
|
+
|
|
2786
|
+
A `TypeError` at wiring, and a compile error: `<at>: social.signUp needs a type whose login is its e-mail — password.login is "<field>", not "<email field>"`.
|
|
2787
|
+
|
|
2788
|
+
**When:** `social: { signUp }` on a type that signs in with a username, or any login other than its e-mail.
|
|
2789
|
+
**Why:** a provider would claim a login on the strength of an e-mail alone; a taken username would reveal an account.
|
|
2790
|
+
**Fix:** drop `signUp` (strangers get `SIGN_UP_DISABLED`), sign users up another way and link, or make the e-mail the login:
|
|
2791
|
+
|
|
2792
|
+
```ts
|
|
2793
|
+
password: { login: 'email' },
|
|
2794
|
+
```
|
|
2795
|
+
|
|
2796
|
+
---
|
|
2797
|
+
|
|
2798
|
+
## Passkeys
|
|
2799
|
+
|
|
2800
|
+
### `PASSKEY_INVALID` — `passkeys.register: the browser's response did not verify (<reason>) — ask for new options`
|
|
2801
|
+
|
|
2802
|
+
`PasskeyError`, 400, carrying `reason` (`malformed`, `challenge`, `origin`, `rpId`, `userVerification`, `signature`, `counterRegression`, `unsupported`), `userId` and `userType`.
|
|
2803
|
+
|
|
2804
|
+
**When:** `passkeys.register` was given a response the verifier refused.
|
|
2805
|
+
**Why:** the response is not the one the options asked for: a wrong `challenge`, an `origin` or `rpId` that is not the configured one, a user who was not verified when `userVerification` is `'required'`, a bad signature, or JSON that is not a credential. The challenge is spent either way. `reason` is for your logs; do not send it to the page.
|
|
2806
|
+
**Fix:** answer 400, and ask for new options. For `origin` or `rpId`, compare `passkeys.origins` and `rpId` with the address bar the page is served from.
|
|
2807
|
+
|
|
2808
|
+
```ts
|
|
2809
|
+
const { options, challenge } = await auth.passkeys.registrationOptions(user);
|
|
2810
|
+
```
|
|
2811
|
+
|
|
2812
|
+
### `PASSKEY_INVALID` — `<call>: name must be 1 to 100 characters once trimmed`
|
|
2813
|
+
|
|
2814
|
+
`PasskeyError`, 400, carrying `field: 'name'`.
|
|
2815
|
+
|
|
2816
|
+
**When:** `passkeys.register` or `passkeys.rename` with a name that is empty, over 100 characters once trimmed, not a string, or holding a NUL or a lone surrogate.
|
|
2817
|
+
**Why:** the name is what the user sees in their list. `register` checks it before the challenge is spent, so the user can correct it and send the same response again.
|
|
2818
|
+
**Fix:** answer 400 with `field`, and let the user retype the name.
|
|
2819
|
+
|
|
2820
|
+
### `PASSKEY_TAKEN` — `passkeys.register: this credential is already registered`
|
|
2821
|
+
|
|
2822
|
+
`PasskeyError`, 409.
|
|
2823
|
+
|
|
2824
|
+
**When:** the credential the response proved is already stored, for this user or another.
|
|
2825
|
+
**Why:** a credential id is unique across all users, and the first registration keeps it. Nothing was written. The excluded credentials in `registrationOptions` make a browser refuse the same authenticator for the same user, so this is mostly a replay or a cloned response.
|
|
2826
|
+
**Fix:** answer 409; to replace a passkey, `passkeys.remove` it first.
|
|
2827
|
+
|
|
2828
|
+
### `PASSKEY_LIMIT` — `passkeys.register: the user already holds <n> passkeys — remove one first`
|
|
2829
|
+
|
|
2830
|
+
`PasskeyLimitError`, 409, carrying `maxActive` (the cap) and `userId`.
|
|
2831
|
+
|
|
2832
|
+
**When:** `passkeys.register` for a user who already holds `passkeys.maxPerUser` passkeys (10 by default).
|
|
2833
|
+
**Why:** a cap keeps a stolen session from filling the list. It is checked before the challenge is spent, so the same challenge and response work once a passkey is removed.
|
|
2834
|
+
**Fix:** answer 409 and let the user remove one (`passkeys.list`, then `passkeys.remove`), or raise the cap:
|
|
2835
|
+
|
|
2836
|
+
```ts
|
|
2837
|
+
passkeys: { /* … */ maxPerUser: 20 },
|
|
2838
|
+
```
|
|
2839
|
+
|
|
2840
|
+
### `SECOND_FACTOR_NOT_ENROLLED` — `passkeys.registrationOptions: the user has no active TOTP — a passkey is only registered beside one`
|
|
2841
|
+
|
|
2842
|
+
Only with `passkeys.firstFactor` off: with it on, a passkey needs no TOTP.
|
|
2843
|
+
|
|
2844
|
+
`SecondFactorError`, 409, carrying `userId` and `userType`. Also from `passkeys.register` when the TOTP was disabled between the two calls, or while the passkey was being stored: the passkey is deleted then, with no event.
|
|
2845
|
+
|
|
2846
|
+
**When:** a user without an **active** TOTP — none, or one enrolled but never activated — asks to register a passkey.
|
|
2847
|
+
**Why:** a passkey is a second factor beside TOTP, never instead of it.
|
|
2848
|
+
**Fix:** answer 409 and send the user through `secondFactor.enroll` and `activate` first.
|
|
2849
|
+
|
|
2850
|
+
### `CODE_INVALID` — `secondFactor.confirmPasskey` / `stepUp.confirmPasskey` refused an assertion
|
|
2851
|
+
|
|
2852
|
+
`TokenError`, 401, carrying `attemptsLeft`, `userId` and `userType`.
|
|
2853
|
+
|
|
2854
|
+
**When:** the browser's answer did not verify; named a credential that is not the user's or does not exist; was made for another challenge (another `signIn`, or a step-up's); had a counter that did not move forward (both counters non-zero) — which also emits `user.passkeyCloneSuspected`; or the sealing keys were rotated between `signIn` and the assertion.
|
|
2855
|
+
**Why:** every such refusal is one attempt of the challenge's five, shared with the app's codes, and tells the visitor nothing more. The cause is in the verifier's `reason` only if your verifier logs it, and in `user.passkeyCloneSuspected` for a regression.
|
|
2856
|
+
**Fix:** let the user try again (`attemptsLeft`), or sign in again once it reaches `0`. If every assertion fails, check that the page passed `result.passkeyOptions` (or `issued.options`) unchanged to `navigator.credentials.get`, and that `rpId` and `origins` match the page. A regression that is a false alarm (a restored backup) is cleared by removing the passkey and registering it again.
|
|
2857
|
+
|
|
2858
|
+
```ts
|
|
2859
|
+
if (result.status === 'secondFactor' && result.methods.includes('passkey')) {
|
|
2860
|
+
const assertion = await navigator.credentials.get({ publicKey: parse(result.passkeyOptions) });
|
|
2861
|
+
}
|
|
2862
|
+
```
|
|
2863
|
+
|
|
2864
|
+
### `SECOND_FACTOR_NOT_ENROLLED` — `stepUp.request: the user holds no passkey …`
|
|
2865
|
+
|
|
2866
|
+
`SecondFactorError`, 409, carrying `userId` and `userType`. Also `stepUp.confirmPasskey: the user no longer has a second factor — request a step-up again` (the TOTP was disabled between the request and the confirmation: the challenge is spent), and `secondFactor.confirmPasskey: the user no longer has a second factor — sign in again`.
|
|
2867
|
+
|
|
2868
|
+
**When:** `stepUp.request(user, { via: 'passkey' })` for a user with no passkey (or without an active TOTP).
|
|
2869
|
+
**Why:** nothing could answer the challenge, and a code is not silently sent instead.
|
|
2870
|
+
**Fix:** for the "no longer has a second factor" form, request a new step-up (or sign in again) with what the user has now. Otherwise offer `stepUp.request(user)` (the app's code) to a user with no passkey, or send them to register one. Read `result.methods` / `passkeys.list(user)` to decide which to offer.
|
|
2871
|
+
|
|
2872
|
+
### `CREDENTIALS_INVALID` with `reason: 'passkey'`, and the `TypeError` naming `passkeys.firstFactor`
|
|
2873
|
+
|
|
2874
|
+
`CredentialError`, 401, from `passkeys.signIn`. The other is a `TypeError` from `passkeys.signInOptions` or `passkeys.signIn` naming `passkeys.firstFactor`.
|
|
2875
|
+
|
|
2876
|
+
**When:** the assertion was refused: unknown credential (including one made on another store), malformed response, a user handle that does not match, wrong `rpId` or origin, or a counter regression (which also emits `user.passkeyCloneSuspected`). A missing, unknown, spent or lapsed challenge is `TOKEN_UNKNOWN`, `TOKEN_SPENT` or `TOKEN_EXPIRED` instead; an inactive user or unverified e-mail is `USER_INACTIVE` or `EMAIL_UNVERIFIED`, only once the assertion verified. The `TypeError` is a call made with `firstFactor` off.
|
|
2877
|
+
**Why:** one answer for every cause, so the response does not tell an attacker which part failed; the challenge is spent by the first try.
|
|
2878
|
+
**Fix:** answer 401 (for the `TOKEN_*` errors too) and ask for new `signInOptions`. For the `TypeError`, turn it on:
|
|
2879
|
+
|
|
2880
|
+
```ts
|
|
2881
|
+
passkeys: { /* … */ firstFactor: true },
|
|
2882
|
+
```
|
|
2883
|
+
|
|
2884
|
+
### `janus: passkeys needs secondFactor …`, `store.passkeys is missing`, `passkeys.rpId` / `origins` / `verifier` …
|
|
2885
|
+
|
|
2886
|
+
A `TypeError` at wiring, and for the first two a compile error on the `passkeys` key.
|
|
2887
|
+
|
|
2888
|
+
**When:** `passkeys` without `secondFactor` and without `firstFactor: true` (first-factor passkeys seal nothing and need no sealing key); with a store that has no `passkeys` slot (`janus() is given passkeys and store.passkeys is missing`); an `rpId` that is not a lowercase host; no `origins`, or one that is not an `https` origin (or `http://localhost` / `http://<name>.localhost` / `http://127.0.0.1`, any port) on `rpId`; a `relatedOrigins` entry that is not a well-formed `https` origin; a `verifier` missing a method; a `userVerification` outside the three; a `freshWithin` that is not a duration; a `maxPerUser` that is not a positive integer.
|
|
2889
|
+
**Why:** each would make registration fail for every user, or accept a response from the wrong place.
|
|
2890
|
+
**An origin on another domain** (`passkeys.origins: "https://…" is not on rpId "example.com" — a credential is only usable from rpId or one of its subdomains`): `origins` only takes `rpId` and its subdomains. List the other domain in `relatedOrigins` instead, and serve `/.well-known/webauthn` on the `rpId` host ([related origins](guide/passkeys.md#related-origins)). `relatedOrigins` entries must be `https` origins with no path.
|
|
2891
|
+
**Fix:** read the message, which names the key:
|
|
2892
|
+
|
|
2893
|
+
```ts
|
|
2894
|
+
passkeys: {
|
|
2895
|
+
rpId: 'example.com', // no scheme, port or path
|
|
2896
|
+
rpName: 'Clinic',
|
|
2897
|
+
origins: ['https://app.example.com'], // on rpId
|
|
2898
|
+
verifier: simpleWebAuthnVerifier(),
|
|
2899
|
+
},
|
|
2900
|
+
```
|
|
2901
|
+
|
|
2902
|
+
Passkeys alone need no `secondFactor`: pass `firstFactor: true`. In local
|
|
2903
|
+
development, `rpId: 'localhost'` with `origins: ['http://localhost:5173']` is
|
|
2904
|
+
accepted, and so is `http://127.0.0.1` on any port. A multi-tenant dev setup
|
|
2905
|
+
can use `rpId: 'tenant.app.localhost'` with
|
|
2906
|
+
`origins: ['http://tenant.app.localhost:3000']`: every `*.localhost` host is a
|
|
2907
|
+
secure context in browsers, so `http` is accepted there too. Any other `http`
|
|
2908
|
+
host is refused. Browsers refuse an IP address as `rpId`, so prefer
|
|
2909
|
+
`localhost`.
|
|
2910
|
+
|
|
2911
|
+
An adapter's stores need their passkeys table or collection — [writing an adapter](guide/adapters.md).
|
|
2912
|
+
|
|
2913
|
+
---
|
|
2914
|
+
|
|
2915
|
+
## User events
|
|
2916
|
+
|
|
2917
|
+
### `[JANUS_EVENT_FAILED] Warning: janus: the events listener failed on <type> <event id> for user <user id>: <name>`
|
|
2918
|
+
|
|
2919
|
+
A process warning, not a thrown error: the flow that sent the event answered as if nothing happened.
|
|
2920
|
+
|
|
2921
|
+
**When:** the function given to `janus({ events })` threw or rejected — a queue that was down, a bug in the listener.
|
|
2922
|
+
**Why:** the write the event reports has landed. Failing the flow would tell the visitor it did not happen, and their retry would hit `LOGIN_TAKEN`. So the failure is warned about, with the event's type, its id and the user's id, and the failure's name — never its message, which may hold anything.
|
|
2923
|
+
**Fix:** make the listener only store the event (a queue, an outbox table) and fix whatever refused it. To send the lost event again, rebuild it from the warning — its type, its `id`, the user's id; the warning has no `occurredAt`, so take the user's `updatedAt` (or the warning's own time) as an approximation:
|
|
2924
|
+
|
|
2925
|
+
```ts
|
|
2926
|
+
process.on('warning', (warning) => {
|
|
2927
|
+
if ((warning as { code?: string }).code === 'JANUS_EVENT_FAILED') logger.error(warning.message);
|
|
2928
|
+
});
|
|
2929
|
+
```
|
|
2930
|
+
|
|
2931
|
+
### An event you expected never arrived
|
|
2932
|
+
|
|
2933
|
+
**When:** a `user.emailVerified` after a confirm, a `user.deleted` after a delete, a `user.created` from a sign-up.
|
|
2934
|
+
**Why:** one of these, in order of likelihood:
|
|
2935
|
+
- the e-mail was already verified: nothing changed, so nothing is sent;
|
|
2936
|
+
- `delete` deleted nobody — a replay, or an id of another user type;
|
|
2937
|
+
- a `user.newDeviceSignedIn` for a sign-in given no `device`, from a known
|
|
2938
|
+
device, or confirmed without the device given again — see
|
|
2939
|
+
[A new device is never reported](#a-new-device-is-never-reported-newdevice-is-always-false);
|
|
2940
|
+
- the flow was refused, or the store failed during the write itself — the call threw, and nothing was written or sent;
|
|
2941
|
+
- the process stopped between the write and the listener — events are sent at most once, from memory;
|
|
2942
|
+
- the listener threw: look for `JANUS_EVENT_FAILED` in the process's warnings.
|
|
2943
|
+
|
|
2944
|
+
**Fix:** for the last two, reconcile against the users themselves and treat events as the fast path, not the record: page through `auth.list()` and compare with the receiver's copy — a user it lacks is a missed `user.created`, a user the receiver has that `auth.find` answers `null` for is a missed `user.deleted`, a user whose `emailVerified` differs is a missed `user.emailVerified`, and a user whose `hasSecondFactor` differs is a missed `user.secondFactorEnabled` or `user.secondFactorDisabled`.
|
|
2945
|
+
|
|
2946
|
+
A store outage **after** the write does not lose the event. `create` and `signUp` send it before the steps that follow; `delete`, `resetPassword.confirm`, and `signInCode.confirm` and `magicLink.confirm` on an e-mail never verified run theirs — removing the sessions, tokens and tuples; revoking the sessions — in a `try`, and send it from its `finally`, whether they succeeded or not. `signInCode.confirm` and `magicLink.confirm` also revoke the sessions **before** the write: an outage there leaves nothing written and nothing sent, and the next code or link proves the e-mail again.
|
|
2947
|
+
|
|
2948
|
+
---
|
|
2949
|
+
|
|
2950
|
+
## Permissions
|
|
2951
|
+
|
|
2952
|
+
### `PERMISSION_DEPTH` — `can: checking <type>#<permission> crossed more than <n> relations without an answer`
|
|
2953
|
+
|
|
2954
|
+
Also `list: listing <type>#<permission> crossed more than <n> relations without an answer`. `PermissionDepthError`, carrying `permission` and `maxDepth`.
|
|
2955
|
+
|
|
2956
|
+
**When:** `access.can(...)` or `access.list(...)`.
|
|
2957
|
+
**Why:** the walk crossed more than `maxDepth` relations (25 by default) and reached no decision. It is not a denial: a check that stopped half-way decided nothing. A cycle in the data — a team member of itself — is cut silently and never causes this.
|
|
2958
|
+
**Fix:** answer 500 and look at the model or the data: a very deep hierarchy, or a chain of subject sets. If the depth is genuine, raise it:
|
|
2959
|
+
|
|
2960
|
+
```ts
|
|
2961
|
+
const access = permissions({ model, store, maxDepth: 50 });
|
|
2962
|
+
```
|
|
2963
|
+
|
|
2964
|
+
### `permissions: this model was not made by defineModel() — pass what defineModel() answered`
|
|
2965
|
+
|
|
2966
|
+
**When:** `permissions({ model, store })`.
|
|
2967
|
+
**Why:** `model` is the plain configuration object, or a copy of the model (spread, `structuredClone`, JSON round trip).
|
|
2968
|
+
**Fix:**
|
|
2969
|
+
|
|
2970
|
+
```ts
|
|
2971
|
+
import { defineModel, permissions } from '@softistx/janus/permissions';
|
|
2972
|
+
|
|
2973
|
+
const model = defineModel({ subjects: auth.types, types: { ... } });
|
|
2974
|
+
const access = permissions({ model, store });
|
|
2975
|
+
```
|
|
2976
|
+
|
|
2977
|
+
### `permissions: store.<method> is missing`
|
|
2978
|
+
|
|
2979
|
+
Also `permissions: maxDepth must be a positive integer`.
|
|
2980
|
+
|
|
2981
|
+
**When:** `permissions({ model, store })`.
|
|
2982
|
+
**Why:** `store` must be a relation store — `write`, `has`, `findSubjectSets`, `findEntities`, `findObjects`, `deleteEntity` — not the `{ users, sessions, tokens }` given to `janus()`.
|
|
2983
|
+
**Fix:** `permissions({ model, store: createMemoryRelations() })`, or your adapter's relation store.
|
|
2984
|
+
|
|
2985
|
+
### `can: <type>.<relation> reads <field>, which the object does not carry — pass the loaded object, spread`
|
|
2986
|
+
|
|
2987
|
+
Also `can: <type>.<relation> reads <field>, which the object holds as something other than a string id`.
|
|
2988
|
+
|
|
2989
|
+
**When:** `access.can(subject, permission, object)` on a type with a `fromField` relation.
|
|
2990
|
+
**Why:** `fromField('doctorId', 'staff')` reads `doctorId` from the object you pass. Missing, it is an error, never a denial. `null` in the field holds nobody.
|
|
2991
|
+
**Fix:** pass the loaded object, spread:
|
|
2992
|
+
|
|
2993
|
+
```ts
|
|
2994
|
+
await access.can(grace, 'view', { type: 'record', ...record });
|
|
2995
|
+
```
|
|
2996
|
+
|
|
2997
|
+
### `can: <type>.<name> reaches a condition, and no ctx was passed — pass { ctx }`
|
|
2998
|
+
|
|
2999
|
+
Also `list: <type>.<name> reaches a condition, and no ctx was passed — pass { ctx }`.
|
|
3000
|
+
|
|
3001
|
+
**When:** `can` or `list`, when a rule reached by the check is a `when(...)`.
|
|
3002
|
+
**Why:** a condition runs on the `ctx` you pass. A missing `ctx` is a caller's bug, not a denial.
|
|
3003
|
+
**Fix:**
|
|
3004
|
+
|
|
3005
|
+
```ts
|
|
3006
|
+
await access.can(grace, 'edit', { type: 'record', ...record }, { ctx: { onShift: true } });
|
|
3007
|
+
```
|
|
3008
|
+
|
|
3009
|
+
### `list: <type>.<relation> is read from a field, and has no lookup to find the <type>s naming a subject of type '<subject type>' — …`
|
|
3010
|
+
|
|
3011
|
+
**When:** `access.list(subject, permission, type)` through a `fromField` relation.
|
|
3012
|
+
**Why:** `list()` walks backwards from the subject, so it cannot read a field of objects it has not found yet. It asks your `lookup` for the ids of the objects whose field names the subject.
|
|
3013
|
+
**Fix:**
|
|
3014
|
+
|
|
3015
|
+
```ts
|
|
3016
|
+
doctors: fromField('doctorId', 'staff', { lookup: (staffId) => db.records.idsByDoctor(staffId) }),
|
|
3017
|
+
```
|
|
3018
|
+
|
|
3019
|
+
A `lookup` is your code and is not guarded: if it throws, `list()` rejects with that error. Never answer `[]` for a database that could not answer — that is an outage turned into a denial.
|
|
3020
|
+
|
|
3021
|
+
### `list: the lookup of <type>.<relation> must answer an array of ids`
|
|
3022
|
+
|
|
3023
|
+
**When:** `access.list(...)`.
|
|
3024
|
+
**Why:** the `lookup` answered something other than `string[]` — documents, `ObjectId`s, or `undefined`.
|
|
3025
|
+
**Fix:** `lookup: async (id) => (await findRecords({ doctorId: id })).map((r) => r.id)`.
|
|
3026
|
+
|
|
3027
|
+
### `grant: <type>.<relation> is read from <field>; there is nothing to store — change the <type> instead`
|
|
3028
|
+
|
|
3029
|
+
Also with `revoke:` and `replace:`.
|
|
3030
|
+
|
|
3031
|
+
**When:** `access.grant(...)`, `access.revoke(...)` or `access.replace(...)` on a `fromField` relation.
|
|
3032
|
+
**Why:** that relation lives in the object's own data, not in a tuple.
|
|
3033
|
+
**Fix:** update the object — for example set `record.doctorId` — in your own database.
|
|
3034
|
+
|
|
3035
|
+
### `grant: <type>.<relation> is not held by <holder>`
|
|
3036
|
+
|
|
3037
|
+
Also with `revoke:` and `replace:`.
|
|
3038
|
+
|
|
3039
|
+
**When:** `access.grant(object, relation, subject)`, or any subject in the list of `access.replace(object, relation, subjects)`; nothing is written.
|
|
3040
|
+
**Why:** the model's relation does not admit that kind of subject: `members: ['staff']` refuses a `patient`, and refuses the subject set `team#members` unless it is listed.
|
|
3041
|
+
**Fix:** grant a subject the relation admits, or add the holder to the model: `members: ['staff', 'team#members']`.
|
|
3042
|
+
With `revoke:` on a tuple stored before the model stopped admitting it, the tuple already grants nothing; remove it through the store: `relations.write({ remove: [tuple] })`.
|
|
3043
|
+
|
|
3044
|
+
### `replace: the subjects must be an array`
|
|
3045
|
+
|
|
3046
|
+
**When:** `access.replace(object, relation, subject)` with one subject instead of a list.
|
|
3047
|
+
**Why:** `replace` makes the list the only holders of the relation, so it takes the whole list.
|
|
3048
|
+
**Fix:** wrap the subject, `access.replace(team, 'members', [ada])`; `[]` empties the relation. See [`replace`](guide/permissions.md#replace).
|
|
3049
|
+
|
|
3050
|
+
### Two `replace` calls at once leave the union of their adds
|
|
3051
|
+
|
|
3052
|
+
**When:** two `replace` calls on the same object and relation run concurrently.
|
|
3053
|
+
**Why:** each reads the holders, then writes its own difference; they are not serialised, so both lists' additions can remain.
|
|
3054
|
+
**Fix:** serialise them yourself (a lock or a queue) when one list must win. See [`replace`](guide/permissions.md#replace).
|
|
3055
|
+
|
|
3056
|
+
### `replace` leaves extra holders on a capped relation store
|
|
3057
|
+
|
|
3058
|
+
**When:** you wrote a `RelationStore` adapter, and `access.replace(object, relation, subjects)` leaves holders you meant to remove, silently.
|
|
3059
|
+
**Why:** `replace` reads every holder of the relation through `findEntities` and `findSubjectSets` and removes those the list does not name. An adapter that caps either answer (a `LIMIT`, a first page) hides the rest from it, so they are never removed.
|
|
3060
|
+
**Fix:** answer every holder from both methods, unpaged, and never cap. The relation-store conformance suite is the place to check an adapter.
|
|
3061
|
+
|
|
3062
|
+
### `holders` answers a short or empty page that has a `nextCursor`
|
|
3063
|
+
|
|
3064
|
+
**When:** `access.holders(object, relation, { matches })` or `{ matchesMany }` answers fewer than `first` holders, even none, and `nextCursor` is not `null`.
|
|
3065
|
+
**Why:** a call looks at most `scanLimit` holders (500 by default) so a filter that keeps few of them has a bounded cost. When the limit is spent it answers what it kept so far and the cursor to resume from. Only a `null` `nextCursor` ends the list.
|
|
3066
|
+
**Fix:** follow `nextCursor` until it is `null`. Read the page's users in one query with `matchesMany`, and raise `scanLimit` (or pass `Infinity`) only when a long call is acceptable. `holders: matches and matchesMany are exclusive` means both were passed: keep one.
|
|
3067
|
+
|
|
3068
|
+
### Other `can:`, `list:`, `grant:`, `revoke:` and `replace:` messages
|
|
3069
|
+
|
|
3070
|
+
Each is a `TypeError` naming the call. TypeScript refuses most of them on the argument first.
|
|
3071
|
+
|
|
3072
|
+
| Message | Fix |
|
|
3073
|
+
| --- | --- |
|
|
3074
|
+
| `can: "<name>" is not a relation or a permission of <type>` | Ask a name the type declares. |
|
|
3075
|
+
| `<call>: "<type>" is not an object type of the model` | Use a type declared under `types`. Also for a subject set — `setOf` included — whose type is neither a user type nor an object type. |
|
|
3076
|
+
| `<call>: the object must be { type, id, …its fields }` | `{ type: 'record', ...record }`. |
|
|
3077
|
+
| `<call>: the subject must be a user, or { type, id }` | Pass the user from `janus()`, or `{ type, id }`. `null` is anonymous and answers `false`. |
|
|
3078
|
+
| `<call>: the object id must be a non-empty string without @, # or parentheses` | Also for `the subject id`. Those characters belong to the tuple notation. |
|
|
3079
|
+
| `grant: the object id holds a NUL character or a lone surrogate, which no store can keep` | Also with `revoke:` and `replace:`, and for `the subject id`. PostgreSQL refuses `\u0000` and half a surrogate pair, so janus refuses them on every adapter: clean the id where it was read. `can()` answers `false` and `list()` an empty page for such an id instead — no tuple can name it. |
|
|
3080
|
+
| `<call>: "<relation>" is not a relation of <type>, so <type>#<relation> is no subject set` | A subject set names a relation of its type: `{ type: 'team', id, relation: 'members' }`. |
|
|
3081
|
+
| `<call>: <type> is a user type the model does not declare as an object type, so <type>#<relation> is no subject set` | `setOf(user, relation)` names a relation on that user: declare the user type under `types` too, with that relation — see [permissions on a user](guide/permissions.md#permissions-on-a-user). The compiler refuses it first. |
|
|
3082
|
+
| `grant: "<relation>" is not a relation of <type>` | Grant a relation, never a permission. Also with `revoke:` and `replace:` — `replace: "<relation>" is not a relation of <type>`, even for an empty list. |
|
|
3083
|
+
| `list: the type must be an object type of the model` | The third argument is a type name: `'record'`. |
|
|
3084
|
+
| `holders: scanLimit must be a positive integer, or Infinity` | Also `holders: matchesMany must answer one boolean per holder, in order` — answer an array as long as the batch — and `holders: matches and matchesMany are exclusive, pass one`, and `holders: matchesMany must be a function, or absent`. |
|
|
3085
|
+
| `list: after must be the nextCursor of a page, or null` | Pass `nextCursor` back as it came. |
|
|
3086
|
+
|
|
3087
|
+
### `defineModel: …`
|
|
3088
|
+
|
|
3089
|
+
`defineModel` refuses with a `TypeError` what only running it can see. The
|
|
3090
|
+
most common:
|
|
3091
|
+
|
|
3092
|
+
| Message | Fix |
|
|
3093
|
+
| --- | --- |
|
|
3094
|
+
| `defineModel: types.<type>.relations is now related: rename the key` | The key before 0.2. Rename it, nothing else: `related: { members: ['staff'] }`. The compiler refuses it first: `team.relations is now related: rename the key`. |
|
|
3095
|
+
| `defineModel: types.<type>.permissions is now permits: rename the key` | The same for the permissions: `permits: { view: ['members'] }`. The compiler refuses it first: `team.permissions is now permits: rename the key`. |
|
|
3096
|
+
| `defineModel: types.<type>.<key> is not a key of an object type: related or permits` | An object type has two keys, `related` and `permits` — `permit:`, singular, is a typo. |
|
|
3097
|
+
| `defineModel: subjects must be an array of subject type names — auth.types from janus(), or your own` | `defineModel({ subjects: auth.types, types })` with `janus()`, or your own names alone: `subjects: ['user']`. |
|
|
3098
|
+
| `defineModel: types declares no object type` | Declare at least one type under `types`. |
|
|
3099
|
+
| `defineModel: types.<type> must be an object` | Also `types.<type>.related must be an object` and `types.<type>.permits must be an object`: each is keyed by name — `related: { members: ['staff'] }`. |
|
|
3100
|
+
| `defineModel: the object type "<name>" must be a camelCase name — letters and digits, starting with a lowercase letter` | Also `types.<type>.related: "<name>" must be a camelCase name — …` for a relation, and `types.<type>.permits: …` for a permission. |
|
|
3101
|
+
| `defineModel: types.<type>: "<name>" names a relation and a permission; rename one` | One name, one meaning. |
|
|
3102
|
+
| `defineModel: types.<type>.related.<relation> must be a non-empty array of subject types, or fromField()` | `members: ['staff']`, or `doctors: fromField('doctorId', 'staff')`. |
|
|
3103
|
+
| `defineModel: types.<type>.related.<relation>: "<holder>" is not a subject type` | Also `"<holder>" is not a subject set — it must name an object type and one of its relations`: `'team#members'`, a declared type and one of its relations. |
|
|
3104
|
+
| `defineModel: types.<type>.permits.<permission> must be a non-empty array of rules` | `view: ['members']`. |
|
|
3105
|
+
| `defineModel: pass { subjects, types }` | From JavaScript: `defineModel` was given something other than an object. |
|
|
3106
|
+
| `defineModel: the subject type "<name>" must be a camelCase name` | A user type from `janus()` is always one; check a list of your own. |
|
|
3107
|
+
| `defineModel: types.<type>.related.<relation>: fromField names "<name>", which is not a subject type` | `fromField('doctorId', 'staff')`: the second argument is a user type or an object type of the model. |
|
|
3108
|
+
| `defineModel: types.<type>.related.<relation>: fromField must name a top-level field` | `fromField('doctorId', …)`, never `'doctor.id'`: the field is read from the object passed to `can()`. |
|
|
3109
|
+
| `defineModel: types.<type>.related.<relation>: fromField's lookup must be a function` | `{ lookup: (staffId) => db.records.idsByDoctor(staffId) }`. |
|
|
3110
|
+
| `defineModel: types.<type>.related.<relation>: a holder must be a string` | `members: ['staff', 'team#members']`. |
|
|
3111
|
+
| `defineModel: types.<type>.permits.<permission>[<i>]: a rule is a name, an arrow, or when()` | `view: ['doctors', 'teams->view', when('doctors', test)]`. |
|
|
3112
|
+
| `defineModel: types.<type>.permits.<permission>[<i>]: when() takes a function as its test` | `when('doctors', (ctx: { onShift: boolean }) => ctx.onShift)`. |
|
|
3113
|
+
| `defineModel: types.<type>.permits.<permission>[<i>]: "<rule>" is not a relation or a permission of <type>` | Name a relation or a permission the type declares — `'members'`, `'manage'`. |
|
|
3114
|
+
| `defineModel: types.<type>.permits: <a> → <b> → <a> is a loop no relation ends` | A permission must cross a relation before it reaches itself again. |
|
|
3115
|
+
| `defineModel: … "<rule>" goes through "<relation>", which is not a relation of <type>` | An arrow starts from a relation of the same type: `'teams->view'` needs `teams` under `related`. |
|
|
3116
|
+
| `defineModel: … "<rule>" goes through "<relation>", which can hold a subject set; an arrow follows object types only` — also `which can hold a <user type>` | An arrow's relation must hold object types: `teams: ['team']`. A user has no permissions to follow. The compiler refuses it first. |
|
|
3117
|
+
| `defineModel: … "<rule>" names "<target>", which <type> does not declare` | Arrow to a relation or permission of the target type. |
|
|
3118
|
+
| `defineModel: … reads <type>.<field>, and a subject set reaches <type>s nobody passed to can() — store that relation instead of reading it` | Only the object passed to `can()` carries data: a `fromField` there cannot be reached through a subject set or an arrow. Store it as a tuple. |
|
|
3119
|
+
| `defineModel: types.<type>.permits.<permission>: "<relation>-><target>" reaches <type>.<target>, which reads <type>.<field>, and only the object passed to can() carries its data — store that relation instead of reading it` | The same through an arrow: `'teams->leads'` where the team's `leads` is a `fromField`. Store it as a tuple. |
|
|
3120
|
+
|
|
3121
|
+
---
|
|
3122
|
+
|
|
3123
|
+
## Subjects
|
|
3124
|
+
|
|
3125
|
+
### `parseTuple: "<text>" is not a relation tuple; expected type:id#relation@subject`
|
|
3126
|
+
|
|
3127
|
+
Also `parseSubject: "<text>" is not a subject; expected type:id, or type:id#relation for a subject set`.
|
|
3128
|
+
|
|
3129
|
+
**When:** `parseTuple(...)` or `parseSubject(...)`, a `TypeError`.
|
|
3130
|
+
**Why:** subjects are typed. `team:t1#members@grace` — Keto's untyped subject — is refused. No part may hold `@`, `#` or a parenthesis, and a type may not hold `:`.
|
|
3131
|
+
**Fix:**
|
|
3132
|
+
|
|
3133
|
+
```ts
|
|
3134
|
+
import { parseTuple } from '@softistx/janus';
|
|
3135
|
+
|
|
3136
|
+
parseTuple('record:r1#teams@team:t1');
|
|
3137
|
+
parseTuple('team:t1#members@team:t2#members');
|
|
3138
|
+
```
|
|
3139
|
+
|
|
3140
|
+
### `setOf: pass a user or { type, id }, then a relation`
|
|
3141
|
+
|
|
3142
|
+
Also `setOf: the relation must be a non-empty string`.
|
|
3143
|
+
|
|
3144
|
+
**When:** `setOf(...)`, a `TypeError`.
|
|
3145
|
+
**Why:** a set is everyone holding one relation on one user or object: it needs both.
|
|
3146
|
+
**Fix:**
|
|
3147
|
+
|
|
3148
|
+
```ts
|
|
3149
|
+
import { setOf } from '@softistx/janus';
|
|
3150
|
+
|
|
3151
|
+
setOf(bob, 'managers'); // a user from janus()
|
|
3152
|
+
setOf({ type: 'team', id: 't1' }, 'members'); // an object
|
|
3153
|
+
```
|
|
3154
|
+
|
|
3155
|
+
---
|
|
3156
|
+
|
|
3157
|
+
## Conformance (adapter authors)
|
|
3158
|
+
|
|
3159
|
+
### `describeJanusStores: no test runner on globalThis — pass runner: { describe, it } (under bun test: import them from 'bun:test')`
|
|
3160
|
+
|
|
3161
|
+
The same for `describeRelationStores`.
|
|
3162
|
+
|
|
3163
|
+
**When:** loading the spec file.
|
|
3164
|
+
**Why:** `bun test` gives a file `describe` and `it` as bare identifiers, not as properties of `globalThis`. jest, and vitest with `globals: true`, are found without it.
|
|
3165
|
+
**Fix:**
|
|
3166
|
+
|
|
3167
|
+
```ts
|
|
3168
|
+
import { describe, it } from 'bun:test';
|
|
3169
|
+
import { describeJanusStores } from '@softistx/janus/conformance';
|
|
3170
|
+
|
|
3171
|
+
describeJanusStores({ name: 'my adapter', runner: { describe, it }, harness });
|
|
3172
|
+
```
|
|
3173
|
+
|
|
3174
|
+
### `[JANUS_TOKEN_STORE_IGNORES_USER_ID] Warning: tokens.consumeToken answered a token of another user although a userId was given: the store ignores its fourth argument. The call was refused, but the token was spent. Put userId in the consumeToken condition and run describeJanusStores (tokens.consumeBound).`
|
|
3175
|
+
|
|
3176
|
+
A process warning, once per store, and `TOKEN_UNKNOWN` for the call.
|
|
3177
|
+
|
|
3178
|
+
**When:** `verifyEmail.confirm(token, { user })` on a custom `TokenStore` written before `consumeToken` took `userId`.
|
|
3179
|
+
**Why:** the store ignores the fourth argument, so it spent and answered another user's token. The core refuses that answer, but the token is already spent and its owner's link is lost.
|
|
3180
|
+
**Fix:** put `userId` in the `consumeToken` condition, beside the hash and the kind, in the same conditional write (never a read followed by a write), and answer `null` when it does not match.
|
|
3181
|
+
|
|
3182
|
+
```ts
|
|
3183
|
+
// MongoDB: one findOneAndUpdate
|
|
3184
|
+
{ _id: tokenHash, kind, ...(userId === undefined ? {} : { userId }) }
|
|
3185
|
+
```
|
|
3186
|
+
|
|
3187
|
+
### `tokens.consumeBound` fails — `consumeToken bound to another user`, `consumeToken bound to an empty id` or `consumeToken bound to the token's own user`
|
|
3188
|
+
|
|
3189
|
+
**When:** running `describeJanusStores` on a custom store.
|
|
3190
|
+
**Why:** `consumeBound` binds the spend three times. Another user's id must answer `null` (first message). An empty id `''` must answer `null` too, not mean "any user" (second). Then the token's own user must still find it unspent (third: the earlier calls spent it).
|
|
3191
|
+
**Fix:** as above. Compare `userId` whenever it is not `undefined`, `''` included, in the write itself.
|
|
3192
|
+
|
|
3193
|
+
### `JANUS_CONFORMANCE_SKIPPED` — `faults not provided: the outage invariant is not proven for this adapter`
|
|
3194
|
+
|
|
3195
|
+
A process warning, and the outage cases reported as skipped.
|
|
3196
|
+
|
|
3197
|
+
**When:** running the suite with a harness that opens stores without `faults`.
|
|
3198
|
+
**Why:** the outage cases need a way to make the database fail. Their absence is reported, never passed over.
|
|
3199
|
+
**Fix:** return `faults` from `open()`, failing **only the method named**, the way the database really fails — for MongoDB, the `failCommand` failpoint. A wrapper that throws in front of the adapter proves the wrapper, not the adapter.
|
|
3200
|
+
|
|
3201
|
+
### `the error is named <Class> but is not @softistx/janus's <Class>: two copies of @softistx/janus are installed. The adapter must list it as a peer dependency, never a dependency`
|
|
3202
|
+
|
|
3203
|
+
**When:** a conformance case that checks the class of an error — the outage, conflict and not-found cases.
|
|
3204
|
+
**Why:** the adapter imports its own copy of `@softistx/janus`, so its `StoreFailure`, `StoreConflict` or `NotFoundError` is not the core's, and `instanceof` fails.
|
|
3205
|
+
**Fix:** move `@softistx/janus` to `peerDependencies` (and `devDependencies` for the tests), then reinstall.
|
|
3206
|
+
|
|
3207
|
+
### `expected <Class>, got <value>`
|
|
3208
|
+
|
|
3209
|
+
The case's own sentence first — `users.findUser under an outage`, `insertUser should refuse a taken login with StoreConflict`.
|
|
3210
|
+
|
|
3211
|
+
**When:** a conformance case that checks the class of an error, and the adapter threw — or answered — something else.
|
|
3212
|
+
**Why:** the port names the class: an outage is `StoreFailure`, a taken login `StoreConflict`, an update of an unknown id `NotFoundError`. A driver's own error, or an answer where a rejection was due, fails the case.
|
|
3213
|
+
**Fix:** wrap the driver's failure in the core's class, with the driver's error as `cause`:
|
|
3214
|
+
|
|
3215
|
+
```ts
|
|
3216
|
+
try {
|
|
3217
|
+
return await collection.findOne({ _id: id });
|
|
3218
|
+
} catch (cause) {
|
|
3219
|
+
throw new StoreFailure('users.findUser: the store could not answer', {
|
|
3220
|
+
slot: 'users',
|
|
3221
|
+
operation: 'findUser',
|
|
3222
|
+
cause,
|
|
3223
|
+
});
|
|
3224
|
+
}
|
|
3225
|
+
```
|
|
3226
|
+
|
|
3227
|
+
### `expected null, got undefined — an absence is null; undefined is a store that forgot to answer`
|
|
3228
|
+
|
|
3229
|
+
**When:** a conformance case on a `find*` method.
|
|
3230
|
+
**Why:** the adapter answers `undefined` for "not found". Many drivers do; the port does not.
|
|
3231
|
+
**Fix:** `return document ?? null;`.
|
|
3232
|
+
|
|
3233
|
+
### `findUser should answer recoveryCodes [] as [] — never null, never undefined`
|
|
3234
|
+
|
|
3235
|
+
Also `updateUser naming secondFactor should replace the second factor whole, its recovery codes in the order written`, followed by `at .recoveryCodes: expected [...], got undefined`.
|
|
3236
|
+
|
|
3237
|
+
**When:** the case `users.secondFactorSlot`, on an adapter written before `@softistx/janus` 0.10.
|
|
3238
|
+
**Why:** `SecondFactorRecord` holds `recoveryCodes`, the keyed hashes of the user's recovery codes. An adapter that maps the factor field by field drops them, and one that stores "no codes" as a missing value answers `undefined` or `null` — a user who lost their phone could then never sign in with a code.
|
|
3239
|
+
**Fix:** store the array as it is, in order, and read a missing value as `[]`:
|
|
3240
|
+
|
|
3241
|
+
```ts
|
|
3242
|
+
secondFactor:
|
|
3243
|
+
document.secondFactor === null
|
|
3244
|
+
? null
|
|
3245
|
+
: {
|
|
3246
|
+
method: document.secondFactor.method,
|
|
3247
|
+
secret: document.secondFactor.secret,
|
|
3248
|
+
confirmedAt: document.secondFactor.confirmedAt,
|
|
3249
|
+
lastStep: document.secondFactor.lastStep,
|
|
3250
|
+
recoveryCodes: [...(document.secondFactor.recoveryCodes ?? [])],
|
|
3251
|
+
},
|
|
3252
|
+
```
|
|
3253
|
+
|
|
3254
|
+
### `reauthenticateSession racing revokeSession: the session should stay revoked — one conditional write, never a read then a write`
|
|
3255
|
+
|
|
3256
|
+
Also `reauthenticateSession on a revoked session — a confirmation racing a revocation must never bring it back`, followed by `expected null, got {…}`.
|
|
3257
|
+
|
|
3258
|
+
**When:** the cases `sessions.reauthenticateRace` and `sessions.reauthenticate`, on an adapter written before `@softistx/janus` 0.12, or one that implemented `reauthenticateSession` as a read followed by a write.
|
|
3259
|
+
**Why:** a step-up moves `authenticatedAt` with `reauthenticateSession`. An adapter that reads the session, then writes it back whole, writes `revokedAt: null` over a revocation that landed between the two: a signed-out session stands again.
|
|
3260
|
+
**Fix:** one conditional write, whose condition holds `revokedAt` null — the one `extendSession` already has:
|
|
3261
|
+
|
|
3262
|
+
```ts
|
|
3263
|
+
// MongoDB
|
|
3264
|
+
const written = await sessions.findOneAndUpdate(
|
|
3265
|
+
{ _id: id, revokedAt: null },
|
|
3266
|
+
{ $set: { authenticatedAt: at } },
|
|
3267
|
+
{ returnDocument: 'after' },
|
|
3268
|
+
);
|
|
3269
|
+
return written === null ? null : toSession(written);
|
|
3270
|
+
```
|
|
3271
|
+
|
|
3272
|
+
In SQL, `update … set authenticated_at = $2 where id = $1 and revoked_at is null returning *`; in Redis, a Lua script that checks `revokedAt == ''` before its `HSET`. See [`SessionStore.reauthenticateSession`](guide/adapters.md#sessionstorereauthenticatesession).
|
|
3273
|
+
|
|
3274
|
+
### `tokens.insertToken: the store could not answer`, in `tokens.everyKind`
|
|
3275
|
+
|
|
3276
|
+
**When:** the case `tokens.everyKind`, on an adapter whose database lists the token kinds — a `CHECK`, a validator's enum.
|
|
3277
|
+
**Why:** the list does not hold `stepUp`, which came in `@softistx/janus` 0.12, `magicLink`, which came in 0.15, `changeEmail`, which came in 0.23, `socialFlow`, or `passkeyRegistration` (passkeys), so the database refuses the insert, and the adapter reports it as the outage it cannot tell apart.
|
|
3278
|
+
**Fix:** add the missing kind to the list, and ship the migration or the validator with it: `'verifyEmail', 'resetPassword', 'secondFactor', 'signInCode', 'magicLink', 'stepUp', 'changeEmail', 'socialFlow', 'passkeyRegistration'`.
|
|
3279
|
+
|
|
3280
|
+
### `consumeToken for a signInCode token redeemed as magicLink`, in `tokens.magicLinkKind`
|
|
3281
|
+
|
|
3282
|
+
Also `countAttempt for a magicLink token counted as signInCode`, `spendUserTokens of magicLink: the link only`, and `spendUserTokens of magicLink should not touch a sign-in code, nor anything else have counted it`.
|
|
3283
|
+
|
|
3284
|
+
**When:** the case `tokens.magicLinkKind`, on an adapter that matches a token by its hash alone, or spends a user's tokens of every kind at once.
|
|
3285
|
+
**Why:** a sign-in code's challenge is handed to whoever asked for the code. Redeemed as a link, it would sign them in with no code at all — the kind is what keeps the two apart, so every token method must match it.
|
|
3286
|
+
**Fix:** put `kind` in the condition of `consumeToken`, `countAttempt` and `spendUserTokens`, beside the hash or the user:
|
|
3287
|
+
|
|
3288
|
+
```ts
|
|
3289
|
+
// MongoDB: consumeToken — the hash and the kind, never the hash alone
|
|
3290
|
+
await tokens.findOneAndUpdate(
|
|
3291
|
+
{ _id: tokenHash, kind },
|
|
3292
|
+
[{ $set: { spentAt: { $ifNull: ['$spentAt', at] } } }],
|
|
3293
|
+
{ returnDocument: 'before' },
|
|
3294
|
+
);
|
|
3295
|
+
```
|
|
3296
|
+
|
|
3297
|
+
In SQL, `… where token_hash = $1 and kind = $2`; `spendUserTokens` holds `user_id = $1 and kind = $2`. See [`TokenStore`](guide/adapters.md#sessionstore-and-tokenstore).
|
|
3298
|
+
|
|
3299
|
+
### `consumeToken for a verifyEmail token redeemed as changeEmail`, in `tokens.changeEmailKind`
|
|
3300
|
+
|
|
3301
|
+
Also `consumeToken for a changeEmail token redeemed as verifyEmail`, `countAttempt for a changeEmail token counted as verifyEmail`, `spendUserTokens of changeEmail: the change only`, and `spendUserTokens of changeEmail should not touch a verification, nor anything else have counted it`.
|
|
3302
|
+
|
|
3303
|
+
**When:** the case `tokens.changeEmailKind`, on an adapter that matches a token by its hash alone, or spends a user's tokens of every kind at once. The case stores a `changeEmail` and a `verifyEmail` token for one user and one address.
|
|
3304
|
+
**Why:** a verification link proves the address its user already holds; an e-mail change moves the user to the address its token names. Redeemed as one another, a link would verify an address it should have changed, or change one it should only have verified — the kind is what keeps the two apart, so every token method must match it.
|
|
3305
|
+
**Fix:** put `kind` in the condition of `consumeToken`, `countAttempt` and `spendUserTokens`, exactly as for `tokens.magicLinkKind` above. If the case instead fails with `expected …, got …` on the record, the adapter dropped `address` or `codeHash`: a `changeEmail` token keeps the new address in the first and the address it replaces, keyed, in the second.
|