@nestjs/authentication 0.0.1

package/dist/interfaces/authentication-registry.interface.d.ts

@@ -0,0 +1,41 @@
+import type { EmailVerificationHandler } from '../account/email-verification.handler.js';
+import type { PasswordResetHandler } from '../account/password-reset.handler.js';
+import type { MagicLinkHandler } from '../magic-link/magic-link.handler.js';
+import type { OidcAccountResolver } from '../oidc/oidc-account.resolver.js';
+import type { AuthenticationProvider } from '../providers/authentication.provider.js';
+/**
+ * The feature handlers, by the name of the module option each one goes
+ * with: what `registerHandler()` takes. A feature needs both, its option and
+ * its handler, or the module refuses to start.
+ */
+export interface AuthenticationHandlers {
+    /** Delivers verification links and records verified addresses. */
+    emailVerification: EmailVerificationHandler;
+    /** Finds accounts, delivers reset links and stores new passwords. */
+    passwordReset: PasswordResetHandler;
+    /** Delivers magic links and maps an address to a user. */
+    magicLink: MagicLinkHandler;
+    /** Maps an OpenID Connect identity to a user. */
+    oidc: OidcAccountResolver;
+}
+export type AuthenticationHandlerName = keyof AuthenticationHandlers;
+/** `registerProvider()` options. */
+export interface RegisterProviderOptions {
+    /**
+     * Where the provider runs in the chain: ascending, the first provider that
+     * returns a user wins. Default `0`. Two providers can't share an order.
+     */
+    order?: number;
+    /** Replace the provider registered at the same `order` (tests, a wrapper around it). */
+    replace?: boolean;
+}
+/** `registerHandler()` options. */
+export interface RegisterHandlerOptions {
+    /** Replace the handler already registered for the feature (tests, a wrapper around it). */
+    replace?: boolean;
+}
+/**
+ * What the guard calls: an `AuthenticationProvider` subclass, or any object
+ * with its `authenticate()` (and optional `challenge()`).
+ */
+export type CredentialProvider<TUser = any, TSession = any> = Pick<AuthenticationProvider<TUser, TSession>, 'authenticate' | 'challenge'>;

package/dist/interfaces/authentication-registry.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/authentication-result.interface.d.ts

@@ -0,0 +1,25 @@
+import type { AuthenticationTypes } from '../index.js';
+/**
+ * The user type the app declared by augmenting {@link AuthenticationTypes}.
+ * Falls back to a string-keyed record when nothing was declared.
+ */
+export type AuthenticatedUser = AuthenticationTypes extends {
+    user: infer U;
+} ? U : Record<string, unknown>;
+/** The session type declared on {@link AuthenticationTypes}, `unknown` otherwise. */
+export type AuthenticatedSession = AuthenticationTypes extends {
+    session: infer S;
+} ? S : unknown;
+/**
+ * `pending`: first factor done, second factor outstanding. Such a result
+ * does not count as signed in: `SignInService.completeMfa()` finishes it.
+ * `verified`: a second factor was presented. Required by
+ * `@Authenticate({ mfa: true })`.
+ */
+export type MfaState = 'pending' | 'verified';
+export interface AuthenticationResult<TUser = AuthenticatedUser, TSession = AuthenticatedSession> {
+    user: TUser;
+    /** Whatever the provider considers the session: a stored record, JWT claims, an `ApiKeySession`. */
+    session?: TSession;
+    mfa?: MfaState;
+}

package/dist/interfaces/authentication-result.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/authentication-storage.interface.d.ts

