@astram/guard 0.1.0 → 0.2.0

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

@@ -0,0 +1,156 @@
+"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.
+ *
+ * ⛔⛔ 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.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 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):
+ *
+ *   identity_credential
+ *   ┌────────────────────────┬──────────────┬────────────────────────────────────┐
+ *   │ column                 │ type         │ notes                              │
+ *   ├────────────────────────┼──────────────┼────────────────────────────────────┤
+ *   │ ic_identity_hint       │ VARCHAR(255) │ UNIQUE — 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_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).
+ *
+ * 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
+ *       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
+ *      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 = ic_totp_secret ? [{ factor:'totp', secret: ic_totp_secret }] : []
+ *   4. NEVER log the hash, the TOTP secret, 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").
+ *
+ * (`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
+ *  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.
+ */
+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; } });
+/**
+ * Normalize the stored `ic_roles` into a role-id string array. Accepts BOTH:
+ *   - a native `string[]` (the mariadb `JSON`-column driver already parsed it);
+ *   - a JSON string (defensive — a `TEXT` column / `autoJsonMap` disabled), which
+ *     is `JSON.parse`d here.
+ *
+ * A malformed roles value is a DATA-INTEGRITY error, not an unknown user — so this
+ * THROWS (the engine treats a resolver throw as fail-closed
+ * `authentication_unavailable`) rather than silently granting an empty role set (a
+ * silent privilege change) OR crashing later. Anything that is not, after
+ * normalization, an array of strings is rejected the same way.
+ */
+function parseRoleIds(raw, hint) {
+    let value = raw;
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            // Never include the raw blob in the message (defensive; it isn't a secret,
+            // but keep the no-detail-leak discipline uniform).
+            throw new Error(`MariaDbCredentialResolver: malformed ic_roles JSON for identity "${hint}" ` +
+                `(data-integrity error — failing closed rather than granting empty roles).`);
+        }
+    }
+    if (!Array.isArray(value) || !value.every((r) => typeof r === 'string')) {
+        throw new Error(`MariaDbCredentialResolver: ic_roles for identity "${hint}" is not an array ` +
+            `of strings (data-integrity error — failing closed).`);
+    }
+    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.
+ */
+class MariaDbCredentialResolver {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * 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 and TOTP secret are NEVER logged; the raw row is never
+     *   logged. On success they are returned to the engine as verify inputs only.
+     */
+    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
+         FROM shield_identity.identity_credential
+        WHERE ic_identity_hint = ?
+        LIMIT 1`, [identityHint]));
+        const row = rows[0];
+        // Unknown hint → null (anti-enumeration). MUST NOT throw here.
+        if (!row) {
+            return null;
+        }
+        const requiredFactors = row.ic_totp_secret
+            ? [{ factor: 'totp', secret: row.ic_totp_secret }]
+            : [];
+        return {
+            passwordHash: row.ic_password_hash,
+            claims: {
+                id: row.ic_principal_id,
+                tenantId: row.ic_tenant_id,
+                roleIds: parseRoleIds(row.ic_roles, identityHint),
+            },
+            requiredFactors,
+        };
+    }
+}
+exports.MariaDbCredentialResolver = MariaDbCredentialResolver;

package/dist/config/app-config.d.ts

