Class: Auth
Defined in: auth/src/auth.ts:335
Constructors
Constructor
> new Auth(options): Auth
Defined in: auth/src/auth.ts:359
Parameters
options
Returns
Auth
Properties
users
> readonly users: UserSource
Defined in: auth/src/auth.ts:336
Methods
activateMfa()
> activateMfa(userId, code): Promise<{ recoveryCodes: string[]; }>
Defined in: auth/src/auth.ts:1007
Confirms enrollment by checking a code against the pending secret, enables MFA, and returns freshly generated single-use recovery codes (shown once).
Parameters
userId
string
code
string
Returns
Promise<{ recoveryCodes: string[]; }>
attempt()
> attempt(email, password): Promise<AuthUser | null>
Defined in: auth/src/auth.ts:606
Verifies credentials without side effects. Null on failure.
Parameters
email
string
password
string
Returns
Promise<AuthUser | null>
createSession()
> createSession(userId, options?): Promise<SessionRecord>
Defined in: auth/src/auth.ts:785
Creates a server-side session. With amr (from login), the returned id — the value to put in the cookie — also carries those authentication methods, HMAC-signed with the auth secret so a client cannot add mfa to a password-only session. Stores are unaffected: they only ever see the random part.
Parameters
userId
string
options?
amr?
readonly string[]
Returns
Promise<SessionRecord>
disableMfa()
> disableMfa(userId, code): Promise<void>
Defined in: auth/src/auth.ts:1025
Turns MFA off. Requires a valid current code (or recovery code).
Parameters
userId
string
code
string
Returns
Promise<void>
enrollMfa()
> enrollMfa(userId): Promise<{ otpauthUri: string; secret: string; }>
Defined in: auth/src/auth.ts:989
Begins MFA enrollment: generates a fresh secret (not yet active) and returns it plus an otpauth:// URI to render as a QR code. Call activateMfa with a code from the app to switch it on.
Parameters
userId
string
Returns
Promise<{ otpauthUri: string; secret: string; }>
expiredSessionCookieHeader()
> expiredSessionCookieHeader(): string
Defined in: auth/src/auth.ts:839
Returns
string
isMfaEnabled()
> isMfaEnabled(userId): Promise<boolean>
Defined in: auth/src/auth.ts:943
Parameters
userId
string
Returns
Promise<boolean>
login()
> login(email, password, mfaCode?, context?): Promise<{ amr: string[]; tokens: TokenPair; user: PublicUser; }>
Defined in: auth/src/auth.ts:641
Credentials → token pair. Emits auth:login / auth:login_failed. Locks the account after too many failures (see LoginThrottle); a success clears the counter.
When the account has MFA enabled, mfaCode (a TOTP or recovery code) is required: a correct password with a missing code throws MfaRequiredError, and a wrong code throws MfaInvalidCodeError. Because MfaRequiredError reveals that the password was right, it counts against the per-account and per-IP login budgets exactly like a failure (a later successful login with the code clears the account counter).
amr lists the authentication methods used — ['pwd'], or ['pwd', 'mfa'] when a second factor was verified. It is also embedded in the access token (amr claim) and carried by every refresh of this login; pass it to createSession so a cookie session carries it too.
Parameters
email
string
password
string
mfaCode?
string
context?
ip?
string
Returns
Promise<{ amr: string[]; tokens: TokenPair; user: PublicUser; }>
logout()
> logout(sessionId): Promise<void>
Defined in: auth/src/auth.ts:860
Parameters
sessionId
string
Returns
Promise<void>
mfaStatus()
> mfaStatus(userId): Promise<{ enabled: boolean; pending: boolean; }>
Defined in: auth/src/auth.ts:947
Parameters
userId
string
Returns
Promise<{ enabled: boolean; pending: boolean; }>
reencryptMfaSecret()
> reencryptMfaSecret(userId): Promise<"none" | "resealed" | "current">
Defined in: auth/src/auth.ts:974
Re-encrypts one user's stored TOTP secret under the active key of mfaEncryption — for key rotation, and to migrate v1: envelopes or plaintext secrets (reading those needs the matching legacy opt-in). Returns 'resealed' when the row was rewritten, 'current' when it was already sealed with the active key, 'none' when the user has no MFA record. Run it over every user id with an MFA row, then drop legacy.
Parameters
userId
string
Returns
Promise<"none" | "resealed" | "current">
refresh()
> refresh(refreshToken): Promise<TokenPair>
Defined in: auth/src/auth.ts:703
Refresh rotation with reuse detection: every refresh consumes the token and issues a new one in the same family. If a consumed token comes back (theft indicator), the whole family is revoked.
Parameters
refreshToken
string
Returns
Promise<TokenPair>
register()
> register(rawEmail, password): Promise<PublicUser>
Defined in: auth/src/auth.ts:416
Parameters
rawEmail
string
password
string
Returns
Promise<PublicUser>
registerSafely()
> registerSafely(rawEmail, password): Promise<void>
Defined in: auth/src/auth.ts:587
Enumeration-safe registration for the public endpoint: creates the account for a new email, or — when the email is already taken — does equivalent work (so timing doesn't leak) and emits auth:register_existing_email so the app can send an out-of-band "you already have an account" email. Returns nothing either way, so the response can't reveal whether the account existed.
With enumerationSafeRegister: false it throws EmailTakenError on a duplicate instead (the classic, enumerable behavior).
Parameters
rawEmail
string
password
string
Returns
Promise<void>
requestEmailVerification()
> requestEmailVerification(email): Promise<{ token: string; user: PublicUser; } | null>
Defined in: auth/src/auth.ts:878
Starts email verification: mints a single-use token and emits auth:verify_requested for the app to email. Returns the token (so a caller can build the link) or null if no account matches — never reveals whether the email exists.
Parameters
email
string
Returns
Promise<{ token: string; user: PublicUser; } | null>
requestPasswordReset()
> requestPasswordReset(email): Promise<{ token: string; user: PublicUser; } | null>
Defined in: auth/src/auth.ts:913
Starts a password reset: mints a single-use token and emits auth:password_reset_requested. Returns null when no account matches (or the per-account request budget is spent — the live link then stays valid), so the caller always responds 200 (no account enumeration).
Parameters
email
string
Returns
Promise<{ token: string; user: PublicUser; } | null>
resetPassword()
> resetPassword(token, newPassword): Promise<PublicUser>
Defined in: auth/src/auth.ts:925
Consumes a reset token, sets the new password, and revokes every existing session/refresh token for the user (a reset logs everyone else out).
Parameters
token
string
newPassword
string
Returns
Promise<PublicUser>
revoke()
> revoke(refreshToken): Promise<void>
Defined in: auth/src/auth.ts:740
Revokes a refresh family — logout for token-based clients.
Parameters
refreshToken
string
Returns
Promise<void>
revokeAllTokens()
> revokeAllTokens(userId): Promise<void>
Defined in: auth/src/auth.ts:772
Revokes every access token issued so far for the user (logout-everywhere), revoking every refresh token and server-side session (when the stores implement revokeAllForUser / deleteAllForUser, as the bundled ones do) and bumping the token version so outstanding access tokens die too (needs a TokenVersionStore; without one, access tokens live until their TTL).
Parameters
userId
string
Returns
Promise<void>
sessionAuth()
> sessionAuth(sessionId): Promise<{ amr?: string[]; user: AuthUser; } | null>
Defined in: auth/src/auth.ts:852
The user of a session plus the authentication methods it was created with (amr is absent for sessions created without them, e.g. before this option).
Parameters
sessionId
string
Returns
Promise<{ amr?: string[]; user: AuthUser; } | null>
sessionCookieHeader()
> sessionCookieHeader(sessionId): string
Defined in: auth/src/auth.ts:813
Parameters
sessionId
string
Returns
string
sessionIdFromCookie()
> sessionIdFromCookie(cookieHeader?): string | null
Defined in: auth/src/auth.ts:820
Parameters
cookieHeader?
string
Returns
string | null
sessionUser()
> sessionUser(sessionId): Promise<AuthUser | null>
Defined in: auth/src/auth.ts:844
Parameters
sessionId
string
Returns
Promise<AuthUser | null>
socialLogin()
> socialLogin(rawEmail, options?): Promise<{ amr: string[]; created: boolean; tokens: TokenPair; user: PublicUser; }>
Defined in: auth/src/auth.ts:452
Logs in an externally-authenticated user (e.g. from an OAuth provider) — find-or-create. A new account is created passwordless (a random, unusable password hash), so password login won't work for it until a password is set. A provider-verified email flips emailVerified. Returns the tokens and whether the account was just created.
With an identity (the provider name and its stable subject, which OAuth always passes) the account is matched by that link first (see AccountLinkStore): a linked provider account reaches its local account whatever email it asserts today. Without a link, the account is matched by email and the link is recorded — for an existing account only under the rules below. Once an account is linked to a provider, a different subject of that provider asserting the same email is refused (AccountLinkConflictError) unless subjectConflict: 'link'.
Linking to an EXISTING account is refused (SocialLinkRefusedError) unless emailVerified is true — an unverified provider email proves nothing about who owns the address. When the existing account had never verified its email, whoever registered it first is not trusted either: its password, sessions, refresh tokens, MFA and account links are revoked before it is adopted (auth:social_account_adopted). An account with MFA enabled requires mfaCode (MfaRequiredError) unless mfa: 'skip' is passed explicitly (only for an IdP that enforces its own second factor).
Parameters
rawEmail
string
options?
emailVerified?
boolean
identity?
{ provider: string; subject: string; }
The provider account behind this login; matched before the email.
identity.provider
string
identity.subject
string
mfa?
"required" | "skip"
mfaCode?
string
subjectConflict?
"refuse" | "link"
An account already linked to another subject of the same provider: 'refuse' (default) or 'link' this subject as well. Only for an IdP that legitimately re-issues subjects (a directory migration).
Returns
Promise<{ amr: string[]; created: boolean; tokens: TokenPair; user: PublicUser; }>
verifyAccess()
> verifyAccess(accessToken): JwtClaims
Defined in: auth/src/auth.ts:746
Structural JWT verification only (signature + expiry).
Parameters
accessToken
string
Returns
verifyAccessToken()
> verifyAccessToken(accessToken): Promise<JwtClaims>
Defined in: auth/src/auth.ts:756
Verifies the access token AND, when token-version revocation is enabled, rejects a token minted before the user's version was last bumped (i.e. revoked by a password reset / revokeAllTokens). Prefer this over verifyAccess on the request path.
Parameters
accessToken
string
Returns
Promise<JwtClaims>
verifyEmail()
> verifyEmail(token): Promise<PublicUser>
Defined in: auth/src/auth.ts:887
Consumes a verification token and marks the user's email verified.
Parameters
token
string
Returns
Promise<PublicUser>
verifyMfaCode()
> verifyMfaCode(userId, code): Promise<boolean>
Defined in: auth/src/auth.ts:1037
Verifies a TOTP code or, failing that, a single-use recovery code (which is consumed on success). Returns false unless MFA is enabled.
Parameters
userId
string
code
string
Returns
Promise<boolean>