@@ -0,0 +1,29 @@
+import type { EmailTokenStore } from './email-token-store.interface.js';
+import type { RefreshTokenStore } from './refresh-token-store.interface.js';
+import type { MagicLinkStore } from './magic-link-store.interface.js';
+import type { MfaStore } from './mfa-store.interface.js';
+import type { OidcStateStore } from './oidc-state-store.interface.js';
+import type { SessionStore } from './session-store.interface.js';
+/**
+ * The storage contracts, by name: what `registerSource()` takes. One
+ * provider may implement several (`{ sessions: this, refreshTokens: this }`),
+ * or several providers split them (sessions in Redis, the rest in SQL).
+ */
+export interface AuthenticationStorageSources {
+    sessions?: SessionStore;
+    refreshTokens?: RefreshTokenStore;
+    /** Authenticators, recovery codes and failed attempts. */
+    mfa?: MfaStore;
+    /** Pending magic links. */
+    magicLinks?: MagicLinkStore;
+    /** OAuth / OpenID Connect logins in progress. */
+    oidcStates?: OidcStateStore;
+    /** Pending password reset and email verification links. */
+    emailTokens?: EmailTokenStore;
+}
+export type AuthenticationStorageContract = keyof AuthenticationStorageSources;
+/** `registerSource()` options. */
+export interface AuthenticationStorageRegisterOptions {
+    /** Replace the source of a contract that is already registered (tests, a wrapper around it). */
+    replace?: boolean;
+}

package/dist/interfaces/authentication-storage.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/duration.interface.d.ts

@@ -0,0 +1,2 @@
+/** Milliseconds, or a string such as `"250ms"`, `"30s"`, `"15m"`, `"6h"`, `"3d"`, `"1w"`. */
+export type Duration = number | `${number}${'ms' | 's' | 'm' | 'h' | 'd' | 'w'}`;

package/dist/interfaces/duration.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/email-token-store.interface.d.ts

@@ -0,0 +1,52 @@
+/** What a mailed token proves when it comes back. */
+export type EmailTokenPurpose = 'password-reset' | 'email-verification';
+/**
+ * A token sent by email to prove control of an address: a password reset
+ * link, or an email verification link. Stored by the SHA-256 of the token;
+ * the token itself only exists in the email.
+ */
+export interface EmailTokenRecord {
+    /** SHA-256 of the token. */
+    id: string;
+    purpose: EmailTokenPurpose;
+    userId: string;
+    /** The address the token was sent to, and the only one it works for. */
+    email: string;
+    /**
+     * Password resets: SHA-256 of the user's password hash when the link was
+     * sent, so a password change (by any route) invalidates the link.
+     */
+    fingerprint?: string;
+    createdAt: Date;
+    expiresAt: Date;
+}
+/**
+ * Storage for password reset and email verification tokens. Implement it
+ * on your database or Redis, and register the provider with
+ * `AuthenticationStorage.registerSource({ emailTokens: this })`.
+ *
+ * `consumeEmailToken()` must be one atomic get-and-delete
+ * (`DELETE … RETURNING`, `GETDEL`), so a link works once however many
+ * requests present it. Anyone can ask for a reset link, so the store must
+ * stay bounded: drop expired tokens as new ones are saved, and cap the
+ * rest. Each method's comment has its rule, and
+ * `authenticationStoreContract()` from `@nestjs/authentication/testing`
+ * checks them.
+ */
+export interface EmailTokenStore {
+    /**
+     * Saves a new token (a fresh random id: a plain insert), then keeps the
+     * store bounded: deletes tokens whose `expiresAt` is at or before this
+     * one's `createdAt`, and past a cap, those that expire first.
+     */
+    saveEmailToken(record: EmailTokenRecord): Promise<void>;
+    /**
+     * Removes and returns the token if it exists and was issued for
+     * `purpose`, in one atomic step; `undefined` otherwise, leaving a token of
+     * another purpose in place. Of several concurrent calls, exactly one gets
+     * the record. Expired tokens may be returned: the services check expiry.
+     */
+    consumeEmailToken(id: string, purpose: EmailTokenPurpose): Promise<EmailTokenRecord | undefined>;
+    /** Deletes the user's outstanding tokens for `purpose` (after a reset, the other reset links). */
+    deleteUserEmailTokens(userId: string, purpose: EmailTokenPurpose): Promise<void>;
+}

package/dist/interfaces/email-token-store.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/email-verification.interface.d.ts

