@astram/guard 0.2.0 → 0.3.0

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

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

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

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

package/dist/auth/totp-enrollment.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Phase 4 MFA-enrollment — the **pure TOTP-enrollment helpers**: generate a fresh
+ * base32 TOTP secret, compose the `otpauth://` provisioning URI an authenticator app
+ * scans, and mint one-time recovery codes.
+ *
+ * ── WHY THIS LIVES IN GUARD (not core) ──────────────────────────────────────
+ * Core owns the TOTP *verifier* (`createTotpFactorVerifier`, RFC 6238) but is
+ * ZERO-dep + node-type-free (ADR-0003), so it cannot mint secrets (needs
+ * `node:crypto.randomBytes`) nor build a URI. Enrollment is the *provisioning* side
+ * — it produces the secret the verifier later checks against. Guard owns node
+ * builtins, so the generation lives here. NO core change: the secret this emits is a
+ * plain base32 string, exactly what `createTotpFactorVerifier` decodes.
+ *
+ * ── SECURITY ─────────────────────────────────────────────────────────────────
+ * The secret + recovery codes are credential material: never logged, returned to the
+ * user exactly ONCE at enrollment, and (recovery codes) stored only Argon2-hashed.
+ * These functions are PURE (no I/O, no storage) — the caller decides what to persist.
+ *
+ * ADR-0003: guard owns `node:crypto`; this file has NO framework/HTTP/DB coupling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateTotpSecret = generateTotpSecret;
+exports.buildOtpauthUri = buildOtpauthUri;
+exports.generateRecoveryCodes = generateRecoveryCodes;
+const node_crypto_1 = require("node:crypto");
+/** RFC 4648 base32 alphabet — the standard TOTP secret encoding (no padding here). */
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+/**
+ * Bytes of entropy behind a generated TOTP secret. 20 bytes = 160 bits → exactly
+ * 32 base32 characters (20 × 8 / 5 = 32, no remainder → no padding), the RFC 4226
+ * recommended HMAC-SHA1 key length.
+ */
+const SECRET_BYTES = 20;
+/** How many recovery codes to mint by default (industry-standard batch of 10). */
+const DEFAULT_RECOVERY_CODE_COUNT = 10;
+/** Bytes per recovery code → 5 bytes = 10 lowercase hex chars, split into two groups. */
+const RECOVERY_CODE_BYTES = 5;
+/**
+ * Encode raw bytes into an RFC 4648 base32 string (no padding). Used to turn the
+ * random secret into the base32 string an authenticator app + the core verifier both
+ * expect. Pure bit-packing: 5 bits per output char, MSB-first.
+ */
+function base32Encode(bytes) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of bytes) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            out += BASE32_ALPHABET[(value >>> bits) & 0x1f];
+        }
+    }
+    if (bits > 0) {
+        // Flush the remaining <5 bits, left-padded with zeros to a full 5-bit group.
+        out += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f];
+    }
+    return out;
+}
+/**
+ * Generate a fresh, cryptographically-random base32 TOTP secret (160 bits → 32
+ * chars). This is what the user's authenticator app is provisioned with and what the
+ * core verifier later checks presented codes against.
+ */
+function generateTotpSecret() {
+    return base32Encode((0, node_crypto_1.randomBytes)(SECRET_BYTES));
+}
+/**
+ * Build the `otpauth://totp/...` provisioning URI an authenticator app scans (or the
+ * user enters manually). `label` identifies the account (shown in the app), `issuer`
+ * names the service. All three URI components are percent-encoded so a label/issuer
+ * with spaces or `:`/`?`/`&` cannot break the URI. Fixed to the defaults the core
+ * verifier uses (SHA-1, 6 digits, 30s period).
+ */
+function buildOtpauthUri(secret, label, issuer) {
+    const encIssuer = encodeURIComponent(issuer);
+    const encLabel = encodeURIComponent(label);
+    return (`otpauth://totp/${encIssuer}:${encLabel}` +
+        `?secret=${secret}&issuer=${encIssuer}&digits=6&period=30`);
+}
+/**
+ * Mint `count` unique one-time recovery codes (each `xxxxx-xxxxx`, 10 lowercase hex
+ * chars grouped for readability). Returned RAW to the caller ONCE at enrollment; the
+ * store persists them Argon2-hashed. Uniqueness is enforced (a hex collision at this
+ * entropy is astronomically unlikely, but the loop guarantees `count` distinct codes).
+ */
+function generateRecoveryCodes(count = DEFAULT_RECOVERY_CODE_COUNT) {
+    const codes = new Set();
+    while (codes.size < count) {
+        const hex = (0, node_crypto_1.randomBytes)(RECOVERY_CODE_BYTES).toString('hex'); // 10 hex chars
+        codes.add(`${hex.slice(0, 5)}-${hex.slice(5)}`);
+    }
+    return [...codes];
+}

