@astram/guard 0.6.0 → 0.8.0

package/dist/auth/rate-limit/trust-proxy-check.js

@@ -0,0 +1,94 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var TrustProxyBootCheck_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrustProxyBootCheck = exports.TRUST_PROXY_WARNING = void 0;
+exports.isTrustProxyConfigured = isTrustProxyConfigured;
+/**
+ * Boot-time `trust proxy` decision for ALL per-IP limiters (security hardening #5,
+ * review F2/F3): the login failure limiter (`login:ip:`), the forgot-password request cap
+ * (`forgot:ip:`) and the reset-password abuse cap (`reset:ip:`).
+ *
+ * Each keys on `req.ip`. Behind a reverse proxy (Traefik in the Astram stack) `req.ip` is
+ * the PROXY's address unless the app sets `app.set('trust proxy', <hop count>)`. With it
+ * unset every client shares one bucket, so a per-IP limit becomes an unauthenticated
+ * global DoS: 50 failed logins lock ALL logins, 10 bad reset tokens 429 EVERY reset, 5
+ * forgot requests silently drop EVERY reset email. Setting it too high lets a client spoof
+ * `X-Forwarded-For`, so the framework cannot pick a value.
+ *
+ * Decision (made ONCE at bootstrap, never per request):
+ *   - Express `trust proxy` explicitly configured (`app.get('trust proxy') !== false`, so an
+ *     explicit `0` = "no proxy" counts) → {@link TrustProxyBootCheck.perIpLimitingEnabled}
+ *     is `true` and AuthController enforces the per-IP limiters;
+ *   - otherwise (unset, a non-Express adapter, or before bootstrap) → `false`: every per-IP
+ *     limiter is OFF and one boot warning says so. The per-account limiters (login,
+ *     forgot-password) and the recovery-code limiter are unaffected.
+ *
+ * Runs on `onApplicationBootstrap` (inside `app.init()` / `app.listen()`), i.e. after a
+ * typical `main.ts` has called `app.set('trust proxy', …)` on the created app.
+ */
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+/**
+ * `true` when the Express app has an explicit `trust proxy` value. Express's default is
+ * `false`; an explicit `0`/`'loopback'`/hop count/subnet list counts as configured.
+ * Returns `null` when the instance is not Express-like (cannot tell).
+ */
+function isTrustProxyConfigured(instance) {
+    if (instance === null || (typeof instance !== 'function' && typeof instance !== 'object'))
+        return null;
+    const get = instance.get;
+    if (typeof get !== 'function')
+        return null;
+    const value = get.call(instance, 'trust proxy');
+    return value !== undefined && value !== false;
+}
+exports.TRUST_PROXY_WARNING = 'per-IP limiting (login, forgot-password, reset-password) is OFF: set trust proxy ' +
+    '(0 if no proxy, else the hop count). Without an explicit Express ' +
+    "'trust proxy' every client behind a reverse proxy shares the proxy's IP, so a per-IP " +
+    "limit would block everyone. In main.ts call app.set('trust proxy', <number of proxy hops " +
+    'in front of this app>) — never more than the real count. The per-account login and ' +
+    'forgot-password limits stay on.';
+let TrustProxyBootCheck = class TrustProxyBootCheck {
+    static { TrustProxyBootCheck_1 = this; }
+    adapterHost;
+    static logger = new common_1.Logger('ShieldAuth');
+    enabled = false;
+    constructor(adapterHost) {
+        this.adapterHost = adapterHost;
+    }
+    /**
+     * Whether AuthController enforces the per-IP limiters (login failures, forgot-password,
+     * reset-password). `false` until bootstrap has confirmed an explicit Express
+     * `trust proxy` (fail-safe: never a global lockout from a shared proxy IP).
+     */
+    get perIpLimitingEnabled() {
+        return this.enabled;
+    }
+    onApplicationBootstrap() {
+        const adapter = this.adapterHost?.httpAdapter;
+        if (!adapter)
+            return; // no HTTP server (e.g. a bare module) → no auth routes; stays off
+        const configured = adapter.getType() === 'express' ? isTrustProxyConfigured(adapter.getInstance()) : null;
+        this.enabled = configured === true;
+        if (!this.enabled)
+            TrustProxyBootCheck_1.logger.warn(exports.TRUST_PROXY_WARNING);
+    }
+};
+exports.TrustProxyBootCheck = TrustProxyBootCheck;
+exports.TrustProxyBootCheck = TrustProxyBootCheck = TrustProxyBootCheck_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [core_1.HttpAdapterHost])
+], TrustProxyBootCheck);

