@astram/guard 0.9.0 → 0.10.1

package/dist/auth/auth.controller.js

@@ -118,6 +118,21 @@ function genericUnauthorized() {
 function retryableUnavailable() {
     throw new common_1.HttpException(RETRYABLE_BODY, common_1.HttpStatus.SERVICE_UNAVAILABLE);
 }
+/**
+ * Phase 9 #10 — count this attempt BEFORE verifying (atomic increment-first). Returns the
+ * verdict, or `null` when no limiter is wired. A limiter that cannot answer throws the
+ * retryable 503: the gate fails CLOSED, never lets an unthrottled guess through.
+ */
+async function consumeOrUnavailable(limiter, key) {
+    if (limiter == null)
+        return null;
+    try {
+        return await limiter.consume(key);
+    }
+    catch {
+        retryableUnavailable();
+    }
+}
 /**
  * The generic 429 for a rate-limited RESET-password (feature #141). Reset is
  * token-gated (a 256-bit single-use token), NOT enumeration-sensitive, so surfacing
@@ -510,15 +525,26 @@ let AuthController = class AuthController {
         // Rate-limit gate (spec §5 / H1 + #5): after M failed attempts within the window —
         // for this ACCOUNT, or from this client IP when per-IP limiting is on — reject BEFORE
         // consulting the authenticator, with the SAME generic 401 as a wrong password
-        // (anti-enumeration: a locked-out account is indistinguishable). Each limiter fails
-        // OPEN on a Redis blip (its own posture — never a lockout from an outage).
+        // (anti-enumeration: a locked-out account is indistinguishable).
+        //
+        // Phase 9 #10: INCREMENT-FIRST. Each limiter counts THIS attempt atomically before the
+        // password is checked (`consume`), so N parallel guesses get N distinct counts and at
+        // most `maxAttempts` of them reach the authenticator. An attempt that turns out not to
+        // be a failure is given back (`refund`) or cleared (`reset`) below, so the counters
+        // keep their meaning (failures only; the IP counter is never reset by a success). A
+        // Redis error on the gate fails CLOSED (503) — before, it failed open (KI #40).
         //
         // Per-IP first (cheap, no DB): a locked IP never reaches the account lookup.
         const ipLimiter = this.perIp(this.loginIpLimiter);
         const ipKey = (0, canonical_hint_js_1.loginIpKey)(ip);
-        if (ipLimiter != null && !(await ipLimiter.check(ipKey))) {
+        const ipVerdict = await consumeOrUnavailable(ipLimiter, ipKey);
+        if (ipVerdict !== null && !ipVerdict.allowed)
             genericUnauthorized();
-        }
+        /** Give back this attempt's IP count (it was not a password failure). */
+        const refundIp = async () => {
+            if (ipVerdict !== null)
+                await ipLimiter?.refund(ipKey);
+        };
         // F1: key the per-account budget on the account the store resolves for this hint
         // (`login:pid:<id>`; unknown → canonical-hash fallback). A store ERROR fails CLOSED
         // (503), consistent with the authenticator's treatment of a resolver outage.
@@ -527,22 +553,44 @@ let AuthController = class AuthController {
             account = await this.lookupAccount(identityHint);
         }
         catch {
+            await refundIp();
             retryableUnavailable();
         }
         const accountId = (0, canonical_hint_js_1.principalIdOf)(account);
         const loginKey = (0, canonical_hint_js_1.loginHintKey)(identityHint, accountId);
-        const hintAllowed = this.loginLimiter == null || (await this.loginLimiter.check(loginKey));
-        if (!hintAllowed) {
-            // Already locked → generic 401. We do NOT audit here: `check()` returns false on
-            // EVERY attempt once locked, so auditing at this gate would flood one event per
-            // attempt. The lockout is audited ONCE on the TRANSITION instead — in the
-            // wrong-password branch below, when recordFailure's count first hits the threshold
-            // (feature #140 audit-on-the-edge, anti-flood).
+        let hintVerdict;
+        try {
+            hintVerdict = await consumeOrUnavailable(this.loginLimiter, loginKey);
+        }
+        catch (err) {
+            await refundIp();
+            throw err;
+        }
+        if (hintVerdict !== null && !hintVerdict.allowed) {
+            // Already locked → generic 401. We do NOT audit here: every attempt past the limit
+            // lands here, so auditing at this gate would flood one event per attempt. The lockout
+            // is audited ONCE on the TRANSITION instead — in the wrong-password branch below,
+            // when the attempt's count equals the threshold (feature #140 audit-on-the-edge).
+            // An attempt refused by the account lock is not an IP failure (as before #10).
+            await refundIp();
             genericUnauthorized();
         }
-        const result = await this.authenticator.authenticate(identityHint, [
-            passwordCredential(password),
-        ]);
+        let result;
+        try {
+            result = await this.authenticator.authenticate(identityHint, [passwordCredential(password)]);
+        }
+        catch (err) {
+            // No verdict: give both attempts back, then surface the error.
+            await this.loginLimiter?.refund(loginKey);
+            await refundIp();
+            throw err;
+        }
+        if (result.outcome !== 'rejected') {
+            // Not a password failure (authenticated / mfa_required): the IP counter counts
+            // failures only, and a success must never reset it (so an attacker's own valid login
+            // cannot wipe the budget) — give back just this attempt.
+            await refundIp();
+        }
         if (result.outcome === 'authenticated') {
             // Correct password → clear the login counter (do not carry earlier failures).
             await this.loginLimiter?.reset(loginKey);
@@ -556,7 +604,9 @@ let AuthController = class AuthController {
         if (result.outcome === 'mfa_required') {
             // Password verified, a second factor is outstanding. NOT a failure — but NOT a
             // success either (#9): the login counter is reset only once `/auth/mfa` completes,
-            // so a stolen password cannot loop login→mfa to guess TOTP codes for free.
+            // so a stolen password cannot loop login→mfa to guess TOTP codes for free. This
+            // attempt's own count is given back (Phase 9 #10), leaving earlier failures intact.
+            await this.loginLimiter?.refund(loginKey);
             //
             // M6: record the password step's SUCCESS — the resolved principal, the typed hint,
             // and a fingerprint of the credential it was checked against — NEVER the password.
@@ -584,33 +634,33 @@ let AuthController = class AuthController {
         // else is the generic 401.
         if (result.reason === REASON_AUTH_UNAVAILABLE) {
             // A transient outage is NOT a credential failure — do NOT count it toward the
-            // lockout (avoids a Redis/DB blip storm from locking out everyone).
+            // lockout (avoids a Redis/DB blip storm from locking out everyone): give both
+            // attempts back.
+            await this.loginLimiter?.refund(loginKey);
+            await refundIp();
             retryableUnavailable();
         }
-        // A genuine wrong-password deny → count it toward the lockout window. recordFailure
-        // returns the NEW count; when it first equals the limiter's threshold this attempt
-        // is the one that TRIPPED the lockout — audit `auth.login.locked` exactly ONCE here
-        // (the edge), never on the already-locked check-gate above (which would flood).
+        // A genuine wrong-password deny: the attempt was already counted by `consume` and
+        // stays counted. When its count equals the limiter's threshold this attempt is the one
+        // that TRIPPED the lockout — audit `auth.login.locked` exactly ONCE here (the edge),
+        // never on the already-locked gate above (which would flood).
         // NO notify: this is pre-auth (the caller has not proven ownership), and mailing the
         // account on every lockout would let anyone email-bomb it / confirm it exists
         // (recordSecurityEvent enforces this too).
-        if (this.loginLimiter != null) {
-            const count = await this.loginLimiter.recordFailure(loginKey);
-            if (count === this.loginLimiter.maxAttempts) {
-                this.recordSecurityEvent({
-                    action: 'auth.login.locked',
-                    identityHint,
-                    attributes: { reason: 'rate_limit' },
-                    notify: false,
-                });
-            }
+        if (this.loginLimiter != null && hintVerdict?.count === this.loginLimiter.maxAttempts) {
+            this.recordSecurityEvent({
+                action: 'auth.login.locked',
+                identityHint,
+                attributes: { reason: 'rate_limit' },
+                notify: false,
+            });
         }
-        // #5: count the failure against the client IP too (failures only — a success never
-        // touches this counter, so an attacker's own valid login cannot reset the budget).
-        // Audited once on the edge, with no hint (the IP budget spans many accounts).
-        if (ipLimiter != null) {
-            const ipCount = await ipLimiter.recordFailure(ipKey);
-            if (ipCount === ipLimiter.maxAttempts) {
+        // #5: the failure also stays counted against the client IP (failures only — a success
+        // gives its attempt back and never resets this counter, so an attacker's own valid
+        // login cannot wipe the budget). Audited once on the edge, with no hint (the IP budget
+        // spans many accounts).
+        if (ipLimiter != null && ipVerdict !== null) {
+            if (ipVerdict.count === ipLimiter.maxAttempts) {
                 this.recordSecurityEvent({
                     action: 'auth.login.ip_locked',
                     identityHint: null,
@@ -1090,42 +1140,46 @@ let AuthController = class AuthController {
      * {@link MfaStepUp} (same `OrTotpVerifier` + replay guard as the authenticator, principal
      * minted by the identity broker).
      *
-     *  - `mfa:pid:<principalId>` is checked BEFORE verifying: locked → generic 401 and the
-     *    step-up is never consulted.
-     *  - a rejected code records a failure; the edge where the count first reaches the
-     *    threshold audits `auth.mfa.locked` ONCE (no notify — pre-auth, see recovery lockout).
-     *  - a transient outage → 503, never counted.
+     *  - the attempt is counted against `mfa:pid:<principalId>` BEFORE verifying (Phase 9
+     *    #10, atomic increment-first): over budget → generic 401 and the step-up is never
+     *    consulted; limiter unreachable → 503 (fail closed).
+     *  - a rejected code stays counted; the attempt whose count equals the threshold audits
+     *    `auth.mfa.locked` ONCE (no notify — pre-auth, see recovery lockout).
+     *  - a transient outage → 503, the attempt is given back (never counted).
      *  - success → establish + bind, then reset the TOTP counter AND the login counter (the
      *    login counter is reset only here, once authentication fully succeeded).
      */
     async completeViaTotp(pending, code) {
         const mfaKey = `mfa:pid:${pending.principalId}`;
-        if (this.mfaLimiter != null && !(await this.mfaLimiter.check(mfaKey))) {
-            genericUnauthorized();
-        }
         const stepUp = this.mfaStepUp;
         if (stepUp == null)
             genericUnauthorized(); // not wired → fail closed
+        // Phase 9 #10: count the attempt FIRST (atomic), so parallel guesses cannot all pass a
+        // read-only check. Over budget → generic 401; limiter unreachable → 503 (fail closed).
+        const verdict = await consumeOrUnavailable(this.mfaLimiter, mfaKey);
+        if (verdict !== null && !verdict.allowed)
+            genericUnauthorized();
         let outcome;
         try {
             outcome = await stepUp.verify(pending, totpCredential(code));
         }
         catch {
-            retryableUnavailable();
+            outcome = { outcome: 'unavailable' };
         }
-        if (outcome.outcome === 'unavailable')
+        if (outcome.outcome === 'unavailable') {
+            // A transient outage is not a wrong code: give the attempt back (never counted).
+            await this.mfaLimiter?.refund(mfaKey);
             retryableUnavailable();
+        }
         if (outcome.outcome !== 'authenticated' || outcome.principal.id !== pending.principalId) {
-            if (this.mfaLimiter != null) {
-                const count = await this.mfaLimiter.recordFailure(mfaKey);
-                if (count === this.mfaLimiter.maxAttempts) {
-                    this.recordSecurityEvent({
-                        action: 'auth.mfa.locked',
-                        actorId: pending.principalId,
-                        attributes: { reason: 'rate_limit' },
-                        notify: false,
-                    });
-                }
+            // The attempt stays counted; the edge (count === threshold) audits ONCE.
+            if (this.mfaLimiter != null && verdict?.count === this.mfaLimiter.maxAttempts) {
+                this.recordSecurityEvent({
+                    action: 'auth.mfa.locked',
+                    actorId: pending.principalId,
+                    attributes: { reason: 'rate_limit' },
+                    notify: false,
+                });
             }
             genericUnauthorized();
         }
@@ -1176,34 +1230,32 @@ let AuthController = class AuthController {
         // consulting the recovery store — the SAME generic 401 as a wrong code (no leak
         // of "rate-limited"; the store is never even touched when locked). Keyed by the
         // RESOLVED principalId (recovery codes don't rotate → a lower ceiling than login).
-        // Fails OPEN on a Redis blip (the limiter's own posture — never a lockout).
+        // Phase 9 #10: the attempt is counted FIRST (atomic increment-first), so parallel
+        // guesses cannot all pass a read-only check and reach the Argon2 scan. A Redis error on
+        // the gate fails CLOSED (503).
         const recoveryKey = `recovery:${principalId}`;
-        if (this.recoveryLimiter != null && !(await this.recoveryLimiter.check(recoveryKey))) {
+        const verdict = await consumeOrUnavailable(this.recoveryLimiter, recoveryKey);
+        if (verdict !== null && !verdict.allowed)
             genericUnauthorized();
-        }
         // Atomic single-use argon2-verify. A throw is swallowed to `false` → generic
         // 401 (never surface a store error as a distinct outcome).
         const ok = await this.recoveryCodes.consume(principalId, code).catch(() => false);
         if (!ok) {
-            // A wrong (or unmatched) recovery code → count it toward the lockout window,
-            // THEN the identical generic 401. recordFailure returns the new count; when it
-            // first equals the threshold this attempt TRIPPED the lockout — audit
-            // `auth.mfa.recovery_locked` exactly ONCE on that edge (never on the already-locked
-            // check-gate above, which returns false on every attempt = flood).
+            // A wrong (or unmatched) recovery code → the attempt stays counted, THEN the
+            // identical generic 401. When its count equals the threshold this attempt TRIPPED
+            // the lockout — audit `auth.mfa.recovery_locked` exactly ONCE on that edge (never on
+            // the already-locked gate above, which every later attempt hits = flood).
             // NO notify: a locked-out attacker is (by assumption) NOT the account owner, so
             // emailing on every recovery lockout would let an attacker email-bomb the owner —
             // audit-only is safer; the once-per-window edge already dedups it.
-            if (this.recoveryLimiter != null) {
-                const count = await this.recoveryLimiter.recordFailure(recoveryKey);
-                if (count === this.recoveryLimiter.maxAttempts) {
-                    this.recordSecurityEvent({
-                        action: 'auth.mfa.recovery_locked',
-                        actorId: principalId,
-                        tenantId: typeof claims.tenantId === 'string' ? claims.tenantId : null,
-                        attributes: { reason: 'rate_limit' },
-                        notify: false,
-                    });
-                }
+            if (this.recoveryLimiter != null && verdict?.count === this.recoveryLimiter.maxAttempts) {
+                this.recordSecurityEvent({
+                    action: 'auth.mfa.recovery_locked',
+                    actorId: principalId,
+                    tenantId: typeof claims.tenantId === 'string' ? claims.tenantId : null,
+                    attributes: { reason: 'rate_limit' },
+                    notify: false,
+                });
             }
             genericUnauthorized();
         }

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

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

package/dist/auth/auth.module.js

@@ -328,8 +328,8 @@ const pendingMfaStoreProvider = {
 };
 /**
  * The TOTP-step limiter (#9) — 5 failures / 15-min window, keyed `mfa:pid:<principalId>`.
- * Checked before the factor is verified; fails open on a Redis outage like every limiter
- * (the code itself still gates — and its replay guard fails closed).
+ * Each attempt is counted before the factor is verified (Phase 9 #10, increment-first);
+ * a Redis outage fails closed (503), like its replay guard.
  */
 const mfaLimiterProvider = {
     provide: tokens_js_1.SHIELD_MFA_LIMITER,
@@ -366,8 +366,9 @@ const authBootLogger = new common_1.Logger('ShieldAuth');
  * the DB collation maps to one account shares one budget; an unknown hint falls back to
  * `login:<sha256(canonical hint)>`; no PII in the Redis key). Same
  * live-Redis provider pattern as {@link sessionTokenBinderProvider} (a `useFactory`
- * injecting {@link SHIELD_REDIS}); provided only under `auth: true`. Fail-open on a
- * Redis outage is the limiter's own behavior (never locks out on a blip).
+ * injecting {@link SHIELD_REDIS}); provided only under `auth: true`. Each attempt is
+ * counted before the password is checked (Phase 9 #10, increment-first); a Redis outage
+ * fails closed (503) — login could not bind a session then anyway.
  */
 const loginLimiterProvider = {
     provide: tokens_js_1.SHIELD_LOGIN_LIMITER,
@@ -379,8 +380,9 @@ const loginLimiterProvider = {
  * Redis-injected {@link AttemptLimiter} keyed `login:ip:<req.ip>`, default 50 failures /
  * 15-min window, configurable through `AppConfig.loginIpLimit` (env
  * `LOGIN_IP_MAX_FAILURES` / `LOGIN_IP_WINDOW_MS`). Stops password spraying across many
- * distinct hints from one client. Failures only; never reset on success. Fails open on
- * a Redis outage like every limiter. ENFORCED ONLY when the app set Express `trust proxy`
+ * distinct hints from one client. Failures only (a non-failure gives its attempt back);
+ * never reset on success. Counted before the password check (Phase 9 #10); a Redis outage
+ * fails closed (503). ENFORCED ONLY when the app set Express `trust proxy`
  * explicitly (0 = no proxy, else the hop count); otherwise {@link TrustProxyBootCheck}
  * switches it OFF at boot with a warning, because every client behind a proxy would share
  * one IP and 50 failures would lock everyone out.
@@ -395,7 +397,8 @@ const loginIpLimiterProvider = {
  * 5 failures / 15-min window, keyed `recovery:<principalId>` (a lower ceiling than
  * login: recovery codes don't rotate, so they're higher-value). Same live-Redis
  * provider pattern as {@link sessionTokenBinderProvider}; provided only under
- * `auth: true`.
+ * `auth: true`. Each attempt is counted before the code is checked (Phase 9 #10); a Redis
+ * outage fails closed (503).
  */
 const recoveryLimiterProvider = {
     provide: tokens_js_1.SHIELD_RECOVERY_LIMITER,

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

@@ -1 +1 @@
-{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../src/auth/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAgB,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,MAAM,SAAS,CAAC;AAC5B,OAAO,EAAoC,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE3F;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAcpD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK,CAc1D;AAED;;;;;;GAMG;AACH,qBACa,mBAAoB,YAAW,eAAe;IAEvD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK;IAGzB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAavC"}
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../src/auth/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAgB,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,MAAM,SAAS,CAAC;AAC5B,OAAO,EAAoC,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE3F;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAcpD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK,CAgB1D;AAED;;;;;;GAMG;AACH,qBACa,mBAAoB,YAAW,eAAe;IAEvD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK;IAGzB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAavC"}

package/dist/auth/connections.js

@@ -81,7 +81,9 @@ function createRedisClient(config) {
     // back instead of failing closed (ADR-0013: "if Redis cannot answer, the request is denied").
     // Now each command fails after `commandTimeout` (default 2 s, `REDIS_COMMAND_TIMEOUT_MS`) or
     // after one reconnect attempt; every caller treats a Redis error as its fail-closed outcome
-    // (401 / 503), except the rate limiters, which fail OPEN by design (never a lockout blip).
+    // (401 / 503). The attempt limiters' increment-first gate (`consume`, Phase 9 #10: login,
+    // /auth/mfa, change-password, the code-gated account MFA routes) fails closed too; only
+    // the read-only `check` (forgot/reset-password) still fails OPEN (never a lockout blip).
     // Reconnects keep ioredis's default strategy. Nothing in the framework relies on queued
     // commands (no pub/sub, no blocking reads, no MULTI/pipeline).
     return new ioredis_1.default(config.redis.url, {

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

@@ -1,16 +1,27 @@
 /**
- * `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>`).
+ * `AttemptLimiter` — a guard-owned, Redis-backed FIXED-WINDOW attempt counter for
+ * anti-brute-force on the auth surface (spec §5). The window starts at the first counted
+ * attempt (`PEXPIRE windowMs`) and is not extended by later ones; the counter resets when
+ * it expires or on a success. One class, one instance per DI token with its own threshold:
+ * `SHIELD_LOGIN_LIMITER` (`login:pid:<id>`, shared by `/auth/login` and change-password),
+ * the per-IP login limiter, `SHIELD_MFA_LIMITER` (`mfa:pid:<id>`, `/auth/mfa` TOTP and the
+ * code-gated account MFA routes), `SHIELD_RECOVERY_LIMITER` (`/auth/mfa` recovery codes),
+ * and the forgot/reset-password limiters.
  *
  * ── CONTRACT ─────────────────────────────────────────────────────────────────
+ *   consume(key)       → Phase 9 #10, the gate for credential-verifying routes (login,
+ *                        /auth/mfa, change-password, the code-gated account MFA routes):
+ *                        atomically COUNTS this attempt first and returns
+ *                        `{ allowed: count <= maxAttempts, count }`. Parallel guesses get
+ *                        distinct counts, so at most `maxAttempts` reach the verifier.
+ *                        FAILS CLOSED: a Redis error throws (caller → 503).
+ *   refund(key)        → give back one consumed attempt that reached no verdict
+ *                        (transient outage; a step that is not a failure). Best-effort.
  *   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).
+ *                        auto-expires (a fixed window from the first failure).
  *                        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.
@@ -21,7 +32,10 @@
  *   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) ──────────────────────
+ * ── FAIL-OPEN-WITH-LOG (spec §5) — the read-only `check()` path only ──────────
+ *   (`consume()` fails CLOSED instead — Phase 9 #10; the routes that use it also need
+ *   Redis to bind or resolve a session, so failing closed locks no one out who could
+ *   otherwise have signed in.) `check()` remains for forgot/reset-password, where:
  *   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
@@ -30,16 +44,42 @@
  *   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.
+ * ── WHAT A LOCK ANSWERS ── the limiter itself is silent; the caller decides. On the
+ *   unauthenticated `/auth/*` routes a lock is the SAME generic 401 as a wrong password /
+ *   wrong code, so a locked-out account is indistinguishable from a bad credential. On the
+ *   authenticated `/account/*` routes (change-password, MFA device remove, recovery-code
+ *   regenerate) the caller already holds a session, so a lock answers 429 (Phase 8 #1,
+ *   Phase 9 #3).
  *
  * 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). */
+/**
+ * Phase 9 #10 — the atomic increment-first step: count the attempt and arm the window TTL
+ * in one script, so the counter can never be left without an expiry between two commands.
+ * The TTL is also re-armed when the key somehow has none (`PTTL == -1`), so a counter
+ * left persistent by an older non-atomic write heals instead of locking forever.
+ */
+export declare const ATTEMPT_CONSUME_SCRIPT = "local n = redis.call('INCR', KEYS[1])\nif n == 1 or redis.call('PTTL', KEYS[1]) == -1 then\n  redis.call('PEXPIRE', KEYS[1], ARGV[1])\nend\nreturn n";
+/** Phase 9 #10 — give back one consumed attempt; deletes the key when it reaches zero. */
+export declare const ATTEMPT_REFUND_SCRIPT = "if redis.call('EXISTS', KEYS[1]) == 0 then return 0 end\nlocal n = redis.call('DECR', KEYS[1])\nif n <= 0 then redis.call('DEL', KEYS[1]) end\nreturn n";
+/** The verdict of {@link AttemptLimiter.consume}. */
+export interface AttemptVerdict {
+    /** `true` iff this attempt is within the budget (`count <= maxAttempts`). */
+    readonly allowed: boolean;
+    /** The attempt count in the current window, including this attempt. */
+    readonly count: number;
+}
+/**
+ * Thrown by {@link AttemptLimiter.consume} when Redis cannot answer: the gate fails CLOSED
+ * and the caller answers a retryable 503. Carries no key or Redis detail.
+ */
+export declare class AttemptLimiterUnavailableError extends Error {
+    constructor();
+}
+/** Per-limiter tuning: the failure ceiling and the fixed-window length (ms). */
 export interface AttemptLimiterConfig {
     /** Number of failures within the window that trips the lockout (check → false). */
     readonly maxAttempts: number;
@@ -68,6 +108,30 @@ export declare class AttemptLimiter {
      * brute-force.
      */
     check(key: string): Promise<boolean>;
+    /**
+     * INCREMENT-FIRST attempt gate (Phase 9 #10). Atomically counts THIS attempt (one Lua
+     * `INCR`, arming the window TTL on the first hit) and reports whether it is within the
+     * budget (`count <= maxAttempts`). Call it BEFORE verifying the credential: N parallel
+     * guesses each get a distinct count, so at most `maxAttempts` of them ever reach the
+     * verifier (the old check → verify → recordFailure shape let every in-flight guess pass
+     * the check). The attempt stays counted when the credential is wrong; on success the
+     * caller calls {@link reset}; when the attempt never reached a verdict (a transient
+     * outage, or a step that is not a failure) the caller calls {@link refund}.
+     *
+     * `count === maxAttempts` on a FAILED attempt is the lockout edge (audit-on-the-edge).
+     *
+     * FAILS CLOSED: a Redis error throws {@link AttemptLimiterUnavailableError} (the caller
+     * answers a retryable 503). Unlike {@link check}, an outage never lets an unthrottled
+     * guess through.
+     */
+    consume(key: string): Promise<AttemptVerdict>;
+    /**
+     * Give back one attempt taken by {@link consume} that never reached a verdict (a
+     * transient dependency failure, or a step that is neither failure nor success, e.g. a
+     * password step that now needs a second factor). Removes the key when it reaches zero,
+     * so a refunded first attempt leaves no counter behind. Best-effort, never throws.
+     */
+    refund(key: string): Promise<void>;
     /**
      * 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

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

@@ -1 +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"}
+{"version":3,"file":"attempt-limiter.d.ts","sourceRoot":"","sources":["../../../src/auth/rate-limit/attempt-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAGH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,yJAI1B,CAAC;AAEV,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,4JAGzB,CAAC;AAEV,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;;CAKxD;AAED,gFAAgF;AAChF,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;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAmBnD;;;;;OAKG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxC;;;;;;;;;;;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"}