package/dist/auth/totp-enrollment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp-enrollment.js","sourceRoot":"","sources":["../../src/auth/totp-enrollment.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;AAiDH,gDAEC;AASD,0CAOC;AAQD,sDAOC;AAhFD,6CAA0C;AAE1C,sFAAsF;AACtF,MAAM,eAAe,GAAG,kCAAkC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,kFAAkF;AAClF,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAEvC,yFAAyF;AACzF,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAiB;IACrC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QAC5B,IAAI,IAAI,CAAC,CAAC;QACV,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC;YACjB,IAAI,IAAI,CAAC,CAAC;YACV,GAAG,IAAI,eAAe,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IACD,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACb,6EAA6E;QAC7E,GAAG,IAAI,eAAe,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB;IAChC,OAAO,YAAY,CAAC,IAAA,yBAAW,EAAC,YAAY,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,MAAc,EAAE,KAAa,EAAE,MAAc;IAC3E,MAAM,SAAS,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,CACL,kBAAkB,SAAS,IAAI,QAAQ,EAAE;QACzC,WAAW,MAAM,WAAW,SAAS,qBAAqB,CAC3D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB,CAAC,QAAgB,2BAA2B;IAC/E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,OAAO,KAAK,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,IAAA,yBAAW,EAAC,mBAAmB,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,eAAe;QAC7E,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC"}

package/dist/authentication/argon2id-password-hasher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argon2id-password-hasher.js","sourceRoot":"","sources":["../../src/authentication/argon2id-password-hasher.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0EH,wDAQC;AAhFD,+CAAiC;AAmBjC,MAAM,cAAc,GAA6B;IAC/C,UAAU,EAAE,MAAM;IAClB,QAAQ,EAAE,CAAC;IACX,WAAW,EAAE,CAAC;CACf,CAAC;AAEF,0EAA0E;AAC7D,QAAA,sBAAsB,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC;AAEvE;;;;GAIG;AACH,MAAa,sBAAsB;IAChB,OAAO,CAAuC;IAE/D,YAAY,SAAyB,EAAE;QACrC,IAAI,CAAC,OAAO,GAAG;YACb,IAAI,EAAE,MAAM,CAAC,QAAQ;YACrB,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,cAAc,CAAC,UAAU;YAC1D,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,cAAc,CAAC,QAAQ;YACpD,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,cAAc,CAAC,WAAW;SAC9D,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,IAAI,CAAC,SAAiB;QAC1B,6EAA6E;QAC7E,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,SAAiB;QAC1C,IAAI,CAAC;YACH,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;YACzE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF;AA/BD,wDA+BC;AAED;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,SAAyB,EAAE;IAIhE,OAAO;QACL,OAAO,EAAE,8BAAsB;QAC/B,QAAQ,EAAE,IAAI,sBAAsB,CAAC,MAAM,CAAC;KAC7C,CAAC;AACJ,CAAC"}

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

