@astram/guard 0.7.0 → 0.8.0

package/dist/authentication/mariadb-credential-resolver.d.ts

@@ -1,110 +1,124 @@
 /**
  * `MariaDbCredentialResolver` — the framework-DEFAULT concrete
- * {@link CredentialResolver} (core port) backed by the single
- * `shield_identity.identity_credential` table. Resolves an `identityHint`
- * (username / email) → a {@link ResolvedCredential} the Authentication engine
- * verifies, or `null` for an unknown hint.
+ * {@link CredentialResolver} (core port) backed by
+ * `shield_identity.identity_credential` (+ the confirmed rows of
+ * `shield_identity.mfa_device`, through the injected {@link MfaDeviceStore}). Resolves an
+ * `identityHint` (username / email) → a {@link ResolvedCredential} the Authentication
+ * engine verifies, or `null` for an unknown hint.
  *
- * ⛔ PASSWORD-ONLY BY DESIGN. This default resolver reads ONLY the columns the
- * framework's shipped seed (`infra/mariadb/init/30-identity-credential.sql`)
- * actually creates: `ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles`.
- * It therefore ALWAYS returns `requiredFactors: []` — it does NOT provide an
- * MFA/second-factor challenge. There is no TOTP column here: the multi-device MFA
- * model moved authenticator secrets out of `identity_credential` into a separate
- * `mfa_device` table, which the framework ships only as an UNIMPLEMENTED port.
- *
- * MFA / required-factors are a CONSUMER concern, delivered by plugging a custom
- * `credentialResolver` (+ a concrete `MfaDeviceStore`) via `ShieldModule.forRoot`
- * — NOT by this default. See astram3's `IdentityCredentialResolver`, which reads
- * this same table AND folds in the consumer's confirmed authenticators via
- * `listConfirmedSecrets(mfa_device)` to populate `requiredFactors`. That seam is
- * the supported way to add MFA-at-login on top of this password-only default.
+ * ── MFA IS ENFORCED BY DEFAULT (security hardening #7, plan decision D8) ──────────
+ * When constructed with an {@link MfaDeviceStore} (the `AuthModule` default wiring injects
+ * `SHIELD_MFA_DEVICE_STORE`), a principal with ≥1 CONFIRMED device gets ONE `totp`
+ * required factor whose `secret` bundles every confirmed device key, newline-joined — the
+ * format `OrTotpVerifier` unpacks to match ANY device. So a user who enrolled MFA through
+ * `/account/mfa/devices/*` is challenged on every password login. No confirmed device →
+ * `requiredFactors: []` (password-only). A device-store ERROR propagates (fail closed:
+ * the authenticator reports `authentication_unavailable` → 503), never "no MFA".
+ * Constructed WITHOUT a device store, the resolver is password-only (legacy behaviour).
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * THE TABLE CONTRACT (infra seed `infra/mariadb/init/30-identity-credential.sql`,
- * in `shield_identity`; the runtime `shield_core` account already has DML there —
- * no new grant). Columns per spec §3 (prefix `ic_` to match the repo's
- * session-table convention):
+ * THE TABLE CONTRACT (created by `@astram/identity` migration
+ * `1710000000003-CreateIdentityCredential`, in `shield_identity`; the runtime `shield_core`
+ * account has DML there — no new grant). Columns (prefix `ic_`):
  *
  *   identity_credential
  *   ┌────────────────────────┬──────────────┬────────────────────────────────────┐
  *   │ column                 │ type         │ notes                              │
  *   ├────────────────────────┼──────────────┼────────────────────────────────────┤
- *   │ ic_identity_hint       │ VARCHAR(255) │ UNIQUE — the login key (user/email)│
+ *   │ ic_identity_hint       │ VARCHAR(255) │ PK — the login key (user/email)    │
  *   │ ic_password_hash       │ VARCHAR(255) │ Argon2id encoded hash (verify in)  │
  *   │ ic_principal_id        │ VARCHAR(255) │ → ResolvedCredential.claims.id     │
  *   │ ic_tenant_id           │ VARCHAR(255) │ → claims.tenantId                  │
- *   │ ic_roles               │ JSON / TEXT  │ role-id array → claims.roleIds     │
+ *   │ ic_roles               │ JSON         │ role-id array → claims.roleIds     │
  *   │ ic_created_at_ms       │ BIGINT       │ UTC epoch ms (platform sets UTC)   │
  *   │ ic_updated_at_ms       │ BIGINT       │ UTC epoch ms                       │
  *   └────────────────────────┴──────────────┴────────────────────────────────────┘
- *   PRIMARY KEY / UNIQUE on ic_identity_hint (single-row resolve by hint).
- *   (No `ic_totp_secret` column — MFA secrets live in the consumer's `mfa_device`
- *    table, resolved by a consumer-plugged resolver, not by this default.)
+ *   (No TOTP column — device keys live in `mfa_device`, one row per device.)
  *
- * The resolver's SELECT must:
+ * The resolver:
  *   1. `SELECT ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles
  *       FROM shield_identity.identity_credential
  *       WHERE ic_identity_hint = ? LIMIT 1` (parameterized — NEVER string-built).
- *   2. Return `null` when NO row matches — the ONLY "not found" signal
+ *   2. Returns `null` when NO row matches — the ONLY "not found" signal
  *      (anti-enumeration; MUST NOT throw for an unknown hint; the engine burns a
  *      decoy verify on `null` so timing is uniform).
- *   3. Map a found row → `ResolvedCredential`:
- *        passwordHash    = ic_password_hash
- *        claims          = { id: ic_principal_id, tenantId: ic_tenant_id,
- *                            roleIds: <parsed ic_roles> }   // canonical Internal claims
- *        requiredFactors = []   // ALWAYS empty — password-only default (see above)
- *   4. NEVER log the hash or the raw row.
- *   5. A store outage (connection/query error) MAY throw — the engine treats a
- *      resolver throw as fail-closed `authentication_unavailable` (never a leak).
- *      It MUST NOT convert a throw into a `null` (that would make an outage look
- *      like "unknown user").
+ *   3. Maps a found row → `ResolvedCredential` (`passwordHash`, canonical claims
+ *      `{ id, tenantId, roleIds }`, `requiredFactors` from the confirmed devices).
+ *   4. NEVER logs the hash, a device key, or the raw row.
+ *   5. A store outage (credential OR device query) propagates — the engine treats a
+ *      resolver throw as fail-closed `authentication_unavailable`. It MUST NOT be
+ *      converted into `null` or into "no MFA".
  *
- * (`claims.kind` is optional — the Internal adapter defaults an absent kind; add
- *  an `ic_kind` column later if a deployment needs non-`user` principals. Do NOT
- *  put any root flag in the row — root is the broker's server-side
- *  allowlist, never a claim, per core/identity.)
+ * (`claims.kind` is optional — the Internal adapter defaults an absent kind. Do NOT
+ *  put any root flag in the row — root is the broker's server-side allowlist, never a
+ *  claim, per core/identity.)
  * ─────────────────────────────────────────────────────────────────────────────
  *
  * ADR-0003: the concrete DB lives in guard (Core stays zero-dep). ADR-0013/0014:
- * reads `shield_identity` via the hot-path `shield_core` account.
+ * reads `shield_identity` via the runtime `shield_core` account.
  */
 import type { Pool } from 'mariadb';
 import type { CredentialResolver, ResolvedCredential } from '@astram/core';