package/dist/auth/tokens.d.ts

@@ -211,13 +211,29 @@ export declare const SHIELD_SCOPE_SUBTREE_RESOLVER: unique symbol;
  */
 export declare const SHIELD_MEMBERSHIP_CHECKER: 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).
+ * The password-login {@link AttemptLimiter} (spec §5 / IdP-hardening H1) — keyed per
+ * ACCOUNT: `login:pid:<principalId>` for the account the credential store resolves for the
+ * typed hint (the DB collation decides which spellings are one account), else
+ * `login:<sha256(canonical hint)>` for an unknown hint — no PII in the key; see
+ * `rate-limit/canonical-hint.ts`. 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 password-login PER-CLIENT-IP {@link AttemptLimiter} (security hardening #5) —
+ * keyed `login:ip:<req.ip>`, default 50 failures / 15-min window (configurable via
+ * `LOGIN_IP_MAX_FAILURES` / `LOGIN_IP_WINDOW_MS`, see `AppConfig.loginIpLimit`). Caps
+ * password spraying across MANY distinct hints from one client. Counts wrong-password
+ * FAILURES only and is NEVER reset by a success (an attacker's own valid login must not
+ * wipe the budget). Checked before the account lookup and the authenticator. Fails open
+ * on a Redis blip (the limiter's posture). ENFORCED ONLY when the app set Express
+ * `trust proxy` explicitly (0 = no proxy, else the hop count): otherwise every client
+ * behind a proxy shares one `req.ip`, so the limiter is switched OFF at boot with a
+ * warning (`TrustProxyBootCheck`) rather than becoming a global login DoS.
+ */
+export declare const SHIELD_LOGIN_IP_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
@@ -226,6 +242,29 @@ export declare const SHIELD_LOGIN_LIMITER: unique symbol;
  * code, `reset` on success.
  */
 export declare const SHIELD_RECOVERY_LIMITER: unique symbol;
+/**
+ * The TOTP-step {@link AttemptLimiter} (security hardening #9) — keyed per account,
+ * `mfa:pid:<principalId>`, default 5 failures / 15-min window. Consumed in the `/auth/mfa`
+ * TOTP branch: `check` BEFORE the factor is verified (locked → generic 401 without
+ * consulting the step-up), `recordFailure` on a rejected factor (the threshold edge audits
+ * `auth.mfa.locked` once), `reset` on success.
+ */
+export declare const SHIELD_MFA_LIMITER: unique symbol;
+/**
+ * The MFA step-up (security hardening M6) — `MfaStepUp.verify(challenge, credential)`
+ * verifies ONLY the second factor for the principal recorded by the password step (no
+ * password is held between the two requests). Default: `CredentialMfaStepUp` over the
+ * credential resolver, the login TOTP verifier and the identity broker. Absent → the
+ * `/auth/mfa` TOTP branch fails closed (generic 401).
+ */
+export declare const SHIELD_MFA_STEP_UP: unique symbol;
+/**
+ * The LOGIN `totp` {@link FactorVerifier}: the OR-across-devices `OrTotpVerifier` (with the
+ * Redis replay guard, M-B) wrapping the base verifier (the consumer `totpVerifier` override
+ * or the framework RFC-6238 one). ONE instance shared by the composed authenticator and the
+ * MFA step-up, so both paths verify — and replay-guard — identically.
+ */
+export declare const SHIELD_LOGIN_TOTP_VERIFIER: 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
@@ -233,14 +272,16 @@ export declare const SHIELD_RECOVERY_LIMITER: unique symbol;
  * 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).
+ * always-204 anti-enumeration posture is preserved). Fail-open on a Redis blip. Keyed on
+ * `req.ip`, so ENFORCED ONLY when the app set Express `trust proxy` explicitly; otherwise
+ * it is OFF (TrustProxyBootCheck), since a shared proxy IP would drop every reset email.
  */
 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