@@ -0,0 +1,18 @@
+import type { Duration } from './duration.interface.js';
+/** What `EmailVerificationHandler.send()` delivers. */
+export interface EmailVerificationLink {
+    userId: string;
+    /** The address to verify, and to send the link to. */
+    email: string;
+    /** `emailVerification.url` with `?token=…`. */
+    url: string;
+    expiresAt: Date;
+}
+export interface EmailVerificationOptions {
+    /** Page that receives `?token=…` and POSTs it back, e.g. `https://app.example.com/verify-email`. */
+    url: string;
+    /** Lifetime of a link. Default `'24h'`. */
+    ttl?: Duration;
+    /** Clock in epoch milliseconds, for tests. */
+    now?: () => number;
+}

package/dist/interfaces/email-verification.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/index.d.ts

@@ -0,0 +1,27 @@
+export * from './api-key.interface.js';
+export * from './authenticate-options.interface.js';
+export * from './authentication-error-options.interface.js';
+export * from './authentication-module-options.interface.js';
+export * from './authentication-registry.interface.js';
+export * from './authentication-result.interface.js';
+export * from './authentication-storage.interface.js';
+export * from './duration.interface.js';
+export * from './email-token-store.interface.js';
+export * from './email-verification.interface.js';
+export * from './jwt-options.interface.js';
+export * from './jwt.interface.js';
+export * from './magic-link-store.interface.js';
+export * from './magic-link.interface.js';
+export * from './mfa-options.interface.js';
+export * from './mfa-store.interface.js';
+export * from './oidc-provider.interface.js';
+export * from './oidc-state-store.interface.js';
+export * from './oidc.interface.js';
+export * from './password-hasher-options.interface.js';
+export * from './password-reset.interface.js';
+export * from './refresh-token-options.interface.js';
+export * from './refresh-token-store.interface.js';
+export * from './session-store.interface.js';
+export * from './session.interface.js';
+export * from './sign-in-options.interface.js';
+export * from './token.interface.js';

package/dist/interfaces/index.js

@@ -0,0 +1,27 @@
+export * from './api-key.interface.js';
+export * from './authenticate-options.interface.js';
+export * from './authentication-error-options.interface.js';
+export * from './authentication-module-options.interface.js';
+export * from './authentication-registry.interface.js';
+export * from './authentication-result.interface.js';
+export * from './authentication-storage.interface.js';
+export * from './duration.interface.js';
+export * from './email-token-store.interface.js';
+export * from './email-verification.interface.js';
+export * from './jwt-options.interface.js';
+export * from './jwt.interface.js';
+export * from './magic-link-store.interface.js';
+export * from './magic-link.interface.js';
+export * from './mfa-options.interface.js';
+export * from './mfa-store.interface.js';
+export * from './oidc-provider.interface.js';
+export * from './oidc-state-store.interface.js';
+export * from './oidc.interface.js';
+export * from './password-hasher-options.interface.js';
+export * from './password-reset.interface.js';
+export * from './refresh-token-options.interface.js';
+export * from './refresh-token-store.interface.js';
+export * from './session-store.interface.js';
+export * from './session.interface.js';
+export * from './sign-in-options.interface.js';
+export * from './token.interface.js';

package/dist/interfaces/jwt-options.interface.d.ts

