@astram/guard 0.1.1 → 0.3.0

package/dist/auth/rate-limit/attempt-limiter.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `AttemptLimiter` — a guard-owned, Redis-backed sliding-window attempt counter for
+ * anti-brute-force on the auth surface (spec §5). ONE class, used at TWO call sites
+ * with independent thresholds: `/auth/login` (H1 password-login lockout, default
+ * 10/15min, keyed `login:<identityHint>`) and the `/auth/mfa` recovery branch
+ * (default 5/15min, keyed `recovery:<principalId>`).
+ *
+ * ── CONTRACT ─────────────────────────────────────────────────────────────────
+ *   check(key)         → `true`  if the caller is UNDER the threshold (allowed);
+ *                        `false` if AT/over it (locked out for the window).
+ *   recordFailure(key) → increment the counter; on the FIRST failure in a window,
+ *                        set the window TTL (`PEXPIRE windowMs`) so the counter
+ *                        auto-expires (a sliding window that resets on inactivity).
+ *                        RETURNS the new count so a caller can detect the LOCKOUT
+ *                        TRANSITION (count === maxAttempts is the exact edge where
+ *                        the NEXT check() flips to `false`) and act ONCE on it — e.g.
+ *                        emit a single lockout audit event, never one per attempt
+ *                        (feature #140's audit-on-the-edge, anti-flood). On a Redis
+ *                        best-effort miss it returns `0` (an unknown count → the
+ *                        caller simply doesn't treat the miss as a transition).
+ *   reset(key)         → clear the counter (a SUCCESS resets — a legitimate user is
+ *                        never penalized for their earlier fat-fingers).
+ *
+ * ── FAIL-OPEN-WITH-LOG (spec §5, the deliberate posture) ──────────────────────
+ *   A limiter differs from the credential path: a Redis outage must NOT lock out
+ *   every legitimate login/recovery. So `check()` FAILS OPEN on a Redis error —
+ *   it returns `true` (allowed) and LOGS the blip. This never grants access on its
+ *   own (the password / recovery code still gates); it only transiently LOOSENS the
+ *   brute-force ceiling. `recordFailure`/`reset` are best-effort and swallow (a
+ *   count we couldn't write just means the window is a touch more lenient — never a
+ *   thrown error into the request path).
+ *
+ * ── ANTI-ENUMERATION ── the limiter itself is silent; the caller maps a `false`
+ *   from `check()` to the SAME generic 401 as a wrong password / wrong code, so a
+ *   locked-out account is indistinguishable from a bad credential.
+ *
+ * ADR-0023: guard owns the infra adapter (ioredis); the class is a thin, injectable
+ * collaborator the controller consumes via a DI token (`SHIELD_LOGIN_LIMITER` /
+ * `SHIELD_RECOVERY_LIMITER`), each provided with the live Redis + its config.
+ */
+import type Redis from 'ioredis';
+/** Per-limiter tuning: the failure ceiling and the sliding-window length (ms). */
+export interface AttemptLimiterConfig {
+    /** Number of failures within the window that trips the lockout (check → false). */
+    readonly maxAttempts: number;
+    /** The window length in ms; the counter auto-expires after this idle span. */
+    readonly windowMs: number;
+}
+export declare class AttemptLimiter {
+    private readonly redis;
+    private readonly cfg;
+    /** One shared logger — the fail-open path warns so a Redis outage is observable. */
+    private static readonly logger;
+    constructor(redis: Redis, cfg: AttemptLimiterConfig);
+    /**
+     * The failure ceiling for this limiter (read-only). A caller uses it to detect the
+     * lockout TRANSITION: {@link recordFailure} returns the new count, and the caller
+     * acts ONCE when that count first equals `maxAttempts` (the edge where the next
+     * {@link check} flips to `false`) — the audit-on-the-edge / anti-flood contract.
+     */
+    get maxAttempts(): number;
+    /** Namespace every key so the two limiters + other Redis users never collide. */
+    private k;
+    /**
+     * `true` iff the caller is UNDER the threshold (allowed). FAILS OPEN on a Redis
+     * error — returns `true` and logs — so a Redis blip never locks out every login
+     * (spec §5). The credential/recovery check still gates access; this only bounds
+     * brute-force.
+     */
+    check(key: string): Promise<boolean>;
+    /**
+     * Increment the failure counter; set the window TTL on the FIRST failure so the
+     * counter auto-expires after `windowMs` of inactivity. Best-effort — a write we
+     * can't land just makes the window slightly more lenient (never a thrown error).
+     *
+     * RETURNS the new failure count so the caller can detect the lockout TRANSITION
+     * (count === {@link maxAttempts} is the exact edge where the next {@link check}
+     * flips to `false`) and act on it exactly ONCE — feature #140's audit-on-the-edge
+     * (never one audit event per attempt past the threshold). On a Redis best-effort
+     * miss it returns `0`: an unknown count the caller must NOT treat as a transition
+     * (so a Redis blip never spuriously fires — or suppresses — the lockout audit).
+     */
+    recordFailure(key: string): Promise<number>;
+    /**
+     * Clear the counter — a SUCCESS resets the window (the user proved themselves; do
+     * not carry their earlier failures forward). Best-effort; a swallowed error just
+     * leaves the (soon-to-expire) counter in place.
+     */
+    reset(key: string): Promise<void>;
+}
+//# sourceMappingURL=attempt-limiter.d.ts.map

package/dist/auth/rate-limit/attempt-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-limiter.d.ts","sourceRoot":"","sources":["../../../src/auth/rate-limit/attempt-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,cAAc;IAKvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IALtB,oFAAoF;IACpF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAmC;gBAG9C,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,oBAAoB;IAG5C;;;;;OAKG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,iFAAiF;IACjF,OAAO,CAAC,CAAC;IAIT;;;;;OAKG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAc1C;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBjD;;;;OAIG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOxC"}

package/dist/auth/rate-limit/attempt-limiter.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * `AttemptLimiter` — a guard-owned, Redis-backed sliding-window attempt counter for
+ * anti-brute-force on the auth surface (spec §5). ONE class, used at TWO call sites
+ * with independent thresholds: `/auth/login` (H1 password-login lockout, default
+ * 10/15min, keyed `login:<identityHint>`) and the `/auth/mfa` recovery branch
+ * (default 5/15min, keyed `recovery:<principalId>`).
+ *
+ * ── CONTRACT ─────────────────────────────────────────────────────────────────
+ *   check(key)         → `true`  if the caller is UNDER the threshold (allowed);
+ *                        `false` if AT/over it (locked out for the window).
+ *   recordFailure(key) → increment the counter; on the FIRST failure in a window,
+ *                        set the window TTL (`PEXPIRE windowMs`) so the counter
+ *                        auto-expires (a sliding window that resets on inactivity).
+ *                        RETURNS the new count so a caller can detect the LOCKOUT
+ *                        TRANSITION (count === maxAttempts is the exact edge where
+ *                        the NEXT check() flips to `false`) and act ONCE on it — e.g.
+ *                        emit a single lockout audit event, never one per attempt
+ *                        (feature #140's audit-on-the-edge, anti-flood). On a Redis
+ *                        best-effort miss it returns `0` (an unknown count → the
+ *                        caller simply doesn't treat the miss as a transition).
+ *   reset(key)         → clear the counter (a SUCCESS resets — a legitimate user is
+ *                        never penalized for their earlier fat-fingers).
+ *
+ * ── FAIL-OPEN-WITH-LOG (spec §5, the deliberate posture) ──────────────────────
+ *   A limiter differs from the credential path: a Redis outage must NOT lock out
+ *   every legitimate login/recovery. So `check()` FAILS OPEN on a Redis error —
+ *   it returns `true` (allowed) and LOGS the blip. This never grants access on its
+ *   own (the password / recovery code still gates); it only transiently LOOSENS the
+ *   brute-force ceiling. `recordFailure`/`reset` are best-effort and swallow (a
+ *   count we couldn't write just means the window is a touch more lenient — never a
+ *   thrown error into the request path).
+ *
+ * ── ANTI-ENUMERATION ── the limiter itself is silent; the caller maps a `false`
+ *   from `check()` to the SAME generic 401 as a wrong password / wrong code, so a
+ *   locked-out account is indistinguishable from a bad credential.
+ *
+ * ADR-0023: guard owns the infra adapter (ioredis); the class is a thin, injectable
+ * collaborator the controller consumes via a DI token (`SHIELD_LOGIN_LIMITER` /
+ * `SHIELD_RECOVERY_LIMITER`), each provided with the live Redis + its config.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttemptLimiter = void 0;
+const common_1 = require("@nestjs/common");
+class AttemptLimiter {
+    redis;
+    cfg;
+    /** One shared logger — the fail-open path warns so a Redis outage is observable. */
+    static logger = new common_1.Logger(AttemptLimiter.name);
+    constructor(redis, cfg) {
+        this.redis = redis;
+        this.cfg = cfg;
+    }
+    /**
+     * The failure ceiling for this limiter (read-only). A caller uses it to detect the
+     * lockout TRANSITION: {@link recordFailure} returns the new count, and the caller
+     * acts ONCE when that count first equals `maxAttempts` (the edge where the next
+     * {@link check} flips to `false`) — the audit-on-the-edge / anti-flood contract.
+     */
+    get maxAttempts() {
+        return this.cfg.maxAttempts;
+    }
+    /** Namespace every key so the two limiters + other Redis users never collide. */
+    k(key) {
+        return `shield:attempts:${key}`;
+    }
+    /**
+     * `true` iff the caller is UNDER the threshold (allowed). FAILS OPEN on a Redis
+     * error — returns `true` and logs — so a Redis blip never locks out every login
+     * (spec §5). The credential/recovery check still gates access; this only bounds
+     * brute-force.
+     */
+    async check(key) {
+        try {
+            const n = await this.redis.get(this.k(key));
+            return n === null || Number(n) < this.cfg.maxAttempts;
+        }
+        catch (err) {
+            // FAIL-OPEN: a limiter must not lock out legitimate users on a Redis outage.
+            // Allow, but LOG so the transient loosening of brute-force protection is seen.
+            AttemptLimiter.logger.warn(`attempt-limiter check failed open (allowing) for a key — Redis unavailable: ${describeError(err)}`);
+            return true;
+        }
+    }
+    /**
+     * Increment the failure counter; set the window TTL on the FIRST failure so the
+     * counter auto-expires after `windowMs` of inactivity. Best-effort — a write we
+     * can't land just makes the window slightly more lenient (never a thrown error).
+     *
+     * RETURNS the new failure count so the caller can detect the lockout TRANSITION
+     * (count === {@link maxAttempts} is the exact edge where the next {@link check}
+     * flips to `false`) and act on it exactly ONCE — feature #140's audit-on-the-edge
+     * (never one audit event per attempt past the threshold). On a Redis best-effort
+     * miss it returns `0`: an unknown count the caller must NOT treat as a transition
+     * (so a Redis blip never spuriously fires — or suppresses — the lockout audit).
+     */
+    async recordFailure(key) {
+        try {
+            const k = this.k(key);
+            const n = await this.redis.incr(k);
+            // First failure in a fresh window → arm the expiry (INCR alone is persistent).
+            if (n === 1)
+                await this.redis.pexpire(k, this.cfg.windowMs);
+            return n;
+        }
+        catch (err) {
+            // Best-effort: a missed increment loosens the ceiling transiently, never fails
+            // the request. Log so a persistent Redis fault is visible. Return 0 (unknown
+            // count) so the caller's transition check (`=== maxAttempts`) never trips off a
+            // miss — the audit fires only on a genuine, counted crossing.
+            AttemptLimiter.logger.warn(`attempt-limiter recordFailure best-effort miss — Redis unavailable: ${describeError(err)}`);
+            return 0;
+        }
+    }
+    /**
+     * Clear the counter — a SUCCESS resets the window (the user proved themselves; do
+     * not carry their earlier failures forward). Best-effort; a swallowed error just
+     * leaves the (soon-to-expire) counter in place.
+     */
+    async reset(key) {
+        try {
+            await this.redis.del(this.k(key));
+        }
+        catch {
+            // Ignore — the counter TTL will expire it anyway; never fail a success path.
+        }
+    }
+}
+exports.AttemptLimiter = AttemptLimiter;
+/** A tiny, secret-free error description for the fail-open log (never logs a key). */
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/auth/rate-limit/attempt-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-limiter.js","sourceRoot":"","sources":["../../../src/auth/rate-limit/attempt-limiter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;;;AAEH,2CAAwC;AAWxC,MAAa,cAAc;IAKN;IACA;IALnB,oFAAoF;IAC5E,MAAM,CAAU,MAAM,GAAG,IAAI,eAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAEjE,YACmB,KAAY,EACZ,GAAyB;QADzB,UAAK,GAAL,KAAK,CAAO;QACZ,QAAG,GAAH,GAAG,CAAsB;IACzC,CAAC;IAEJ;;;;;OAKG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC;IAC9B,CAAC;IAED,iFAAiF;IACzE,CAAC,CAAC,GAAW;QACnB,OAAO,mBAAmB,GAAG,EAAE,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,GAAW;QACrB,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5C,OAAO,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,6EAA6E;YAC7E,+EAA+E;YAC/E,cAAc,CAAC,MAAM,CAAC,IAAI,CACxB,+EAA+E,aAAa,CAAC,GAAG,CAAC,EAAE,CACpG,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,aAAa,CAAC,GAAW;QAC7B,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACtB,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACnC,+EAA+E;YAC/E,IAAI,CAAC,KAAK,CAAC;gBAAE,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC5D,OAAO,CAAC,CAAC;QACX,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,+EAA+E;YAC/E,6EAA6E;YAC7E,gFAAgF;YAChF,8DAA8D;YAC9D,cAAc,CAAC,MAAM,CAAC,IAAI,CACxB,uEAAuE,aAAa,CAAC,GAAG,CAAC,EAAE,CAC5F,CAAC;YACF,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,GAAW;QACrB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,6EAA6E;QAC/E,CAAC;IACH,CAAC;;AAtFH,wCAuFC;AAED,sFAAsF;AACtF,SAAS,aAAa,CAAC,GAAY;IACjC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC"}

package/dist/auth/tokens.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Phase 0b Auth-surface **DI provider tokens** — the shared injection seams the
+ * three parallel teams bind/consume so they never collide (ADR-0023: composition
+ * is the framework's job; these are the framework's internal wiring points).
+ *
+ * ⛔ FROZEN by this prelude. Team B (composition) PROVIDES these; Team A
+ * (credential store) provides the resolver behind {@link SHIELD_CREDENTIAL_RESOLVER};
+ * Team C (`/auth` controllers) CONSUMES {@link SHIELD_AUTHENTICATOR} +
+ * {@link SHIELD_SESSION_AUTHORITY}. Do not rename these Symbols — a rename is a
+ * breaking change to every team's wiring.
+ *
+ * NOTE — some session/hasher adapters already ship their OWN tokens in
+ * `@astram/guard` (`SHIELD_PASSWORD_HASHER`, `SHIELD_SESSION_RECORD_STORE`,
+ * `SHIELD_HOT_SESSION_STORE`, `SHIELD_TOKEN_GENERATOR`, `SHIELD_REFRESH_HASHER`,
+ * `SHIELD_CLOCK`). Those stay the canonical tokens for those adapters. This file
+ * adds ONLY the NEW seams Phase 0b introduces: the live connections
+ * ({@link SHIELD_DB_POOL} / {@link SHIELD_REDIS}), the credential resolver, and the
+ * two COMPOSED engines ({@link SHIELD_AUTHENTICATOR} / {@link SHIELD_SESSION_AUTHORITY}).
+ * {@link SHIELD_PASSWORD_HASHER} is re-exported from the argon2 adapter for
+ * convenience so a team can import every auth-relevant token from one module.
+ *
+ * ADR-0003: no framework/DB/crypto imports here — just Symbols (+ one re-export).
+ */
+export { SHIELD_PASSWORD_HASHER } from '../authentication/argon2id-password-hasher.js';
+/**
+ * The ONE live `mariadb` `Pool` (the `shield_core` account — DML on
+ * `shield_identity`, ADR-0013/0014). **Provided by Team B** (the persistence
+ * factory — the single place a live DB connection is created). **Consumed by**
+ * the {@link SHIELD_CREDENTIAL_RESOLVER} factory and the
+ * {@link SHIELD_SESSION_RECORD_STORE} factory. Disposed on app shutdown.
+ */
+export declare const SHIELD_DB_POOL: unique symbol;
+/**
+ * The ONE live `ioredis` client (the hot session tier, ADR-0013). **Provided by
+ * Team B** (the persistence factory). **Consumed by** the
+ * {@link SHIELD_HOT_SESSION_STORE} factory. Disposed on app shutdown.
+ */
+export declare const SHIELD_REDIS: unique symbol;
+/**
+ * The `CredentialResolver` (core port) that resolves an identity hint →
+ * `ResolvedCredential | null`. **Provided by Team A** (the
+ * `MariaDbCredentialResolver`, injected with {@link SHIELD_DB_POOL}). **Consumed
+ * by** the {@link SHIELD_AUTHENTICATOR} factory (Team B) as
+ * `createAuthenticator({ resolver })`.
+ */
+export declare const SHIELD_CREDENTIAL_RESOLVER: unique symbol;
+/**
+ * The `ProfileResolver` (guard port, see `../auth/profile-resolver.ts`) that turns
+ * an authenticated `Principal` → the current-user display profile for `GET /auth/me`.
+ * OPTIONAL: supplied by the consumer via `ShieldModule.forRoot({ profileResolver })`
+ * and threaded through `AuthModule.forRoot`. When ABSENT the `/auth/me` route returns
+ * an honest "profile unavailable" (the framework is org-schema-agnostic — see the
+ * port header). Consumed by {@link AuthController}'s `me()` handler.
+ */
+export declare const SHIELD_PROFILE_RESOLVER: unique symbol;
+/**
+ * The composed `Authenticator` (core engine) — `createAuthenticator({ hasher,
+ * resolver, identityBroker, factorVerifiers:[totp] })`. **Provided by Team B**
+ * (the AuthModule factory). **Consumed by** Team C's `/auth/login` +
+ * `/auth/mfa` controllers.
+ */
+export declare const SHIELD_AUTHENTICATOR: unique symbol;
+/**
+ * The composed `SessionAuthority` (core engine) — `createSessionAuthority({
+ * recordStore, hotStore, tokenGenerator, refreshHasher, clock, lifetimes })`.
+ * **Provided by Team B** (the AuthModule factory). **Consumed by** Team C's
+ * `/auth/login` (establish), `/auth/refresh` (rotate), `/auth/logout` (revoke),
+ * and `/auth/mfa` (establish after factor).
+ */
+export declare const SHIELD_SESSION_AUTHORITY: unique symbol;
+/**
+ * The `CredentialWriter` (guard port, `../auth/ports/credential-writer.ts`) — the
+ * WRITE side of the credential store (set password hash, read the stored hash by
+ * principal id). Consumed by change-password + reset-password. Absent (`null`) →
+ * those routes return 501. (TOTP secrets no longer live here — the multi-device
+ * MFA model stores them in {@link SHIELD_MFA_DEVICE_STORE}.)
+ */
+export declare const SHIELD_CREDENTIAL_WRITER: unique symbol;
+/**
+ * The `ResetTokenStore` (guard port, `../auth/ports/reset-token-store.ts`) — the
+ * single-use, TTL'd password-reset token store (framework hands it a SHA-256 hash,
+ * never the raw token). Consumed by forgot-password + reset-password.
+ */
+export declare const SHIELD_RESET_TOKEN_STORE: unique symbol;
+/**
+ * The `EmailSender` (guard port, `../auth/ports/email-sender.ts`) — the delivery
+ * seam (SendGrid/SMTP/test capturer). The framework builds the message; the
+ * consumer delivers it. Consumed by forgot-password.
+ */
+export declare const SHIELD_EMAIL_SENDER: unique symbol;
+/**
+ * The `RecoveryCodeStore` (guard port, `../auth/ports/recovery-code-store.ts`) —
+ * persists Argon2-hashed one-time MFA recovery codes. Consumed by MFA enrollment.
+ */
+export declare const SHIELD_RECOVERY_CODE_STORE: unique symbol;
+/**
+ * The `ProfileWriter` (guard port, `../auth/ports/profile-writer.ts`) — the
+ * self-service profile-edit seam (name/email). Consumed by `PATCH /account/profile`.
+ */
+export declare const SHIELD_PROFILE_WRITER: unique symbol;
+/**
+ * The `AuditSink` (guard port, `../auth/ports/audit-sink.ts`) — the auth-surface audit
+ * seam (spec §6.2). `record(event)` persists a framework-built {@link AuthAuditEvent}
+ * (the FIRST auth audit event: the recovery-code login). OPTIONAL, consumer-plugged
+ * exactly like {@link SHIELD_PROFILE_RESOLVER}: supplied → bound app-wide; omitted →
+ * bound `null`, so the `@Optional()` injection in {@link AuthController} resolves to
+ * "no seam" and the best-effort audit call is a no-op (the login still works,
+ * un-audited). Consumed by the `/auth/mfa` recovery branch (fire-and-forget).
+ */
+export declare const SHIELD_AUDIT_SINK: unique symbol;
+/**
+ * The `MfaDeviceStore` (guard port, `../auth/ports/mfa-device-store.ts`) — persists
+ * a principal's N TOTP authenticator DEVICES (multi-device MFA). Consumed
+ * by the `/account/mfa/devices/*` routes (list/begin/confirm/rename/remove) + the
+ * consumer's login resolver (which bundles {@link MfaDeviceStore.listConfirmedSecrets}
+ * for the OR-match). Absent (`null`) → the device routes return 501.
+ */
+export declare const SHIELD_MFA_DEVICE_STORE: unique symbol;
+/**
+ * The `SessionSweeper` (guard port, `../auth/ports/session-sweeper.ts`) — revokes a
+ * principal's sessions after a credential change (all, or all-but-current). The core
+ * has no revoke-all-for-principal, so the consumer implements it. Consumed by
+ * change-password (others) + reset-password (all).
+ */
+export declare const SHIELD_SESSION_SWEEPER: unique symbol;
+/**
+ * The reset-link base URL (a plain `string` value, NOT a port). The framework
+ * composes the emailed reset link as `${base}?token=<rawToken>` so the
+ * {@link SHIELD_EMAIL_SENDER} seam stays a dumb delivery channel (no URL/token
+ * logic). Bound app-wide by `AuthModule` from the environment
+ * (`RESET_LINK_BASE_URL`, default `http://localhost:5173/reset-password`). Consumed
+ * by `POST /auth/forgot-password`.
+ */
+export declare const SHIELD_RESET_LINK_BASE_URL: unique symbol;
+/**
+ * The core single-secret `FactorVerifier` for TOTP (`createTotpFactorVerifier({
+ * hmacSha1 })`), PROVIDED by `AuthModule` (which loads the core factory lazily — the
+ * CJS↔ESM invariant, same as {@link SHIELD_AUTHENTICATOR}). It is the SAME base
+ * verifier the login default uses, provided pre-built app-wide so the multi-device
+ * MFA routes (Phase 3) can check a presented code against a SPECIFIC device's secret
+ * without importing `@astram/core` at the controller's top level (that becomes a
+ * runtime `require` on the ESM-only core in the built CJS dist). Distinct from the
+ * login OR-verifier the consumer plugs through {@link SHIELD_TOTP_VERIFIER_OVERRIDE}
+ * (Phase 2): this stays single-secret, for per-device checks.
+ */
+export declare const SHIELD_TOTP_VERIFIER: unique symbol;
+/**
+ * OPTIONAL consumer override for the LOGIN `totp` {@link FactorVerifier} — the
+ * verifier the composed `Authenticator` uses to satisfy a `RequiredFactor` of
+ * factor `'totp'`. Threaded through `ShieldModule.forRoot({ totpVerifier })` →
+ * `AuthModule.forRoot`, `@Optional()` (bound `null` when absent). When supplied it
+ * REPLACES the framework's default `createTotpFactorVerifier({ hmacSha1 })` in the
+ * authenticator's `factorVerifiers` — the seam multi-device MFA needs so a
+ * consumer can plug an OR-matching verifier (one required-factor whose `secret` is a
+ * bundle of the user's N device secrets; the verifier matches ANY). Default absent →
+ * behavior EXACTLY unchanged (single-secret RFC-6238). Distinct from
+ * {@link SHIELD_TOTP_VERIFIER} (the pre-built single-secret verifier the account MFA
+ * routes use for per-device checks — that one is never overridden).
+ */
+export declare const SHIELD_TOTP_VERIFIER_OVERRIDE: unique symbol;
+/**
+ * OPTIONAL root allowlist — the server-side, trusted set of canonical
+ * principal ids that ARE roots on the framework's Internal identity
+ * source. Threaded through `ShieldModule.forRoot({ rootIds })` →
+ * `AuthModule.forRoot` and passed to `createIdentityBroker({ internalRootIds })`,
+ * `@Optional()` (bound `[]` when absent → nobody is a root, default-deny).
+ *
+ * ROOT SAFETY (core `internal-adapter.ts`): the `isRoot` flag is set
+ * `true` iff the authenticated principal's `id` is in THIS allowlist — it is NEVER read
+ * from a caller-supplied claim. So this is the ONLY way a login mints a root, and
+ * an attacker who can influence claim VALUES cannot flip it (they'd have to be in this
+ * server-side list, which they can't write). Default absent → `[]` → default-deny,
+ * exactly the historical behavior (`createIdentityBroker()` with an empty allowlist).
+ */
+export declare const SHIELD_ROOT_IDS: unique symbol;
+/**
+ * OPTIONAL {@link import('./ports/session-facts-projector.js').SessionFactsProjector}
+ * — the ADR-0011 eager-projection seam. Threaded through
+ * `ShieldModule.forRoot({ sessionFactsProjector })` → `AuthModule.forRoot`, `@Optional()`
+ * (bound `null` when absent). When PRESENT, the auth controller calls `project(...)` at
+ * login + refresh and caches the returned `CoarseGrants` on the session binding, so gate
+ * 5 serves the principal's coarse grants from the request's `cachedFacts` instead of a DB
+ * reload every request. ABSENT → the controller omits `cachedFacts` → today's exact
+ * behavior (DB reload every request). Purely additive + opt-in. Only consulted under
+ * `auth: true`.
+ */
+export declare const SHIELD_SESSION_FACTS_PROJECTOR: unique symbol;
+/**
+ * The password-login {@link AttemptLimiter} (spec §5 / IdP-hardening H1) — keyed
+ * `login:<identityHint>`, default 10 failures / 15-min window. Consumed at the TOP
+ * of `POST /auth/login` (`check` → generic 401 when locked) and on the outcome
+ * (`recordFailure` on a rejected wrong-password; `reset` on `authenticated` OR
+ * `mfa_required` — a correct password that merely needs MFA is NOT a failure).
+ */
+export declare const SHIELD_LOGIN_LIMITER: unique symbol;
+/**
+ * The recovery-code {@link AttemptLimiter} (spec §5) — keyed `recovery:<principalId>`,
+ * default 5 failures / 15-min window (recovery codes are higher-value than a rotating
+ * 30-s TOTP). Consumed in the `/auth/mfa` recovery branch: `check` BEFORE `consume`
+ * (locked → generic 401 without consulting the store), `recordFailure` on a wrong
+ * code, `reset` on success.
+ */
+export declare const SHIELD_RECOVERY_LIMITER: unique symbol;
+/**
+ * The forgot-password IP {@link AttemptLimiter} (feature #141) — keyed
+ * `forgot:ip:<clientIp>`, default 5 per 15-min window. Consumed at the TOP of
+ * `POST /auth/forgot-password`. UNLIKE login, forgot-password is ALWAYS 204 (a 429
+ * would itself be an enumeration/probing signal), so this is a request-rate cap: the
+ * handler counts EVERY forgot request against the IP budget and, once the budget is
+ * exceeded, SILENTLY skips the email-send work while STILL returning 204 (the existing
+ * always-204 anti-enumeration posture is preserved). Fail-open on a Redis blip. The
+ * client IP is read from the TRUSTED `req.ip` (the consumer sets `trust proxy` so
+ * X-Forwarded-For can't be spoofed).
+ */
+export declare const SHIELD_FORGOT_LIMITER: unique symbol;
+/**
+ * The forgot-password PER-HINT {@link AttemptLimiter} (feature #141) — keyed
+ * `forgot:<identityHint>`, default 3 per 60-min window (generous). Caps how often ANY
+ * caller (across IPs) can trigger a reset email for ONE account, so a single victim
+ * can't be email-bombed from a rotating IP pool. Same request-rate-cap + silent-skip-
+ * still-204 semantics as {@link SHIELD_FORGOT_LIMITER}; consumed alongside it in
+ * `POST /auth/forgot-password`.
+ */
+export declare const SHIELD_FORGOT_HINT_LIMITER: unique symbol;
+/**
+ * The reset-password IP {@link AttemptLimiter} (feature #141) — keyed
+ * `reset:ip:<clientIp>`, default 10 per 15-min window. Consumed at the TOP of
+ * `POST /auth/reset-password` (`check` BEFORE token work). Reset is token-gated (a
+ * 256-bit single-use token), so this is DoS/abuse throttling, NOT anti-brute-force —
+ * and it MAY return a GENERIC 429 on lockout (a token-gated endpoint is not
+ * enumeration-sensitive). `recordFailure` on a bad/invalid token (the abuse signal);
+ * `reset` on a successful reset (204). Fail-open on a Redis blip. IP is the trusted
+ * `req.ip`.
+ */
+export declare const SHIELD_RESET_LIMITER: unique symbol;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/auth/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/auth/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,YAAY,eAAyB,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAW3E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,eAAmC,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,eAA0C,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,eAA2C,CAAC;AAUvF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC"}