@nestjs/authentication 0.0.1

package/dist/mfa/mfa.service.js

@@ -0,0 +1,346 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var MfaService_1;
+import { randomBytes, randomInt, scrypt } from 'node:crypto';
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { AUTHENTICATION_MODULE_OPTIONS } from '../authentication.constants.js';
+import { safeEqual } from '../utils/crypto.util.js';
+import { durationOr } from '../utils/duration.util.js';
+import { requireIntegerOption } from '../utils/options.util.js';
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { AuthenticationEvents } from '../events/authentication-events.service.js';
+import { SecretDecryptionError } from '../errors/secret-decryption.error.js';
+import { MfaAlreadyEnrolledError } from '../errors/mfa-already-enrolled.error.js';
+import { base32Decode, base32Encode, hotp, totpStep } from './otp.util.js';
+import { SecretCipher } from './secret-cipher.service.js';
+const PERIOD = 30;
+const DIGITS = 6;
+// Crockford-style alphabet: no 0/O or 1/I/L confusion.
+const CODE_ALPHABET = '23456789ABCDEFGHJKMNPQRSTVWXYZ';
+/**
+ * A recovery code as stored: scrypt (N=2^14, r=8, p=1, 16 MiB), salted with
+ * the user id. The salt is deterministic so the store can still look codes
+ * up by hash (`consumeRecoveryCode` is an atomic delete), and per user, so a
+ * dump has to be attacked one user at a time. A code carries ~49 bits:
+ * cheap to exhaust at SHA-256 speed, decades per user at this cost.
+ */
+function hashRecoveryCode(userId, normalized) {
+    const salt = `nestjs-authentication recovery-code v1 ${userId}`;
+    return new Promise((resolve, reject) => scrypt(normalized, salt, 32, { N: 2 ** 14, r: 8, p: 1 }, (error, key) => error ? reject(error) : resolve(`rc1.${key.toString('base64url')}`)));
+}
+/**
+ * TOTP second factor (RFC 6238 over RFC 4226 HOTP, SHA-1, 6 digits, 30 s:
+ * the parameters every authenticator app supports) plus recovery codes.
+ *
+ * - `enroll()` stores an unconfirmed 160-bit secret and returns the
+ *   `otpauth://` URI for the QR code; `confirm()` activates it once a
+ *   code verifies. It refuses to touch a confirmed authenticator
+ *   ({@link MfaAlreadyEnrolledError}): replacing one takes
+ *   `{ replace: true }`, which stages the new secret while the current one
+ *   keeps working until `confirm()`. Call that only from a route that
+ *   requires a verified second factor (`@Authenticate({ mfa: true })`), or
+ *   remove the authenticator with `disable()` first.
+ * - Secrets are encrypted before they reach the store (AES-256-GCM, bound to
+ *   the user id) and decrypted only to compute codes. A secret encrypted with
+ *   an older key is re-encrypted with the current one after its next
+ *   successful verification, or by `reencrypt(userId)`.
+ * - Each time step is accepted once per user (replay protection), across
+ *   the ±`window` range.
+ * - After `maxAttempts` failures in `lockoutWindow` every check fails;
+ *   6 digits are otherwise brute-forceable. Each attempt is counted before
+ *   it is checked, so a burst of parallel guesses cannot outrun the limit.
+ *   This is a per-account control on the verifier, not request rate
+ *   limiting.
+ * - Recovery codes are shown once, and stored under a slow hash salted
+ *   with the user id (~49 bits of entropy each, plus the attempt limit).
+ */
+let MfaService = MfaService_1 = class MfaService {
+    constructor(storage, options, events = new AuthenticationEvents()) {
+        this.storage = storage;
+        this.events = events;
+        this.options = options?.mfa;
+        this.lockoutWindow = durationOr(this.options?.lockoutWindow, '15m');
+        if (!this.options) {
+            return; // MFA unused: isEnrolled() works, enrollment throws
+        }
+        if (this.options.encryption === undefined) {
+            throw new Error('MFA: `mfa.encryption` is required. TOTP secrets cannot be hashed, so a store dump would let anyone ' +
+                'mint valid codes. Pass `{ keys: [key] }`, or `false` to store them in plaintext deliberately.');
+        }
+        if (this.options.encryption) {
+            this.cipher = new SecretCipher(this.options.encryption);
+        }
+        // A `NaN` limit would never be reached: every guess would be checked.
+        requireIntegerOption(this.options.maxAttempts, 'mfa.maxAttempts', { min: 1 });
+        // Each step either side adds two codes that every guess may hit; 30 would be seconds, not steps.
+        requireIntegerOption(this.options.window, 'mfa.window', { min: 0, max: 10 });
+        requireIntegerOption(this.options.recoveryCodes, 'mfa.recoveryCodes', { min: 1 });
+    }
+    async isEnrolled(userId) {
+        // Truthy, not `=== true`: a store that reads the flag back as `1` must not skip the second factor.
+        return !!(await this.store.getTotp(userId))?.confirmed;
+    }
+    /**
+     * Starts an enrollment. Throws {@link MfaAlreadyEnrolledError} when the user
+     * has a confirmed authenticator, unless `replace` is set: then the new
+     * secret is staged and the current authenticator stays active until
+     * `confirm()` succeeds with a code from the new one.
+     */
+    async enroll(userId, accountName, { replace = false } = {}) {
+        const current = await this.store.getTotp(userId);
+        const secret = base32Encode(randomBytes(20));
+        const sealed = this.seal(userId, secret);
+        if (current?.confirmed) {
+            if (!replace) {
+                throw new MfaAlreadyEnrolledError(userId);
+            }
+            await this.store.saveTotp(userId, { ...current, pendingSecret: sealed });
+        }
+        else {
+            await this.store.saveTotp(userId, { secret: sealed, confirmed: false });
+        }
+        return { secret, uri: this.keyUri(secret, accountName) };
+    }
+    /**
+     * Activates a pending enrollment (or a staged replacement, which then
+     * takes the place of the current authenticator).
+     */
+    async confirm(userId, code) {
+        const record = await this.store.getTotp(userId);
+        const candidate = record?.confirmed ? record.pendingSecret : record?.secret;
+        if (!record || !candidate) {
+            return false;
+        }
+        const opened = this.open(userId, candidate);
+        if (!opened || !(await this.check(userId, opened, code))) {
+            return false;
+        }
+        // Read again: it carries the step just claimed, and a disable() or re-enrollment meanwhile wins.
+        const latest = await this.store.getTotp(userId);
+        const stillPending = !!latest && (record.confirmed ? latest.pendingSecret === candidate : latest.secret === candidate);
+        if (!latest || !stillPending) {
+            return false; // re-enrolled or disabled concurrently
+        }
+        const { pendingSecret: _, ...rest } = latest;
+        const secret = opened.needsReencrypt ? this.seal(userId, opened.plaintext) : candidate;
+        await this.store.saveTotp(userId, { ...rest, secret, confirmed: true });
+        this.events.emit({ type: 'mfa-enabled', userId, replaced: record.confirmed });
+        return true;
+    }
+    async verifyTotp(userId, code) {
+        const record = await this.store.getTotp(userId);
+        if (!record?.confirmed) {
+            return false;
+        }
+        const opened = this.open(userId, record.secret);
+        if (!opened || !(await this.check(userId, opened, code))) {
+            return false;
+        }
+        if (opened.needsReencrypt) {
+            // Read again: it keeps the claimed step, and an authenticator disabled or replaced meanwhile stays so.
+            const latest = await this.store.getTotp(userId);
+            if (latest?.secret === record.secret) {
+                await this.store.saveTotp(userId, { ...latest, secret: this.seal(userId, opened.plaintext) });
+            }
+        }
+        this.events.emit({ type: 'mfa-verified', userId, method: 'totp' });
+        return true;
+    }
+    /**
+     * Re-encrypts the stored secret with the current key if it was sealed
+     * with an older one (or is legacy plaintext under `migratePlaintext`).
+     * For key-rotation jobs; returns whether anything was rewritten.
+     */
+    async reencrypt(userId) {
+        const record = await this.store.getTotp(userId);
+        if (!record || !this.cipher || !this.cipher.needsReencrypt(record.secret)) {
+            return false;
+        }
+        const opened = this.open(userId, record.secret);
+        if (!opened) {
+            return false;
+        }
+        // Read again before writing: a disable() or a confirmed replacement meanwhile must stay.
+        const latest = await this.store.getTotp(userId);
+        if (latest?.secret !== record.secret) {
+            return false;
+        }
+        await this.store.saveTotp(userId, { ...latest, secret: this.seal(userId, opened.plaintext) });
+        return true;
+    }
+    /**
+     * Returns fresh plaintext codes (show once); replaces any previous batch.
+     * Codes are a second factor: for a user with a confirmed authenticator,
+     * call it right after `confirm()` succeeded, or from a route that requires
+     * a verified second factor (`@Authenticate({ mfa: true })`). Otherwise an
+     * API key, or a token issued before the user enrolled, could mint codes
+     * that finish a sign-in with the password alone.
+     */
+    async generateRecoveryCodes(userId) {
+        const codes = Array.from({ length: this.options?.recoveryCodes ?? 10 }, () => {
+            const chars = Array.from({ length: 10 }, () => CODE_ALPHABET[randomInt(CODE_ALPHABET.length)]).join('');
+            return `${chars.slice(0, 5)}-${chars.slice(5)}`;
+        });
+        const hashes = await Promise.all(codes.map((c) => hashRecoveryCode(userId, normalizeCode(c))));
+        await this.store.saveRecoveryCodes(userId, hashes);
+        this.events.emit({ type: 'recovery-codes-generated', userId, count: codes.length });
+        return codes;
+    }
+    async verifyRecoveryCode(userId, code) {
+        const attempt = await this.begin(userId, 'recovery-code');
+        if (attempt === undefined) {
+            return false;
+        }
+        const normalized = typeof code === 'string' ? normalizeCode(code) : '';
+        if (normalized.length === 10 &&
+            (await this.store.consumeRecoveryCode(userId, await hashRecoveryCode(userId, normalized)))) {
+            await this.store.clearMfaFailures(userId);
+            this.events.emit({ type: 'mfa-verified', userId, method: 'recovery-code' });
+            return true;
+        }
+        this.failed(userId, 'recovery-code', attempt);
+        return false;
+    }
+    remainingRecoveryCodes(userId) {
+        return this.store.countRecoveryCodes(userId);
+    }
+    /**
+     * Removes the authenticator and the recovery codes. Call it only from a
+     * route that requires a verified second factor
+     * (`@Authenticate({ mfa: true })`): an API key, or a token issued before
+     * the user enrolled, is no second factor.
+     */
+    async disable(userId) {
+        await this.store.saveTotp(userId, null);
+        await this.store.saveRecoveryCodes(userId, []);
+        this.events.emit({ type: 'mfa-disabled', userId });
+    }
+    keyUri(secret, accountName) {
+        const issuer = this.options?.issuer ?? 'NestJS';
+        const label = `${encodeURIComponent(issuer)}:${encodeURIComponent(accountName)}`;
+        const params = new URLSearchParams({ secret, issuer, algorithm: 'SHA1', digits: String(DIGITS), period: String(PERIOD) });
+        return `otpauth://totp/${label}?${params}`;
+    }
+    /** `opened` is undefined when the secret could not be decrypted: fail closed, not counted against the user. */
+    async check(userId, opened, code) {
+        const attempt = await this.begin(userId, 'totp');
+        if (attempt === undefined) {
+            return false;
+        }
+        const step = this.matchingStep(opened.plaintext, code);
+        if (step !== undefined && (await this.store.claimTotpStep(userId, step))) {
+            await this.store.clearMfaFailures(userId);
+            return true;
+        }
+        this.failed(userId, 'totp', attempt);
+        return false;
+    }
+    /**
+     * Counts an attempt before it is checked, and returns its number within
+     * the window, or `undefined` when it must be refused unchecked. Counting
+     * first is what stops a burst of parallel guesses: each one gets its own
+     * number from the store, and only the first `maxAttempts` are checked.
+     * An attempt made while already locked out is not counted, so the lockout
+     * ends `lockoutWindow` after it began.
+     */
+    async begin(userId, method) {
+        const failures = await this.store.countMfaFailures(userId, this.lockoutWindow, this.now());
+        if (failures >= this.maxAttempts) {
+            this.events.emit({ type: 'mfa-failed', userId, method, failures, locked: true });
+            return undefined;
+        }
+        const attempt = await this.store.recordMfaFailure(userId, this.lockoutWindow, this.now());
+        if (attempt > this.maxAttempts) {
+            this.events.emit({ type: 'mfa-failed', userId, method, failures: attempt, locked: true });
+            return undefined;
+        }
+        return attempt;
+    }
+    /** The attempt was already counted by {@link begin}; this reports it. */
+    failed(userId, method, attempt) {
+        this.events.emit({ type: 'mfa-failed', userId, method, failures: attempt, locked: attempt >= this.maxAttempts });
+    }
+    seal(userId, secret) {
+        if (!this.options) {
+            throw new Error('MFA is not configured: add `mfa: { encryption: … }` to the AuthenticationModule options');
+        }
+        return this.cipher ? this.cipher.encrypt(secret, `totp.${userId}`) : secret;
+    }
+    open(userId, stored) {
+        if (!this.options) {
+            throw new Error('MFA is not configured: add `mfa: { encryption: … }` to the AuthenticationModule options');
+        }
+        if (!this.cipher) {
+            return { plaintext: stored, needsReencrypt: false };
+        }
+        try {
+            return this.cipher.decrypt(stored, `totp.${userId}`);
+        }
+        catch (error) {
+            if (!(error instanceof SecretDecryptionError)) {
+                throw error;
+            }
+            // Tampering, a row copied from another user, or a key removed too early.
+            MfaService_1.logger.error(`TOTP secret of user ${userId} could not be decrypted: ${error.message}`);
+            return undefined;
+        }
+    }
+    matchingStep(secret, code) {
+        if (typeof code !== 'string' || !/^\d{6}$/.test(code)) {
+            return undefined;
+        }
+        let key;
+        try {
+            key = base32Decode(secret);
+        }
+        catch {
+            return undefined; // not a base32 secret (e.g. ciphertext stored while `encryption: false`)
+        }
+        // RFC 4226 §4 asks for 128 bits at least (enroll() makes 160): an empty secret (a NULL column
+        // read back as '') would give codes anyone can compute.
+        if (key.length < 16) {
+            return undefined;
+        }
+        const current = totpStep(Math.floor(this.now() / 1000), PERIOD);
+        const window = this.options?.window ?? 1;
+        let found;
+        // Check every candidate (no early exit) so timing does not reveal which step matched.
+        for (let step = current - window; step <= current + window; step++) {
+            if (safeEqual(hotp(key, step, DIGITS), code) && found === undefined) {
+                found = step;
+            }
+        }
+        return found;
+    }
+    /** Read at each call, never in the constructor: the registry locks once the module starts. */
+    get store() {
+        return this.storage.mfa;
+    }
+    get maxAttempts() {
+        return this.options?.maxAttempts ?? 5;
+    }
+    now() {
+        return this.options?.now?.() ?? Date.now();
+    }
+};
+MfaService.logger = new Logger('MfaService');
+MfaService = MfaService_1 = __decorate([
+    Injectable(),
+    __param(1, Optional()),
+    __param(1, Inject(AUTHENTICATION_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [AuthenticationStorage, Object, AuthenticationEvents])
+], MfaService);
+export { MfaService };
+function normalizeCode(code) {
+    return code.toUpperCase().replace(/[\s-]/g, '');
+}

package/dist/mfa/otp.util.d.ts

@@ -0,0 +1,7 @@
+/** RFC 4648 base32, no padding (the form authenticator apps expect). */
+export declare function base32Encode(data: Buffer): string;
+export declare function base32Decode(input: string): Buffer;
+/** HOTP (RFC 4226 §5.3) with HMAC-SHA1. */
+export declare function hotp(key: Buffer, counter: number, digits?: number): string;
+/** The RFC 6238 time step for a Unix time in seconds. */
+export declare function totpStep(unixSeconds: number, period?: number): number;

package/dist/mfa/otp.util.js

@@ -0,0 +1,52 @@
+import { createHmac } from 'node:crypto';
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+/** RFC 4648 base32, no padding (the form authenticator apps expect). */
+export function base32Encode(data) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of data) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            out += ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0) {
+        out += ALPHABET[(value << (5 - bits)) & 31];
+    }
+    return out;
+}
+export function base32Decode(input) {
+    const clean = input.replace(/=+$/, '').toUpperCase();
+    const bytes = [];
+    let bits = 0;
+    let value = 0;
+    for (const char of clean) {
+        const index = ALPHABET.indexOf(char);
+        if (index === -1) {
+            throw new Error('invalid base32');
+        }
+        value = (value << 5) | index;
+        bits += 5;
+        if (bits >= 8) {
+            bytes.push((value >>> (bits - 8)) & 255);
+            bits -= 8;
+        }
+    }
+    return Buffer.from(bytes);
+}
+/** HOTP (RFC 4226 §5.3) with HMAC-SHA1. */
+export function hotp(key, counter, digits = 6) {
+    const message = Buffer.alloc(8);
+    message.writeBigUInt64BE(BigInt(counter));
+    const mac = createHmac('sha1', key).update(message).digest();
+    const offset = mac[mac.length - 1] & 0x0f;
+    const binary = mac.readUInt32BE(offset) & 0x7fffffff;
+    return String(binary % 10 ** digits).padStart(digits, '0');
+}
+/** The RFC 6238 time step for a Unix time in seconds. */
+export function totpStep(unixSeconds, period = 30) {
+    return Math.floor(unixSeconds / period);
+}