@@ -0,0 +1,68 @@
+import type { KeyObject } from 'node:crypto';
+import type { JwksClient } from '../jwt/jwks.client.js';
+import type { Duration } from './duration.interface.js';
+import type { ClaimRules, JwsAlgorithm } from './jwt.interface.js';
+export interface JwksClientOptions {
+    /** How long a fetched key set is trusted. Default `'10m'`. */
+    cacheTtl?: Duration;
+    /**
+     * Minimum gap between refetches triggered by an unknown `kid`. Default
+     * `'30s'`. Stops a flood of tokens with random `kid`s from turning into a
+     * flood of requests to the IdP.
+     */
+    cooldown?: Duration;
+    /** Request timeout. Default `'5s'`. */
+    timeout?: Duration;
+    fetch?: typeof fetch;
+    /** Clock in epoch milliseconds, for tests. */
+    now?: () => number;
+}
+export interface JwtVerifierOptions extends ClaimRules {
+    /**
+     * A static key: an HS256 secret (at least 32 bytes), or a public or
+     * private key as a `KeyObject` or PEM text (a string or a `Buffer`). A
+     * public key needs `issuer` and `audience`, as a `jwks` does: it is an
+     * identity provider's, which signs the tokens of all its clients with it.
+     * A JWK, or DER, is refused (read as bytes, it would be an HS256 secret):
+     * pass `createPublicKey({ key: jwk, format: 'jwk' })`.
+     */
+    key?: KeyObject | string | Buffer;
+    /**
+     * A JWKS URL, or a shared {@link JwksClient}. Needs `issuer` and
+     * `audience`: an identity provider's keys sign the tokens of every one of
+     * its clients.
+     */
+    jwks?: string | JwksClient;
+    /**
+     * Accepted `alg` values. Defaults: `['HS256']` for a secret, the key's own
+     * algorithm for an asymmetric key, `['RS256', 'ES256']` for a JWKS.
+     * `none` is never accepted.
+     */
+    algorithms?: JwsAlgorithm[];
+    /** Required `typ` header, e.g. `at+jwt` (RFC 9068). Not checked by default. */
+    type?: string;
+}
+export interface JwtSignerOptions {
+    /**
+     * An HS256 secret (at least 32 bytes), or a private key for RS256, ES256
+     * or EdDSA: a `KeyObject`, or PEM text (a string or a `Buffer`). A JWK, or
+     * DER, is refused: pass `createPrivateKey({ key: jwk, format: 'jwk' })`.
+     */
+    key: KeyObject | string | Buffer;
+    /** Default: HS256 for a secret, the key's own algorithm for a private key. */
+    alg?: JwsAlgorithm;
+    /** Published in the header so verifiers can pick the key from a JWKS. */
+    kid?: string;
+    issuer?: string;
+    audience?: string | string[];
+    /** Lifetime of a token. Default `'15m'`: access tokens should be short-lived. */
+    ttl?: Duration;
+    /** `typ` header. Default `JWT`; RFC 9068 access tokens use `at+jwt`. */
+    type?: string;
+    /** Clock in epoch milliseconds, for tests. */
+    now?: () => number;
+}
+export interface JwtBearerProviderOptions extends JwtVerifierOptions {
+    /** `realm` in the `WWW-Authenticate` challenge. Default `api`. */
+    realm?: string;
+}

package/dist/interfaces/jwt-options.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/jwt.interface.d.ts

@@ -0,0 +1,36 @@
+import type { Duration } from './duration.interface.js';
+/**
+ * Supported JWS algorithms. EdDSA means Ed25519 only: Ed448 is rejected
+ * (untested here, and rare in practice).
+ */
+export type JwsAlgorithm = 'HS256' | 'RS256' | 'ES256' | 'EdDSA';
+export interface JwtClaims {
+    iss?: string;
+    sub?: string;
+    aud?: string | string[];
+    exp?: number;
+    nbf?: number;
+    iat?: number;
+    jti?: string;
+    [claim: string]: unknown;
+}
+export interface ClaimRules {
+    issuer?: string;
+    /**
+     * Accepted `aud` values. `false` accepts any audience, for tokens that
+     * carry none (check the claim that names your client in `validate()`).
+     */
+    audience?: string | string[] | false;
+    /**
+     * Leeway for `exp`, `nbf` and `iat`. Default `0`, right for the app's own
+     * tokens. Set it (`'30s'`) for another issuer's: a clock a second ahead
+     * would otherwise issue tokens "in the future".
+     */
+    clockTolerance?: Duration;
+    /** Reject tokens issued longer ago than this (needs `iat`). */
+    maxAge?: Duration;
+    /** Claims that must be present. `exp` is required by default. */
+    required?: string[];
+    /** Clock in epoch milliseconds, for tests. */
+    now?: () => number;
+}

package/dist/interfaces/jwt.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/magic-link-store.interface.d.ts