+ * per ACCOUNT, `forgot:pid:<principalId>` (unknown hint → `forgot:<sha256(canonical)>`),
+ * same PII-free scheme as the login key,
+ * 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
@@ -254,8 +295,9 @@ export declare const SHIELD_FORGOT_HINT_LIMITER: unique symbol;
  * 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`.
+ * `reset` on a successful reset (204). Fail-open on a Redis blip. Keyed on `req.ip`, so
+ * ENFORCED ONLY when the app set Express `trust proxy` explicitly; otherwise it is OFF
+ * (TrustProxyBootCheck), since a shared proxy IP would 429 every reset.
  */
 export declare const SHIELD_RESET_LIMITER: unique symbol;
 /**
@@ -267,4 +309,21 @@ export declare const SHIELD_RESET_LIMITER: unique symbol;
  * or version, which would fail-OPEN).
  */
 export declare const SHIELD_PERMISSION_FACTS: unique symbol;
+/**
+ * The Redis permission-version cache (ADR-0035, GAPS #6) — a
+ * {@link import('../authz/permission-version-cache.js').RedisPermissionVersionCache} over
+ * {@link SHIELD_REDIS}. Provided and exported by `AuthModule` (`auth: true`). Consumed by the
+ * framework-built decision authority (gate 5 reads the version from Redis) and, through the
+ * `@Global` ShieldModule, by `@astram/identity`'s permission-version bumper (publish after commit).
+ * Absent (`auth: false`) → gate 5 keeps the app port's own version read.
+ */
+export declare const SHIELD_PERMISSION_VERSION_CACHE: unique symbol;
+/**
+ * The durable session-restriction store (Phase 3B review P1, ADR-0035 §3) — a
+ * {@link import('../session/session-restriction-store.js').SessionRestrictionStore}. Persists the
+ * recovery-login re-enroll restriction on the durable session and answers the refresh rebuild
+ * (restriction + account status). Provided by `AuthModule` over {@link SHIELD_DB_POOL}. Absent →
+ * the rebuild is refused (401) and recovery logins cannot be marked (they fail closed).
+ */
+export declare const SHIELD_SESSION_RESTRICTIONS: 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;;;;;;;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;AAEvF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,eAA0C,CAAC;AAErF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAU7E;;;;;;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;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,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;AAEvF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,eAA0C,CAAC;AAErF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAU7E;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,eAA4C,CAAC;AAEzF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,eAAwC,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_PERMISSION_FACTS = exports.SHIELD_RESET_LIMITER = exports.SHIELD_FORGOT_HINT_LIMITER = exports.SHIELD_FORGOT_LIMITER = exports.SHIELD_RECOVERY_LIMITER = exports.SHIELD_LOGIN_LIMITER = exports.SHIELD_MEMBERSHIP_CHECKER = exports.SHIELD_SCOPE_SUBTREE_RESOLVER = 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;
+exports.SHIELD_SESSION_RESTRICTIONS = exports.SHIELD_PERMISSION_VERSION_CACHE = exports.SHIELD_PERMISSION_FACTS = exports.SHIELD_RESET_LIMITER = exports.SHIELD_FORGOT_HINT_LIMITER = exports.SHIELD_FORGOT_LIMITER = exports.SHIELD_LOGIN_TOTP_VERIFIER = exports.SHIELD_MFA_STEP_UP = exports.SHIELD_MFA_LIMITER = exports.SHIELD_RECOVERY_LIMITER = exports.SHIELD_LOGIN_IP_LIMITER = exports.SHIELD_LOGIN_LIMITER = exports.SHIELD_MEMBERSHIP_CHECKER = exports.SHIELD_SCOPE_SUBTREE_RESOLVER = 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; } });
 /**
@@ -230,13 +230,29 @@ exports.SHIELD_MEMBERSHIP_CHECKER = Symbol('SHIELD_MEMBERSHIP_CHECKER');
 // 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).
+ * The password-login {@link AttemptLimiter} (spec §5 / IdP-hardening H1) — keyed per
+ * ACCOUNT: `login:pid:<principalId>` for the account the credential store resolves for the
+ * typed hint (the DB collation decides which spellings are one account), else
+ * `login:<sha256(canonical hint)>` for an unknown hint — no PII in the key; see
+ * `rate-limit/canonical-hint.ts`. 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 password-login PER-CLIENT-IP {@link AttemptLimiter} (security hardening #5) —
+ * keyed `login:ip:<req.ip>`, default 50 failures / 15-min window (configurable via
+ * `LOGIN_IP_MAX_FAILURES` / `LOGIN_IP_WINDOW_MS`, see `AppConfig.loginIpLimit`). Caps
+ * password spraying across MANY distinct hints from one client. Counts wrong-password
+ * FAILURES only and is NEVER reset by a success (an attacker's own valid login must not
+ * wipe the budget). Checked before the account lookup and the authenticator. Fails open
+ * on a Redis blip (the limiter's posture). ENFORCED ONLY when the app set Express
+ * `trust proxy` explicitly (0 = no proxy, else the hop count): otherwise every client
+ * behind a proxy shares one `req.ip`, so the limiter is switched OFF at boot with a
+ * warning (`TrustProxyBootCheck`) rather than becoming a global login DoS.
+ */
+exports.SHIELD_LOGIN_IP_LIMITER = Symbol('SHIELD_LOGIN_IP_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
@@ -245,6 +261,29 @@ exports.SHIELD_LOGIN_LIMITER = Symbol('SHIELD_LOGIN_LIMITER');
  * code, `reset` on success.
  */
 exports.SHIELD_RECOVERY_LIMITER = Symbol('SHIELD_RECOVERY_LIMITER');
+/**
+ * The TOTP-step {@link AttemptLimiter} (security hardening #9) — keyed per account,
+ * `mfa:pid:<principalId>`, default 5 failures / 15-min window. Consumed in the `/auth/mfa`
+ * TOTP branch: `check` BEFORE the factor is verified (locked → generic 401 without
+ * consulting the step-up), `recordFailure` on a rejected factor (the threshold edge audits
+ * `auth.mfa.locked` once), `reset` on success.
+ */
+exports.SHIELD_MFA_LIMITER = Symbol('SHIELD_MFA_LIMITER');
+/**
+ * The MFA step-up (security hardening M6) — `MfaStepUp.verify(challenge, credential)`
+ * verifies ONLY the second factor for the principal recorded by the password step (no
+ * password is held between the two requests). Default: `CredentialMfaStepUp` over the
+ * credential resolver, the login TOTP verifier and the identity broker. Absent → the
+ * `/auth/mfa` TOTP branch fails closed (generic 401).
+ */
+exports.SHIELD_MFA_STEP_UP = Symbol('SHIELD_MFA_STEP_UP');
+/**
+ * The LOGIN `totp` {@link FactorVerifier}: the OR-across-devices `OrTotpVerifier` (with the
+ * Redis replay guard, M-B) wrapping the base verifier (the consumer `totpVerifier` override
+ * or the framework RFC-6238 one). ONE instance shared by the composed authenticator and the
+ * MFA step-up, so both paths verify — and replay-guard — identically.
+ */
+exports.SHIELD_LOGIN_TOTP_VERIFIER = Symbol('SHIELD_LOGIN_TOTP_VERIFIER');
 /**
  * The forgot-password IP {@link AttemptLimiter} (feature #141) — keyed
  * `forgot:ip:<clientIp>`, default 5 per 15-min window. Consumed at the TOP of
@@ -252,14 +291,16 @@ exports.SHIELD_RECOVERY_LIMITER = Symbol('SHIELD_RECOVERY_LIMITER');
  * 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).
+ * always-204 anti-enumeration posture is preserved). Fail-open on a Redis blip. Keyed on
+ * `req.ip`, so ENFORCED ONLY when the app set Express `trust proxy` explicitly; otherwise
+ * it is OFF (TrustProxyBootCheck), since a shared proxy IP would drop every reset email.
  */
 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
+ * per ACCOUNT, `forgot:pid:<principalId>` (unknown hint → `forgot:<sha256(canonical)>`),
+ * same PII-free scheme as the login key,
+ * 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
@@ -273,8 +314,9 @@ exports.SHIELD_FORGOT_HINT_LIMITER = Symbol('SHIELD_FORGOT_HINT_LIMITER');
  * 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`.
