@c9up/warden 0.1.4 → 0.1.5

package/dist/mfa/MfaManager.d.ts

@@ -0,0 +1,107 @@
+/**
+ * MfaManager — orchestrates the stateful "enable 2FA" lifecycle for a user:
+ * TOTP enrollment (pending → confirmed) and single-use backup codes, over a
+ * pluggable factor store (in-memory default).
+ *
+ * OTP (email/SMS) and WebAuthn are NOT folded in here: OTP is ephemeral
+ * (challenge/response, no enrollment) and WebAuthn already persists its own
+ * passkeys in its credential store. Use `OtpProvider` / `WebauthnProvider`
+ * directly for those, alongside this manager.
+ */
+import type { BackupCodesProvider } from "./BackupCodesProvider.js";
+import type { TotpProvider } from "./TotpProvider.js";
+export type MfaFactorKind = "totp" | "backup_codes";
+export interface MfaFactor {
+    id: string;
+    userId: string;
+    kind: MfaFactorKind;
+    label?: string;
+    /** TOTP shared secret (base32), present for `totp` factors. */
+    secret?: string;
+    /** Salted hashes of the remaining backup codes, for `backup_codes` factors. */
+    backupHashes?: string[];
+    /** Epoch ms when the factor became usable; absent while pending. */
+    confirmedAt?: number;
+    createdAt: number;
+}
+/** Public, secret-free view of an enrolled factor. */
+export interface MfaFactorSummary {
+    id: string;
+    kind: MfaFactorKind;
+    label?: string;
+    confirmed: boolean;
+}
+export interface MfaFactorStore {
+    save(factor: MfaFactor): Promise<void>;
+    findById(id: string): Promise<MfaFactor | null>;
+    findByUser(userId: string): Promise<MfaFactor[]>;
+    delete(id: string): Promise<void>;
+}
+export declare class MemoryMfaFactorStore implements MfaFactorStore {
+    #private;
+    save(factor: MfaFactor): Promise<void>;
+    findById(id: string): Promise<MfaFactor | null>;
+    findByUser(userId: string): Promise<MfaFactor[]>;
+    delete(id: string): Promise<void>;
+}
+export interface MfaRateLimitConfig {
+    /** Failed verifications allowed per user before lockout. Default `5`. */
+    maxAttempts?: number;
+    /** Lockout / counter window in seconds. Default `900` (15 min). */
+    windowSeconds?: number;
+}
+export interface MfaManagerConfig {
+    /** App/brand name shown in the authenticator (the TOTP issuer). */
+    issuer: string;
+    totp?: TotpProvider;
+    backupCodes?: BackupCodesProvider;
+    store?: MfaFactorStore;
+    /** Per-user brute-force protection on `verify()`. Defaults to 5 / 15 min. */
+    rateLimit?: MfaRateLimitConfig;
+}
+export declare class MfaManager {
+    #private;
+    constructor(config: MfaManagerConfig);
+    /**
+     * Begin TOTP enrollment: persist a pending factor and return the secret +
+     * `otpauth://` URI to show as a QR code. The factor is unusable until
+     * `confirmTotp()` succeeds.
+     */
+    enrollTotp(user: {
+        id: string;
+        name: string;
+    }, label?: string): Promise<{
+        factorId: string;
+        secret: string;
+        uri: string;
+    }>;
+    /** Confirm a pending TOTP factor by verifying a first code. */
+    confirmTotp(factorId: string, code: string): Promise<boolean>;
+    /** Verify a TOTP code against the user's confirmed authenticator factors. */
+    verifyTotp(userId: string, code: string): Promise<boolean>;
+    /**
+     * Generate (or regenerate) the user's backup codes. Returns the plaintext
+     * codes to display ONCE; only hashes are stored. Any prior backup-code
+     * factor is replaced.
+     */
+    createBackupCodes(userId: string, label?: string): Promise<string[]>;
+    /** Verify and consume one backup code for the user. */
+    verifyBackupCode(userId: string, code: string): Promise<boolean>;
+    /**
+     * Verify a code entered in a single "2FA code" field: tries the user's TOTP
+     * factors first, then falls back to consuming a backup code.
+     */
+    verify(userId: string, code: string): Promise<boolean>;
+    /**
+     * Whether the user is currently locked out of `verify()` after too many
+     * failed attempts. Use it to surface a "try again later" message.
+     */
+    isLocked(userId: string): boolean;
+    /** List the user's factors without exposing any secret material. */
+    listFactors(userId: string): Promise<MfaFactorSummary[]>;
+    /** Whether the user has at least one confirmed factor. */
+    isEnabled(userId: string): Promise<boolean>;
+    /** Remove a factor (e.g. the user disables their authenticator). */
+    disableFactor(factorId: string): Promise<void>;
+}
+//# sourceMappingURL=MfaManager.d.ts.map