@@ -0,0 +1,36 @@
+export interface MagicLinkRecord {
+    /**
+     * SHA-256 of the token, and of the secret that binds the link to the
+     * browser that requested it (`magicLink.bindToBrowser`): the link alone
+     * does not find it.
+     */
+    id: string;
+    email: string;
+    createdAt: Date;
+    expiresAt: Date;
+    redirectTo?: string;
+}
+/**
+ * Storage for pending magic links. Implement it on your database or Redis,
+ * and register the provider with
+ * `AuthenticationStorage.registerSource({ magicLinks: this })`.
+ *
+ * `consumeMagicLink()` must be one atomic get-and-delete
+ * (`DELETE … RETURNING`, `GETDEL`), so a link works once however many
+ * requests present it. Anyone can request links, so the store must stay
+ * bounded: drop expired links as new ones are saved, and cap the rest.
+ */
+export interface MagicLinkStore {
+    /**
+     * Saves a new link (a fresh random id: a plain insert), then keeps the
+     * store bounded: deletes links whose `expiresAt` is at or before this
+     * one's `createdAt`, and past a cap, those that expire first.
+     */
+    saveMagicLink(record: MagicLinkRecord): Promise<void>;
+    /**
+     * Removes and returns the link, in one atomic step; `undefined` if there
+     * is none. Of several concurrent calls, exactly one gets the record.
+     * Expired links may be returned: `MagicLinkService` checks expiry.
+     */
+    consumeMagicLink(id: string): Promise<MagicLinkRecord | undefined>;
+}

package/dist/interfaces/magic-link-store.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/magic-link.interface.d.ts

@@ -0,0 +1,55 @@
+import type { CookieAttributes } from '../session/cookies.util.js';
+import type { Duration } from './duration.interface.js';
+export interface MagicLink {
+    email: string;
+    url: string;
+    expiresAt: Date;
+}
+/** The account behind an address, as `MagicLinkHandler.resolveUser()` returns it. */
+export interface MagicLinkAccount {
+    id: string;
+    /**
+     * The address the account has stored. The link signs the account in only
+     * when it is the link's address (compared trimmed and lowercased).
+     */
+    email: string;
+}
+export interface MagicLinkOptions {
+    /** Page that receives `?token=…`, e.g. `https://app.example.com/auth/magic`. */
+    url: string;
+    /** Lifetime of a link. Default `'15m'`. */
+    ttl?: Duration;
+    /**
+     * Whether a link works only in the browser that requested it. Default
+     * `true`: `create()` sets a transaction cookie, and `consume()` refuses a
+     * link the browser holds no cookie for (`magic-link-refused`,
+     * `not-this-browser`). Without it, anyone can request a link for their
+     * own address and get someone else to open it, which signs that person's
+     * browser in to the attacker's account (login CSRF). `false` trades that
+     * for links that work on another device than the one that asked for them
+     * (requested on the laptop, opened on the phone).
+     */
+    bindToBrowser?: boolean;
+    /**
+     * Attributes of the transaction cookie, `__Host-magic_link_tx` (or
+     * `magic_link_tx` when they rule the prefix out). `secure` defaults to
+     * `true`; `SameSite` is always `Lax`, which lets the cookie through the
+     * top-level navigation from the mail client to the page.
+     */
+    cookie?: CookieAttributes;
+    /** Clock in epoch milliseconds, for tests. */
+    now?: () => number;
+}
+/** The HTTP request that presents a link, as Express and Fastify provide it. */
+export type MagicLinkRequest = {
+    headers: Record<string, string | string[] | undefined>;
+};
+export interface CreatedMagicLink {
+    expiresAt: Date;
+    /**
+     * The `Set-Cookie` value of the transaction cookie, already set on the HTTP
+     * response when called from a handler; send it yourself elsewhere. Absent
+     * with `bindToBrowser: false`.
+     */
+    cookie?: string;
+}

package/dist/interfaces/magic-link.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/mfa-options.interface.d.ts