@@ -30,6 +30,76 @@ export interface AppConfig {
     readonly environment: 'development' | 'test' | 'production';
     /** ADR-0018 connection-pool budget (validated at boot, fail-closed). */
     readonly pool: PoolBudgetConfig;
+    /**
+     * The runtime MariaDB connection descriptor (the `shield_core` account — DML on
+     * `shield_identity` where the session + credential tables live). Consumed by
+     * the Phase 0b persistence provider that creates the ONE live `mariadb` Pool.
+     */
+    readonly db: DbConfig;
+    /**
+     * The Redis (hot session tier, ADR-0013) connection descriptor. Consumed by the
+     * Phase 0b persistence provider that creates the ONE live `ioredis` client.
+     */
+    readonly redis: RedisConfig;
+    /**
+     * The keyed-HMAC secret for the refresh-token hasher (`SHIELD_REFRESH_HMAC_KEY`).
+     * ⛔ REQUIRED FOR AUTH — this is a SECRET (a leaked DB would be offline-brute-
+     * forceable without it). {@link loadAppConfig} reads it but does NOT throw when
+     * blank, so the ENFORCEMENT-ONLY scaffold (example-backend / a freshly-scaffolded
+     * app with no auth wired) still boots with no `.env`. The FAIL-CLOSED gate is
+     * {@link assertRefreshHmacKey}, invoked by the auth composition (AuthModule /
+     * persistence factory) at the moment auth is actually wired — so a blank key can
+     * never produce a working-looking authenticator, while a non-auth app is
+     * unaffected. Never logged, never returned to a client.
+     */
+    readonly refreshHmacKey: string;
+    /**
+     * Optional session/token lifetime overrides (ADR-0015). Any omitted field
+     * defaults in `@astram/core`'s `resolveLifetimes` to 15 min access / 14 d idle /
+     * 60 d absolute cap. `Partial` so the composition can hand it straight to
+     * `createSessionAuthority({ lifetimes })`.
+     */
+    readonly lifetimes: SessionLifetimeOverrides;
+}
+/**
+ * The runtime MariaDB connection descriptor. Non-secret host/port/user/database
+ * plus the account password (a secret — supplied via env/secrets-manager, NEVER
+ * committed). Maps 1:1 onto `mariadb`'s `createPool({ host, port, user, password,
+ * database, connectionLimit })`. The pool cap comes from the ADR-0018 budget
+ * (`pool.perAccountMax.shield_core`), NOT duplicated here.
+ */
+export interface DbConfig {
+    readonly host: string;
+    readonly port: number;
+    readonly user: string;
+    /** ⛔ Secret — resolved from env/secrets-manager; never logged. */
+    readonly password: string;
+    readonly database: string;
+}
+/**
+ * The Redis connection descriptor. A single `url` (e.g. `redis://host:6379`) is
+ * the canonical form `ioredis` accepts directly; host/port are provided as a
+ * convenience fallback the persistence provider composes into a url when `url` is
+ * absent.
+ */
+export interface RedisConfig {
+    /** Full connection url (`redis://[:password@]host:port[/db]`). Preferred. */
+    readonly url: string;
+}
+/**
+ * Optional per-deployment overrides for the three ADR-0015 session lifetimes.
+ * Shape mirrors `@astram/core`'s `Partial<SessionLifetimeConfig>` so it is passed
+ * straight into `createSessionAuthority({ lifetimes })` — omitted fields take the
+ * core defaults. Kept as a local shape (not a core import) so this config file
+ * stays a plain env-reader; the composition owns the core wiring.
+ */
+export interface SessionLifetimeOverrides {
+    /** Access-token TTL in ms (core default 15 min). Omitted ⇒ core default. */
+    readonly accessTtlMs?: number;
+    /** Sliding refresh idle window in ms (core default 14 days). */
+    readonly refreshIdleMs?: number;
+    /** Absolute session cap in ms (core default 60 days). */
+    readonly refreshAbsoluteCapMs?: number;
 }
 /**
  * The ADR-0018 connection-pool budget surface. Every field is configurable per
@@ -84,9 +154,72 @@ export declare const SCHEMA_SVC_POOL_HARD_CAP = 2;
  *   perAccountMax.shield_schema_svc ← SHIELD_POOL_MAX_SCHEMA_SVC
  */
 export declare function loadPoolBudget(env?: NodeJS.ProcessEnv): PoolBudgetConfig;
