@udibo/oauth2 0.1.0

package/esm/identity/mfa/service.js

@@ -0,0 +1,351 @@
+/**
+ * The MFA orchestrator: a small service that wires the TOTP and recovery-code
+ * primitives to an app-owned {@link MfaStore} — the same thin storage seam as
+ * every other layer here. It owns the lifecycle rules (pending vs. active
+ * secrets, TOTP replay rejection, recovery-code burning); the app owns the
+ * rows, the routes, and the policy for *when* MFA is required.
+ *
+ * @module
+ */
+import { IdentityError } from "../errors.js";
+import { dispatchIdentityEvent, } from "../events.js";
+import { enforceRateLimit } from "../rate-limit.js";
+import { generateRecoveryCodes, hashRecoveryCode, normalizeRecoveryCode, RECOVERY_CODE_LENGTH, } from "./recovery-codes.js";
+import { buildOtpauthUri, generateTotpSecret, validateTotpParams, verifyTotpCode, } from "./totp.js";
+/**
+ * Orchestrates TOTP enrollment, verification, and recovery codes over an
+ * app-owned {@link MfaStore}.
+ *
+ * Lifecycle: {@link startEnrollment} stores a *pending* secret (ignored by
+ * {@link verify}, so an unconfirmed enrollment can never lock a user out);
+ * {@link confirmEnrollment} proves the user's authenticator works, activates
+ * the secret, and issues recovery codes; {@link verify} accepts either a TOTP
+ * code (rejecting replays via the stored last step) or a recovery code
+ * (burning it on use). Replacing an active credential requires
+ * {@link disable} first — gate that route behind a fresh re-authentication,
+ * or a hijacked session could silently swap the user's authenticator.
+ * Deciding *when* to demand a code — sign-in policy, step-up, admin reset —
+ * is the app's job.
+ *
+ * @example Enroll, confirm, and verify
+ * ```ts
+ * const mfa = new MfaService({ store, rateLimiter });
+ * const { otpauthUri } = await mfa.startEnrollment(user.id, {
+ *   issuer: "Udibo", accountName: user.email,
+ * });
+ * // …render QR, user scans and submits a code…
+ * const confirmation = await mfa.confirmEnrollment(user.id, code);
+ * // …later, at sign-in…
+ * const result = await mfa.verify(user.id, submittedCode);
+ * ```
+ */
+export class MfaService {
+    #store;
+    #totp;
+    #recoveryCodeCount;
+    #rateLimiter;
+    #enforce;
+    #onEvent;
+    /**
+     * Builds the service around an app-owned {@link MfaStore}.
+     *
+     * @throws {TypeError} on unusable configuration — non-positive-integer
+     * `digits`/`periodSeconds`/`recoveryCodeCount` or negative `windows` — so a
+     * miswired deploy fails at construction instead of silently rejecting every
+     * code an enrolled user submits.
+     */
+    constructor(options) {
+        validateTotpParams(options.totp ?? {});
+        const count = options.recoveryCodeCount;
+        if (count !== undefined && (!Number.isInteger(count) || count <= 0)) {
+            throw new TypeError("recoveryCodeCount must be a positive integer");
+        }
+        this.#store = options.store;
+        this.#totp = options.totp ?? {};
+        this.#recoveryCodeCount = count;
+        this.#rateLimiter = options.rateLimiter;
+        this.#enforce = (options.protectionMode ?? "enforce") === "enforce";
+        this.#onEvent = options.onEvent;
+    }
+    /**
+     * Begin TOTP enrollment: generates a fresh secret, stores it as *pending*,
+     * and returns what the enrollment screen needs. Repeating the call replaces
+     * the pending secret.
+     *
+     * @throws {IdentityError} `mfa_already_enrolled` when an active credential
+     * exists — replacing an authenticator requires {@link disable} first (behind
+     * re-authentication), so a stolen session cannot silently swap it.
+     */
+    async startEnrollment(userId, options) {
+        this.#assertNotEnrolled(await this.#store.getTotp(userId));
+        const { base32 } = generateTotpSecret();
+        await this.#store.setPendingTotp(userId, base32);
+        return {
+            base32,
+            otpauthUri: buildOtpauthUri({
+                secret: base32,
+                issuer: options.issuer,
+                accountName: options.accountName,
+                digits: this.#totp.digits,
+                periodSeconds: this.#totp.periodSeconds,
+                algorithm: this.#totp.algorithm,
+            }),
+        };
+    }
+    /**
+     * Confirm enrollment by verifying a code against the *pending* secret. On
+     * success the secret becomes active, a fresh recovery-code set is generated
+     * and stored, and the plaintext codes are returned for one-time display.
+     * Returns `{ confirmed: false }` when the code is wrong, no enrollment is
+     * pending, or the pending secret changed under a concurrent enrollment. If
+     * storing the recovery codes fails after activation, the just-activated
+     * credential is rolled back and the error rethrown — a failure leaves the
+     * user *not* enrolled (free to retry), never enrolled without the recovery
+     * codes they were promised.
+     *
+     * @throws {IdentityError} `mfa_already_enrolled` when an active credential
+     * exists (see {@link startEnrollment}).
+     */
+    async confirmEnrollment(userId, code, options) {
+        const record = await this.#store.getTotp(userId);
+        this.#assertNotEnrolled(record);
+        const pending = record?.pendingSecretBase32;
+        if (!pending)
+            return { confirmed: false };
+        const result = await verifyTotpCode({
+            secret: pending,
+            code,
+            timestamp: options?.timestamp,
+            ...this.#totp,
+        });
+        if (!result.valid)
+            return { confirmed: false };
+        const activated = await this.#store.activateTotp(userId, pending, result.matchedStep);
+        if (!activated)
+            return { confirmed: false };
+        let recoveryCodes;
+        try {
+            recoveryCodes = await this.#issueRecoveryCodes(userId);
+        }
+        catch (error) {
+            await this.#store.clearTotp(userId);
+            throw error;
+        }
+        await this.#emit({ type: "mfa.enrollment.confirmed", userId });
+        return { confirmed: true, recoveryCodes };
+    }
+    /**
+     * Verify a second-factor code: first as TOTP against the *active* secret
+     * (pending secrets are ignored — they need {@link confirmEnrollment}), then
+     * as a recovery code (restrict with {@link MfaVerifyOptions.method}). An
+     * accepted TOTP code atomically advances the stored last step, so the same
+     * code is rejected on replay even under concurrent submission; an accepted
+     * recovery code is atomically burned, so it is single-use. Without an
+     * active credential every code is rejected — recovery codes are a fallback
+     * *for* the enrolled factor, so stale hashes can never authenticate a user
+     * whose MFA was disabled. A successful verification resets the per-user
+     * rate-limit window. On failure the result carries a
+     * {@link MfaVerifyFailureReason} — `"replayed"` for a valid-but-spent TOTP
+     * code, `"invalid"` otherwise — so a caller can distinguish a reused code
+     * from a wrong one without subscribing to `onEvent`.
+     *
+     * @throws {IdentityError} `rate_limited` when a `rateLimiter` is configured,
+     * the per-user limit is hit, and `protectionMode` is `"enforce"`.
+     */
+    async verify(userId, code, options) {
+        await this.#throttle(userId);
+        const secret = (await this.#store.getTotp(userId))?.secretBase32;
+        if (!secret)
+            return await this.#verifyFailed(userId, "invalid");
+        const method = options?.method;
+        if (method !== "recovery") {
+            const outcome = await this.#verifyTotp(userId, secret, code, options?.timestamp);
+            if (outcome)
+                return outcome;
+        }
+        if (method !== "totp") {
+            const outcome = await this.#verifyRecovery(userId, code);
+            if (outcome)
+                return outcome;
+        }
+        return await this.#verifyFailed(userId, "invalid");
+    }
+    /** Whether the user has an *active* (confirmed) TOTP credential. */
+    async isEnrolled(userId) {
+        const record = await this.#store.getTotp(userId);
+        return record?.secretBase32 !== undefined;
+    }
+    /**
+     * The user's TOTP enrollment stage — `"none"`, `"pending"`, or `"active"`
+     * (see {@link MfaEnrollmentStatus}). Unlike {@link isEnrolled}, this also
+     * reveals a started-but-unconfirmed enrollment, so an enrollment screen can
+     * resume a pending secret the user already scanned rather than calling
+     * {@link startEnrollment} again and invalidating it.
+     */
+    async enrollmentStatus(userId) {
+        const record = await this.#store.getTotp(userId);
+        if (record?.secretBase32 !== undefined)
+            return "active";
+        if (record?.pendingSecretBase32 !== undefined)
+            return "pending";
+        return "none";
+    }
+    /**
+     * Remove the user's MFA entirely: recovery codes first, then active and
+     * pending secrets — so a partial failure can only leave MFA still *on*,
+     * never a "disabled" account whose old recovery codes still authenticate.
+     * Gate the route that calls this behind a fresh re-authentication —
+     * disabling MFA is what an account takeover wants most.
+     */
+    async disable(userId) {
+        await this.#store.setRecoveryHashes(userId, []);
+        await this.#store.clearTotp(userId);
+        await this.#emit({ type: "mfa.disabled", userId });
+    }
+    /**
+     * Replace the user's recovery codes with a fresh set and return the
+     * plaintext for one-time display. All previously issued codes stop working.
+     *
+     * @throws {IdentityError} `mfa_not_enrolled` when the user has no active
+     * TOTP enrollment.
+     */
+    async regenerateRecoveryCodes(userId) {
+        if (!await this.isEnrolled(userId)) {
+            throw new IdentityError("mfa_not_enrolled", "cannot regenerate recovery codes: MFA is not enrolled");
+        }
+        const codes = await this.#issueRecoveryCodes(userId);
+        await this.#emit({ type: "mfa.recovery_codes.regenerated", userId });
+        return codes;
+    }
+    async #verifyTotp(userId, secret, code, timestamp) {
+        const result = await verifyTotpCode({
+            secret,
+            code,
+            timestamp,
+            ...this.#totp,
+        });
+        if (!result.valid)
+            return undefined;
+        if (!await this.#store.advanceLastStep(userId, result.matchedStep)) {
+            return await this.#verifyFailed(userId, "replayed");
+        }
+        await this.#resetThrottle(userId);
+        await this.#emit({ type: "mfa.verify.succeeded", userId, method: "totp" });
+        return { valid: true, method: "totp" };
+    }
+    async #verifyRecovery(userId, code) {
+        if (normalizeRecoveryCode(code).length !== RECOVERY_CODE_LENGTH) {
+            return undefined;
+        }
+        const consumed = await this.#store.consumeRecoveryHash(userId, await hashRecoveryCode(code));
+        if (!consumed)
+            return undefined;
+        const remainingRecoveryCodes = (await this.#store.getRecoveryHashes(userId)).length;
+        await this.#resetThrottle(userId);
+        await this.#emit({
+            type: "mfa.verify.succeeded",
+            userId,
+            method: "recovery",
+            remainingRecoveryCodes,
+        });
+        return { valid: true, method: "recovery", remainingRecoveryCodes };
+    }
+    #assertNotEnrolled(record) {
+        if (record?.secretBase32) {
+            throw new IdentityError("mfa_already_enrolled", "disable MFA before enrolling a new authenticator");
+        }
+    }
+    async #issueRecoveryCodes(userId) {
+        const { codes, hashes } = await generateRecoveryCodes({
+            count: this.#recoveryCodeCount,
+        });
+        await this.#store.setRecoveryHashes(userId, hashes);
+        return codes;
+    }
+    #rateKey(userId) {
+        return `mfa:verify:${userId}`;
+    }
+    #throttle(userId) {
+        return enforceRateLimit({
+            rateLimiter: this.#rateLimiter,
+            key: this.#rateKey(userId),
+            message: "too many MFA attempts",
+            enforce: this.#enforce,
+            event: { type: "mfa.verify.rate_limited", userId },
+            emit: (e) => this.#emit(e),
+        });
+    }
+    async #resetThrottle(userId) {
+        await this.#rateLimiter?.reset(this.#rateKey(userId));
+    }
+    async #verifyFailed(userId, reason) {
+        await this.#emit({ type: "mfa.verify.failed", userId, reason });
+        return { valid: false, reason };
+    }
+    #emit(event) {
+        return dispatchIdentityEvent(this.#onEvent, "mfa", event);
+    }
+}
+/**
+ * In-memory {@link MfaStore} for development and tests. State is lost on
+ * restart; back the contract with a database (secrets encrypted at rest,
+ * conditional writes for the atomic methods) for production.
+ */
+export class MemoryMfaStore {
+    #totp = new Map();
+    #recovery = new Map();
+    /** Return a copy of the user's TOTP record, or `undefined`. */
+    getTotp(userId) {
+        const record = this.#totp.get(userId);
+        return Promise.resolve(record ? { ...record } : undefined);
+    }
+    /** Store a pending secret, keeping any active credential. */
+    setPendingTotp(userId, secretBase32) {
+        const record = this.#totp.get(userId) ?? {};
+        record.pendingSecretBase32 = secretBase32;
+        this.#totp.set(userId, record);
+        return Promise.resolve();
+    }
+    /** Promote the matching pending secret to active; `false` when it changed. */
+    activateTotp(userId, secretBase32, lastStep) {
+        const record = this.#totp.get(userId);
+        if (record?.pendingSecretBase32 !== secretBase32) {
+            return Promise.resolve(false);
+        }
+        this.#totp.set(userId, { secretBase32, lastStep });
+        return Promise.resolve(true);
+    }
+    /** Delete the user's TOTP record. */
+    clearTotp(userId) {
+        this.#totp.delete(userId);
+        return Promise.resolve();
+    }
+    /** Advance the replay guard only forward; `false` when the step was spent. */
+    advanceLastStep(userId, step) {
+        const record = this.#totp.get(userId);
+        if (!record || step <= (record.lastStep ?? -1)) {
+            return Promise.resolve(false);
+        }
+        record.lastStep = step;
+        return Promise.resolve(true);
+    }
+    /** Return the user's stored recovery hashes (empty when none). */
+    getRecoveryHashes(userId) {
+        return Promise.resolve([...(this.#recovery.get(userId) ?? [])]);
+    }
+    /** Replace the user's recovery hashes with exactly this set. */
+    setRecoveryHashes(userId, hashes) {
+        this.#recovery.set(userId, [...hashes]);
+        return Promise.resolve();
+    }
+    /** Delete one hash, reporting whether it was present. */
+    consumeRecoveryHash(userId, hash) {
+        const hashes = this.#recovery.get(userId) ?? [];
+        const index = hashes.indexOf(hash);
+        if (index === -1)
+            return Promise.resolve(false);
+        hashes.splice(index, 1);
+        this.#recovery.set(userId, hashes);
+        return Promise.resolve(true);
+    }
+}

package/esm/identity/mfa/totp.d.ts

@@ -0,0 +1,186 @@
+/**
+ * TOTP primitives (RFC 6238 over RFC 4226 HOTP) built on Web Crypto — no
+ * dependencies beyond `@std`. Generate a secret, render the `otpauth://` URI an
+ * authenticator app scans, and verify submitted codes with a constant-time
+ * comparison.
+ *
+ * Verification returns the matched time-step counter so the caller can enforce
+ * single use: persist the last accepted step per user and reject any code whose
+ * `matchedStep` is `<=` the stored value (see {@link verifyTotpCode}). The
+ * package owns the math; replay state, like all storage, stays app-owned.
+ *
+ * @module
+ */
+/**
+ * The HMAC hash a TOTP credential uses. `"SHA-1"` is the RFC default and what
+ * authenticator apps universally support; prefer it unless you control the
+ * client. Some authenticators silently ignore the `algorithm` URI parameter and
+ * always use SHA-1, so a non-default choice can produce codes that never match.
+ */
+export type TotpAlgorithm = "SHA-1" | "SHA-256" | "SHA-512";
+/**
+ * Assert that TOTP parameters are usable: `digits` and `periodSeconds` must be
+ * positive integers and `windows` a non-negative integer. Every TOTP entry
+ * point applies this, so a corrupted or miswired configuration fails loudly
+ * instead of silently rejecting every code.
+ *
+ * @throws {TypeError} on the first invalid value.
+ */
+export declare function validateTotpParams(params: {
+    digits?: number;
+    periodSeconds?: number;
+    windows?: number;
+}): void;
+/**
+ * Decode a base32 TOTP secret into raw key bytes. Tolerates lowercase,
+ * whitespace, and missing `=` padding (authenticator conventions vary).
+ *
+ * @throws {TypeError} if the value is not valid RFC 4648 base32.
+ */
+export declare function decodeTotpSecret(base32: string): Uint8Array;
+/** A freshly generated TOTP secret, in both raw and shareable forms. */
+export interface GeneratedTotpSecret {
+    /** The raw 20-byte (160-bit) secret key. */
+    secret: Uint8Array;
+    /**
+     * The secret encoded as unpadded RFC 4648 base32 — the form authenticator
+     * apps accept for manual entry and the `otpauth://` URI carries.
+     */
+    base32: string;
+}
+/**
+ * Generate a random 160-bit TOTP secret (the RFC 4226 recommended size and
+ * what authenticator apps expect). Store it encrypted at rest — it is a
+ * symmetric key, not a hash: anyone who reads it can mint valid codes.
+ *
+ * @example Enroll a user
+ * ```ts
+ * const { base32 } = generateTotpSecret();
+ * const uri = buildOtpauthUri({
+ *   secret: base32,
+ *   issuer: "Example",
+ *   accountName: "user@example.com",
+ * });
+ * // render `uri` as a QR code; store `base32` encrypted
+ * ```
+ */
+export declare function generateTotpSecret(): GeneratedTotpSecret;
+/** Options for {@link buildOtpauthUri}. */
+export interface OtpauthUriOptions {
+    /** The base32-encoded TOTP secret (from {@link generateTotpSecret}). */
+    secret: string;
+    /** The service name shown in the authenticator app (e.g. `"Udibo"`). */
+    issuer: string;
+    /** The account label shown under the issuer (typically the user's email). */
+    accountName: string;
+    /** Code length. Defaults to `6`. */
+    digits?: number;
+    /** Time-step length in seconds. Defaults to `30`. */
+    periodSeconds?: number;
+    /** HMAC hash. Defaults to `"SHA-1"` (see {@link TotpAlgorithm}). */
+    algorithm?: TotpAlgorithm;
+}
+/**
+ * Build the `otpauth://totp/...` provisioning URI an enrollment screen renders
+ * as a QR code. Follows the de-facto Google Authenticator format: the issuer
+ * appears both as the URI-encoded label prefix (`Issuer:account`) and as the
+ * `issuer` query parameter, so apps that read either convention group the
+ * entry correctly.
+ *
+ * @throws {TypeError} if the secret is not base32 or `digits`/`periodSeconds`
+ * are not positive integers, so a corrupted value cannot inject URI parameters.
+ */
+export declare function buildOtpauthUri(options: OtpauthUriOptions): string;
+/** Options for {@link generateTotpCode}. */
+export interface GenerateTotpCodeOptions {
+    /** The TOTP secret, as base32 or raw key bytes. */
+    secret: string | Uint8Array;
+    /** Epoch milliseconds to generate the code for. Defaults to `Date.now()`. */
+    timestamp?: number;
+    /** Code length. Defaults to `6`. */
+    digits?: number;
+    /** Time-step length in seconds. Defaults to `30`. */
+    periodSeconds?: number;
+    /** HMAC hash. Defaults to `"SHA-1"` (see {@link TotpAlgorithm}). */
+    algorithm?: TotpAlgorithm;
+}
+/**
+ * Compute the TOTP code for a moment in time — what an authenticator app
+ * displays. Exported for tests and for tooling that needs to mint codes (e.g.
+ * an enrollment simulator); server-side verification should go through
+ * {@link verifyTotpCode}, which also handles the clock-skew window and
+ * constant-time comparison.
+ *
+ * @example Mint the current code in a test
+ * ```ts
+ * const code = await generateTotpCode({ secret: base32 });
+ * ```
+ *
+ * @throws {TypeError} if `digits` or `periodSeconds` is not a positive
+ * integer, or the secret is not valid base32.
+ */
+export declare function generateTotpCode(options: GenerateTotpCodeOptions): Promise<string>;
+/** Options for {@link verifyTotpCode}. */
+export interface VerifyTotpCodeOptions {
+    /** The TOTP secret, as base32 or raw key bytes. */
+    secret: string | Uint8Array;
+    /**
+     * The code the user submitted. Whitespace is stripped before checking, so
+     * a code pasted in the spaced groups authenticator apps display verifies.
+     */
+    code: string;
+    /** Epoch milliseconds to verify against. Defaults to `Date.now()`. */
+    timestamp?: number;
+    /**
+     * How many time steps of clock skew to accept on each side of the current
+     * step. Defaults to `1` (accepts the previous, current, and next step —
+     * ±30 seconds at the default period). Keep it small: every extra window
+     * widens the guessing surface.
+     */
+    windows?: number;
+    /** Code length. Defaults to `6`. */
+    digits?: number;
+    /** Time-step length in seconds. Defaults to `30`. */
+    periodSeconds?: number;
+    /** HMAC hash. Defaults to `"SHA-1"` (see {@link TotpAlgorithm}). */
+    algorithm?: TotpAlgorithm;
+}
+/** The outcome of {@link verifyTotpCode}. */
+export type TotpVerification = {
+    valid: false;
+} | {
+    valid: true;
+    /**
+     * The time-step counter the code matched. Persist the highest accepted
+     * step per user and reject codes with `matchedStep <= lastStep` — that is
+     * what makes each code single-use.
+     */
+    matchedStep: number;
+};
+/**
+ * Verify a submitted TOTP code against the secret, accepting `windows` steps
+ * of clock skew on either side. Code comparison is constant-time, and every
+ * candidate step is checked even after a match, so timing does not reveal
+ * which step (if any) matched. When adjacent steps happen to produce the same
+ * code, the newest step wins, so the replay guard below never rejects a fresh
+ * code over a stale tie.
+ *
+ * **Replay protection is the caller's half of the contract:** a valid result
+ * includes `matchedStep`; store the last accepted step and reject any code
+ * whose `matchedStep` is `<=` that value ({@link MfaService} in this module
+ * does this for you). Without it, a code stays valid for the whole skew
+ * window and can be replayed.
+ *
+ * @example Verify with replay rejection
+ * ```ts
+ * const result = await verifyTotpCode({ secret, code });
+ * if (result.valid && result.matchedStep > lastAcceptedStep) {
+ *   lastAcceptedStep = result.matchedStep; // persist atomically
+ *   // accepted
+ * }
+ * ```
+ *
+ * @throws {TypeError} if `digits`/`periodSeconds` is not a positive integer,
+ * `windows` is not a non-negative integer, or the secret is not valid base32.
+ */
+export declare function verifyTotpCode(options: VerifyTotpCodeOptions): Promise<TotpVerification>;