@@ -1,20 +1,30 @@
 /**
- * `MariaDbCredentialResolver` — the concrete {@link CredentialResolver} (core
- * port) backed by the `shield_identity.identity_credential` table. Resolves an
- * `identityHint` (username / email) → a {@link ResolvedCredential} the
- * Authentication engine verifies, or `null` for an unknown hint.
+ * `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.
  *
- * ⛔⛔ PHASE 0b PRELUDE SKELETON — the CONTRACT is frozen here; **Team A fills the
- * body**. `resolve()` currently THROWS "not implemented" so a missing Team-A impl
- * fails CLOSED (a broken resolver can NEVER silently authenticate). Do not change
- * the constructor shape (it takes the `SHIELD_DB_POOL`) or the return type — the
- * composition (Team B) and the engine depend on them.
+ * ⛔ 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.
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * THE TABLE CONTRACT Team A must create (infra migration/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 (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):
  *
  *   identity_credential
  *   ┌────────────────────────┬──────────────┬────────────────────────────────────┐
@@ -25,16 +35,16 @@
  *   │ 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_totp_secret         │ VARCHAR(255) │ NULLABLE — base32 TOTP secret;     │
- *   │                        │              │ present ⇒ requiredFactors:[totp]   │
  *   │ 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.)
  *
  * The resolver's SELECT must:
- *   1. `SELECT ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles,
- *       ic_totp_secret FROM shield_identity.identity_credential
+ *   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
  *      (anti-enumeration; MUST NOT throw for an unknown hint; the engine burns a
@@ -43,16 +53,16 @@
  *        passwordHash    = ic_password_hash
  *        claims          = { id: ic_principal_id, tenantId: ic_tenant_id,
  *                            roleIds: <parsed ic_roles> }   // canonical Internal claims
- *        requiredFactors = ic_totp_secret ? [{ factor:'totp', secret: ic_totp_secret }] : []
- *   4. NEVER log the hash, the TOTP secret, or the raw row.
+ *        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).
- *      Team A does NOT need to swallow it, but MUST NOT convert it into a `null`
- *      (that would make an outage look like "unknown user").
+ *      It MUST NOT convert a throw into a `null` (that would make an outage look
+ *      like "unknown user").
  *
  * (`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 superuser flag in the row — superuser is the broker's server-side
+ *  put any root flag in the row — root is the broker's server-side
  *  allowlist, never a claim, per core/identity.)
  * ─────────────────────────────────────────────────────────────────────────────
  *
@@ -88,8 +98,12 @@ export declare class MariaDbCredentialResolver implements CredentialResolver {
      *   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 and TOTP secret are NEVER logged; the raw row is never
-     *   logged. On success they are returned to the engine as verify inputs only.
+     * - 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`.
      */
     resolve(identityHint: string): Promise<ResolvedCredential | null>;
 }

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;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;AAwD/D;;;;;;;GAOG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEvC;;;;;;;;;;;;;;;;OAgBG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

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