package/dist/mfa/MfaManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MfaManager.d.ts","sourceRoot":"","sources":["../../src/mfa/MfaManager.ts"],"names":[],"mappings":"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"}

package/dist/mfa/MfaManager.js

@@ -0,0 +1,219 @@
+/**
+ * MfaManager — orchestrates the stateful "enable 2FA" lifecycle for a user:
+ * TOTP enrollment (pending → confirmed) and single-use backup codes, over a
+ * pluggable factor store (in-memory default).
+ *
+ * OTP (email/SMS) and WebAuthn are NOT folded in here: OTP is ephemeral
+ * (challenge/response, no enrollment) and WebAuthn already persists its own
+ * passkeys in its credential store. Use `OtpProvider` / `WebauthnProvider`
+ * directly for those, alongside this manager.
+ */
+import { randomBytes } from "node:crypto";
+import { WardenError } from "../errors.js";
+export class MemoryMfaFactorStore {
+    #store = new Map();
+    async save(factor) {
+        this.#store.set(factor.id, factor);
+    }
+    async findById(id) {
+        return this.#store.get(id) ?? null;
+    }
+    async findByUser(userId) {
+        return [...this.#store.values()].filter((f) => f.userId === userId);
+    }
+    async delete(id) {
+        this.#store.delete(id);
+    }
+}
+export class MfaManager {
+    #issuer;
+    #totp;
+    #backupCodes;
+    #store;
+    #maxAttempts;
+    #windowMs;
+    #attempts = new Map();
+    constructor(config) {
+        if (!config?.issuer) {
+            throw new WardenError("INVALID_CONFIG", "MfaManager requires an issuer");
+        }
+        this.#issuer = config.issuer;
+        this.#totp = config.totp;
+        this.#backupCodes = config.backupCodes;
+        this.#store = config.store ?? new MemoryMfaFactorStore();
+        this.#maxAttempts = config.rateLimit?.maxAttempts ?? 5;
+        this.#windowMs = (config.rateLimit?.windowSeconds ?? 900) * 1000;
+    }
+    // ── TOTP enrollment ──────────────────────────────────────────────
+    /**
+     * Begin TOTP enrollment: persist a pending factor and return the secret +
+     * `otpauth://` URI to show as a QR code. The factor is unusable until
+     * `confirmTotp()` succeeds.
+     */
+    async enrollTotp(user, label) {
+        const totp = this.#requireTotp();
+        const { secret, uri } = totp.enroll(user.name, this.#issuer);
+        const factor = {
+            id: newId(),
+            userId: user.id,
+            kind: "totp",
+            label,
+            secret,
+            createdAt: Date.now(),
+        };
+        await this.#store.save(factor);
+        return { factorId: factor.id, secret, uri };
+    }
+    /** Confirm a pending TOTP factor by verifying a first code. */
+    async confirmTotp(factorId, code) {
+        const totp = this.#requireTotp();
+        const factor = await this.#store.findById(factorId);
+        if (!factor || factor.kind !== "totp" || !factor.secret) {
+            return false;
+        }
+        if (!totp.verify(factor.secret, code)) {
+            return false;
+        }
+        await this.#store.save({ ...factor, confirmedAt: Date.now() });
+        return true;
+    }
+    /** Verify a TOTP code against the user's confirmed authenticator factors. */
+    async verifyTotp(userId, code) {
+        const totp = this.#requireTotp();
+        const factors = await this.#store.findByUser(userId);
+        return factors.some((f) => f.kind === "totp" &&
+            f.confirmedAt !== undefined &&
+            f.secret !== undefined &&
+            totp.verify(f.secret, code));
+    }
+    // ── Backup codes ─────────────────────────────────────────────────
+    /**
+     * Generate (or regenerate) the user's backup codes. Returns the plaintext
+     * codes to display ONCE; only hashes are stored. Any prior backup-code
+     * factor is replaced.
+     */
+    async createBackupCodes(userId, label) {
+        const provider = this.#requireBackupCodes();
+        const existing = await this.#store.findByUser(userId);
+        for (const f of existing) {
+            if (f.kind === "backup_codes") {
+                await this.#store.delete(f.id);
+            }
+        }
+        const { codes, hashes } = provider.generate();
+        await this.#store.save({
+            id: newId(),
+            userId,
+            kind: "backup_codes",
+            label,
+            backupHashes: hashes,
+            // Backup codes are usable as soon as they are shown.
+            confirmedAt: Date.now(),
+            createdAt: Date.now(),
+        });
+        return codes;
+    }
+    /** Verify and consume one backup code for the user. */
+    async verifyBackupCode(userId, code) {
+        const provider = this.#requireBackupCodes();
+        const factors = await this.#store.findByUser(userId);
+        for (const factor of factors) {
+            if (factor.kind !== "backup_codes" || !factor.backupHashes) {
+                continue;
+            }
+            const result = provider.verify(factor.backupHashes, code);
+            if (result.ok) {
+                await this.#store.save({ ...factor, backupHashes: result.remaining });
+                return true;
+            }
+        }
+        return false;
+    }
+    // ── Unified verify + status ──────────────────────────────────────
+    /**
+     * Verify a code entered in a single "2FA code" field: tries the user's TOTP
+     * factors first, then falls back to consuming a backup code.
+     */
+    async verify(userId, code) {
+        if (this.#isLocked(userId)) {
+            return false;
+        }
+        let ok = false;
+        if (this.#totp && (await this.verifyTotp(userId, code))) {
+            ok = true;
+        }
+        else if (this.#backupCodes &&
+            (await this.verifyBackupCode(userId, code))) {
+            ok = true;
+        }
+        if (ok) {
+            this.#attempts.delete(userId);
+        }
+        else {
+            this.#recordFailure(userId);
+        }
+        return ok;
+    }
+    /**
+     * Whether the user is currently locked out of `verify()` after too many
+     * failed attempts. Use it to surface a "try again later" message.
+     */
+    isLocked(userId) {
+        return this.#isLocked(userId);
+    }
+    /** List the user's factors without exposing any secret material. */
+    async listFactors(userId) {
+        const factors = await this.#store.findByUser(userId);
+        return factors.map((f) => ({
+            id: f.id,
+            kind: f.kind,
+            label: f.label,
+            confirmed: f.confirmedAt !== undefined,
+        }));
+    }
+    /** Whether the user has at least one confirmed factor. */
+    async isEnabled(userId) {
+        const factors = await this.#store.findByUser(userId);
+        return factors.some((f) => f.confirmedAt !== undefined);
+    }
+    /** Remove a factor (e.g. the user disables their authenticator). */
+    async disableFactor(factorId) {
+        await this.#store.delete(factorId);
+    }
+    #isLocked(userId) {
+        const entry = this.#attempts.get(userId);
+        if (!entry) {
+            return false;
+        }
+        if (entry.resetAt < Date.now()) {
+            this.#attempts.delete(userId);
+            return false;
+        }
+        return entry.count >= this.#maxAttempts;
+    }
+    #recordFailure(userId) {
+        const now = Date.now();
+        let entry = this.#attempts.get(userId);
+        if (!entry || entry.resetAt < now) {
+            entry = { count: 0, resetAt: now + this.#windowMs };
+            this.#attempts.set(userId, entry);
+        }
+        entry.count++;
+    }
+    #requireTotp() {
+        if (!this.#totp) {
+            throw new WardenError("INVALID_CONFIG", "MfaManager has no TotpProvider configured");
+        }
+        return this.#totp;
+    }
+    #requireBackupCodes() {
+        if (!this.#backupCodes) {
+            throw new WardenError("INVALID_CONFIG", "MfaManager has no BackupCodesProvider configured");
+        }
+        return this.#backupCodes;
+    }
+}
+function newId() {
+    return randomBytes(16).toString("hex");
+}
+//# sourceMappingURL=MfaManager.js.map