+ * `reset` on a successful reset (204). Fail-open on a Redis blip. Keyed on `req.ip`, so
+ * ENFORCED ONLY when the app set Express `trust proxy` explicitly; otherwise it is OFF
+ * (TrustProxyBootCheck), since a shared proxy IP would 429 every reset.
  */
 exports.SHIELD_RESET_LIMITER = Symbol('SHIELD_RESET_LIMITER');
 /**
@@ -286,3 +328,20 @@ exports.SHIELD_RESET_LIMITER = Symbol('SHIELD_RESET_LIMITER');
  * or version, which would fail-OPEN).
  */
 exports.SHIELD_PERMISSION_FACTS = Symbol('SHIELD_PERMISSION_FACTS');
+/**
+ * The Redis permission-version cache (ADR-0035, GAPS #6) — a
+ * {@link import('../authz/permission-version-cache.js').RedisPermissionVersionCache} over
+ * {@link SHIELD_REDIS}. Provided and exported by `AuthModule` (`auth: true`). Consumed by the
+ * framework-built decision authority (gate 5 reads the version from Redis) and, through the
+ * `@Global` ShieldModule, by `@astram/identity`'s permission-version bumper (publish after commit).
+ * Absent (`auth: false`) → gate 5 keeps the app port's own version read.
+ */
+exports.SHIELD_PERMISSION_VERSION_CACHE = Symbol('SHIELD_PERMISSION_VERSION_CACHE');
+/**
+ * The durable session-restriction store (Phase 3B review P1, ADR-0035 §3) — a
+ * {@link import('../session/session-restriction-store.js').SessionRestrictionStore}. Persists the
+ * recovery-login re-enroll restriction on the durable session and answers the refresh rebuild
+ * (restriction + account status). Provided by `AuthModule` over {@link SHIELD_DB_POOL}. Absent →
+ * the rebuild is refused (401) and recovery logins cannot be marked (they fail closed).
+ */
+exports.SHIELD_SESSION_RESTRICTIONS = Symbol('SHIELD_SESSION_RESTRICTIONS');