package/dist/mfa/secret-cipher.service.d.ts

@@ -0,0 +1,28 @@
+import type { SecretEncryptionOptions } from '../interfaces/mfa-options.interface.js';
+/**
+ * AES-256-GCM for secrets the server must read back (TOTP seeds cannot be
+ * hashed). Format: `v1.<keyId>.<iv>.<ciphertext>.<tag>`, base64url parts.
+ *
+ * - The key id is derived from the key (8 characters of its SHA-256), so
+ *   rotation finds the right key without anyone naming keys, and the id
+ *   reveals nothing about the key.
+ * - A fresh 96-bit IV per encryption (NIST SP 800-38D §8.2.2 random IVs;
+ *   fine far below 2^32 encryptions per key).
+ * - Additional authenticated data binds the version, key id, purpose and
+ *   owner (`v1.<keyId>.<context>`), so a ciphertext copied to another user's
+ *   row, or with a rewritten header, fails authentication.
+ * - Decryption fails closed: any malformed value, unknown key id or bad tag
+ *   throws {@link SecretDecryptionError}.
+ */
+export declare class SecretCipher {
+    private readonly options;
+    private readonly keys;
+    private readonly currentId;
+    constructor(options: SecretEncryptionOptions);
+    encrypt(plaintext: string, context: string): string;
+    decrypt(stored: string, context: string): {
+        plaintext: string;
+        needsReencrypt: boolean;
+    };
+    needsReencrypt(stored: string): boolean;
+}