package/dist/mfa/MfaManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MfaManager.js","sourceRoot":"","sources":["../../src/mfa/MfaManager.ts"],"names":[],"mappings":"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"}

package/dist/mfa/OtpProvider.d.ts

@@ -0,0 +1,67 @@
+/**
+ * OtpProvider — delivered one-time passcodes (email / SMS). Unlike TOTP this is
+ * a challenge/response flow: `start()` mints a code, persists it (hashed, with
+ * an expiry and an attempt budget) and hands it to a delivery channel; the user
+ * later submits it to `verify()`.
+ *
+ * Delivery is pluggable — the app supplies an email or SMS channel. The store
+ * is pluggable too, with an in-memory default mirroring the rest of warden.
+ */
+/** Sends the code to the user. Implemented by the consuming app (email/SMS). */
+export interface OtpDeliveryChannel {
+    send(recipient: string, code: string): Promise<void>;
+}
+/** A persisted, pending OTP challenge. */
+export interface OtpChallenge {
+    id: string;
+    recipient: string;
+    /** Salted hash of the code — never the plaintext. */
+    hash: string;
+    expiresAt: number;
+    attempts: number;
+}
+/** Storage for pending challenges. */
+export interface OtpChallengeStore {
+    save(challenge: OtpChallenge): Promise<void>;
+    find(id: string): Promise<OtpChallenge | null>;
+    delete(id: string): Promise<void>;
+}
+export declare class MemoryOtpChallengeStore implements OtpChallengeStore {
+    #private;
+    save(c: OtpChallenge): Promise<void>;
+    find(id: string): Promise<OtpChallenge | null>;
+    delete(id: string): Promise<void>;
+}
+export interface OtpConfig {
+    channel: OtpDeliveryChannel;
+    /** Where pending challenges live. Default in-memory. */
+    store?: OtpChallengeStore;
+    /** Number of digits in the code. Default `6`. */
+    digits?: number;
+    /** How long a code stays valid, in seconds. Default `300` (5 min). */
+    ttlSeconds?: number;
+    /** Max verification attempts before the challenge is burned. Default `5`. */
+    maxAttempts?: number;
+}
+export interface OtpStartResult {
+    challengeId: string;
+    expiresAt: number;
+}
+export type OtpFailureReason = "not_found" | "expired" | "too_many_attempts" | "mismatch";
+export interface OtpVerification {
+    ok: boolean;
+    reason?: OtpFailureReason;
+}
+export declare class OtpProvider {
+    #private;
+    readonly kind: "otp";
+    constructor(config: OtpConfig);
+    /** Mint a code, persist the challenge, and deliver it to `recipient`. */
+    start(recipient: string, nowMs?: number): Promise<OtpStartResult>;
+    /**
+     * Verify a submitted code. Wrong codes consume an attempt; the challenge is
+     * deleted on success, on expiry, or once the attempt budget is exhausted.
+     */
+    verify(challengeId: string, code: string, nowMs?: number): Promise<OtpVerification>;
+}
+//# sourceMappingURL=OtpProvider.d.ts.map