package/dist/authentication/log-email-sender.d.ts

@@ -1,8 +1,13 @@
 /**
- * LogEmailSender — the framework DEV-DEFAULT EmailSender. Does NOT deliver mail; it LOGS the outgoing
- * message (recipient + subject + link) so forgot/reset-password works end-to-end in development with no
- * external provider. A real SMTP/SendGrid sender stays a consumer override for production. Never throws
- * (a logging failure must not fail the forgot-password flow, which is fail-closed/no-op-safe by design).
+ * LogEmailSender — the framework DEV-ONLY EmailSender. Does NOT deliver mail; it LOGS the outgoing
+ * message (recipient + subject + the FULL text, i.e. the live `?token=` reset link) to stdout so
+ * forgot/reset-password works end-to-end in development with no external provider.
+ *
+ * ⛔ It prints usable reset tokens. AuthModule binds it by default ONLY when the RAW `NODE_ENV` is
+ * explicitly `development` or `test` (with a startup warning); in any other environment — including
+ * an UNSET `NODE_ENV` — auth composition fails unless the app supplies a real `emailSender` or
+ * `emailSender: 'disabled'` (security hardening #6). Never throws (a logging failure must not fail
+ * the forgot-password flow, which is fail-closed/no-op-safe by design).
  */
 import type { EmailSender, EmailMessage } from '../auth/ports/email-sender.js';
 export declare class LogEmailSender implements EmailSender {

package/dist/authentication/log-email-sender.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-email-sender.d.ts","sourceRoot":"","sources":["../../src/authentication/log-email-sender.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE/E,qBAAa,cAAe,YAAW,WAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAA4B;IACzE,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAGjD"}
+{"version":3,"file":"log-email-sender.d.ts","sourceRoot":"","sources":["../../src/authentication/log-email-sender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE/E,qBAAa,cAAe,YAAW,WAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAA4B;IACzE,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAKjD"}

package/dist/authentication/mariadb-api-key-store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * MariaDbApiKeyStore — the framework-DEFAULT {@link ApiKeyStore} (ADR-0033), backing
+ * service-account API-key authentication. Persisted in `shield_authz`.`service_account_key`.
+ *
+ * HASH-ONLY (like the reset-token / refresh-token stores): the raw secret is hashed (Argon2id, via
+ * the PasswordHasher) BEFORE it reaches this store — the store holds only `sak_secret_hash`, never
+ * the plaintext. A store breach yields no usable key.
+ *
+ * `getByAccountId` returns the CURRENT (highest-version, non-superseded) key record, or `null` for
+ * an unknown account (anti-enumeration — the authenticator maps null → a uniform failure). Its
+ * scope is the account's LIVE `shield_app.service_account.sa_scope_subtree` (JOINed), never the
+ * copy stored on the key at issue time; a disabled account, a missing account row, or an account
+ * whose tenant disagrees with the key's also yields `null` (security hardening Phase 1C). A genuine
+ * store OUTAGE (the `query` rejecting) PROPAGATES (the authenticator catches it → fail-closed), never
+ * swallowed to null. Every query is parameterized; the hash is never logged.
+ *
+ * The `issue`/`rotate`/`revoke` writer methods are provided for the admin lifecycle (mint + show the
+ * key once elsewhere; here we only persist the HASH + metadata).
+ */
+import type { Pool } from 'mariadb';
+import type { ApiKeyStore, ApiKeyRecord } from '@astram/core';
+export declare class MariaDbApiKeyStore implements ApiKeyStore {
+    private readonly pool;
+    constructor(pool: Pool);
+    getByAccountId(accountId: string): Promise<ApiKeyRecord | null>;
+    /**
+     * Persist a NEW key version for an account (issue or rotate). Only the HASH is stored. `version`
+     * is monotonic per account; the caller mints the secret + computes the hash. Idempotency is on
+     * the natural key `(account, version)`.
+     */
+    putVersion(input: {
+        accountId: string;
+        tenantId: string;
+        scopeSubtreeNodeIds: readonly string[];
+        roleIds: readonly string[];
+        secretHash: string;
+        version: number;
+        expiresAtMs?: number;
+        createdAtMs: number;
+    }): Promise<void>;
+    /** The current highest version for an account (0 if none) — for computing the next on rotate. */
+    currentVersion(accountId: string): Promise<number>;
+    /** Revoke ALL of an account's keys (immediate fail-closed on the next request). Idempotent. */
+    revoke(accountId: string, atMs: number): Promise<void>;
+}
+//# sourceMappingURL=mariadb-api-key-store.d.ts.map

package/dist/authentication/mariadb-api-key-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-api-key-store.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-api-key-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA6C9D,qBAAa,kBAAmB,YAAW,WAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEjC,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA8CrE;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;QACvC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;QAC3B,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBjB,iGAAiG;IAC3F,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQxD,+FAA+F;IACzF,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ7D"}

package/dist/authentication/mariadb-api-key-store.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbApiKeyStore = void 0;
+const AUTHZ = 'shield_authz';
+/** The account rows (`service_account`, created by the identity migration `…018`). */
+const APP = 'shield_app';
+/**
+ * Read a JSON-array column into a `string[]`. The mariadb driver returns a JSON/`longtext` column
+ * EITHER already-parsed (an array/object — its default for JSON columns) OR as a raw string,
+ * depending on driver/column config — so we handle BOTH: an array is filtered to its string
+ * elements directly; a string is `JSON.parse`d first. Anything else (or a parse failure) → `[]`
+ * (fail-safe: an unreadable scope/roles slot yields the empty set, never a crash or a wrong value).
+ */
+function parseJsonArray(v) {
+    const arr = Array.isArray(v)
+        ? v
+        : typeof v === 'string'
+            ? (() => {
+                try {
+                    return JSON.parse(v);
+                }
+                catch {
+                    return [];
+                }
+            })()
+            : [];
+    return Array.isArray(arr) ? arr.filter((x) => typeof x === 'string') : [];
+}
+class MariaDbApiKeyStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async getByAccountId(accountId) {
+        // The CURRENT key = highest version for the account. (Rotation inserts a new version; the old
+        // may linger for an overlap window but only the current is returned for auth.)
+        //
+        // LIVE SCOPE (security hardening Phase 1C): the key row keeps the scope COPIED at issue time,
+        // which goes stale the moment an admin narrows the account. So the account row is JOINed and
+        // its CURRENT `sa_scope_subtree` is the scope returned. An INNER JOIN: a key whose account row
+        // is gone matches nothing → null (deny). This is the same single per-request read as before
+        // (the machine path already reads this store on every `ask_…` request; it is not the session
+        // hot path of invariant #12), now one indexed PK join wider. `shield_core` holds SELECT on
+        // `shield_app.*`, so no grant change.
+        //
+        // LIVE ROLES (security hardening Phase 3, KI #22, ADR-0035): same reasoning for the roles — the
+        // key row's `sak_role_ids` is the issue-time copy; the account's CURRENT `sa_role_ids` (the same
+        // column gate 5's `readRoleIdsForTenant` reads) is what the principal carries, so role-keyed
+        // record rules, list scope and shares see a role change on the next request.
+        const rows = (await this.pool.query(`SELECT k.sak_account_id, k.sak_tenant_id, k.sak_role_ids,
+              k.sak_secret_hash, k.sak_version, k.sak_expires_at_ms, k.sak_revoked_at_ms,
+              sa.sa_scope_subtree, sa.sa_role_ids, sa.sa_status, sa.sa_tenant_id
+         FROM \`${AUTHZ}\`.\`service_account_key\` k
+         JOIN \`${APP}\`.\`service_account\` sa ON sa.sa_id = k.sak_account_id
+        WHERE k.sak_account_id = ?
+        ORDER BY k.sak_version DESC
+        LIMIT 1`, [accountId]));
+        const row = rows[0];
+        if (!row)
+            return null;
+        // Deny (the authenticator's uniform failure) when the account is not active, or when the
+        // account's tenant disagrees with the tenant the key was bound to — the key never carries a
+        // principal into a tenant its account is no longer in.
+        if (row.sa_status !== 'active')
+            return null;
+        if (row.sa_tenant_id !== row.sak_tenant_id)
+            return null;
+        return {
+            accountId: row.sak_account_id,
+            tenantId: row.sak_tenant_id,
+            scopeSubtreeNodeIds: parseJsonArray(row.sa_scope_subtree),
+            roleIds: parseJsonArray(row.sa_role_ids),
+            secretHash: row.sak_secret_hash,
+            version: Number(row.sak_version),
+            ...(row.sak_expires_at_ms !== null ? { expiresAtMs: Number(row.sak_expires_at_ms) } : {}),
+            ...(row.sak_revoked_at_ms !== null ? { revokedAtMs: Number(row.sak_revoked_at_ms) } : {}),
+        };
+    }
+    /**
+     * Persist a NEW key version for an account (issue or rotate). Only the HASH is stored. `version`
+     * is monotonic per account; the caller mints the secret + computes the hash. Idempotency is on
+     * the natural key `(account, version)`.
+     */
+    async putVersion(input) {
+        await this.pool.query(`INSERT INTO \`${AUTHZ}\`.\`service_account_key\`
+         (sak_account_id, sak_tenant_id, sak_scope_subtree, sak_role_ids,
+          sak_secret_hash, sak_version, sak_expires_at_ms, sak_revoked_at_ms, sak_created_at_ms)
+       VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?)`, [
+            input.accountId,
+            input.tenantId,
+            JSON.stringify([...input.scopeSubtreeNodeIds]),
+            JSON.stringify([...input.roleIds]),
+            input.secretHash,
+            input.version,
+            input.expiresAtMs ?? null,
+            input.createdAtMs,
+        ]);
+    }
+    /** The current highest version for an account (0 if none) — for computing the next on rotate. */
+    async currentVersion(accountId) {
+        const rows = (await this.pool.query(`SELECT MAX(sak_version) AS v FROM \`${AUTHZ}\`.\`service_account_key\` WHERE sak_account_id = ?`, [accountId]));
+        return rows[0]?.v != null ? Number(rows[0].v) : 0;
+    }
+    /** Revoke ALL of an account's keys (immediate fail-closed on the next request). Idempotent. */
+    async revoke(accountId, atMs) {
+        await this.pool.query(`UPDATE \`${AUTHZ}\`.\`service_account_key\`
+          SET sak_revoked_at_ms = ?
+        WHERE sak_account_id = ? AND sak_revoked_at_ms IS NULL`, [atMs, accountId]);
+    }
+}
+exports.MariaDbApiKeyStore = MariaDbApiKeyStore;