@@ -0,0 +1,44 @@
+import type { Duration } from './duration.interface.js';
+export interface MfaOptions {
+    /**
+     * Encryption of TOTP secrets at rest (AES-256-GCM): `{ keys: [key] }`,
+     * newest key first. Required once `mfa` is configured: pass `false` to
+     * store plaintext deliberately (tests, throwaway in-memory setups).
+     */
+    encryption: SecretEncryptionOptions | false;
+    /** Shown in authenticator apps. */
+    issuer?: string;
+    /** Accepted 30-second steps either side of now: an integer from 0 to 10. Default 1, per RFC 6238 §5.2. */
+    window?: number;
+    /** Failed codes allowed per `lockoutWindow` before every code is refused: an integer of at least 1. Default 5. */
+    maxAttempts?: number;
+    /** Default `'15m'`. */
+    lockoutWindow?: Duration;
+    /** Recovery codes per batch: an integer of at least 1. Default 10. */
+    recoveryCodes?: number;
+    /**
+     * How long a session that passed its first factor may wait for the second
+     * (`mfa: 'pending'`) before it expires. Default `'10m'`, never more than
+     * `session.absoluteTtl`. A pending cookie is half a credential: this keeps a
+     * stolen one from staying useful for the session's full lifetime.
+     */
+    pendingTtl?: Duration;
+    /** Clock in epoch milliseconds, for tests. */
+    now?: () => number;
+}
+export interface SecretEncryptionOptions {
+    /**
+     * AES-256-GCM keys: 32-byte `Buffer`s, or strings of at least 32
+     * characters (random secrets, expanded with HKDF-SHA256; not passwords).
+     * The first key encrypts, and every key decrypts. Prepend a new key to
+     * rotate.
+     */
+    keys: (string | Buffer)[];
+    /**
+     * Accept stored values that are not ciphertext (secrets saved before
+     * encryption was turned on) and re-encrypt them on the next successful
+     * verification. Off by default: with encryption on, a plaintext value in
+     * the store is otherwise indistinguishable from one an attacker planted.
+     */
+    migratePlaintext?: boolean;
+}

package/dist/interfaces/mfa-options.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/mfa-store.interface.d.ts

@@ -0,0 +1,70 @@
+export interface TotpRecord {
+    /** Sealed secret (`v1.<keyId>.…`, see `SecretCipher`); base32 plaintext only with `encryption: false`. */
+    secret: string;
+    /** `false` until the user proved the authenticator works. */
+    confirmed: boolean;
+    /**
+     * A replacement secret (sealed like `secret`) staged by
+     * `enroll(…, { replace: true })`. `secret` stays active until `confirm()`
+     * proves the new authenticator works.
+     */
+    pendingSecret?: string;
+    /** Last accepted time step, for replay protection. */
+    lastUsedStep?: number;
+}
+/**
+ * Second-factor storage: each user's authenticator, recovery code hashes,
+ * and failed attempts. Implement it on your database or Redis, and register
+ * the provider with `AuthenticationStorage.registerSource({ mfa: this })`.
+ *
+ * Four methods are what stop a code from being accepted twice, or a burst
+ * of guesses from outrunning the lockout, and must be single atomic writes
+ * (a conditional update or delete, an upsert, a Lua script), never a read
+ * followed by a write: `saveTotp()`, `claimTotpStep()`,
+ * `consumeRecoveryCode()` and `recordMfaFailure()`. Each one's comment has
+ * the race it prevents, and `authenticationStoreContract()` from
+ * `@nestjs/authentication/testing` checks them (`concurrent: true`).
+ *
+ * Times (`now`) are epoch milliseconds from `MfaService`'s clock, never the
+ * store's. Optional fields come back absent (`undefined`), never `null`.
+ */
+export interface MfaStore {
+    getTotp(userId: string): Promise<TotpRecord | undefined>;
+    /**
+     * Saves the user's authenticator (an upsert), or deletes it (`null`).
+     * Never lowers the stored `lastUsedStep`: keep the larger of the stored
+     * one and the record's (`GREATEST()` in the upsert). A record read before
+     * a concurrent `claimTotpStep()` must not reopen the step it claimed.
+     */
+    saveTotp(userId: string, record: TotpRecord | null): Promise<void>;
+    /**
+     * Sets `lastUsedStep = step` iff the user has an authenticator and `step`
+     * is greater than the stored one (or none is stored), in one conditional
+     * write; `true` if it did. Of several concurrent calls with the same step,
+     * exactly one gets `true`: a TOTP code works once.
+     */
+    claimTotpStep(userId: string, step: number): Promise<boolean>;
+    /** Replaces the user's recovery code hashes with `hashes` (`[]` deletes them). */
+    saveRecoveryCodes(userId: string, hashes: string[]): Promise<void>;
+    /**
+     * Removes one recovery code hash of this user, in one conditional delete;
+     * `true` if this call removed it. Of several concurrent calls, exactly one
+     * gets `true`.
+     */
+    consumeRecoveryCode(userId: string, hash: string): Promise<boolean>;
+    countRecoveryCodes(userId: string): Promise<number>;
+    /**
+     * Records a failed attempt at `now`, then returns the failures within
+     * `windowMs` before `now` (`at > now - windowMs`), this one included.
+     * Record first, count second, each visible to other callers as soon as it
+     * returns: parallel calls each count every attempt recorded before them,
+     * so no more than `n` of them see a count of `n` or less. `MfaService`
+     * calls it *before* checking a code, which is what stops a burst of
+     * parallel guesses.
+     */
+    recordMfaFailure(userId: string, windowMs: number, now: number): Promise<number>;
+    /** The failures within `windowMs` before `now`, without recording one. */
+    countMfaFailures(userId: string, windowMs: number, now: number): Promise<number>;
+    /** Forgets the user's failures (after a code verified). */
+    clearMfaFailures(userId: string): Promise<void>;
+}

