@astram/guard 0.2.0 → 0.4.0

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/tokens.d.ts

@@ -44,6 +44,15 @@ export declare const SHIELD_REDIS: unique symbol;
  * `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**
@@ -59,4 +68,169 @@ export declare const SHIELD_AUTHENTICATOR: unique symbol;
  * 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

@@ -1 +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;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC"}
+{"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"}

package/dist/auth/tokens.js

@@ -23,7 +23,7 @@
  * ADR-0003: no framework/DB/crypto imports here — just Symbols (+ one re-export).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SHIELD_SESSION_AUTHORITY = exports.SHIELD_AUTHENTICATOR = exports.SHIELD_CREDENTIAL_RESOLVER = exports.SHIELD_REDIS = exports.SHIELD_DB_POOL = exports.SHIELD_PASSWORD_HASHER = void 0;
+exports.SHIELD_RESET_LIMITER = exports.SHIELD_FORGOT_HINT_LIMITER = exports.SHIELD_FORGOT_LIMITER = exports.SHIELD_RECOVERY_LIMITER = exports.SHIELD_LOGIN_LIMITER = exports.SHIELD_SESSION_FACTS_PROJECTOR = exports.SHIELD_ROOT_IDS = exports.SHIELD_TOTP_VERIFIER_OVERRIDE = exports.SHIELD_TOTP_VERIFIER = exports.SHIELD_RESET_LINK_BASE_URL = exports.SHIELD_SESSION_SWEEPER = exports.SHIELD_MFA_DEVICE_STORE = exports.SHIELD_AUDIT_SINK = exports.SHIELD_PROFILE_WRITER = exports.SHIELD_RECOVERY_CODE_STORE = exports.SHIELD_EMAIL_SENDER = exports.SHIELD_RESET_TOKEN_STORE = exports.SHIELD_CREDENTIAL_WRITER = exports.SHIELD_SESSION_AUTHORITY = exports.SHIELD_AUTHENTICATOR = exports.SHIELD_PROFILE_RESOLVER = exports.SHIELD_CREDENTIAL_RESOLVER = exports.SHIELD_REDIS = exports.SHIELD_DB_POOL = exports.SHIELD_PASSWORD_HASHER = void 0;
 var argon2id_password_hasher_js_1 = require("../authentication/argon2id-password-hasher.js");
 Object.defineProperty(exports, "SHIELD_PASSWORD_HASHER", { enumerable: true, get: function () { return argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER; } });
 /**
@@ -48,6 +48,15 @@ exports.SHIELD_REDIS = Symbol('SHIELD_REDIS');
  * `createAuthenticator({ resolver })`.
  */
 exports.SHIELD_CREDENTIAL_RESOLVER = Symbol('SHIELD_CREDENTIAL_RESOLVER');
+/**
+ * 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.
+ */
+exports.SHIELD_PROFILE_RESOLVER = Symbol('SHIELD_PROFILE_RESOLVER');
 /**
  * The composed `Authenticator` (core engine) — `createAuthenticator({ hasher,
  * resolver, identityBroker, factorVerifiers:[totp] })`. **Provided by Team B**
@@ -63,3 +72,183 @@ exports.SHIELD_AUTHENTICATOR = Symbol('SHIELD_AUTHENTICATOR');
  * and `/auth/mfa` (establish after factor).
  */
 exports.SHIELD_SESSION_AUTHORITY = Symbol('SHIELD_SESSION_AUTHORITY');
+// ---------------------------------------------------------------------------
+// Account & credential surface seams (forgot/reset, change-password, MFA
+// enrollment, profile edit). All OPTIONAL, consumer-plugged through
+// `ShieldModule.forRoot({...})` → `AuthModule.forRoot` (exactly like
+// {@link SHIELD_PROFILE_RESOLVER}). Each binds to the supplied port impl, or to
+// `null` when absent so the `@Optional()` injection in the routes resolves to "no
+// seam" → the route returns 501. See `../auth/ports/*.ts` for each contract.
+// ---------------------------------------------------------------------------
+/**
+ * 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}.)
+ */
+exports.SHIELD_CREDENTIAL_WRITER = Symbol('SHIELD_CREDENTIAL_WRITER');
+/**
+ * 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.
+ */
+exports.SHIELD_RESET_TOKEN_STORE = Symbol('SHIELD_RESET_TOKEN_STORE');
+/**
+ * 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.
+ */
+exports.SHIELD_EMAIL_SENDER = Symbol('SHIELD_EMAIL_SENDER');
+/**
+ * The `RecoveryCodeStore` (guard port, `../auth/ports/recovery-code-store.ts`) —
+ * persists Argon2-hashed one-time MFA recovery codes. Consumed by MFA enrollment.
+ */
+exports.SHIELD_RECOVERY_CODE_STORE = Symbol('SHIELD_RECOVERY_CODE_STORE');
+/**
+ * The `ProfileWriter` (guard port, `../auth/ports/profile-writer.ts`) — the
+ * self-service profile-edit seam (name/email). Consumed by `PATCH /account/profile`.
+ */
+exports.SHIELD_PROFILE_WRITER = Symbol('SHIELD_PROFILE_WRITER');
+/**
+ * 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).
+ */
+exports.SHIELD_AUDIT_SINK = Symbol('SHIELD_AUDIT_SINK');
+/**
+ * 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.
+ */
+exports.SHIELD_MFA_DEVICE_STORE = Symbol('SHIELD_MFA_DEVICE_STORE');
+/**
+ * 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).
+ */
+exports.SHIELD_SESSION_SWEEPER = Symbol('SHIELD_SESSION_SWEEPER');
+/**
+ * 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`.
+ */
+exports.SHIELD_RESET_LINK_BASE_URL = Symbol('SHIELD_RESET_LINK_BASE_URL');
+/**
+ * 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.
+ */
+exports.SHIELD_TOTP_VERIFIER = Symbol('SHIELD_TOTP_VERIFIER');
+/**
+ * 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).
+ */
+exports.SHIELD_TOTP_VERIFIER_OVERRIDE = Symbol('SHIELD_TOTP_VERIFIER_OVERRIDE');
+/**
+ * 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).
+ */
+exports.SHIELD_ROOT_IDS = Symbol('SHIELD_ROOT_IDS');
+/**
+ * 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`.
+ */
+exports.SHIELD_SESSION_FACTS_PROJECTOR = Symbol('SHIELD_SESSION_FACTS_PROJECTOR');
+// ---------------------------------------------------------------------------
+// Rate-limit seams (anti-brute-force, spec §5) — ONE `AttemptLimiter` class
+// (Redis-backed), provided as TWO instances with independent thresholds under
+// these tokens. Both are always provided under `auth: true` (they need the live
+// {@link SHIELD_REDIS}); the controller injects each `@Optional()` so an absent
+// limiter degrades to "allow" (never a lock-out from missing wiring).
+// ---------------------------------------------------------------------------
+/**
+ * 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).
+ */
+exports.SHIELD_LOGIN_LIMITER = Symbol('SHIELD_LOGIN_LIMITER');
+/**
+ * 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.
+ */
+exports.SHIELD_RECOVERY_LIMITER = Symbol('SHIELD_RECOVERY_LIMITER');
+/**
+ * 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).
+ */
+exports.SHIELD_FORGOT_LIMITER = Symbol('SHIELD_FORGOT_LIMITER');
+/**
+ * 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`.
+ */
+exports.SHIELD_FORGOT_HINT_LIMITER = Symbol('SHIELD_FORGOT_HINT_LIMITER');
+/**
+ * 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`.
+ */
+exports.SHIELD_RESET_LIMITER = Symbol('SHIELD_RESET_LIMITER');