@@ -1,21 +1,31 @@
 "use strict";
 /**
- * `MariaDbCredentialResolver` — the concrete {@link CredentialResolver} (core
- * port) backed by the `shield_identity.identity_credential` table. Resolves an
- * `identityHint` (username / email) → a {@link ResolvedCredential} the
- * Authentication engine verifies, or `null` for an unknown hint.
+ * `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.
  *
- * ⛔⛔ PHASE 0b PRELUDE SKELETON — the CONTRACT is frozen here; **Team A fills the
- * body**. `resolve()` currently THROWS "not implemented" so a missing Team-A impl
- * fails CLOSED (a broken resolver can NEVER silently authenticate). Do not change
- * the constructor shape (it takes the `SHIELD_DB_POOL`) or the return type — the
- * composition (Team B) and the engine depend on them.
+ * ⛔ 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.
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * THE TABLE CONTRACT Team A must create (infra migration/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 (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):
  *
  *   identity_credential
  *   ┌────────────────────────┬──────────────┬────────────────────────────────────┐
@@ -26,16 +36,16 @@
  *   │ 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_totp_secret         │ VARCHAR(255) │ NULLABLE — base32 TOTP secret;     │
- *   │                        │              │ present ⇒ requiredFactors:[totp]   │
  *   │ 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.)
  *
  * The resolver's SELECT must:
- *   1. `SELECT ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles,
- *       ic_totp_secret FROM shield_identity.identity_credential
+ *   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
  *      (anti-enumeration; MUST NOT throw for an unknown hint; the engine burns a
@@ -44,16 +54,16 @@
  *        passwordHash    = ic_password_hash
  *        claims          = { id: ic_principal_id, tenantId: ic_tenant_id,
  *                            roleIds: <parsed ic_roles> }   // canonical Internal claims
- *        requiredFactors = ic_totp_secret ? [{ factor:'totp', secret: ic_totp_secret }] : []
- *   4. NEVER log the hash, the TOTP secret, or the raw row.
+ *        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).
- *      Team A does NOT need to swallow it, but MUST NOT convert it into a `null`
- *      (that would make an outage look like "unknown user").
+ *      It MUST NOT convert a throw into a `null` (that would make an outage look
+ *      like "unknown user").
  *
  * (`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 superuser flag in the row — superuser is the broker's server-side
+ *  put any root flag in the row — root is the broker's server-side
  *  allowlist, never a claim, per core/identity.)
  * ─────────────────────────────────────────────────────────────────────────────
  *
@@ -123,14 +133,18 @@ class MariaDbCredentialResolver {
      *   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 and TOTP secret are NEVER logged; the raw row is never
-     *   logged. On success they are returned to the engine as verify inputs only.
+     * - 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`.
      */
     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, ic_totp_secret
+        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]));
@@ -139,9 +153,9 @@ class MariaDbCredentialResolver {
         if (!row) {
             return null;
         }
-        const requiredFactors = row.ic_totp_secret
-            ? [{ factor: 'totp', secret: row.ic_totp_secret }]
-            : [];
+        // Password-only default: no second factor is derived here. MFA is a consumer
+        // concern (custom resolver + MfaDeviceStore), so requiredFactors is always [].
+        const requiredFactors = [];
         return {
             passwordHash: row.ic_password_hash,
             claims: {

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

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-credential-resolver.js","sourceRoot":"","sources":["../../src/authentication/mariadb-credential-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;;;AASH,kFAAkF;AAClF,+CAA+D;AAAtD,uHAAA,0BAA0B,OAAA;AAkBnC;;;;;;;;;;;GAWG;AACH,SAAS,YAAY,CAAC,GAAY,EAAE,IAAY;IAC9C,IAAI,KAAK,GAAY,GAAG,CAAC;IACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,2EAA2E;YAC3E,mDAAmD;YACnD,MAAM,IAAI,KAAK,CACb,oEAAoE,IAAI,IAAI;gBAC1E,2EAA2E,CAC9E,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,KAAK,CACb,qDAAqD,IAAI,oBAAoB;YAC3E,qDAAqD,CACxD,CAAC;IACJ,CAAC;IACD,OAAO,KAA0B,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAa,yBAAyB;IACP;IAA7B,YAA6B,IAAU;QAAV,SAAI,GAAJ,IAAI,CAAM;IAAG,CAAC;IAE3C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,OAAO,CAAC,YAAoB;QAChC,8EAA8E;QAC9E,8EAA8E;QAC9E,8CAA8C;QAC9C,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CACjC;;;gBAGU,EACV,CAAC,YAAY,CAAC,CACf,CAAoB,CAAC;QAEtB,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,+DAA+D;QAC/D,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,IAAI,CAAC;QACd,CAAC;QAED,6EAA6E;QAC7E,+EAA+E;QAC/E,MAAM,eAAe,GAAqB,EAAE,CAAC;QAE7C,OAAO;YACL,YAAY,EAAE,GAAG,CAAC,gBAAgB;YAClC,MAAM,EAAE;gBACN,EAAE,EAAE,GAAG,CAAC,eAAe;gBACvB,QAAQ,EAAE,GAAG,CAAC,YAAY;gBAC1B,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC;aAClD;YACD,eAAe;SAChB,CAAC;IACJ,CAAC;CACF;AAxDD,8DAwDC"}