package/dist/mfa/secret-cipher.service.js

@@ -0,0 +1,106 @@
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from 'node:crypto';
+import { requireOption } from '../utils/options.util.js';
+import { SecretDecryptionError } from '../errors/secret-decryption.error.js';
+const VERSION = 'v1';
+const HKDF_INFO = 'nestjs-authentication totp-secret v1';
+const MIN_SECRET_LENGTH = 32;
+const OPTION = 'mfa.encryption.keys';
+/**
+ * AES-256-GCM for secrets the server must read back (TOTP seeds cannot be
+ * hashed). Format: `v1.<keyId>.<iv>.<ciphertext>.<tag>`, base64url parts.
+ *
+ * - The key id is derived from the key (8 characters of its SHA-256), so
+ *   rotation finds the right key without anyone naming keys, and the id
+ *   reveals nothing about the key.
+ * - A fresh 96-bit IV per encryption (NIST SP 800-38D §8.2.2 random IVs;
+ *   fine far below 2^32 encryptions per key).
+ * - Additional authenticated data binds the version, key id, purpose and
+ *   owner (`v1.<keyId>.<context>`), so a ciphertext copied to another user's
+ *   row, or with a rewritten header, fails authentication.
+ * - Decryption fails closed: any malformed value, unknown key id or bad tag
+ *   throws {@link SecretDecryptionError}.
+ */
+export class SecretCipher {
+    constructor(options) {
+        this.options = options;
+        this.keys = new Map();
+        const list = options?.keys;
+        if (!Array.isArray(list) || list.length === 0) {
+            throw new TypeError(`MFA: \`${OPTION}\` must list at least one key (newest first).`);
+        }
+        const derived = list.map(deriveKey);
+        // A key listed twice has one id: the first entry wins, and both are the same key.
+        for (const { id, key } of derived) {
+            if (!this.keys.has(id)) {
+                this.keys.set(id, key);
+            }
+        }
+        this.currentId = derived[0].id;
+    }
+    encrypt(plaintext, context) {
+        const iv = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', this.keys.get(this.currentId), iv);
+        cipher.setAAD(aad(this.currentId, context));
+        const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+        return [VERSION, this.currentId, iv, ciphertext, cipher.getAuthTag()]
+            .map((part) => (typeof part === 'string' ? part : part.toString('base64url')))
+            .join('.');
+    }
+    decrypt(stored, context) {
+        if (!stored.startsWith(`${VERSION}.`)) {
+            if (this.options.migratePlaintext) {
+                return { plaintext: stored, needsReencrypt: true };
+            }
+            throw new SecretDecryptionError('value is not encrypted');
+        }
+        const parts = stored.split('.');
+        if (parts.length !== 5) {
+            throw new SecretDecryptionError('malformed ciphertext');
+        }
+        const [, keyId, iv, ciphertext, tag] = parts.map((p, i) => (i < 2 ? p : Buffer.from(p, 'base64url')));
+        const key = this.keys.get(keyId);
+        if (!key) {
+            throw new SecretDecryptionError(`unknown key id '${keyId}'`);
+        }
+        if (iv.length !== 12 || tag.length !== 16) {
+            throw new SecretDecryptionError('malformed ciphertext');
+        }
+        try {
+            const decipher = createDecipheriv('aes-256-gcm', key, iv, { authTagLength: 16 });
+            decipher.setAAD(aad(keyId, context));
+            decipher.setAuthTag(tag);
+            const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+            return { plaintext, needsReencrypt: keyId !== this.currentId };
+        }
+        catch {
+            throw new SecretDecryptionError('authentication failed');
+        }
+    }
+    needsReencrypt(stored) {
+        return !stored.startsWith(`${VERSION}.${this.currentId}.`);
+    }
+}
+function aad(keyId, context) {
+    return Buffer.from(`${VERSION}.${keyId}.${context}`, 'utf8');
+}
+/** The AES key for one `keys` entry, and its id. Errors name the entry, never its value. */
+function deriveKey(material, index) {
+    const option = `${OPTION}[${index}]`;
+    requireOption(material, option, `32 random bytes, or a random string of at least ${MIN_SECRET_LENGTH} characters`);
+    let key;
+    if (Buffer.isBuffer(material)) {
+        if (material.length !== 32) {
+            throw new TypeError(`MFA: \`${option}\` is a Buffer of ${material.length} bytes; it must be 32 bytes.`);
+        }
+        key = material;
+    }
+    else if (typeof material === 'string' && material.length >= MIN_SECRET_LENGTH) {
+        key = Buffer.from(hkdfSync('sha256', material, Buffer.alloc(0), HKDF_INFO, 32));
+    }
+    else {
+        throw new TypeError(`MFA: \`${option}\` must be 32 random bytes, or a random string of at least ${MIN_SECRET_LENGTH} ` +
+            'characters (for example `openssl rand -base64 32`), not a password.');
+    }
+    const id = createHash('sha256').update(key).digest('base64url').slice(0, 8);
+    return { id, key };
+}