package/dist/auth/totp-enrollment.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Phase 4 MFA-enrollment — the **pure TOTP-enrollment helpers**: generate a fresh
+ * base32 TOTP secret, compose the `otpauth://` provisioning URI an authenticator app
+ * scans, and mint one-time recovery codes.
+ *
+ * ── WHY THIS LIVES IN GUARD (not core) ──────────────────────────────────────
+ * Core owns the TOTP *verifier* (`createTotpFactorVerifier`, RFC 6238) but is
+ * ZERO-dep + node-type-free (ADR-0003), so it cannot mint secrets (needs
+ * `node:crypto.randomBytes`) nor build a URI. Enrollment is the *provisioning* side
+ * — it produces the secret the verifier later checks against. Guard owns node
+ * builtins, so the generation lives here. NO core change: the secret this emits is a
+ * plain base32 string, exactly what `createTotpFactorVerifier` decodes.
+ *
+ * ── SECURITY ─────────────────────────────────────────────────────────────────
+ * The secret + recovery codes are credential material: never logged, returned to the
+ * user exactly ONCE at enrollment, and (recovery codes) stored only Argon2-hashed.
+ * These functions are PURE (no I/O, no storage) — the caller decides what to persist.
+ *
+ * ADR-0003: guard owns `node:crypto`; this file has NO framework/HTTP/DB coupling.
+ */
+/**
+ * Generate a fresh, cryptographically-random base32 TOTP secret (160 bits → 32
+ * chars). This is what the user's authenticator app is provisioned with and what the
+ * core verifier later checks presented codes against.
+ */
+export declare function generateTotpSecret(): string;
+/**
+ * Build the `otpauth://totp/...` provisioning URI an authenticator app scans (or the
+ * user enters manually). `label` identifies the account (shown in the app), `issuer`
+ * names the service. All three URI components are percent-encoded so a label/issuer
+ * with spaces or `:`/`?`/`&` cannot break the URI. Fixed to the defaults the core
+ * verifier uses (SHA-1, 6 digits, 30s period).
+ */
+export declare function buildOtpauthUri(secret: string, label: string, issuer: string): string;
+/**
+ * Mint `count` unique one-time recovery codes (each `xxxxx-xxxxx`, 10 lowercase hex
+ * chars grouped for readability). Returned RAW to the caller ONCE at enrollment; the
+ * store persists them Argon2-hashed. Uniqueness is enforced (a hex collision at this
+ * entropy is astronomically unlikely, but the loop guarantees `count` distinct codes).
+ */
+export declare function generateRecoveryCodes(count?: number): string[];
+//# sourceMappingURL=totp-enrollment.d.ts.map

package/dist/auth/totp-enrollment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp-enrollment.d.ts","sourceRoot":"","sources":["../../src/auth/totp-enrollment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA4CH;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAOrF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,MAAoC,GAAG,MAAM,EAAE,CAO3F"}