package/dist/mfa/OtpProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OtpProvider.d.ts","sourceRoot":"","sources":["../../src/mfa/OtpProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IAClC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IACjC,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,qBAAa,uBAAwB,YAAW,iBAAiB;;IAE1D,IAAI,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAGpC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAG9C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGvC;AAED,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,wDAAwD;IACxD,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,gBAAgB,GACzB,WAAW,GACX,SAAS,GACT,mBAAmB,GACnB,UAAU,CAAC;AAEd,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED,qBAAa,WAAW;;IACvB,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;gBAOnB,MAAM,EAAE,SAAS;IAc7B,yEAAyE;IACnE,KAAK,CACV,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,MAAmB,GACxB,OAAO,CAAC,cAAc,CAAC;IAe1B;;;OAGG;IACG,MAAM,CACX,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAmB,GACxB,OAAO,CAAC,eAAe,CAAC;CA0B3B"}

package/dist/mfa/OtpProvider.js

@@ -0,0 +1,104 @@
+/**
+ * OtpProvider — delivered one-time passcodes (email / SMS). Unlike TOTP this is
+ * a challenge/response flow: `start()` mints a code, persists it (hashed, with
+ * an expiry and an attempt budget) and hands it to a delivery channel; the user
+ * later submits it to `verify()`.
+ *
+ * Delivery is pluggable — the app supplies an email or SMS channel. The store
+ * is pluggable too, with an in-memory default mirroring the rest of warden.
+ */
+import { createHash, randomBytes, randomInt, timingSafeEqual, } from "node:crypto";
+import { WardenError } from "../errors.js";
+export class MemoryOtpChallengeStore {
+    #store = new Map();
+    async save(c) {
+        this.#store.set(c.id, c);
+    }
+    async find(id) {
+        return this.#store.get(id) ?? null;
+    }
+    async delete(id) {
+        this.#store.delete(id);
+    }
+}
+export class OtpProvider {
+    kind = "otp";
+    #channel;
+    #store;
+    #digits;
+    #ttlMs;
+    #maxAttempts;
+    constructor(config) {
+        if (!config?.channel) {
+            throw new WardenError("INVALID_CONFIG", "OtpProvider requires a delivery channel (email/SMS)");
+        }
+        this.#channel = config.channel;
+        this.#store = config.store ?? new MemoryOtpChallengeStore();
+        this.#digits = config.digits ?? 6;
+        this.#ttlMs = (config.ttlSeconds ?? 300) * 1000;
+        this.#maxAttempts = config.maxAttempts ?? 5;
+    }
+    /** Mint a code, persist the challenge, and deliver it to `recipient`. */
+    async start(recipient, nowMs = Date.now()) {
+        const code = this.#randomCode();
+        const id = randomBytes(16).toString("hex");
+        const expiresAt = nowMs + this.#ttlMs;
+        await this.#store.save({
+            id,
+            recipient,
+            hash: saltedHash(code),
+            expiresAt,
+            attempts: 0,
+        });
+        await this.#channel.send(recipient, code);
+        return { challengeId: id, expiresAt };
+    }
+    /**
+     * Verify a submitted code. Wrong codes consume an attempt; the challenge is
+     * deleted on success, on expiry, or once the attempt budget is exhausted.
+     */
+    async verify(challengeId, code, nowMs = Date.now()) {
+        const challenge = await this.#store.find(challengeId);
+        if (!challenge) {
+            return { ok: false, reason: "not_found" };
+        }
+        if (nowMs > challenge.expiresAt) {
+            await this.#store.delete(challengeId);
+            return { ok: false, reason: "expired" };
+        }
+        if (matchesStored(challenge.hash, code.replace(/\s/g, ""))) {
+            await this.#store.delete(challengeId);
+            return { ok: true };
+        }
+        const attempts = challenge.attempts + 1;
+        if (attempts >= this.#maxAttempts) {
+            await this.#store.delete(challengeId);
+            return { ok: false, reason: "too_many_attempts" };
+        }
+        await this.#store.save({ ...challenge, attempts });
+        return { ok: false, reason: "mismatch" };
+    }
+    #randomCode() {
+        const max = 10 ** this.#digits;
+        return randomInt(0, max).toString().padStart(this.#digits, "0");
+    }
+}
+function saltedHash(code) {
+    const salt = randomBytes(8);
+    const digest = createHash("sha256").update(salt).update(code).digest();
+    return `${salt.toString("hex")}$${digest.toString("hex")}`;
+}
+function matchesStored(stored, candidate) {
+    const sep = stored.indexOf("$");
+    if (sep === -1) {
+        return false;
+    }
+    const salt = Buffer.from(stored.slice(0, sep), "hex");
+    const expected = Buffer.from(stored.slice(sep + 1), "hex");
+    const actual = createHash("sha256").update(salt).update(candidate).digest();
+    if (actual.length !== expected.length) {
+        return false;
+    }
+    return timingSafeEqual(actual, expected);
+}
+//# sourceMappingURL=OtpProvider.js.map