+/** Documented defaults for the runtime MariaDB descriptor (local docker substrate). */
+export declare const DEFAULT_DB_CONFIG: Omit<DbConfig, 'password'>;
+/** Documented default Redis url (local docker substrate). */
+export declare const DEFAULT_REDIS_URL = "redis://localhost:6379";
+/**
+ * Build the runtime {@link DbConfig} from env with documented defaults.
+ * Field ↔ env name:
+ *   host     ← SHIELD_DB_HOST      port     ← SHIELD_DB_PORT
+ *   user     ← SHIELD_DB_USER      password ← SHIELD_DB_PASSWORD (secret)
+ *   database ← SHIELD_DB_NAME
+ * The password defaults to '' when absent — a live connection then fails at
+ * connect time (loud), which is correct for a runtime that needs real creds; the
+ * secret is deliberately NOT hard-required at config load (unlike the HMAC key,
+ * which is a fail-closed security invariant even for unit tests).
+ */
+export declare function loadDbConfig(env?: NodeJS.ProcessEnv): DbConfig;
+/**
+ * Build the {@link RedisConfig} from env. Prefers `SHIELD_REDIS_URL`; falls back
+ * to composing `redis://host:port` from `SHIELD_REDIS_HOST`/`SHIELD_REDIS_PORT`,
+ * else the documented default.
+ */
+export declare function loadRedisConfig(env?: NodeJS.ProcessEnv): RedisConfig;
+/**
+ * Build the optional {@link SessionLifetimeOverrides} from env. Every field is
+ * optional (omitted ⇒ core ADR-0015 default). The bounds validation is the
+ * core's `resolveLifetimes` job (throws LOUD at composition) — this loader only
+ * reads the numbers.
+ * Field ↔ env name:
+ *   accessTtlMs          ← SHIELD_ACCESS_TTL_MS
+ *   refreshIdleMs        ← SHIELD_REFRESH_IDLE_MS
+ *   refreshAbsoluteCapMs ← SHIELD_REFRESH_ABSOLUTE_CAP_MS
+ */
+export declare function loadSessionLifetimes(env?: NodeJS.ProcessEnv): SessionLifetimeOverrides;
+/**
+ * Read the refresh-token HMAC key from env (raw; `''` when absent/blank). Total —
+ * does NOT throw, so {@link loadAppConfig} stays boot-safe for a non-auth scaffold.
+ * The FAIL-CLOSED enforcement lives in {@link assertRefreshHmacKey}. Never logs
+ * the key's value.
+ */
+export declare function loadRefreshHmacKey(env?: NodeJS.ProcessEnv): string;
+/**
+ * ⛔ FAIL-CLOSED GATE for the refresh-token HMAC key. Called by the auth
+ * composition (AuthModule / persistence factory) at the moment auth is wired:
+ * throws LOUD when the key is blank so the app can NEVER compose a working-looking
+ * authenticator/session-authority on an empty HMAC key (a leaked DB would then be
+ * offline-brute-forceable, and every refresh-token hash would be unkeyed). Mirrors
+ * `Sha256RefreshTokenHasher`'s constructor guard but surfaces a clear composition
+ * error. Returns the validated non-empty key. NEVER logs the key's value.
+ *
+ * WHY here and not in `loadAppConfig`: an enforcement-only app (example-backend, a
+ * freshly-scaffolded app with no auth wired) must still boot with no `.env`
+ * (`create-astram-app/template/_env.example` promises exactly this). Gating at the
+ * auth boundary keeps that promise while making auth fail closed the instant it is
+ * actually composed.
+ */
+export declare function assertRefreshHmacKey(key: string): string;
 /**
  * Build the {@link AppConfig} from `process.env` (or an injected env bag, for
- * testability). Pure + side-effect-free so it is trivially unit-testable.
+ * testability). Pure, total, and side-effect-free — trivially unit-testable and
+ * boot-safe with NO `.env`.
+ *
+ * Every Phase 0b field has a documented default (DB/Redis descriptors, lifetimes)
+ * and `refreshHmacKey` is read-but-not-required HERE, so existing callers
+ * (example-backend / template `main.ts`, which read only `.port`) are unaffected.
+ * The refresh-key fail-closed check is deferred to {@link assertRefreshHmacKey} at
+ * auth-composition time (see its doc).
  */
 export declare function loadAppConfig(env?: NodeJS.ProcessEnv): AppConfig;
 /** Result of evaluating a {@link PoolBudgetConfig} against the ADR-0018 budget. */

package/dist/config/app-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-config.d.ts","sourceRoot":"","sources":["../../src/config/app-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,aAAa,GAAG,MAAM,GAAG,YAAY,CAAC;IAC5D,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,wEAAwE;IACxE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,EAAE,gBASjC,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAwB1C;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAuBrF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,CAM7E;AAMD,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,GAAG,oBAAoB,CAgB9E"}
+{"version":3,"file":"app-config.d.ts","sourceRoot":"","sources":["../../src/config/app-config.ts"],"names":[],"mappings":"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"}

package/dist/config/app-config.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SCHEMA_SVC_POOL_HARD_CAP = exports.DEFAULT_POOL_BUDGET = void 0;
+exports.DEFAULT_REDIS_URL = exports.DEFAULT_DB_CONFIG = exports.SCHEMA_SVC_POOL_HARD_CAP = exports.DEFAULT_POOL_BUDGET = void 0;
 exports.loadPoolBudget = loadPoolBudget;
+exports.loadDbConfig = loadDbConfig;
+exports.loadRedisConfig = loadRedisConfig;
+exports.loadSessionLifetimes = loadSessionLifetimes;
+exports.loadRefreshHmacKey = loadRefreshHmacKey;
+exports.assertRefreshHmacKey = assertRefreshHmacKey;
 exports.loadAppConfig = loadAppConfig;
 exports.evaluatePoolBudget = evaluatePoolBudget;
 /** Documented MVP single-node defaults (see the class doc + my.cnf). */
@@ -61,15 +66,152 @@ function loadPoolBudget(env = process.env) {
         },
     };
 }