+import type { MfaDeviceStore } from '../auth/ports/mfa-device-store.js';
 /** DI token for the resolver — re-exported from the shared auth tokens module. */
 export { SHIELD_CREDENTIAL_RESOLVER } from '../auth/tokens.js';
 /**
- * The concrete MariaDB-backed {@link CredentialResolver}. Constructed with the
- * live `shield_core` {@link Pool} (via {@link SHIELD_CREDENTIAL_RESOLVER}'s
- * factory, which injects {@link SHIELD_DB_POOL}). Stateless per call apart from
- * the injected pool.
- *
- * ⛔ SKELETON: `resolve()` throws until Team A implements the SELECT above.
+ * The concrete MariaDB-backed {@link CredentialResolver}. Constructed with the live
+ * `shield_core` {@link Pool} and (default wiring) the {@link MfaDeviceStore}; stateless
+ * per call apart from those two collaborators.
  */
 export declare class MariaDbCredentialResolver implements CredentialResolver {
     private readonly pool;
-    constructor(pool: Pool);
+    /**
+     * The device store whose CONFIRMED keys become the login's `totp` required factor.
+     * Optional only for back-compat (absent → password-only); `AuthModule` always
+     * injects `SHIELD_MFA_DEVICE_STORE`.
+     */
+    private readonly mfaDevices?;
+    /** Clock (epoch-ms) for the users-table re-probe window. */
+    private readonly now;
+    /**
+     * Until when (epoch-ms) the users JOIN is skipped after the table was found missing (errno
+     * 1146). Re-probed after {@link USERS_TABLE_REPROBE_MS}, so a table created later (identity
+     * installed or migrated while the process runs) is enforced without a restart.
+     */
+    private usersTableMissingUntil;
+    constructor(pool: Pool, 
+    /**
+     * The device store whose CONFIRMED keys become the login's `totp` required factor.
+     * Optional only for back-compat (absent → password-only); `AuthModule` always
+     * injects `SHIELD_MFA_DEVICE_STORE`.
+     */
+    mfaDevices?: (Pick<MfaDeviceStore, "listConfirmedSecrets"> | null) | undefined, 
+    /** Clock (epoch-ms) for the users-table re-probe window. */
+    now?: () => number);
     /**
      * Resolve `identityHint` → {@link ResolvedCredential}, or `null` when no such
      * principal exists.
      *
      * - Parameterized SELECT (`WHERE ic_identity_hint = ? LIMIT 1`) — never
      *   string-built, so the hint can never inject SQL.
-     * - **No row ⇒ `null`** — the ONLY "not found" signal (anti-enumeration; the
-     *   engine burns a decoy password verify on `null` so an unknown user is
-     *   indistinguishable from a wrong password by content or timing). We do NOT
-     *   throw for an unknown hint.
-     * - A **query/connection ERROR propagates** (rejects) — an outage is NOT an
-     *   unknown user; the engine treats a resolver throw as fail-closed
-     *   `authentication_unavailable`. We never convert an error into `null` (that
-     *   would mask an outage AND make it look like "no such user").
-     * - The password hash is NEVER logged; the raw row is never logged. On success
-     *   it is returned to the engine as a verify input only.
-     * - **Password-only:** `requiredFactors` is ALWAYS `[]`. This default provides
-     *   no second-factor challenge; MFA-at-login is delivered by a consumer-plugged
-     *   `credentialResolver` (+ `MfaDeviceStore`) — see the class doc header and
-     *   astram3's `IdentityCredentialResolver`.
+     * - **No row ⇒ `null`** — the ONLY "not found" signal (anti-enumeration).
+     * - A **query/connection ERROR propagates** (credential or device read) — an outage
+     *   is NOT an unknown user and NOT "no MFA"; the engine fails closed
+     *   (`authentication_unavailable`).
+     * - **Enrolled MFA is required:** ≥1 confirmed device → one `totp` factor bundling
+     *   the device keys (newline-joined, for `OrTotpVerifier`).
+     * - The password hash and device keys are NEVER logged.
      */
     resolve(identityHint: string): Promise<ResolvedCredential | null>;
+    /**
+     * The credential row + the account status, in ONE indexed lookup: the credential by its hint
+     * (PK), LEFT JOINed to `shield_app.users` by its PK. An app that keeps no `shield_app.users`
+     * table (MariaDB errno 1146) falls back to the credential-only lookup — for 60 s, then the JOIN
+     * is probed again — and has no account status to enforce (the same rule as the guard's session
+     * restriction store). Any other error propagates (fail closed).
+     */
+    private lookup;
+    /**
+     * The principal's required second factors: one `totp` factor bundling every CONFIRMED
+     * device key, or `[]` when none (or no device store wired). A store error propagates.
+     */
+    private requiredFactorsFor;
 }
 //# sourceMappingURL=mariadb-credential-resolver.d.ts.map