package/dist/mfa/OtpProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OtpProvider.js","sourceRoot":"","sources":["../../src/mfa/OtpProvider.ts"],"names":[],"mappings":"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"}

package/dist/mfa/TotpProvider.d.ts

@@ -0,0 +1,52 @@
+/**
+ * TotpProvider — RFC 6238 time-based one-time passwords (HOTP/RFC 4226 under
+ * the hood). Pure TypeScript on Node's `crypto.createHmac` — no native binding
+ * and no third-party dependency: a TOTP is a single HMAC, not CPU-bound work.
+ *
+ * Compatible with Google Authenticator / 1Password / Authy by default
+ * (SHA1, 6 digits, 30s period).
+ */
+export type TotpAlgorithm = "SHA1" | "SHA256" | "SHA512";
+export interface TotpConfig {
+    /** HMAC algorithm. Default `SHA1` (authenticator-app compatible). */
+    algorithm?: TotpAlgorithm;
+    /** Number of digits in the generated code. Default `6`. */
+    digits?: number;
+    /** Time step in seconds. Default `30`. */
+    period?: number;
+    /**
+     * How many time steps before/after `now` are accepted on `verify`, to
+     * tolerate clock skew. Default `1` (i.e. ±30s with the default period).
+     */
+    window?: number;
+}
+export interface TotpEnrollment {
+    /** Base32 secret to persist against the user. */
+    secret: string;
+    /** `otpauth://` URI to render as a QR code during enrollment. */
+    uri: string;
+}
+export declare class TotpProvider {
+    #private;
+    readonly kind: "totp";
+    constructor(config?: TotpConfig);
+    /**
+     * Generate a fresh secret and the `otpauth://` provisioning URI. Persist
+     * `secret`; render `uri` as a QR code for the user to scan.
+     *
+     * @param account  Identifies the account in the authenticator (usually the
+     *                 user's email or username).
+     * @param issuer   Your app/brand name, shown as the entry label.
+     */
+    enroll(account: string, issuer: string): TotpEnrollment;
+    /** Build the `otpauth://totp/...` provisioning URI for an existing secret. */
+    uri(secret: string, account: string, issuer: string): string;
+    /** Generate the code for a given secret at a given time (ms since epoch). */
+    generate(secret: string, atMs?: number): string;
+    /**
+     * Verify a user-supplied code against the secret, accepting codes from the
+     * surrounding `window` time steps to tolerate clock skew. Constant-time.
+     */
+    verify(secret: string, code: string, atMs?: number): boolean;
+}
+//# sourceMappingURL=TotpProvider.d.ts.map

package/dist/mfa/TotpProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TotpProvider.d.ts","sourceRoot":"","sources":["../../src/mfa/TotpProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEzD,MAAM,WAAW,UAAU;IAC1B,qEAAqE;IACrE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC9B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;CACZ;AASD,qBAAa,YAAY;;IACxB,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;gBAGpB,MAAM,GAAE,UAAe;IAUnC;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc;IAKvD,8EAA8E;IAC9E,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAY5D,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,MAAmB,GAAG,MAAM;IAK3D;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAmB,GAAG,OAAO;CAoCxE"}