basalt / auth/src / AuthPluginOptions
Interface: AuthPluginOptions
Defined in: auth/src/plugin.ts:81
Extends
Omit<AuthOptions,"hooks">
Properties
accessTtl?
> optional accessTtl?: DurationInput
Defined in: auth/src/auth.ts:245
Inherited from
accountLinks?
> optional accountLinks?: AccountLinkStore
Defined in: auth/src/auth.ts:298
Store binding provider subjects to accounts (Auth.socialLogin). Default: in-memory — use a durable one (@basaltkit/auth-prisma, @basaltkit/auth-sqlite) with OAuth, or links are forgotten on restart and logins fall back to the email match.
Inherited from
csrf?
> optional csrf?: false | CsrfOptions
Defined in: auth/src/plugin.ts:91
CSRF defence for the session cookie (on by default). A request whose ONLY credential is the ambient session cookie and whose method is not GET/HEAD/OPTIONS is not authenticated when the browser says it is cross-site or same-site (Sec-Fetch-Site), or when its Origin is neither the request's own host nor a trusted origin; a route requiring auth then answers 403 AUTH_CSRF_REJECTED. Bearer tokens, x-session-id and API keys are not ambient and are not affected. false disables the check.
emailRequestThrottle?
> optional emailRequestThrottle?: false | LoginThrottle
Defined in: auth/src/auth.ts:266
Per-account throttle on password-reset and email-verification requests. Over budget, a request is silently dropped (no new token, no hook, the live link keeps working) — so the endpoints cannot be used to mail-bomb a user or keep invalidating their reset link. Default: 3 per 15 minutes per account and purpose; pass false to disable.
Inherited from
AuthOptions.emailRequestThrottle
enumerationSafeRegister?
> optional enumerationSafeRegister?: boolean
Defined in: auth/src/auth.ts:283
Make the public registration endpoint enumeration-safe: a request for an email that already exists returns the same response (and does equivalent work) as a fresh signup, instead of a 409 that reveals the account exists. Applies to Auth.registerSafely (used by the register route); the lower-level Auth.register always throws on a duplicate. Default true.
Inherited from
AuthOptions.enumerationSafeRegister
hasher?
> optional hasher?: PasswordHasher
Defined in: auth/src/auth.ts:242
Inherited from
ipLoginThrottle?
> optional ipLoginThrottle?: false | LoginThrottle
Defined in: auth/src/auth.ts:258
Per-IP login throttle — blunts password spraying (1 attempt across many accounts) and lockout-DoS that a per-email counter alone misses. Enabled by default with a higher budget than the per-email one; pass false to disable. Only applies when the caller passes the client ip to login.
Inherited from
loginThrottle?
> optional loginThrottle?: false | LoginThrottle
Defined in: auth/src/auth.ts:251
Brute-force lockout (per email). Enabled by default; pass false to disable.
Inherited from
mfa?
> optional mfa?: MfaStore
Defined in: auth/src/auth.ts:291
Store for MFA (TOTP) enrollment state. Default: in-memory.
Inherited from
mfaEncryption?
> optional mfaEncryption?: object
Defined in: auth/src/auth.ts:317
Encrypts TOTP secrets at rest (AES-256-GCM, HKDF-derived keys, each ciphertext bound to its user). keys is a ring: the first key seals new secrets, the others stay readable (rotation). A stored value that is not an envelope sealed for that user is refused — a database write cannot swap in a plaintext secret the writer knows. legacy reads v1: envelopes and/or plaintext during a migration only; move rows over with Auth.reencryptMfaSecret, then remove it.
Omit (and omit mfaEncryptionKey) to store secrets in plaintext.
keys
> keys: SecretBoxKey[]
legacy?
> optional legacy?: SecretBoxLegacyOptions
Inherited from
mfaEncryptionKey?
> optional mfaEncryptionKey?: string | Buffer<ArrayBufferLike>
Defined in: auth/src/auth.ts:324
Shorthand for mfaEncryption: { keys: [{ id: 'default', key }] } (at least 32 bytes). It does not read the old v1: envelopes or plaintext: to migrate from a pre-4.0 mfaEncryptionKey, use mfaEncryption with legacy: { v1Keys: [oldKey] }.
Inherited from
mfaIssuer?
> optional mfaIssuer?: string
Defined in: auth/src/auth.ts:326
Issuer name shown in authenticator apps. Default 'Basalt'.
Inherited from
refreshTokens?
> optional refreshTokens?: RefreshTokenStore
Defined in: auth/src/auth.ts:244
Inherited from
refreshTtl?
> optional refreshTtl?: DurationInput
Defined in: auth/src/auth.ts:246
Inherited from
requireMfa?
> optional requireMfa?: boolean | ((user, context) => boolean | Promise<boolean>)
Defined in: auth/src/plugin.ts:107
Require multi-factor authentication. true for every user, or a policy (user, context) => boolean | Promise<boolean> (e.g. only admins, only some tenants). An authenticated request whose credential was not obtained with a second factor (ctx().amr lacks mfa) is refused with 403 AUTH_MFA_ENROLLMENT_REQUIRED (the account has no MFA yet — enrol, then sign in again) or AUTH_MFA_REQUIRED (sign in again with a code).
Routes declaring meta.mfa: false are exempt — every authRoutes() route and the enrol / activate / status routes of mfaRoutes(), so a user can still sign in, read /auth/me, enrol and log out. API-key requests are not subject to the policy (a key is a machine credential; minting one needs an MFA session under the policy). Independently of the policy, meta.mfa: true requires MFA on a single route (step-up). Default: off.
resetTtl?
> optional resetTtl?: DurationInput
Defined in: auth/src/auth.ts:289
Password-reset link lifetime. Default 1h.
Inherited from
secret
> secret: string
Defined in: auth/src/auth.ts:241
Inherited from
sessionCookie?
> optional sessionCookie?: SessionCookieOptions
Defined in: auth/src/auth.ts:248
Inherited from
sessions?
> optional sessions?: SessionStore
Defined in: auth/src/auth.ts:243
Inherited from
sessionTtl?
> optional sessionTtl?: DurationInput
Defined in: auth/src/auth.ts:247
Inherited from
throttleStore?
> optional throttleStore?: ThrottleStore
Defined in: auth/src/auth.ts:275
Where the DEFAULT throttles above (login, per-ip login, email requests) keep their counters. Default: in memory, per process — each replica then grants its own budget. Pass a shared store (e.g. RedisThrottleStore) so a cluster enforces one budget; each throttle uses its own namespace (login, login-ip, email-request). Ignored for a throttle passed explicitly (give that one its own store).
Inherited from
tokens?
> optional tokens?: AuthTokenStore
Defined in: auth/src/auth.ts:285
Store for verification/reset tokens. Default: in-memory.
Inherited from
tokenVersions?
> optional tokenVersions?: TokenVersionStore
Defined in: auth/src/auth.ts:305
Enables access-token revocation. When set, access tokens carry a version (tv) and resetPassword/revokeAllTokens bump it — invalidating every token issued before the bump, even before its TTL expires. Opt-in; access verification then costs one store read per request. Default: off.
Inherited from
users
> users: UserSource
Defined in: auth/src/auth.ts:240
Inherited from
verificationTtl?
> optional verificationTtl?: DurationInput
Defined in: auth/src/auth.ts:287
Email-verification link lifetime. Default 24h.