package/dist/oidc/in-memory-oidc-state.store.d.ts

@@ -0,0 +1,13 @@
+import type { OidcTransaction } from '../interfaces/oidc.interface.js';
+import type { OidcStateStore } from '../interfaces/oidc-state-store.interface.js';
+/**
+ * Process-local store: the default when no source is registered, and a
+ * test double. Drops expired logins as new ones are saved, and holds at
+ * most 10,000, dropping the oldest: anyone can start a login, so the store
+ * must not grow with them.
+ */
+export declare class InMemoryOidcStateStore implements OidcStateStore {
+    private readonly pending;
+    saveOidcState(transaction: OidcTransaction): Promise<void>;
+    consumeOidcState(state: string): Promise<OidcTransaction | undefined>;
+}

package/dist/oidc/in-memory-oidc-state.store.js

@@ -0,0 +1,45 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Injectable } from '@nestjs/common';
+const MAX_PENDING = 10_000;
+/**
+ * Process-local store: the default when no source is registered, and a
+ * test double. Drops expired logins as new ones are saved, and holds at
+ * most 10,000, dropping the oldest: anyone can start a login, so the store
+ * must not grow with them.
+ */
+let InMemoryOidcStateStore = class InMemoryOidcStateStore {
+    constructor() {
+        this.pending = new Map();
+    }
+    async saveOidcState(transaction) {
+        const now = transaction.createdAt.getTime();
+        // Insertion order is expiry order (one lifetime per service): stop at the first live entry.
+        for (const [state, tx] of this.pending) {
+            if (tx.expiresAt.getTime() > now) {
+                break;
+            }
+            this.pending.delete(state);
+        }
+        this.pending.set(transaction.state, { ...transaction });
+        for (const state of this.pending.keys()) {
+            if (this.pending.size <= MAX_PENDING) {
+                break;
+            }
+            this.pending.delete(state); // insertion order: the oldest first
+        }
+    }
+    async consumeOidcState(state) {
+        const tx = this.pending.get(state);
+        this.pending.delete(state);
+        return tx;
+    }
+};
+InMemoryOidcStateStore = __decorate([
+    Injectable()
+], InMemoryOidcStateStore);
+export { InMemoryOidcStateStore };