package/dist/authentication/mariadb-credential-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb-credential-resolver.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-credential-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EACV,kBAAkB,EAElB,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAEtB,kFAAkF;AAClF,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAqD/D;;;;;;;GAOG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEvC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAgCxE"}
+{"version":3,"file":"mariadb-credential-resolver.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-credential-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,kBAAkB,EAAkB,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAExE,kFAAkF;AAClF,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AA6D/D;;;;GAIG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IAShE,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC5B,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,GAAG;IAhBtB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB,CAAK;gBAGhB,IAAI,EAAE,IAAI;IAC3B;;;;OAIG;IACc,UAAU,CAAC,GAAE,IAAI,CAAC,cAAc,EAAE,sBAAsB,CAAC,GAAG,IAAI,aAAA;IACjF,4DAA4D;IAC3C,GAAG,GAAE,MAAM,MAAiB;IAG/C;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAoCvE;;;;;;OAMG;YACW,MAAM;IAyBpB;;;OAGG;YACW,kBAAkB;CAQjC"}

package/dist/authentication/mariadb-credential-resolver.js

@@ -1,80 +1,72 @@
 "use strict";
 /**
  * `MariaDbCredentialResolver` — the framework-DEFAULT concrete
- * {@link CredentialResolver} (core port) backed by the single
- * `shield_identity.identity_credential` table. Resolves an `identityHint`
- * (username / email) → a {@link ResolvedCredential} the Authentication engine
- * verifies, or `null` for an unknown hint.
+ * {@link CredentialResolver} (core port) backed by
+ * `shield_identity.identity_credential` (+ the confirmed rows of
+ * `shield_identity.mfa_device`, through the injected {@link MfaDeviceStore}). Resolves an
+ * `identityHint` (username / email) → a {@link ResolvedCredential} the Authentication
+ * engine verifies, or `null` for an unknown hint.
  *
- * ⛔ PASSWORD-ONLY BY DESIGN. This default resolver reads ONLY the columns the
- * framework's shipped seed (`infra/mariadb/init/30-identity-credential.sql`)
- * actually creates: `ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles`.
- * It therefore ALWAYS returns `requiredFactors: []` — it does NOT provide an
- * MFA/second-factor challenge. There is no TOTP column here: the multi-device MFA
- * model moved authenticator secrets out of `identity_credential` into a separate
- * `mfa_device` table, which the framework ships only as an UNIMPLEMENTED port.
- *
- * MFA / required-factors are a CONSUMER concern, delivered by plugging a custom
- * `credentialResolver` (+ a concrete `MfaDeviceStore`) via `ShieldModule.forRoot`
- * — NOT by this default. See astram3's `IdentityCredentialResolver`, which reads
- * this same table AND folds in the consumer's confirmed authenticators via
- * `listConfirmedSecrets(mfa_device)` to populate `requiredFactors`. That seam is
- * the supported way to add MFA-at-login on top of this password-only default.
+ * ── MFA IS ENFORCED BY DEFAULT (security hardening #7, plan decision D8) ──────────
+ * When constructed with an {@link MfaDeviceStore} (the `AuthModule` default wiring injects
+ * `SHIELD_MFA_DEVICE_STORE`), a principal with ≥1 CONFIRMED device gets ONE `totp`
+ * required factor whose `secret` bundles every confirmed device key, newline-joined — the
+ * format `OrTotpVerifier` unpacks to match ANY device. So a user who enrolled MFA through
+ * `/account/mfa/devices/*` is challenged on every password login. No confirmed device →
+ * `requiredFactors: []` (password-only). A device-store ERROR propagates (fail closed:
+ * the authenticator reports `authentication_unavailable` → 503), never "no MFA".
+ * Constructed WITHOUT a device store, the resolver is password-only (legacy behaviour).
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * THE TABLE CONTRACT (infra seed `infra/mariadb/init/30-identity-credential.sql`,
- * in `shield_identity`; the runtime `shield_core` account already has DML there —
- * no new grant). Columns per spec §3 (prefix `ic_` to match the repo's
- * session-table convention):
+ * THE TABLE CONTRACT (created by `@astram/identity` migration
+ * `1710000000003-CreateIdentityCredential`, in `shield_identity`; the runtime `shield_core`
+ * account has DML there — no new grant). Columns (prefix `ic_`):
  *
  *   identity_credential
  *   ┌────────────────────────┬──────────────┬────────────────────────────────────┐
  *   │ column                 │ type         │ notes                              │
  *   ├────────────────────────┼──────────────┼────────────────────────────────────┤
- *   │ ic_identity_hint       │ VARCHAR(255) │ UNIQUE — the login key (user/email)│
+ *   │ ic_identity_hint       │ VARCHAR(255) │ PK — the login key (user/email)    │
  *   │ ic_password_hash       │ VARCHAR(255) │ Argon2id encoded hash (verify in)  │
  *   │ ic_principal_id        │ VARCHAR(255) │ → ResolvedCredential.claims.id     │
  *   │ ic_tenant_id           │ VARCHAR(255) │ → claims.tenantId                  │
- *   │ ic_roles               │ JSON / TEXT  │ role-id array → claims.roleIds     │
+ *   │ ic_roles               │ JSON         │ role-id array → claims.roleIds     │
  *   │ ic_created_at_ms       │ BIGINT       │ UTC epoch ms (platform sets UTC)   │
  *   │ ic_updated_at_ms       │ BIGINT       │ UTC epoch ms                       │
  *   └────────────────────────┴──────────────┴────────────────────────────────────┘
- *   PRIMARY KEY / UNIQUE on ic_identity_hint (single-row resolve by hint).
- *   (No `ic_totp_secret` column — MFA secrets live in the consumer's `mfa_device`
- *    table, resolved by a consumer-plugged resolver, not by this default.)
+ *   (No TOTP column — device keys live in `mfa_device`, one row per device.)
  *
- * The resolver's SELECT must:
+ * The resolver:
  *   1. `SELECT ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles
  *       FROM shield_identity.identity_credential
  *       WHERE ic_identity_hint = ? LIMIT 1` (parameterized — NEVER string-built).
- *   2. Return `null` when NO row matches — the ONLY "not found" signal
+ *   2. Returns `null` when NO row matches — the ONLY "not found" signal
  *      (anti-enumeration; MUST NOT throw for an unknown hint; the engine burns a
  *      decoy verify on `null` so timing is uniform).
- *   3. Map a found row → `ResolvedCredential`:
- *        passwordHash    = ic_password_hash
- *        claims          = { id: ic_principal_id, tenantId: ic_tenant_id,
- *                            roleIds: <parsed ic_roles> }   // canonical Internal claims
- *        requiredFactors = []   // ALWAYS empty — password-only default (see above)
- *   4. NEVER log the hash or the raw row.
- *   5. A store outage (connection/query error) MAY throw — the engine treats a
- *      resolver throw as fail-closed `authentication_unavailable` (never a leak).
- *      It MUST NOT convert a throw into a `null` (that would make an outage look
- *      like "unknown user").
+ *   3. Maps a found row → `ResolvedCredential` (`passwordHash`, canonical claims
+ *      `{ id, tenantId, roleIds }`, `requiredFactors` from the confirmed devices).
+ *   4. NEVER logs the hash, a device key, or the raw row.
+ *   5. A store outage (credential OR device query) propagates — the engine treats a
+ *      resolver throw as fail-closed `authentication_unavailable`. It MUST NOT be
+ *      converted into `null` or into "no MFA".
  *
- * (`claims.kind` is optional — the Internal adapter defaults an absent kind; add
- *  an `ic_kind` column later if a deployment needs non-`user` principals. Do NOT
- *  put any root flag in the row — root is the broker's server-side
- *  allowlist, never a claim, per core/identity.)
+ * (`claims.kind` is optional — the Internal adapter defaults an absent kind. Do NOT
+ *  put any root flag in the row — root is the broker's server-side allowlist, never a
+ *  claim, per core/identity.)
  * ─────────────────────────────────────────────────────────────────────────────
  *
  * ADR-0003: the concrete DB lives in guard (Core stays zero-dep). ADR-0013/0014:
- * reads `shield_identity` via the hot-path `shield_core` account.
+ * reads `shield_identity` via the runtime `shield_core` account.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MariaDbCredentialResolver = exports.SHIELD_CREDENTIAL_RESOLVER = void 0;
 /** DI token for the resolver — re-exported from the shared auth tokens module. */
 var tokens_js_1 = require("../auth/tokens.js");
 Object.defineProperty(exports, "SHIELD_CREDENTIAL_RESOLVER", { enumerable: true, get: function () { return tokens_js_1.SHIELD_CREDENTIAL_RESOLVER; } });