package/dist/interfaces/mfa-store.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/oidc-provider.interface.d.ts

@@ -0,0 +1,56 @@
+import type { JwsAlgorithm } from './jwt.interface.js';
+export interface OidcProfile {
+    /** Config key of the provider (`google`, `github`, …). */
+    provider: string;
+    /** Stable account id at the provider. Link accounts by (provider, subject), never by email. */
+    subject: string;
+    email?: string;
+    /** Only `true` when the provider asserted it. Unverified emails must not link accounts. */
+    emailVerified: boolean;
+    name?: string;
+    picture?: string;
+    /** Verified ID token claims merged with userinfo (OIDC), or the raw userinfo (OAuth 2.0). */
+    claims: Record<string, unknown>;
+}
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    expiresIn?: number;
+    scope?: string;
+}
+export interface ProfileContext {
+    provider: string;
+    tokens: OAuthTokens;
+    /** GET with the access token, JSON response. For extra API calls. */
+    fetchJson(url: string): Promise<any>;
+}
+export interface OidcProviderConfig {
+    /** `oidc` (default): discovery + ID token. `oauth2`: plain OAuth 2.0 (GitHub), profile from an API. */
+    kind?: 'oidc' | 'oauth2';
+    /** OIDC issuer; discovery is `${issuer}/.well-known/openid-configuration`. */
+    issuer?: string;
+    clientId: string;
+    clientSecret?: string;
+    /** Default `openid email profile` for OIDC. */
+    scopes?: string[];
+    /** Override or (for `oauth2`) supply endpoints. */
+    authorizationEndpoint?: string;
+    tokenEndpoint?: string;
+    userinfoEndpoint?: string;
+    jwksUri?: string;
+    /** Accepted ID token algorithms. Default `RS256`, `ES256`. */
+    idTokenAlgorithms?: JwsAlgorithm[];
+    /** Default `client_secret_basic` with a secret, `none` without (public client + PKCE). */
+    tokenEndpointAuthMethod?: 'client_secret_basic' | 'client_secret_post' | 'none';
+    /**
+     * Extra authorization request parameters (`prompt`, `hd`, `login_hint`,
+     * …). They travel through the browser, which can change or drop them:
+     * hints to the provider, never checks. Check what they ask for in the
+     * resolver, on the verified claims (`profile.claims.hd`, `acr`,
+     * `auth_time`).
+     */
+    authorizationParams?: Record<string, string>;
+    /** `oauth2` only: builds the profile from the userinfo response. */
+    profile?(userinfo: any, context: ProfileContext): OidcProfile | Promise<OidcProfile>;
+}

package/dist/interfaces/oidc-provider.interface.js

@@ -0,0 +1 @@
+export {};