@nage-api/auth 1.0.0-beta.2

package/dist/jwt.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Access-token signing and verification (PLAN.md §12, §15.1).
+ *
+ * RS256 by default: verifiers hold only the public key, so a compromised API
+ * gateway or a downstream service cannot mint tokens. `jose` does the crypto;
+ * this file is about the parts that get security reviews wrong — that the
+ * algorithm is pinned rather than read from the token header, that issuer and
+ * audience are actually checked, and that a verification failure is mapped to a
+ * typed error instead of leaking a library message to the caller.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JoseTokenSigner = void 0;
+exports.buildClaims = buildClaims;
+exports.parseClaims = parseClaims;
+exports.actorId = actorId;
+const node_crypto_1 = require("node:crypto");
+const jose_1 = require("jose");
+const core_1 = require("@nage-api/core");
+class JoseTokenSigner {
+    #config;
+    #signingKey;
+    #verificationKey;
+    constructor(options) {
+        const { config } = options;
+        this.#config = config;
+        if (options.privateKey.trim() === '') {
+            throw new core_1.ConfigurationError({
+                detail: 'A JWT signing key is required; set JWT_PRIVATE_KEY',
+                meta: { setting: 'auth.jwt.privateKey' },
+            });
+        }
+        if (config.jwt.algorithm === 'HS256') {
+            const secret = (0, node_crypto_1.createSecretKey)(Buffer.from(options.privateKey, 'utf8'));
+            this.#signingKey = secret;
+            this.#verificationKey = secret;
+            return;
+        }
+        if (options.publicKey === undefined || options.publicKey.trim() === '') {
+            // Deriving the public key from the private one would work, but requiring
+            // it makes the deployment state what verifiers are expected to hold.
+            throw new core_1.ConfigurationError({
+                detail: `A public key is required to verify ${config.jwt.algorithm} tokens; set JWT_PUBLIC_KEY`,
+                meta: { setting: 'auth.jwt.publicKey', algorithm: config.jwt.algorithm },
+            });
+        }
+        try {
+            this.#signingKey = (0, node_crypto_1.createPrivateKey)(options.privateKey);
+            this.#verificationKey = (0, node_crypto_1.createPublicKey)(options.publicKey);
+        }
+        catch (error) {
+            throw new core_1.ConfigurationError({
+                detail: 'The configured JWT key pair could not be parsed; expected PEM encoding',
+                cause: error,
+                meta: { setting: 'auth.jwt', algorithm: config.jwt.algorithm },
+            });
+        }
+    }
+    async sign(claims, options) {
+        const issuedAt = Math.floor(Date.now() / 1000);
+        const header = { alg: this.#config.jwt.algorithm };
+        if (this.#config.jwt.keyId !== undefined)
+            header.kid = this.#config.jwt.keyId;
+        return new jose_1.SignJWT(claims)
+            .setProtectedHeader(header)
+            .setIssuedAt(issuedAt)
+            .setExpirationTime(issuedAt + options.expiresInSeconds)
+            .setIssuer(this.#config.jwt.issuer)
+            .setAudience(audienceFor(this.#config.jwt.audience))
+            .sign(this.#signingKey);
+    }
+    async verify(token) {
+        try {
+            const { payload } = await (0, jose_1.jwtVerify)(token, this.#verificationKey, {
+                // Pinned: without this, `jose` would accept whatever the token's own
+                // header asks for, which is how algorithm-confusion attacks work.
+                algorithms: [this.#config.jwt.algorithm],
+                issuer: this.#config.jwt.issuer,
+                audience: audienceFor(this.#config.jwt.audience),
+                clockTolerance: this.#config.jwt.clockToleranceSeconds,
+            });
+            return payload;
+        }
+        catch (error) {
+            // Expiry is worth distinguishing — a client should refresh rather than
+            // send the user back to a login form.
+            const expired = error instanceof Error &&
+                (error.name === 'JWTExpired' ||
+                    error.message.includes('"exp" claim timestamp check failed'));
+            throw new core_1.AuthenticationError(expired ? 'AUTH_TOKEN_EXPIRED' : 'AUTH_TOKEN_INVALID', {
+                detail: `Access token rejected: ${error instanceof Error ? error.message : String(error)}`,
+                cause: error,
+            });
+        }
+    }
+}
+exports.JoseTokenSigner = JoseTokenSigner;
+/** The claim set, kept in one place so signing and parsing cannot disagree. */
+function buildClaims(input) {
+    return {
+        sub: input.userId,
+        sid: input.sessionId,
+        roles: input.roles,
+        permissions: input.permissions,
+        ...(input.tenantId === undefined ? {} : { tenantId: input.tenantId }),
+        ...(input.impersonatedBy === undefined ? {} : { act: { sub: input.impersonatedBy } }),
+    };
+}
+/**
+ * Read a verified payload back into typed claims.
+ *
+ * The payload is verified but still **untrusted in shape**: a token minted by
+ * an older version of this service, or by a deliberately odd one, can carry a
+ * `roles` that is not an array. Anything malformed is dropped rather than cast.
+ */
+function parseClaims(payload) {
+    const subject = payload['sub'];
+    const sessionId = payload['sid'];
+    if (typeof subject !== 'string' || typeof sessionId !== 'string') {
+        throw new core_1.AuthenticationError('AUTH_TOKEN_INVALID', {
+            detail: 'Access token is missing its sub or sid claim',
+        });
+    }
+    return {
+        sub: subject,
+        sid: sessionId,
+        iss: typeof payload['iss'] === 'string' ? payload['iss'] : '',
+        aud: readAudience(payload['aud']),
+        iat: typeof payload['iat'] === 'number' ? payload['iat'] : 0,
+        exp: typeof payload['exp'] === 'number' ? payload['exp'] : 0,
+        roles: stringArray(payload['roles']),
+        permissions: stringArray(payload['permissions']),
+        ...(typeof payload['tenantId'] === 'string' ? { tenantId: payload['tenantId'] } : {}),
+    };
+}
+/** The impersonator's id, when the token carries an `act` claim (RFC 8693). */
+function actorId(payload) {
+    const actor = payload['act'];
+    if (typeof actor !== 'object' || actor === null)
+        return undefined;
+    const subject = actor['sub'];
+    return typeof subject === 'string' ? subject : undefined;
+}
+/**
+ * `jose` takes a mutable array; the config holds a readonly one. A single
+ * audience stays a bare string, which is the conventional encoding and what
+ * other verifiers expect to see on the wire.
+ */
+function audienceFor(audience) {
+    return typeof audience === 'string' ? audience : [...audience];
+}
+/** `aud` is a string or an array of them, per RFC 7519. */
+function readAudience(value) {
+    if (typeof value === 'string')
+        return value;
+    return stringArray(value);
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === 'string')
+        : [];
+}
+//# sourceMappingURL=jwt.js.map

package/dist/lockout.service.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Failed-attempt lockout (PLAN.md §15.1).
+ *
+ * Distinct from the global rate limit in `@nage-api/core`: that one bounds request
+ * volume, this one bounds *guesses against a specific account*. An attacker
+ * spreading a credential-stuffing run across a botnet stays under any per-IP
+ * limit while hammering one mailbox, so the counter is keyed by identity as
+ * well as by address.
+ *
+ * A lockout is temporary by design. Permanent lockout on failed passwords hands
+ * anyone who knows an email address a denial-of-service button.
+ */
+import type { AuthAuditSink, Clock, LockoutStore } from './ports.js';
+import type { ResolvedAuthConfig } from './config.js';
+export interface LockoutServiceOptions {
+    readonly store: LockoutStore;
+    readonly config: ResolvedAuthConfig['lockout'];
+    readonly clock?: Clock;
+    readonly audit?: AuthAuditSink;
+}
+export interface LockoutStatus {
+    readonly locked: boolean;
+    readonly failures: number;
+    readonly retryAfterSeconds?: number;
+}
+export declare class LockoutService {
+    #private;
+    constructor(options: LockoutServiceOptions);
+    /** Compose a key; callers should include both the identity and the source. */
+    static key(scope: string, ...parts: readonly (string | undefined)[]): string;
+    status(key: string): Promise<LockoutStatus>;
+    /** Throw if the key is locked. Call **before** verifying a credential. */
+    assertNotLocked(key: string): Promise<void>;
+    /**
+     * Count a failure and lock once the threshold is crossed.
+     *
+     * @returns the status after recording, so the caller can audit a fresh lock.
+     */
+    recordFailure(key: string, meta?: Readonly<Record<string, unknown>>): Promise<LockoutStatus>;
+    /** Clear the counter after a success. */
+    recordSuccess(key: string): Promise<void>;
+}
+//# sourceMappingURL=lockout.service.d.ts.map

package/dist/lockout.service.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Failed-attempt lockout (PLAN.md §15.1).
+ *
+ * Distinct from the global rate limit in `@nage-api/core`: that one bounds request
+ * volume, this one bounds *guesses against a specific account*. An attacker
+ * spreading a credential-stuffing run across a botnet stays under any per-IP
+ * limit while hammering one mailbox, so the counter is keyed by identity as
+ * well as by address.
+ *
+ * A lockout is temporary by design. Permanent lockout on failed passwords hands
+ * anyone who knows an email address a denial-of-service button.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LockoutService = void 0;
+const core_1 = require("@nage-api/core");
+class LockoutService {
+    #store;
+    #config;
+    #clock;
+    #audit;
+    constructor(options) {
+        this.#store = options.store;
+        this.#config = options.config;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+        this.#audit = options.audit;
+    }
+    /** Compose a key; callers should include both the identity and the source. */
+    static key(scope, ...parts) {
+        return [scope, ...parts.filter((part) => part !== undefined && part !== '')].join(':');
+    }
+    async status(key) {
+        const record = await this.#store.get(key);
+        if (record === undefined)
+            return { locked: false, failures: 0 };
+        const now = this.#clock.now();
+        if (record.lockedUntil !== undefined && record.lockedUntil > now) {
+            return {
+                locked: true,
+                failures: record.failures,
+                retryAfterSeconds: Math.ceil((record.lockedUntil - now) / 1000),
+            };
+        }
+        // The counting window has passed with no lock: the slate is clean.
+        if (now - record.firstFailureAt > this.#config.windowSeconds * 1000) {
+            return { locked: false, failures: 0 };
+        }
+        return { locked: false, failures: record.failures };
+    }
+    /** Throw if the key is locked. Call **before** verifying a credential. */
+    async assertNotLocked(key) {
+        const status = await this.status(key);
+        if (!status.locked)
+            return;
+        throw new core_1.AuthenticationError('AUTH_ACCOUNT_LOCKED', {
+            detail: `${key} is locked for another ${String(status.retryAfterSeconds ?? 0)}s after ${String(status.failures)} failed attempts`,
+            meta: { retryAfterSeconds: status.retryAfterSeconds, failures: status.failures },
+        });
+    }
+    /**
+     * Count a failure and lock once the threshold is crossed.
+     *
+     * @returns the status after recording, so the caller can audit a fresh lock.
+     */
+    async recordFailure(key, meta = {}) {
+        const now = this.#clock.now();
+        const existing = await this.#store.get(key);
+        const withinWindow = existing !== undefined && now - existing.firstFailureAt <= this.#config.windowSeconds * 1000;
+        const failures = (withinWindow ? existing.failures : 0) + 1;
+        const firstFailureAt = withinWindow ? existing.firstFailureAt : now;
+        const locked = failures >= this.#config.maxAttempts;
+        const lockedUntil = locked ? now + this.#config.durationSeconds * 1000 : undefined;
+        await this.#store.set({
+            key,
+            failures,
+            firstFailureAt,
+            ...(lockedUntil === undefined ? {} : { lockedUntil }),
+        });
+        if (locked) {
+            await this.#audit?.record({ name: 'login.locked', at: now, meta: { ...meta, failures } });
+        }
+        return {
+            locked,
+            failures,
+            ...(lockedUntil === undefined ? {} : { retryAfterSeconds: this.#config.durationSeconds }),
+        };
+    }
+    /** Clear the counter after a success. */
+    async recordSuccess(key) {
+        await this.#store.clear(key);
+    }
+}
+exports.LockoutService = LockoutService;
+//# sourceMappingURL=lockout.service.js.map

package/dist/memory-stores.d.ts

@@ -0,0 +1,84 @@
+/**
+ * In-memory reference implementations of the auth ports (PLAN.md §19).
+ *
+ * Not mocks — real implementations with the same semantics, which is what makes
+ * them useful. Every rule the guards depend on (a rotated session stays
+ * rotated, revoking a family revokes siblings, an OTP is consumed once) is
+ * enforced here, so a test that passes against these is exercising the service
+ * logic rather than a stub that agrees with it.
+ *
+ * They are also the ports' executable specification: a SQL-backed
+ * `SessionStore` should behave exactly like `MemorySessionStore`.
+ */
+import type { Id, SessionRecord } from '@nage-api/contracts';
+import type { ApiKeyRecord, ApiKeyStore, AuthAuditSink, AuthEvent, AuthUserRecord, AuthUserStore, LockoutRecord, LockoutStore, OtpChannel, OtpPurpose, OtpRecord, OtpStore, SessionStore } from './ports.js';
+export declare class MemoryAuthUserStore implements AuthUserStore {
+    #private;
+    constructor(users?: readonly AuthUserRecord[]);
+    add(user: AuthUserRecord): this;
+    findById(id: Id): Promise<AuthUserRecord | undefined>;
+    findByEmail(email: string): Promise<AuthUserRecord | undefined>;
+    setPasswordHash(id: Id, hash: string): Promise<void>;
+}
+export declare class MemorySessionStore implements SessionStore {
+    #private;
+    create(session: SessionRecord): Promise<void>;
+    findByHashedToken(hashedToken: string): Promise<SessionRecord | undefined>;
+    markRotated(id: string, rotatedAt: number): Promise<void>;
+    revoke(id: string, revokedAt: number): Promise<void>;
+    revokeFamily(familyId: string, revokedAt: number): Promise<number>;
+    isFamilyRevoked(familyId: string): Promise<boolean>;
+    revokeAllForUser(userId: Id, revokedAt: number): Promise<number>;
+    deleteExpired(now: number): Promise<number>;
+    /** Test helper: every stored session, in insertion order. */
+    get all(): readonly SessionRecord[];
+}
+export declare class MemoryOtpStore implements OtpStore {
+    #private;
+    create(record: OtpRecord): Promise<void>;
+    findActive(subject: string, purpose: OtpPurpose): Promise<OtpRecord | undefined>;
+    recordAttempt(id: string, attempts: number): Promise<void>;
+    consume(id: string, consumedAt: number): Promise<void>;
+    invalidate(subject: string, purpose: OtpPurpose): Promise<number>;
+    get all(): readonly OtpRecord[];
+}
+export declare class MemoryApiKeyStore implements ApiKeyStore {
+    #private;
+    create(record: ApiKeyRecord): Promise<void>;
+    findByPrefix(prefix: string): Promise<ApiKeyRecord | undefined>;
+    touch(id: string, usedAt: number): Promise<void>;
+    revoke(id: string, revokedAt: number): Promise<void>;
+}
+export declare class MemoryLockoutStore implements LockoutStore {
+    #private;
+    get(key: string): Promise<LockoutRecord | undefined>;
+    set(record: LockoutRecord): Promise<void>;
+    clear(key: string): Promise<void>;
+}
+/**
+ * Collects the codes that would have been sent.
+ *
+ * The default channel in tests and in `nage create` output, so a developer can
+ * exercise the OTP flow before any email provider exists.
+ */
+export declare class MemoryOtpChannel implements OtpChannel {
+    readonly sent: {
+        subject: string;
+        code: string;
+        purpose: OtpPurpose;
+    }[];
+    send(input: {
+        subject: string;
+        code: string;
+        purpose: OtpPurpose;
+    }): Promise<void>;
+    /** The most recent code for a subject, which is what a test wants to assert. */
+    latest(subject: string): string | undefined;
+}
+/** Keeps auth events in memory so tests can assert on what was recorded. */
+export declare class MemoryAuthAuditSink implements AuthAuditSink {
+    readonly events: AuthEvent[];
+    record(event: AuthEvent): void;
+    names(): readonly string[];
+}
+//# sourceMappingURL=memory-stores.d.ts.map

package/dist/memory-stores.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * In-memory reference implementations of the auth ports (PLAN.md §19).
+ *
+ * Not mocks — real implementations with the same semantics, which is what makes
+ * them useful. Every rule the guards depend on (a rotated session stays
+ * rotated, revoking a family revokes siblings, an OTP is consumed once) is
+ * enforced here, so a test that passes against these is exercising the service
+ * logic rather than a stub that agrees with it.
+ *
+ * They are also the ports' executable specification: a SQL-backed
+ * `SessionStore` should behave exactly like `MemorySessionStore`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryAuthAuditSink = exports.MemoryOtpChannel = exports.MemoryLockoutStore = exports.MemoryApiKeyStore = exports.MemoryOtpStore = exports.MemorySessionStore = exports.MemoryAuthUserStore = void 0;
+class MemoryAuthUserStore {
+    #byId = new Map();
+    constructor(users = []) {
+        for (const user of users)
+            this.add(user);
+    }
+    add(user) {
+        this.#byId.set(String(user.id), user);
+        return this;
+    }
+    async findById(id) {
+        await Promise.resolve();
+        return this.#byId.get(String(id));
+    }
+    async findByEmail(email) {
+        await Promise.resolve();
+        const wanted = email.trim().toLowerCase();
+        for (const user of this.#byId.values()) {
+            if (user.email.toLowerCase() === wanted)
+                return user;
+        }
+        return undefined;
+    }
+    async setPasswordHash(id, hash) {
+        await Promise.resolve();
+        const user = this.#byId.get(String(id));
+        if (user !== undefined)
+            this.#byId.set(String(id), { ...user, passwordHash: hash });
+    }
+}
+exports.MemoryAuthUserStore = MemoryAuthUserStore;
+class MemorySessionStore {
+    #byId = new Map();
+    #byHash = new Map();
+    async create(session) {
+        await Promise.resolve();
+        this.#byId.set(session.id, session);
+        this.#byHash.set(session.hashedToken, session.id);
+    }
+    async findByHashedToken(hashedToken) {
+        await Promise.resolve();
+        const id = this.#byHash.get(hashedToken);
+        return id === undefined ? undefined : this.#byId.get(id);
+    }
+    async markRotated(id, rotatedAt) {
+        await Promise.resolve();
+        const session = this.#byId.get(id);
+        if (session !== undefined)
+            this.#byId.set(id, { ...session, rotatedAt });
+    }
+    async revoke(id, revokedAt) {
+        await Promise.resolve();
+        const session = this.#byId.get(id);
+        if (session !== undefined)
+            this.#byId.set(id, { ...session, revokedAt });
+    }
+    async revokeFamily(familyId, revokedAt) {
+        await Promise.resolve();
+        let revoked = 0;
+        for (const [id, session] of this.#byId) {
+            if (session.familyId !== familyId || session.revokedAt !== undefined)
+                continue;
+            this.#byId.set(id, { ...session, revokedAt });
+            revoked += 1;
+        }
+        return revoked;
+    }
+    async isFamilyRevoked(familyId) {
+        await Promise.resolve();
+        for (const session of this.#byId.values()) {
+            if (session.familyId === familyId && session.revokedAt !== undefined)
+                return true;
+        }
+        return false;
+    }
+    async revokeAllForUser(userId, revokedAt) {
+        await Promise.resolve();
+        let revoked = 0;
+        for (const [id, session] of this.#byId) {
+            if (String(session.userId) !== String(userId) || session.revokedAt !== undefined)
+                continue;
+            this.#byId.set(id, { ...session, revokedAt });
+            revoked += 1;
+        }
+        return revoked;
+    }
+    async deleteExpired(now) {
+        await Promise.resolve();
+        let deleted = 0;
+        for (const [id, session] of this.#byId) {
+            if (session.expiresAt > now)
+                continue;
+            this.#byId.delete(id);
+            this.#byHash.delete(session.hashedToken);
+            deleted += 1;
+        }
+        return deleted;
+    }
+    /** Test helper: every stored session, in insertion order. */
+    get all() {
+        return [...this.#byId.values()];
+    }
+}
+exports.MemorySessionStore = MemorySessionStore;
+class MemoryOtpStore {
+    #records = new Map();
+    async create(record) {
+        await Promise.resolve();
+        this.#records.set(record.id, record);
+    }
+    async findActive(subject, purpose) {
+        await Promise.resolve();
+        let newest;
+        for (const record of this.#records.values()) {
+            if (record.subject !== subject || record.purpose !== purpose)
+                continue;
+            if (record.consumedAt !== undefined)
+                continue;
+            if (newest === undefined || record.issuedAt > newest.issuedAt)
+                newest = record;
+        }
+        return newest;
+    }
+    async recordAttempt(id, attempts) {
+        await Promise.resolve();
+        const record = this.#records.get(id);
+        if (record !== undefined)
+            this.#records.set(id, { ...record, attempts });
+    }
+    async consume(id, consumedAt) {
+        await Promise.resolve();
+        const record = this.#records.get(id);
+        if (record !== undefined)
+            this.#records.set(id, { ...record, consumedAt });
+    }
+    async invalidate(subject, purpose) {
+        await Promise.resolve();
+        let invalidated = 0;
+        for (const [id, record] of this.#records) {
+            if (record.subject !== subject || record.purpose !== purpose)
+                continue;
+            if (record.consumedAt !== undefined)
+                continue;
+            this.#records.set(id, { ...record, consumedAt: record.issuedAt });
+            invalidated += 1;
+        }
+        return invalidated;
+    }
+    get all() {
+        return [...this.#records.values()];
+    }
+}
+exports.MemoryOtpStore = MemoryOtpStore;
+class MemoryApiKeyStore {
+    #byId = new Map();
+    async create(record) {
+        await Promise.resolve();
+        this.#byId.set(record.id, record);
+    }
+    async findByPrefix(prefix) {
+        await Promise.resolve();
+        for (const record of this.#byId.values()) {
+            if (record.prefix === prefix)
+                return record;
+        }
+        return undefined;
+    }
+    async touch(id, usedAt) {
+        await Promise.resolve();
+        const record = this.#byId.get(id);
+        if (record !== undefined)
+            this.#byId.set(id, { ...record, lastUsedAt: usedAt });
+    }
+    async revoke(id, revokedAt) {
+        await Promise.resolve();
+        const record = this.#byId.get(id);
+        if (record !== undefined)
+            this.#byId.set(id, { ...record, revokedAt });
+    }
+}
+exports.MemoryApiKeyStore = MemoryApiKeyStore;
+class MemoryLockoutStore {
+    #records = new Map();
+    async get(key) {
+        await Promise.resolve();
+        return this.#records.get(key);
+    }
+    async set(record) {
+        await Promise.resolve();
+        this.#records.set(record.key, record);
+    }
+    async clear(key) {
+        await Promise.resolve();
+        this.#records.delete(key);
+    }
+}
+exports.MemoryLockoutStore = MemoryLockoutStore;
+/**
+ * Collects the codes that would have been sent.
+ *
+ * The default channel in tests and in `nage create` output, so a developer can
+ * exercise the OTP flow before any email provider exists.
+ */
+class MemoryOtpChannel {
+    sent = [];
+    async send(input) {
+        await Promise.resolve();
+        this.sent.push(input);
+    }
+    /** The most recent code for a subject, which is what a test wants to assert. */
+    latest(subject) {
+        for (let index = this.sent.length - 1; index >= 0; index -= 1) {
+            if (this.sent[index]?.subject === subject)
+                return this.sent[index]?.code;
+        }
+        return undefined;
+    }
+}
+exports.MemoryOtpChannel = MemoryOtpChannel;
+/** Keeps auth events in memory so tests can assert on what was recorded. */
+class MemoryAuthAuditSink {
+    events = [];
+    record(event) {
+        this.events.push(event);
+    }
+    names() {
+        return this.events.map((event) => event.name);
+    }
+}
+exports.MemoryAuthAuditSink = MemoryAuthAuditSink;
+//# sourceMappingURL=memory-stores.js.map

package/dist/otp.service.d.ts

@@ -0,0 +1,47 @@
+/**
+ * One-time codes (PLAN.md §12, §15.1).
+ *
+ * Codes are drawn from the CSPRNG (`randomOtp`, which rejects and re-draws
+ * rather than folding a range, so no digit is more likely than another), stored
+ * as an HMAC, compared in constant time, and consumed on first correct use.
+ *
+ * Three limits make a six-digit code defensible: a short TTL, a per-code
+ * attempt ceiling, and a resend cooldown. Without the cooldown, an attacker
+ * requests a fresh code every time the attempt counter runs out and the
+ * ceiling stops mattering.
+ */
+import type { AuthAuditSink, Clock, OtpChannel, OtpPurpose, OtpStore } from './ports.js';
+import type { ResolvedAuthConfig } from './config.js';
+export interface OtpServiceOptions {
+    readonly store: OtpStore;
+    readonly channel: OtpChannel;
+    readonly config: ResolvedAuthConfig['otp'];
+    readonly pepper: string;
+    readonly clock?: Clock;
+    readonly audit?: AuthAuditSink;
+}
+export interface OtpIssueResult {
+    readonly issued: boolean;
+    /** Set when a resend was refused; seconds until one is allowed. */
+    readonly retryAfterSeconds?: number;
+}
+export declare class OtpService {
+    #private;
+    constructor(options: OtpServiceOptions);
+    /**
+     * Issue a code and hand it to the channel.
+     *
+     * Returns `issued: false` while the cooldown is in force rather than
+     * throwing: the caller replies the same way either way, because telling an
+     * unauthenticated client "you already have a code" confirms the account
+     * exists.
+     */
+    issue(subject: string, purpose: OtpPurpose): Promise<OtpIssueResult>;
+    /**
+     * Verify and consume a code.
+     *
+     * @throws AuthenticationError `AUTH_OTP_INVALID` or `AUTH_OTP_EXPIRED`
+     */
+    verify(subject: string, purpose: OtpPurpose, code: string): Promise<void>;
+}
+//# sourceMappingURL=otp.service.d.ts.map