package/dist/oidc/oidc-account.resolver.d.ts

@@ -0,0 +1,23 @@
+import type { OAuthTokens, OidcProfile } from '../interfaces/oidc-provider.interface.js';
+import type { OidcResolveContext } from '../interfaces/oidc.interface.js';
+/**
+ * Implemented by the app: maps an external identity to a local user
+ * (find by `(provider, subject)`, link, or create). Return `null` to refuse.
+ * An ordinary provider of one of your modules, which registers itself from
+ * its constructor: `registry.registerHandler('oidc', this)`.
+ *
+ * Linking a new identity to an existing account by email is only safe when
+ * both sides verified the address: `profile.emailVerified` (the provider
+ * asserted it) and your own record (the owner proved it to you). Otherwise
+ * someone could register the address first, with a password of their
+ * choosing, and keep access once the real owner signs in with the provider
+ * (account pre-hijacking). Refuse, and let the user sign in and link from
+ * their account (`context.linkTo`).
+ */
+export declare abstract class OidcAccountResolver {
+    abstract resolveUser(profile: OidcProfile, tokens: OAuthTokens, context: OidcResolveContext): {
+        id: string;
+    } | null | Promise<{
+        id: string;
+    } | null>;
+}

package/dist/oidc/oidc-account.resolver.js

@@ -0,0 +1,16 @@
+/**
+ * Implemented by the app: maps an external identity to a local user
+ * (find by `(provider, subject)`, link, or create). Return `null` to refuse.
+ * An ordinary provider of one of your modules, which registers itself from
+ * its constructor: `registry.registerHandler('oidc', this)`.
+ *
+ * Linking a new identity to an existing account by email is only safe when
+ * both sides verified the address: `profile.emailVerified` (the provider
+ * asserted it) and your own record (the owner proved it to you). Otherwise
+ * someone could register the address first, with a password of their
+ * choosing, and keep access once the real owner signs in with the provider
+ * (account pre-hijacking). Refuse, and let the user sign in and link from
+ * their account (`context.linkTo`).
+ */
+export class OidcAccountResolver {
+}