+// ---------------------------------------------------------------------------
+// Phase 0b Auth-surface config loaders (additive) — DB / Redis / secret /
+// lifetimes. All pure env-readers with documented defaults; the ONLY hard-
+// required value is the refresh HMAC key (fail-closed).
+// ---------------------------------------------------------------------------
+/** Documented defaults for the runtime MariaDB descriptor (local docker substrate). */
+exports.DEFAULT_DB_CONFIG = {
+    host: 'localhost',
+    port: 3306,
+    user: 'shield_core',
+    database: 'shield_identity',
+};
+/** Documented default Redis url (local docker substrate). */
+exports.DEFAULT_REDIS_URL = 'redis://localhost:6379';
+/** Read a string from env with a fallback (trims; blank ⇒ fallback). */
+function parseString(raw, fallback) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    return raw.trim();
+}
+/**
+ * Read an OPTIONAL positive-int env override, or `undefined` when absent/blank/
+ * invalid — so an omitted lifetime falls through to the core default rather than
+ * being coerced to a bogus number. (Distinct from {@link parsePositiveInt}, which
+ * always returns a concrete fallback for the pool budget.)
+ */
+function parseOptionalPositiveInt(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    const n = Number.parseInt(raw, 10);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+/**
+ * Build the runtime {@link DbConfig} from env with documented defaults.
+ * Field ↔ env name:
+ *   host     ← SHIELD_DB_HOST      port     ← SHIELD_DB_PORT
+ *   user     ← SHIELD_DB_USER      password ← SHIELD_DB_PASSWORD (secret)
+ *   database ← SHIELD_DB_NAME
+ * The password defaults to '' when absent — a live connection then fails at
+ * connect time (loud), which is correct for a runtime that needs real creds; the
+ * secret is deliberately NOT hard-required at config load (unlike the HMAC key,
+ * which is a fail-closed security invariant even for unit tests).
+ */
+function loadDbConfig(env = process.env) {
+    return {
+        host: parseString(env.SHIELD_DB_HOST, exports.DEFAULT_DB_CONFIG.host),
+        port: parsePort(env.SHIELD_DB_PORT, exports.DEFAULT_DB_CONFIG.port),
+        user: parseString(env.SHIELD_DB_USER, exports.DEFAULT_DB_CONFIG.user),
+        password: parseString(env.SHIELD_DB_PASSWORD, ''),
+        database: parseString(env.SHIELD_DB_NAME, exports.DEFAULT_DB_CONFIG.database),
+    };
+}
+/**
+ * Build the {@link RedisConfig} from env. Prefers `SHIELD_REDIS_URL`; falls back
+ * to composing `redis://host:port` from `SHIELD_REDIS_HOST`/`SHIELD_REDIS_PORT`,
+ * else the documented default.
+ */
+function loadRedisConfig(env = process.env) {
+    const explicit = env.SHIELD_REDIS_URL;
+    if (explicit !== undefined && explicit.trim() !== '') {
+        return { url: explicit.trim() };
+    }
+    const host = env.SHIELD_REDIS_HOST;
+    const port = env.SHIELD_REDIS_PORT;
+    if ((host !== undefined && host.trim() !== '') || (port !== undefined && port.trim() !== '')) {
+        const h = parseString(host, 'localhost');
+        const p = parsePort(port, 6379);
+        return { url: `redis://${h}:${p}` };
+    }
+    return { url: exports.DEFAULT_REDIS_URL };
+}
+/**
+ * Build the optional {@link SessionLifetimeOverrides} from env. Every field is
+ * optional (omitted ⇒ core ADR-0015 default). The bounds validation is the
+ * core's `resolveLifetimes` job (throws LOUD at composition) — this loader only
+ * reads the numbers.
+ * Field ↔ env name:
+ *   accessTtlMs          ← SHIELD_ACCESS_TTL_MS
+ *   refreshIdleMs        ← SHIELD_REFRESH_IDLE_MS
+ *   refreshAbsoluteCapMs ← SHIELD_REFRESH_ABSOLUTE_CAP_MS
+ */
+function loadSessionLifetimes(env = process.env) {
+    const overrides = {};
+    const access = parseOptionalPositiveInt(env.SHIELD_ACCESS_TTL_MS);
+    const idle = parseOptionalPositiveInt(env.SHIELD_REFRESH_IDLE_MS);
+    const cap = parseOptionalPositiveInt(env.SHIELD_REFRESH_ABSOLUTE_CAP_MS);
+    if (access !== undefined)
+        overrides.accessTtlMs = access;
+    if (idle !== undefined)
+        overrides.refreshIdleMs = idle;
+    if (cap !== undefined)
+        overrides.refreshAbsoluteCapMs = cap;
+    return overrides;
+}
+/**
+ * Read the refresh-token HMAC key from env (raw; `''` when absent/blank). Total —
+ * does NOT throw, so {@link loadAppConfig} stays boot-safe for a non-auth scaffold.
+ * The FAIL-CLOSED enforcement lives in {@link assertRefreshHmacKey}. Never logs
+ * the key's value.
+ */
+function loadRefreshHmacKey(env = process.env) {
+    return parseString(env.SHIELD_REFRESH_HMAC_KEY, '');
+}
+/**
+ * ⛔ FAIL-CLOSED GATE for the refresh-token HMAC key. Called by the auth
+ * composition (AuthModule / persistence factory) at the moment auth is wired:
+ * throws LOUD when the key is blank so the app can NEVER compose a working-looking
+ * authenticator/session-authority on an empty HMAC key (a leaked DB would then be
+ * offline-brute-forceable, and every refresh-token hash would be unkeyed). Mirrors
+ * `Sha256RefreshTokenHasher`'s constructor guard but surfaces a clear composition
+ * error. Returns the validated non-empty key. NEVER logs the key's value.
+ *
+ * WHY here and not in `loadAppConfig`: an enforcement-only app (example-backend, a
+ * freshly-scaffolded app with no auth wired) must still boot with no `.env`
+ * (`create-astram-app/template/_env.example` promises exactly this). Gating at the
+ * auth boundary keeps that promise while making auth fail closed the instant it is
+ * actually composed.
+ */
+function assertRefreshHmacKey(key) {
+    if (typeof key !== 'string' || key.trim() === '') {
+        throw new Error('Shield auth composition: SHIELD_REFRESH_HMAC_KEY is required and must be ' +
+            'non-empty (fail-closed — refusing to compose auth with a blank refresh-token ' +
+            'HMAC key). Set it from your secrets manager; never commit the value.');
+    }
+    return key;
+}
 /**
  * Build the {@link AppConfig} from `process.env` (or an injected env bag, for
- * testability). Pure + side-effect-free so it is trivially unit-testable.
+ * testability). Pure, total, and side-effect-free — trivially unit-testable and
+ * boot-safe with NO `.env`.
+ *
+ * Every Phase 0b field has a documented default (DB/Redis descriptors, lifetimes)
+ * and `refreshHmacKey` is read-but-not-required HERE, so existing callers
+ * (example-backend / template `main.ts`, which read only `.port`) are unaffected.
+ * The refresh-key fail-closed check is deferred to {@link assertRefreshHmacKey} at
+ * auth-composition time (see its doc).
  */
 function loadAppConfig(env = process.env) {
     return {
         port: parsePort(env.PORT, 3000),
         environment: parseEnvironment(env.NODE_ENV),
         pool: loadPoolBudget(env),
+        db: loadDbConfig(env),
+        redis: loadRedisConfig(env),
+        refreshHmacKey: loadRefreshHmacKey(env),
+        lifetimes: loadSessionLifetimes(env),
     };
 }
 /**

package/dist/index.d.ts

@@ -22,5 +22,13 @@ export { Argon2idPasswordHasher, argon2idHasherProvider, SHIELD_PASSWORD_HASHER,
 export { MariaDbSessionRecordStore, SHIELD_SESSION_RECORD_STORE, RedisHotSessionStore, SHIELD_HOT_SESSION_STORE, CryptoTokenGenerator, Sha256RefreshTokenHasher, SystemClock, cryptoTokenGeneratorProvider, refreshHasherProvider, systemClockProvider, SHIELD_TOKEN_GENERATOR, SHIELD_REFRESH_HASHER, SHIELD_CLOCK, } from './session/index.js';
 export { BootSequence, assertPoolBudget } from './boot/boot-sequence.js';
 export { APP_CONFIG } from './config/config.module.js';
-export { loadAppConfig, loadPoolBudget, evaluatePoolBudget, DEFAULT_POOL_BUDGET, SCHEMA_SVC_POOL_HARD_CAP, type AppConfig, type PoolBudgetConfig, type PoolBudgetEvaluation, type RuntimeAccountPools, } from './config/app-config.js';
+export { loadAppConfig, loadPoolBudget, evaluatePoolBudget, DEFAULT_POOL_BUDGET, SCHEMA_SVC_POOL_HARD_CAP, type AppConfig, type PoolBudgetConfig, type PoolBudgetEvaluation, type RuntimeAccountPools, loadDbConfig, loadRedisConfig, loadSessionLifetimes, loadRefreshHmacKey, assertRefreshHmacKey, DEFAULT_DB_CONFIG, DEFAULT_REDIS_URL, type DbConfig, type RedisConfig, type SessionLifetimeOverrides, } from './config/app-config.js';
+export { SHIELD_DB_POOL, SHIELD_REDIS, SHIELD_CREDENTIAL_RESOLVER, SHIELD_AUTHENTICATOR, SHIELD_SESSION_AUTHORITY, } from './auth/tokens.js';
+export { MariaDbCredentialResolver } from './authentication/mariadb-credential-resolver.js';
+export type { SessionView, SessionTokensView, SessionSuccess, LoginRequest, MfaChallengeResponse, LoginResponse, MfaRequest, MfaResponse, RefreshRequest, RefreshResponse, LogoutRequest, LogoutAck, } from './auth/dto.js';
+export { PersistenceModule } from './auth/persistence.module.js';
+export { AuthModule, type AuthModuleOptions } from './auth/auth.module.js';
+export type { CredentialResolver, ResolvedCredential, RequiredFactor, } from '@astram/core';
+export { AuthController } from './auth/auth.controller.js';
+export { PendingMfaStore } from './auth/pending-mfa-store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACL,YAAY,EACZ,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,MAAM,EACN,UAAU,EACV,uBAAuB,GACxB,MAAM,2CAA2C,CAAC;AAUnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAKnF,OAAO,EACL,qBAAqB,EACrB,KAAK,MAAM,EACX,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,4BAA4B,CAAC;AAMpC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,cAAc,GACpB,MAAM,8CAA8C,CAAC;AAOtD,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,wBAAwB,EACxB,WAAW,EACX,4BAA4B,EAC5B,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAOzE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EACL,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,GACzB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACL,YAAY,EACZ,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,MAAM,EACN,UAAU,EACV,uBAAuB,GACxB,MAAM,2CAA2C,CAAC;AAUnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAKnF,OAAO,EACL,qBAAqB,EACrB,KAAK,MAAM,EACX,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,4BAA4B,CAAC;AAMpC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,cAAc,GACpB,MAAM,8CAA8C,CAAC;AAOtD,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,wBAAwB,EACxB,WAAW,EACX,4BAA4B,EAC5B,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAOzE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EACL,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAGxB,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC;AAchC,OAAO,EACL,cAAc,EACd,YAAY,EACZ,0BAA0B,EAC1B,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,yBAAyB,EAAE,MAAM,iDAAiD,CAAC;AAI5F,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,aAAa,EACb,UAAU,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,aAAa,EACb,SAAS,GACV,MAAM,eAAe,CAAC;AAKvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAS3E,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,GACf,MAAM,cAAc,CAAC;AAOtB,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -16,7 +16,7 @@
  * `@nestjs/core`, `reflect-metadata`, `rxjs` so the host owns one copy of each.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SCHEMA_SVC_POOL_HARD_CAP = exports.DEFAULT_POOL_BUDGET = exports.evaluatePoolBudget = exports.loadPoolBudget = exports.loadAppConfig = exports.APP_CONFIG = exports.assertPoolBudget = exports.BootSequence = exports.SHIELD_CLOCK = exports.SHIELD_REFRESH_HASHER = exports.SHIELD_TOKEN_GENERATOR = exports.systemClockProvider = exports.refreshHasherProvider = exports.cryptoTokenGeneratorProvider = exports.SystemClock = exports.Sha256RefreshTokenHasher = exports.CryptoTokenGenerator = exports.SHIELD_HOT_SESSION_STORE = exports.RedisHotSessionStore = exports.SHIELD_SESSION_RECORD_STORE = exports.MariaDbSessionRecordStore = exports.SHIELD_PASSWORD_HASHER = exports.argon2idHasherProvider = exports.Argon2idPasswordHasher = exports.stubDecisionAuthority = exports.GlobalEnforcementGuard = exports.CLASSIFICATION_METADATA = exports.Classified = exports.Public = exports.SHIELD_DECISION_AUTHORITY = exports.ShieldModule = void 0;
+exports.PendingMfaStore = exports.AuthController = exports.AuthModule = exports.PersistenceModule = exports.MariaDbCredentialResolver = exports.SHIELD_SESSION_AUTHORITY = exports.SHIELD_AUTHENTICATOR = exports.SHIELD_CREDENTIAL_RESOLVER = exports.SHIELD_REDIS = exports.SHIELD_DB_POOL = exports.DEFAULT_REDIS_URL = exports.DEFAULT_DB_CONFIG = exports.assertRefreshHmacKey = exports.loadRefreshHmacKey = exports.loadSessionLifetimes = exports.loadRedisConfig = exports.loadDbConfig = exports.SCHEMA_SVC_POOL_HARD_CAP = exports.DEFAULT_POOL_BUDGET = exports.evaluatePoolBudget = exports.loadPoolBudget = exports.loadAppConfig = exports.APP_CONFIG = exports.assertPoolBudget = exports.BootSequence = exports.SHIELD_CLOCK = exports.SHIELD_REFRESH_HASHER = exports.SHIELD_TOKEN_GENERATOR = exports.systemClockProvider = exports.refreshHasherProvider = exports.cryptoTokenGeneratorProvider = exports.SystemClock = exports.Sha256RefreshTokenHasher = exports.CryptoTokenGenerator = exports.SHIELD_HOT_SESSION_STORE = exports.RedisHotSessionStore = exports.SHIELD_SESSION_RECORD_STORE = exports.MariaDbSessionRecordStore = exports.SHIELD_PASSWORD_HASHER = exports.argon2idHasherProvider = exports.Argon2idPasswordHasher = exports.stubDecisionAuthority = exports.GlobalEnforcementGuard = exports.CLASSIFICATION_METADATA = exports.Classified = exports.Public = exports.SHIELD_DECISION_AUTHORITY = exports.ShieldModule = void 0;
 // The single registration seam.
 var shield_module_js_1 = require("./module/shield.module.js");
 Object.defineProperty(exports, "ShieldModule", { enumerable: true, get: function () { return shield_module_js_1.ShieldModule; } });
@@ -86,3 +86,48 @@ Object.defineProperty(exports, "loadPoolBudget", { enumerable: true, get: functi
 Object.defineProperty(exports, "evaluatePoolBudget", { enumerable: true, get: function () { return app_config_js_1.evaluatePoolBudget; } });
 Object.defineProperty(exports, "DEFAULT_POOL_BUDGET", { enumerable: true, get: function () { return app_config_js_1.DEFAULT_POOL_BUDGET; } });
 Object.defineProperty(exports, "SCHEMA_SVC_POOL_HARD_CAP", { enumerable: true, get: function () { return app_config_js_1.SCHEMA_SVC_POOL_HARD_CAP; } });
+// Phase 0b Auth-surface config (additive): the DB/Redis/lifetime loaders + the
+// required-secret resolver/gate + the new config shapes.
+Object.defineProperty(exports, "loadDbConfig", { enumerable: true, get: function () { return app_config_js_1.loadDbConfig; } });
+Object.defineProperty(exports, "loadRedisConfig", { enumerable: true, get: function () { return app_config_js_1.loadRedisConfig; } });
+Object.defineProperty(exports, "loadSessionLifetimes", { enumerable: true, get: function () { return app_config_js_1.loadSessionLifetimes; } });
+Object.defineProperty(exports, "loadRefreshHmacKey", { enumerable: true, get: function () { return app_config_js_1.loadRefreshHmacKey; } });
+Object.defineProperty(exports, "assertRefreshHmacKey", { enumerable: true, get: function () { return app_config_js_1.assertRefreshHmacKey; } });
+Object.defineProperty(exports, "DEFAULT_DB_CONFIG", { enumerable: true, get: function () { return app_config_js_1.DEFAULT_DB_CONFIG; } });
+Object.defineProperty(exports, "DEFAULT_REDIS_URL", { enumerable: true, get: function () { return app_config_js_1.DEFAULT_REDIS_URL; } });
+// ---------------------------------------------------------------------------
+// Phase 0b Auth surface (framework-owned login → session, spec §2/§3/§4).
+//
+// PRELUDE CONTRACT (this commit): the frozen DI tokens, endpoint DTO shapes, the
+// credential-resolver skeleton (Team A fills), and the composition module
+// skeletons (Team B fills). Team C's `/auth/*` controllers consume
+// SHIELD_AUTHENTICATOR / SHIELD_SESSION_AUTHORITY. All ADDITIVE — the enforcement
+// path is untouched; ShieldModule wiring is deferred to the integration owner.
+// ---------------------------------------------------------------------------
+// Shared DI provider tokens (the seams the teams bind/consume — see tokens.ts for
+// who provides/consumes each).
+var tokens_js_1 = require("./auth/tokens.js");
+Object.defineProperty(exports, "SHIELD_DB_POOL", { enumerable: true, get: function () { return tokens_js_1.SHIELD_DB_POOL; } });
+Object.defineProperty(exports, "SHIELD_REDIS", { enumerable: true, get: function () { return tokens_js_1.SHIELD_REDIS; } });
+Object.defineProperty(exports, "SHIELD_CREDENTIAL_RESOLVER", { enumerable: true, get: function () { return tokens_js_1.SHIELD_CREDENTIAL_RESOLVER; } });
+Object.defineProperty(exports, "SHIELD_AUTHENTICATOR", { enumerable: true, get: function () { return tokens_js_1.SHIELD_AUTHENTICATOR; } });
+Object.defineProperty(exports, "SHIELD_SESSION_AUTHORITY", { enumerable: true, get: function () { return tokens_js_1.SHIELD_SESSION_AUTHORITY; } });
+// The credential-store contract (skeleton — Team A implements the SELECT).
+var mariadb_credential_resolver_js_1 = require("./authentication/mariadb-credential-resolver.js");
+Object.defineProperty(exports, "MariaDbCredentialResolver", { enumerable: true, get: function () { return mariadb_credential_resolver_js_1.MariaDbCredentialResolver; } });
+// The composition module skeletons (Team B fills the factory bodies; the
+// integration owner imports AuthModule into ShieldModule — see auth.module.ts /
+// DONE.md).
+var persistence_module_js_1 = require("./auth/persistence.module.js");
+Object.defineProperty(exports, "PersistenceModule", { enumerable: true, get: function () { return persistence_module_js_1.PersistenceModule; } });
+var auth_module_js_1 = require("./auth/auth.module.js");
+Object.defineProperty(exports, "AuthModule", { enumerable: true, get: function () { return auth_module_js_1.AuthModule; } });
+// The framework-owned `/auth/*` HTTP controller (Team C) + its pending-MFA store.
+// The controller CONSUMES SHIELD_AUTHENTICATOR / SHIELD_SESSION_AUTHORITY and the
+// PendingMfaStore. It is EXPORTED so AuthModule (Team B) / the integration owner
+// registers it in the module's `controllers` and provides `PendingMfaStore` — this
+// file (Team C) does NOT edit auth.module.ts. See auth.controller.ts header.
+var auth_controller_js_1 = require("./auth/auth.controller.js");
+Object.defineProperty(exports, "AuthController", { enumerable: true, get: function () { return auth_controller_js_1.AuthController; } });
+var pending_mfa_store_js_1 = require("./auth/pending-mfa-store.js");
+Object.defineProperty(exports, "PendingMfaStore", { enumerable: true, get: function () { return pending_mfa_store_js_1.PendingMfaStore; } });

package/dist/module/shield.module.d.ts

@@ -1,4 +1,5 @@
 import { type DynamicModule } from '@nestjs/common';
+import type { CredentialResolver } from '@astram/core';
 import type { CoreDecisionAuthority } from '../enforcement/core-seam.js';
 import { type AppConfig } from '../config/app-config.js';
 /**
@@ -27,6 +28,37 @@ export interface ShieldModuleOptions {
      * inject computed config through the one seam rather than editing the framework.
      */
     readonly config?: AppConfig;
+    /**
+     * ⛔ OPT-IN: the framework-owned login → session auth surface (Phase 0b — the
+     * `/auth/*` endpoints + the composed `Authenticator` / `SessionAuthority`).
+     *
+     * DEFAULT `false` (ABSENT): an enforcement-only app does NOT import
+     * {@link AuthModule} — so it never opens a MariaDB pool / Redis client, never
+     * fires the fail-closed `assertRefreshHmacKey` gate, and keeps the no-`.env`
+     * boot promised by `create-astram-app`. `ShieldModule.forRoot()` composes with
+     * a blank refresh-HMAC key and no live connection (enforcement-only).
+     *
+     * `true`: imports {@link AuthModule.forRoot} (which pulls the live connections +
+     * composes the authenticator + session authority + registers the four `/auth/*`
+     * routes) and re-exports {@link SHIELD_AUTHENTICATOR} / {@link SHIELD_SESSION_AUTHORITY}
+     * app-wide. An auth-enabled app fails LOUD at boot if `SHIELD_REFRESH_HMAC_KEY`
+     * is blank — auth can never compose unkeyed.
+     */
+    readonly auth?: boolean;
+    /**
+     * OPTIONAL custom credential resolver (the store login checks against). Omit →
+     * the framework's default `MariaDbCredentialResolver` (reads
+     * `shield_identity.identity_credential`). Supply a consumer implementation of the
+     * core `CredentialResolver` port to authenticate against your OWN user/identity
+     * schema (e.g. a multi-tenant users+roles model) WITHOUT editing the framework.
+     *
+     * Only consulted when `auth: true` (a no-op without it — no AuthModule composes,
+     * so no resolver is wired). The seam swaps the STORE only: a supplied resolver
+     * still flows through the SAME composed authenticator (anti-enumeration decoy
+     * verify, MFA, no-secret-leak). A resolver returning `null` = unknown principal
+     * (generic 401); throwing = fail-closed transient — exactly the default contract.
+     */
+    readonly credentialResolver?: CredentialResolver;
 }
 /** Async variant of {@link ShieldModuleOptions} (DI-computed config). */
 export interface ShieldModuleAsyncOptions {
@@ -36,6 +68,25 @@ export interface ShieldModuleAsyncOptions {
     readonly useFactory: (...args: readonly unknown[]) => Promise<ShieldModuleOptions> | ShieldModuleOptions;
     /** Modules exporting the injected providers. */
     readonly imports?: readonly unknown[];
+    /**
+     * ⛔ OPT-IN auth (see {@link ShieldModuleOptions.auth}). STATIC here (not part of
+     * the async factory result): whether an app wires the auth surface is a
+     * deployment-topology decision known at REGISTRATION time, and a NestJS
+     * `DynamicModule.imports` list is composed statically — it cannot depend on the
+     * async-resolved `ShieldModuleOptions`. So the flag lives on the async-options
+     * object directly, gating the {@link AuthModule} import + engine re-exports
+     * exactly like {@link forRoot}. DEFAULT `false` (no auth → no live connection →
+     * no-`.env` boot preserved).
+     */
+    readonly auth?: boolean;
+    /**
+     * OPTIONAL custom credential resolver — see {@link ShieldModuleOptions.credentialResolver}.
+     * STATIC here (like {@link auth}, NOT part of the async factory result): the
+     * resolver instance is a registration-time collaborator threaded into the
+     * statically-composed {@link AuthModule} import, so it cannot depend on the
+     * async-resolved options. Only consulted when `auth: true`.
+     */
+    readonly credentialResolver?: CredentialResolver;
 }
 /**
  * `ShieldModule` — the SINGLE registration seam (ADR-0023 §4).