+/** MariaDB `ER_NO_SUCH_TABLE`: the app keeps no `shield_app.users` table. */
+const ER_NO_SUCH_TABLE = 1146;
+/** How long the credential-only fallback is used before the users JOIN is tried again. */
+const USERS_TABLE_REPROBE_MS = 60_000;
 /**
  * Normalize the stored `ic_roles` into a role-id string array. Accepts BOTH:
  *   - a native `string[]` (the mariadb `JSON`-column driver already parsed it);
@@ -107,17 +99,32 @@ function parseRoleIds(raw, hint) {
     return value;
 }
 /**
- * The concrete MariaDB-backed {@link CredentialResolver}. Constructed with the
- * live `shield_core` {@link Pool} (via {@link SHIELD_CREDENTIAL_RESOLVER}'s
- * factory, which injects {@link SHIELD_DB_POOL}). Stateless per call apart from
- * the injected pool.
- *
- * ⛔ SKELETON: `resolve()` throws until Team A implements the SELECT above.
+ * The concrete MariaDB-backed {@link CredentialResolver}. Constructed with the live
+ * `shield_core` {@link Pool} and (default wiring) the {@link MfaDeviceStore}; stateless
+ * per call apart from those two collaborators.
  */
 class MariaDbCredentialResolver {
     pool;
-    constructor(pool) {
+    mfaDevices;
+    now;
+    /**
+     * Until when (epoch-ms) the users JOIN is skipped after the table was found missing (errno
+     * 1146). Re-probed after {@link USERS_TABLE_REPROBE_MS}, so a table created later (identity
+     * installed or migrated while the process runs) is enforced without a restart.
+     */
+    usersTableMissingUntil = 0;
+    constructor(pool, 
+    /**
+     * The device store whose CONFIRMED keys become the login's `totp` required factor.
+     * Optional only for back-compat (absent → password-only); `AuthModule` always
+     * injects `SHIELD_MFA_DEVICE_STORE`.
+     */
+    mfaDevices, 
+    /** Clock (epoch-ms) for the users-table re-probe window. */
+    now = Date.now) {
         this.pool = pool;
+        this.mfaDevices = mfaDevices;
+        this.now = now;
     }
     /**
      * Resolve `identityHint` → {@link ResolvedCredential}, or `null` when no such
@@ -125,46 +132,82 @@ class MariaDbCredentialResolver {
      *
      * - Parameterized SELECT (`WHERE ic_identity_hint = ? LIMIT 1`) — never
      *   string-built, so the hint can never inject SQL.
-     * - **No row ⇒ `null`** — the ONLY "not found" signal (anti-enumeration; the
-     *   engine burns a decoy password verify on `null` so an unknown user is
-     *   indistinguishable from a wrong password by content or timing). We do NOT
-     *   throw for an unknown hint.
-     * - A **query/connection ERROR propagates** (rejects) — an outage is NOT an
-     *   unknown user; the engine treats a resolver throw as fail-closed
-     *   `authentication_unavailable`. We never convert an error into `null` (that
-     *   would mask an outage AND make it look like "no such user").
-     * - The password hash is NEVER logged; the raw row is never logged. On success
-     *   it is returned to the engine as a verify input only.
-     * - **Password-only:** `requiredFactors` is ALWAYS `[]`. This default provides
-     *   no second-factor challenge; MFA-at-login is delivered by a consumer-plugged
-     *   `credentialResolver` (+ `MfaDeviceStore`) — see the class doc header and
-     *   astram3's `IdentityCredentialResolver`.
+     * - **No row ⇒ `null`** — the ONLY "not found" signal (anti-enumeration).
+     * - A **query/connection ERROR propagates** (credential or device read) — an outage
+     *   is NOT an unknown user and NOT "no MFA"; the engine fails closed
+     *   (`authentication_unavailable`).
+     * - **Enrolled MFA is required:** ≥1 confirmed device → one `totp` factor bundling
+     *   the device keys (newline-joined, for `OrTotpVerifier`).
+     * - The password hash and device keys are NEVER logged.
      */
     async resolve(identityHint) {
         // A failed query rejects out of here unchanged (fail-closed): we deliberately
         // do NOT wrap this in a try/catch that returns null — only a genuine "no row"
         // maps to null (below), never a store outage.
-        const rows = (await this.pool.query(`SELECT ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles
-         FROM shield_identity.identity_credential
-        WHERE ic_identity_hint = ?
-        LIMIT 1`, [identityHint]));
+        const rows = await this.lookup(identityHint);
         const row = rows[0];
         // Unknown hint → null (anti-enumeration). MUST NOT throw here.
         if (!row) {
             return null;
         }
-        // Password-only default: no second factor is derived here. MFA is a consumer
-        // concern (custom resolver + MfaDeviceStore), so requiredFactors is always [].
-        const requiredFactors = [];
+        const roleIds = parseRoleIds(row.ic_roles, identityHint);
+        // The device read runs for a disabled account too, so it does the same work as an active one.
+        const requiredFactors = await this.requiredFactorsFor(row.ic_principal_id);
+        // DISABLED ACCOUNT (security hardening Phase 3): `shield_app.users.u_status` set and not
+        // `active` → answered exactly like an unknown hint. The core authenticator then runs its decoy
+        // verify and returns the SAME generic rejection as a wrong password — no "disabled" oracle.
+        // The MFA step-up and the recovery-code branch re-resolve through this resolver, so they refuse
+        // too. No users row (a principal kept elsewhere) → unchanged.
+        if (typeof row.u_status === 'string' && row.u_status !== 'active') {
+            return null;
+        }
         return {
             passwordHash: row.ic_password_hash,
             claims: {
                 id: row.ic_principal_id,
                 tenantId: row.ic_tenant_id,
-                roleIds: parseRoleIds(row.ic_roles, identityHint),
+                roleIds,
             },
             requiredFactors,
         };
     }
+    /**
+     * The credential row + the account status, in ONE indexed lookup: the credential by its hint
+     * (PK), LEFT JOINed to `shield_app.users` by its PK. An app that keeps no `shield_app.users`
+     * table (MariaDB errno 1146) falls back to the credential-only lookup — for 60 s, then the JOIN
+     * is probed again — and has no account status to enforce (the same rule as the guard's session
+     * restriction store). Any other error propagates (fail closed).
+     */
+    async lookup(identityHint) {
+        if (this.now() >= this.usersTableMissingUntil) {
+            try {
+                return (await this.pool.query(`SELECT ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles, u.u_status
+             FROM shield_identity.identity_credential
+             LEFT JOIN shield_app.users u ON u.u_uuid = ic_principal_id
+            WHERE ic_identity_hint = ?
+            LIMIT 1`, [identityHint]));
+            }
+            catch (err) {
+                if (err.errno !== ER_NO_SUCH_TABLE)
+                    throw err;
+                this.usersTableMissingUntil = this.now() + USERS_TABLE_REPROBE_MS;
+            }
+        }
+        return (await this.pool.query(`SELECT ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles
+         FROM shield_identity.identity_credential
+        WHERE ic_identity_hint = ?
+        LIMIT 1`, [identityHint]));
+    }
+    /**
+     * The principal's required second factors: one `totp` factor bundling every CONFIRMED
+     * device key, or `[]` when none (or no device store wired). A store error propagates.
+     */
+    async requiredFactorsFor(principalId) {
+        const store = this.mfaDevices;
+        if (store === undefined || store === null)
+            return [];
+        const keys = (await store.listConfirmedSecrets(principalId)).filter((k) => typeof k === 'string' && k.trim() !== '');
+        return keys.length > 0 ? [{ factor: 'totp', secret: keys.join('\n') }] : [];
+    }
 }
 exports.MariaDbCredentialResolver = MariaDbCredentialResolver;

package/dist/authentication/mariadb-credential-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb-credential-writer.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-credential-writer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAI3E,qBAAa,uBAAwB,YAAW,gBAAgB;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAQ,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAhC,IAAI,EAAE,IAAI,EAAmB,GAAG,GAAE,MAAM,MAAiB;IAEhF,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrE,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAOnE"}
+{"version":3,"file":"mariadb-credential-writer.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-credential-writer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAM3E,qBAAa,uBAAwB,YAAW,gBAAgB;IAE5D,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,IAAI,EAAE,IAAI,EACV,GAAG,GAAE,MAAM,MAAiB;IAGzC,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrE,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAOnE"}

package/dist/authentication/mariadb-or-totp-verifier.d.ts

@@ -8,24 +8,42 @@
  * matches ANY device secret — delegating the RFC-6238 arithmetic per secret to the
  * wrapped BASE single-secret verifier.
  *
- * On a match it best-effort stamps `stampUsed` for the matched device (matched by its
- * unique secret — the verify signature is `(credential, secret)` and carries no
+ * REPLAY GUARD (security hardening M-B): when a Redis client is supplied (the `AuthModule`
+ * default), a matched code is CLAIMED with
+ * `SET shield:totp:used:<sha256(deviceKey)>:<code> 1 NX PX 90000` before it counts. A code
+ * already claimed inside the window (±1 step ≈ 90 s) is rejected; a Redis ERROR propagates
+ * (fail closed — this is the login path, not the per-request hot path, so the caller turns
+ * it into `authentication_unavailable`). No device key appears in a Redis key name.
+ *
+ * On an accepted match it best-effort stamps `stampUsed` for the matched device (matched by
+ * its unique secret — the verify signature is `(credential, secret)` and carries no
  * principalId; secrets are high-entropy random so the match is exact). The stamp is
  * fire-and-forget: a stamp failure must NEVER fail a login.
  */
+import type Redis from 'ioredis';
 import type { Credential, FactorVerdict, FactorVerifier } from '@astram/core';
 import type { MfaDeviceStore } from '../auth/ports/mfa-device-store.js';
+/** How long an accepted code stays claimed: the ±1-step window (3 × 30 s). */
+export declare const TOTP_REPLAY_WINDOW_MS = 90000;
+/** The minimal Redis surface the replay guard needs (`SET … PX … NX`). */
+export type TotpReplayStore = Pick<Redis, 'set'>;
 export declare class OrTotpVerifier implements FactorVerifier {
     /** The single-secret RFC-6238 TOTP verifier (delegated to per device secret). */
     private readonly base;
     /** The device store — only `stampUsed` is needed (best-effort last-used stamp). */
     private readonly devices;
+    /** Redis for the replay guard. Absent → no replay guard (legacy behaviour). */
+    private readonly replay?;
     readonly factor: "totp";
     constructor(
     /** The single-secret RFC-6238 TOTP verifier (delegated to per device secret). */
     base: FactorVerifier, 
     /** The device store — only `stampUsed` is needed (best-effort last-used stamp). */
-    devices: Pick<MfaDeviceStore, 'stampUsed'>);
+    devices: Pick<MfaDeviceStore, 'stampUsed'>, 
+    /** Redis for the replay guard. Absent → no replay guard (legacy behaviour). */
+    replay?: (TotpReplayStore | null) | undefined);
     verify(credential: Credential, bundledSecret: string): Promise<FactorVerdict>;
+    /** `true` iff this is the first use of the code for the device (or no guard is wired). */
+    private claim;
 }
 //# sourceMappingURL=mariadb-or-totp-verifier.d.ts.map

package/dist/authentication/mariadb-or-totp-verifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb-or-totp-verifier.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-or-totp-verifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAExE,qBAAa,cAAe,YAAW,cAAc;IAIjD,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAU;;IAGhC,iFAAiF;IAChE,IAAI,EAAE,cAAc;IACrC,mFAAmF;IAClE,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC;IAGvD,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAgBpF"}
+{"version":3,"file":"mariadb-or-totp-verifier.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-or-totp-verifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAExE,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAMjD,qBAAa,cAAe,YAAW,cAAc;IAIjD,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAR1B,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAU;;IAGhC,iFAAiF;IAChE,IAAI,EAAE,cAAc;IACrC,mFAAmF;IAClE,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC;IAC3D,+EAA+E;IAC9D,MAAM,CAAC,GAAE,eAAe,GAAG,IAAI,aAAA;IAG5C,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAoBnF,0FAA0F;YAC5E,KAAK;CAapB"}

package/dist/authentication/mariadb-or-totp-verifier.js

@@ -9,24 +9,41 @@
  * matches ANY device secret — delegating the RFC-6238 arithmetic per secret to the
  * wrapped BASE single-secret verifier.
  *
- * On a match it best-effort stamps `stampUsed` for the matched device (matched by its
- * unique secret — the verify signature is `(credential, secret)` and carries no
+ * REPLAY GUARD (security hardening M-B): when a Redis client is supplied (the `AuthModule`
+ * default), a matched code is CLAIMED with
+ * `SET shield:totp:used:<sha256(deviceKey)>:<code> 1 NX PX 90000` before it counts. A code
+ * already claimed inside the window (±1 step ≈ 90 s) is rejected; a Redis ERROR propagates
+ * (fail closed — this is the login path, not the per-request hot path, so the caller turns
+ * it into `authentication_unavailable`). No device key appears in a Redis key name.
+ *
+ * On an accepted match it best-effort stamps `stampUsed` for the matched device (matched by
+ * its unique secret — the verify signature is `(credential, secret)` and carries no
  * principalId; secrets are high-entropy random so the match is exact). The stamp is
  * fire-and-forget: a stamp failure must NEVER fail a login.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OrTotpVerifier = void 0;
+exports.OrTotpVerifier = exports.TOTP_REPLAY_WINDOW_MS = void 0;
+const node_crypto_1 = require("node:crypto");
+/** How long an accepted code stays claimed: the ±1-step window (3 × 30 s). */
+exports.TOTP_REPLAY_WINDOW_MS = 90_000;
+function replayKey(deviceKey, code) {
+    return `shield:totp:used:${(0, node_crypto_1.createHash)('sha256').update(deviceKey).digest('hex')}:${code}`;
+}
 class OrTotpVerifier {
     base;
     devices;
+    replay;
     factor = 'totp';
     constructor(
     /** The single-secret RFC-6238 TOTP verifier (delegated to per device secret). */
     base, 
     /** The device store — only `stampUsed` is needed (best-effort last-used stamp). */
-    devices) {
+    devices, 
+    /** Redis for the replay guard. Absent → no replay guard (legacy behaviour). */
+    replay) {
         this.base = base;
         this.devices = devices;
+        this.replay = replay;
     }
     async verify(credential, bundledSecret) {
         const secrets = String(bundledSecret ?? '')
@@ -35,14 +52,28 @@ class OrTotpVerifier {
             .filter(Boolean);
         for (const secret of secrets) {
             const verdict = await this.base.verify(credential, secret);
-            if (verdict.satisfied) {
+            if (verdict.satisfied === true) {
+                // M-B: claim the code for this device; a code already used in the window is a
+                // replay → reject. A Redis error propagates (fail closed).
+                if (!(await this.claim(secret, credential)))
+                    return { satisfied: false };
                 // Best-effort last-used stamp for the device whose secret verified; never
                 // awaited into the deny path (a stamp failure must not fail the login).
-                void this.devices.stampUsed(secret);
+                void this.devices.stampUsed(secret).catch(() => undefined);
                 return { satisfied: true };
             }
         }
         return { satisfied: false };
     }
+    /** `true` iff this is the first use of the code for the device (or no guard is wired). */
+    async claim(deviceKey, credential) {
+        if (this.replay === undefined || this.replay === null)
+            return true;
+        const code = credential.payload?.code;
+        if (typeof code !== 'string' || code === '')
+            return false;
+        const res = await this.replay.set(replayKey(deviceKey, code), '1', 'PX', exports.TOTP_REPLAY_WINDOW_MS, 'NX');
+        return res === 'OK';
+    }
 }
 exports.OrTotpVerifier = OrTotpVerifier;

package/dist/authentication/mariadb-profile-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb-profile-resolver.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-profile-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAe,MAAM,6BAA6B,CAAC;AAMpG,qBAAa,sBAAuB,YAAW,eAAe;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAQ,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAhC,IAAI,EAAE,IAAI,EAAmB,GAAG,GAAE,MAAM,MAAiB;IAEhF,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;YA4BzD,gBAAgB;CAc/B"}
+{"version":3,"file":"mariadb-profile-resolver.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-profile-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAe,MAAM,6BAA6B,CAAC;AAcpG,qBAAa,sBAAuB,YAAW,eAAe;IAE1D,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,IAAI,EAAE,IAAI,EACV,GAAG,GAAE,MAAM,MAAiB;IAGzC,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;YA4BzD,gBAAgB;CAc/B"}