@astram/guard 0.1.1 → 0.2.0

package/dist/auth/auth.module.js

@@ -0,0 +1,318 @@
+"use strict";
+/**
+ * `AuthModule` — the Phase 0b **composition seam** that assembles the core auth
+ * engines from guard's adapters + the live connections, and exposes them under
+ * {@link SHIELD_AUTHENTICATOR} / {@link SHIELD_SESSION_AUTHORITY} for Team C's
+ * `/auth/*` controllers (spec §4).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Team B (connection + composition) OWNS this file. It wires the frozen tokens to
+ * the real engines:
+ *
+ *  SHIELD_PASSWORD_HASHER      →  new Argon2idPasswordHasher()  (the flagged fix —
+ *      the authenticator factory injects it, so THIS module must provide it).
+ *  SHIELD_CREDENTIAL_RESOLVER  →  new MariaDbCredentialResolver(pool)  (Team A's
+ *      class; its `resolve()` body is Team A's — until then it throws not-implemented,
+ *      which the engine treats as fail-closed `authentication_unavailable`).
+ *  SHIELD_SESSION_RECORD_STORE →  new MariaDbSessionRecordStore(pool).
+ *  SHIELD_HOT_SESSION_STORE    →  new RedisHotSessionStore(redis).
+ *  SHIELD_TOKEN_GENERATOR      →  new CryptoTokenGenerator().
+ *  SHIELD_CLOCK                →  new SystemClock().
+ *  SHIELD_REFRESH_HASHER       →  new Sha256RefreshTokenHasher(
+ *        assertRefreshHmacKey(config.refreshHmacKey))          ⛔ FAIL-CLOSED gate:
+ *      `assertRefreshHmacKey` THROWS on a blank key, so auth can NEVER compose with
+ *      an unkeyed refresh-token hasher. This is the boot-time fail-closed point for
+ *      the required secret (loadAppConfig deliberately does NOT throw, so a
+ *      non-auth scaffold still boots with no `.env` — see app-config.ts).
+ *
+ *  SHIELD_SESSION_AUTHORITY  →  createSessionAuthority({ recordStore, hotStore,
+ *        tokenGenerator, refreshHasher, clock, lifetimes: config.lifetimes }).
+ *      `createSessionAuthority` validates lifetime bounds eagerly (throws LOUD on a
+ *      nonsensical config — construction-time, correct).
+ *
+ *  SHIELD_AUTHENTICATOR  →  createAuthenticator({ hasher, resolver,
+ *        identityBroker: createIdentityBroker(),               // default Internal, empty
+ *        factorVerifiers: [ createTotpFactorVerifier({ hmacSha1 }) ] }).  The TOTP
+ *      verifier is wired so MFA works; `hmacSha1` is the {@link hmacSha1} node:crypto
+ *      one-liner (guard owns node:crypto, core does not). `createIdentityBroker()`
+ *      with no args registers the default Internal adapter with an EMPTY superuser
+ *      allowlist (default-deny).
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * ⛔ OPT-IN (how the integration owner gates this — for the no-`.env` boot):
+ * AuthModule opens live connections (via PersistenceModule) and fires the
+ * fail-closed `assertRefreshHmacKey` gate the moment it composes. So it MUST be
+ * imported ONLY when a deployment wants auth. `ShieldModule.forRoot(options)`
+ * should conditionally add `AuthModule.forRoot()` to its `imports` gated behind an
+ * option (e.g. `ShieldModule.forRoot({ auth: true })`) or an env flag:
+ *
+ *     imports: [
+ *       EnforcementModule, BootModule,
+ *       ...(options?.auth ? [AuthModule.forRoot()] : []),   // ← opt-in
+ *     ],
+ *     exports: [APP_CONFIG, SHIELD_DECISION_AUTHORITY,
+ *               ...(options?.auth ? [SHIELD_AUTHENTICATOR, SHIELD_SESSION_AUTHORITY] : [])],
+ *
+ * An enforcement-only app that does NOT opt in never imports AuthModule → never
+ * opens a pool/redis → never calls `assertRefreshHmacKey` → keeps the no-`.env`
+ * boot. An auth-enabled app fails LOUD at boot if `SHIELD_REFRESH_HMAC_KEY` is
+ * blank — auth can never compose unkeyed. `APP_CONFIG` is already `@Global` from
+ * `ShieldModule`, so AuthModule's config-injecting factories resolve. See DONE.md.
+ *
+ * ADR-0003: the core factories (`createAuthenticator`/`createSessionAuthority`/
+ * `createIdentityBroker`/`createTotpFactorVerifier`) are pure; the adapters + the
+ * node:crypto HMAC live in guard. Core stays zero-dep + unchanged.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var AuthModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthModule = exports.hmacSha1 = void 0;
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+const app_config_js_1 = require("../config/app-config.js");
+const config_module_js_1 = require("../config/config.module.js");
+const argon2id_password_hasher_js_1 = require("../authentication/argon2id-password-hasher.js");
+const mariadb_credential_resolver_js_1 = require("../authentication/mariadb-credential-resolver.js");
+const index_js_1 = require("../session/index.js");
+const persistence_module_js_1 = require("./persistence.module.js");
+const auth_controller_js_1 = require("./auth.controller.js");
+const pending_mfa_store_js_1 = require("./pending-mfa-store.js");
+const tokens_js_1 = require("./tokens.js");
+/**
+ * The injected HMAC-SHA1 primitive the core TOTP verifier needs (Core is zero-dep
+ * + node-type-free, so it cannot import `node:crypto`). Guard owns node:crypto and
+ * supplies this one-liner: raw key bytes + message bytes → the 20-byte HMAC-SHA1
+ * digest. Never logs the key or message.
+ */
+const hmacSha1 = (key, message) => new Uint8Array((0, node_crypto_1.createHmac)('sha1', Buffer.from(key)).update(Buffer.from(message)).digest());
+exports.hmacSha1 = hmacSha1;
+/**
+ * A `Function`-wrapped dynamic `import()` that survives the CommonJS **build**.
+ * Under `module: commonjs`, `tsc` rewrites a literal `import()` into
+ * `Promise.resolve().then(() => require(...))` — which fails on the ESM-only core.
+ * Routing the import through the `Function` constructor hides it from that
+ * transform, so the emitted dist keeps a genuine native `import()` and Node's
+ * CJS→ESM interop loads core at runtime. (This path is used by the BUILT dist —
+ * e.g. example-backend. It does NOT work under vitest, whose sandbox can't resolve
+ * a specifier from an eval'd context — hence the two-strategy loadCore() below.)
+ */
+const evalImport = new Function('specifier', 'return import(specifier);');
+let cachedCore;
+/**
+ * Lazily load `@astram/core`'s four auth factory functions — invoked ONLY inside
+ * the two async provider factories (i.e. only when `forRoot()` actually composes
+ * auth), NEVER at module top-level. This keeps a runtime `require('@astram/core')`
+ * out of the guard barrel's load path (see the top-of-file note), so importing
+ * `@astram/guard`'s built dist for the enforcement-only path does not touch core.
+ *
+ * TWO strategies, so it works in BOTH runtimes:
+ *  1. A plain dynamic `import('@astram/core')` — the vitest/SWC source path keeps
+ *     this native, and vitest's resolver maps the workspace package. (In the
+ *     tsc-built CJS dist this literal is downleveled to a `require`, which throws on
+ *     the ESM core — caught below.)
+ *  2. On failure, the {@link evalImport} `Function`-wrapped native `import()` — the
+ *     BUILT dist path (Node CJS→ESM interop), which vitest can't use.
+ * Cached after the first success.
+ */
+async function loadCore() {
+    if (cachedCore !== undefined)
+        return cachedCore;
+    try {
+        // Strategy 1 — native in vitest/SWC; a `require` (that may throw) in the CJS dist.
+        cachedCore = (await Promise.resolve().then(() => __importStar(require('@astram/core'))));
+    }
+    catch {
+        // Strategy 2 — the built-dist path: a genuine `import()` via the Function shim.
+        cachedCore = (await evalImport('@astram/core'));
+    }
+    return cachedCore;
+}
+// --- Adapter-backed providers (Team A resolver + session adapters) ----------
+/** Argon2id password hasher (⛔ the flagged fix — provide it HERE so the authenticator factory's `inject` resolves). */
+const passwordHasherProvider = {
+    provide: argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER,
+    useFactory: () => new argon2id_password_hasher_js_1.Argon2idPasswordHasher(),
+};
+/**
+ * Credential resolver (the store login checks against).
+ *
+ * DEFAULT (no consumer override): a `useFactory` that constructs the framework's
+ * {@link MariaDbCredentialResolver} injected with the live {@link SHIELD_DB_POOL}
+ * — the historical binding, unchanged.
+ *
+ * OVERRIDE (Phase 1a seam): when the consumer supplies a `credentialResolver`
+ * through {@link ShieldModuleOptions.credentialResolver} → {@link AuthModule.forRoot},
+ * the token instead binds a plain **value provider** to that instance, so login
+ * authenticates against the consumer's OWN store (e.g. a richer users/roles model)
+ * WITHOUT editing the framework. The seam swaps the STORE only — the supplied
+ * resolver still flows through the SAME composed authenticator (anti-enumeration
+ * decoy verify, MFA, no-secret-leak); its `null`/throw contract is unchanged.
+ */
+function makeCredentialResolverProvider(override) {
+    return override
+        ? { provide: tokens_js_1.SHIELD_CREDENTIAL_RESOLVER, useValue: override }
+        : {
+            provide: tokens_js_1.SHIELD_CREDENTIAL_RESOLVER,
+            useFactory: (pool) => new mariadb_credential_resolver_js_1.MariaDbCredentialResolver(pool),
+            inject: [tokens_js_1.SHIELD_DB_POOL],
+        };
+}
+/** Durable session record store (MariaDB adapter, injected with the live pool). */
+const sessionRecordStoreProvider = {
+    provide: index_js_1.SHIELD_SESSION_RECORD_STORE,
+    useFactory: (pool) => new index_js_1.MariaDbSessionRecordStore(pool),
+    inject: [tokens_js_1.SHIELD_DB_POOL],
+};
+/** Hot session store (Redis adapter, injected with the live client). */
+const hotSessionStoreProvider = {
+    provide: index_js_1.SHIELD_HOT_SESSION_STORE,
+    useFactory: (redis) => new index_js_1.RedisHotSessionStore(redis),
+    inject: [tokens_js_1.SHIELD_REDIS],
+};
+/** Opaque token generator (node:crypto adapter). */
+const tokenGeneratorProvider = {
+    provide: index_js_1.SHIELD_TOKEN_GENERATOR,
+    useFactory: () => new index_js_1.CryptoTokenGenerator(),
+};
+/**
+ * Keyed refresh hasher (HMAC adapter). ⛔ FAIL-CLOSED HMAC-key gate:
+ * `assertRefreshHmacKey` THROWS on a blank key, so auth can never compose with an
+ * unkeyed refresh-token hasher.
+ */
+const refreshHasherProvider = {
+    provide: index_js_1.SHIELD_REFRESH_HASHER,
+    useFactory: (config) => new index_js_1.Sha256RefreshTokenHasher((0, app_config_js_1.assertRefreshHmacKey)(config.refreshHmacKey)),
+    inject: [config_module_js_1.APP_CONFIG],
+};
+/** System clock. */
+const clockProvider = {
+    provide: index_js_1.SHIELD_CLOCK,
+    useFactory: () => new index_js_1.SystemClock(),
+};
+// --- Composed core engines --------------------------------------------------
+/** The composed SessionAuthority (core) — establish / rotate / revoke. */
+const sessionAuthorityProvider = {
+    provide: tokens_js_1.SHIELD_SESSION_AUTHORITY,
+    // async: loads the core factory lazily (CJS→ESM, see loadCore()); Nest awaits it.
+    useFactory: async (recordStore, hotStore, tokenGenerator, refreshHasher, clock, config) => {
+        const { createSessionAuthority } = await loadCore();
+        return createSessionAuthority({
+            recordStore,
+            hotStore,
+            tokenGenerator,
+            refreshHasher,
+            clock,
+            lifetimes: config.lifetimes,
+        });
+    },
+    inject: [
+        index_js_1.SHIELD_SESSION_RECORD_STORE,
+        index_js_1.SHIELD_HOT_SESSION_STORE,
+        index_js_1.SHIELD_TOKEN_GENERATOR,
+        index_js_1.SHIELD_REFRESH_HASHER,
+        index_js_1.SHIELD_CLOCK,
+        config_module_js_1.APP_CONFIG,
+    ],
+};
+/** The composed Authenticator (core) — password + TOTP factor, anti-enumeration. */
+const authenticatorProvider = {
+    provide: tokens_js_1.SHIELD_AUTHENTICATOR,
+    // async: loads the core factories lazily (CJS→ESM, see loadCore()); Nest awaits it.
+    useFactory: async (hasher, resolver) => {
+        const { createAuthenticator, createIdentityBroker, createTotpFactorVerifier } = await loadCore();
+        return createAuthenticator({
+            hasher,
+            resolver,
+            identityBroker: createIdentityBroker(),
+            factorVerifiers: [createTotpFactorVerifier({ hmacSha1: exports.hmacSha1 })],
+        });
+    },
+    inject: [argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER, tokens_js_1.SHIELD_CREDENTIAL_RESOLVER],
+};
+/**
+ * The auth composition module. Imports {@link PersistenceModule} (the live
+ * connections) and provides the adapters + composed engines. Exports the two
+ * engines (Team C consumes them) and the resolver token. Opt-in: imported ONLY by
+ * an auth-enabled `ShieldModule.forRoot({ auth: true })` — see the file header +
+ * DONE.md for the exact gating the integration owner applies.
+ */
+let AuthModule = AuthModule_1 = class AuthModule {
+    /**
+     * Compose the auth surface. `options.credentialResolver`, when supplied, REPLACES
+     * the default MariaDb store with the consumer's own (a value provider under
+     * {@link SHIELD_CREDENTIAL_RESOLVER}); omitted → the historical default binding,
+     * EXACTLY unchanged (zero behavior change for existing consumers).
+     */
+    static forRoot(options = {}) {
+        return {
+            module: AuthModule_1,
+            imports: [persistence_module_js_1.PersistenceModule.forRoot()],
+            // Team C's four `@Public()` /auth/* endpoints. Registered here (integration
+            // wiring) so the routes exist the moment auth is opted in — the controller
+            // injects the two composed engines (below) + PendingMfaStore.
+            controllers: [auth_controller_js_1.AuthController],
+            providers: [
+                passwordHasherProvider,
+                makeCredentialResolverProvider(options.credentialResolver),
+                sessionRecordStoreProvider,
+                hotSessionStoreProvider,
+                tokenGeneratorProvider,
+                refreshHasherProvider,
+                clockProvider,
+                sessionAuthorityProvider,
+                authenticatorProvider,
+                // Team C's server-side, single-use, TTL'd challenge store backing the
+                // login→mfa handoff (a plain class provider the controller injects).
+                pending_mfa_store_js_1.PendingMfaStore,
+            ],
+            exports: [
+                tokens_js_1.SHIELD_AUTHENTICATOR,
+                tokens_js_1.SHIELD_SESSION_AUTHORITY,
+                tokens_js_1.SHIELD_CREDENTIAL_RESOLVER,
+                argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER,
+            ],
+        };
+    }
+};
+exports.AuthModule = AuthModule;
+exports.AuthModule = AuthModule = AuthModule_1 = __decorate([
+    (0, common_1.Module)({})
+], AuthModule);

package/dist/auth/connections.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Live-connection factories + a shutdown registrar for the Phase 0b auth surface
+ * (Team B). This is the ONE module in the framework that opens a real MariaDB pool
+ * and a real Redis client (spec §4); everything auth persists (sessions,
+ * credentials, hot state) flows through the two connections created here.
+ *
+ * WHY a separate helper (not inline in the provider factory): a Nest `useFactory`
+ * value provider is NOT itself lifecycle-aware — `onModuleDestroy` only fires on
+ * PROVIDER CLASSES with that method. So the pool/redis are created by the pure
+ * factories below, and a tiny {@link ConnectionLifecycle} provider (a class Nest
+ * WILL call `onModuleDestroy` on) holds their handles and closes them on shutdown.
+ * This keeps `SHIELD_DB_POOL` / `SHIELD_REDIS` as the raw driver objects the
+ * adapters expect (`new MariaDbSessionRecordStore(pool)` etc.) while still getting
+ * graceful teardown.
+ *
+ * ⛔ SECURITY — never logs a credential. The DB password + Redis url (which may
+ * carry a password) are handed straight to the drivers; nothing here stringifies
+ * or logs the config.
+ *
+ * ADR-0003: the real `mariadb` / `ioredis` live in guard (Core stays zero-dep).
+ * ADR-0018: the pool cap is taken from the connection-pool budget
+ * (`config.pool.perAccountMax.shield_core`), NOT a duplicate knob.
+ */
+import { type OnModuleDestroy } from '@nestjs/common';
+import { type Pool } from 'mariadb';
+import Redis from 'ioredis';
+import type { AppConfig } from '../config/app-config.js';
+/**
+ * Create the ONE live `mariadb` {@link Pool} for the `shield_core` account from
+ * {@link AppConfig}. The `connectionLimit` comes from the ADR-0018 budget
+ * (`config.pool.perAccountMax.shield_core`) so per-worker pools stay within the DB
+ * `max_connections` ceiling — it is NOT a separate configurable.
+ *
+ * A blank `db.password` is ALLOWED here (it is not hard-required at config load);
+ * a wrong/blank password fails LOUD at connect time, which is the correct place
+ * for a runtime credential error. The host/port/user/database always have
+ * documented defaults, so the descriptor is always well-formed.
+ */
+export declare function createDbPool(config: AppConfig): Pool;
+/**
+ * Create the ONE live `ioredis` client (the hot session tier, ADR-0013) from
+ * {@link AppConfig}. `config.redis.url` is the canonical `ioredis`-native form
+ * (`redis://[:pw@]host:port[/db]`) with a documented default. Lazy-connect is left
+ * at ioredis's default (connects on first command); a dead Redis surfaces as the
+ * `unavailable` hot-store outcome (fail-closed), never a silent `absent`.
+ */
+export declare function createRedisClient(config: AppConfig): Redis;
+/**
+ * Lifecycle-aware holder that owns the pool + redis handles and closes them on
+ * app shutdown. Provided ALONGSIDE the two raw-connection providers so Nest calls
+ * `onModuleDestroy` here (value providers get no lifecycle callback). The teardown
+ * is best-effort + idempotent: a close error is swallowed so shutdown never hangs
+ * or throws, and both connections are always attempted.
+ */
+export declare class ConnectionLifecycle implements OnModuleDestroy {
+    private readonly pool;
+    private readonly redis;
+    constructor(pool: Pool, redis: Redis);
+    onModuleDestroy(): Promise<void>;
+}
+//# sourceMappingURL=connections.d.ts.map

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

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

package/dist/auth/connections.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * Live-connection factories + a shutdown registrar for the Phase 0b auth surface
+ * (Team B). This is the ONE module in the framework that opens a real MariaDB pool
+ * and a real Redis client (spec §4); everything auth persists (sessions,
+ * credentials, hot state) flows through the two connections created here.
+ *
+ * WHY a separate helper (not inline in the provider factory): a Nest `useFactory`
+ * value provider is NOT itself lifecycle-aware — `onModuleDestroy` only fires on
+ * PROVIDER CLASSES with that method. So the pool/redis are created by the pure
+ * factories below, and a tiny {@link ConnectionLifecycle} provider (a class Nest
+ * WILL call `onModuleDestroy` on) holds their handles and closes them on shutdown.
+ * This keeps `SHIELD_DB_POOL` / `SHIELD_REDIS` as the raw driver objects the
+ * adapters expect (`new MariaDbSessionRecordStore(pool)` etc.) while still getting
+ * graceful teardown.
+ *
+ * ⛔ SECURITY — never logs a credential. The DB password + Redis url (which may
+ * carry a password) are handed straight to the drivers; nothing here stringifies
+ * or logs the config.
+ *
+ * ADR-0003: the real `mariadb` / `ioredis` live in guard (Core stays zero-dep).
+ * ADR-0018: the pool cap is taken from the connection-pool budget
+ * (`config.pool.perAccountMax.shield_core`), NOT a duplicate knob.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionLifecycle = void 0;
+exports.createDbPool = createDbPool;
+exports.createRedisClient = createRedisClient;
+const common_1 = require("@nestjs/common");
+const mariadb_1 = __importDefault(require("mariadb"));
+const ioredis_1 = __importDefault(require("ioredis"));
+/**
+ * Create the ONE live `mariadb` {@link Pool} for the `shield_core` account from
+ * {@link AppConfig}. The `connectionLimit` comes from the ADR-0018 budget
+ * (`config.pool.perAccountMax.shield_core`) so per-worker pools stay within the DB
+ * `max_connections` ceiling — it is NOT a separate configurable.
+ *
+ * A blank `db.password` is ALLOWED here (it is not hard-required at config load);
+ * a wrong/blank password fails LOUD at connect time, which is the correct place
+ * for a runtime credential error. The host/port/user/database always have
+ * documented defaults, so the descriptor is always well-formed.
+ */
+function createDbPool(config) {
+    const { db, pool } = config;
+    return mariadb_1.default.createPool({
+        host: db.host,
+        port: db.port,
+        user: db.user,
+        password: db.password,
+        database: db.database,
+        connectionLimit: pool.perAccountMax.shield_core,
+        // Fail fast on an unreachable DB rather than hanging the boot indefinitely.
+        connectTimeout: 10_000,
+        // All platform timestamps are UTC (parity with the session adapters).
+        timezone: 'Z',
+    });
+}
+/**
+ * Create the ONE live `ioredis` client (the hot session tier, ADR-0013) from
+ * {@link AppConfig}. `config.redis.url` is the canonical `ioredis`-native form
+ * (`redis://[:pw@]host:port[/db]`) with a documented default. Lazy-connect is left
+ * at ioredis's default (connects on first command); a dead Redis surfaces as the
+ * `unavailable` hot-store outcome (fail-closed), never a silent `absent`.
+ */
+function createRedisClient(config) {
+    // `maxRetriesPerRequest: null` keeps a transient blip from turning into a thrown
+    // command (the hot-store adapter classifies unreachable as `unavailable`).
+    return new ioredis_1.default(config.redis.url, { maxRetriesPerRequest: null, lazyConnect: false });
+}
+/**
+ * Lifecycle-aware holder that owns the pool + redis handles and closes them on
+ * app shutdown. Provided ALONGSIDE the two raw-connection providers so Nest calls
+ * `onModuleDestroy` here (value providers get no lifecycle callback). The teardown
+ * is best-effort + idempotent: a close error is swallowed so shutdown never hangs
+ * or throws, and both connections are always attempted.
+ */
+let ConnectionLifecycle = class ConnectionLifecycle {
+    pool;
+    redis;
+    constructor(pool, redis) {
+        this.pool = pool;
+        this.redis = redis;
+    }
+    async onModuleDestroy() {
+        // Close both; never let one failure prevent the other, never throw.
+        try {
+            await this.pool.end();
+        }
+        catch {
+            // best-effort — a pool already ending / a mid-query close is non-fatal here.
+        }
+        try {
+            await this.redis.quit();
+        }
+        catch {
+            // best-effort — quit on an already-closed client is non-fatal.
+        }
+    }
+};
+exports.ConnectionLifecycle = ConnectionLifecycle;
+exports.ConnectionLifecycle = ConnectionLifecycle = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object, ioredis_1.default])
+], ConnectionLifecycle);

package/dist/auth/dto.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Phase 0b Auth-surface **endpoint DTOs / view types** — the request/response
+ * SHAPES the four `@Public()` `/auth/*` endpoints speak (spec §2). ⛔ FROZEN by
+ * this prelude; **Team C builds controllers to these**. Types only — no NestJS /
+ * class-validator decorators here (the prelude froze the wire shape; Team C adds
+ * the validation decorators on its own DTO classes if it wants runtime
+ * validation, keeping this file framework-agnostic and importable anywhere).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SECURITY RULES these shapes ENCODE (spec §2, ACs 2/3/6; enforce in controllers):
+ *
+ * • ANTI-ENUMERATION — `/auth/login` and `/auth/mfa` failure responses are a
+ *   SINGLE generic 401 for {unknown user, wrong password, wrong/expired factor}.
+ *   The response body MUST NOT distinguish which failed (the engine's decoy-verify
+ *   already equalizes timing). NEVER add a `reason`/`field`/`code` that leaks
+ *   "no such user" vs "bad password".
+ * • NO SECRET LEAK — NO response/log ever carries a password, a password hash, a
+ *   TOTP secret, or a RAW refresh/access token OTHER than the two token fields a
+ *   successful lifecycle event legitimately returns ({@link SessionTokensView}).
+ *   The {@link SessionView} below deliberately OMITS every secret — it is the
+ *   ONLY session shape a response body may embed.
+ * • FAIL-CLOSED — a store/transient failure on refresh is the ADR-0016 retryable
+ *   signal (503-style), NOT a terminal deny/logout (see {@link RefreshResponse}).
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * ADR-0003: framework-agnostic — no framework / HTTP / DB imports.
+ */
+/**
+ * The client-safe view of an established session. Carries ONLY non-secret
+ * lifecycle facts a caller may see. ⛔ It MUST NOT contain any token, hash, or
+ * secret — tokens travel ONLY in {@link SessionTokensView}. `principalId` /
+ * `tenantId` are opaque internal ids (not rendered to end users as UUIDs — the UI
+ * resolves display labels; these are for the client's own session bookkeeping).
+ */
+export interface SessionView {
+    readonly sessionId: string;
+    readonly principalId: string;
+    readonly tenantId: string;
+    readonly status: 'active' | 'rotated' | 'revoked' | 'expired';
+    /** UTC epoch ms. */
+    readonly issuedAtMs: number;
+    /** UTC epoch ms. */
+    readonly expiresAtMs: number;
+}
+/**
+ * The token pair minted at a session lifecycle event. ⛔ These are SECRETS in
+ * transit — returned to the caller EXACTLY at login / mfa-success / refresh, never
+ * persisted raw, never logged. The refresh token is stored server-side only as
+ * its keyed hash.
+ */
+export interface SessionTokensView {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+}
+/** A successful session establishment payload (login / mfa / refresh success). */
+export interface SessionSuccess {
+    readonly session: SessionView;
+    readonly tokens: SessionTokensView;
+}
+/** `POST /auth/login` request body. */
+export interface LoginRequest {
+    /** Username or email — resolved to a principal by the credential resolver. */
+    readonly identityHint: string;
+    /** ⛔ The plaintext password — verified then discarded; NEVER logged/echoed. */
+    readonly password: string;
+}
+/**
+ * The MFA-challenge branch of a login/step-up response: the password was correct
+ * but a second factor is required, so NO session is established yet. The caller
+ * re-submits to `/auth/mfa` with the `challengeToken`. ⛔ `challengeToken` is a
+ * short-TTL opaque handle to the pending authentication — it is NOT a session
+ * token and grants no access on its own; it carries no secret about the user.
+ */
+export interface MfaChallengeResponse {
+    readonly mfaRequired: true;
+    readonly challengeToken: string;
+}
+/**
+ * `POST /auth/login` response — a discriminated union:
+ *   • {@link SessionSuccess}         — password-only user, authenticated + session;
+ *   • {@link MfaChallengeResponse}   — MFA-enabled user, challenge issued (no session).
+ * A FAILURE (unknown user / wrong password) is NOT modeled here — it is a generic
+ * HTTP 401 with a non-distinguishing body (anti-enumeration; see file header).
+ */
+export type LoginResponse = SessionSuccess | MfaChallengeResponse;
+/**
+ * `POST /auth/mfa` request body — completes a pending MFA challenge. `factor` is
+ * `'totp'` in Phase 0b (the only real factor; WebAuthn/recovery are contract slots
+ * only). `code` is the presented one-time code (digits). ⛔ `code` is single-use
+ * material — never logged.
+ */
+export interface MfaRequest {
+    /** The opaque handle from {@link MfaChallengeResponse}. Short-TTL, single-use. */
+    readonly challengeToken: string;
+    /** The second-factor class being satisfied (Phase 0b: `'totp'`). */
+    readonly factor: 'totp';
+    /** The presented one-time code. NEVER logged. */
+    readonly code: string;
+}
+/**
+ * `POST /auth/mfa` response — on success, the session + tokens
+ * ({@link SessionSuccess}). A wrong/expired code is a generic HTTP 401 (no session,
+ * no leak of why), NOT modeled as a body variant.
+ */
+export type MfaResponse = SessionSuccess;
+/**
+ * `POST /auth/refresh` request body. The refresh token may alternatively arrive
+ * via an HttpOnly cookie (Team C's transport choice) — the shape is the same.
+ * ⛔ Secret — never logged; server matches it by keyed hash only.
+ */
+export interface RefreshRequest {
+    readonly refreshToken: string;
+}
+/**
+ * `POST /auth/refresh` response — new tokens + the (rotated) session on success
+ * ({@link SessionSuccess}).
+ *
+ * ⛔ TWO distinct failure modes the controller MUST keep separate (spec §2, AC 7):
+ *   • reuse/invalid/expired token → generic `session_rejected` (HTTP 401), lineage
+ *     killed (ADR-0015) — a TERMINAL deny.
+ *   • transient store outage (hot store unavailable) → the ADR-0016 RETRYABLE
+ *     signal (HTTP 503-style), NOT a deny/logout. Conflating the two either logs
+ *     everyone out on a blip or fails open — both are bugs.
+ * Neither failure is a body variant here; both are HTTP-status outcomes with
+ * non-secret bodies.
+ */
+export type RefreshResponse = SessionSuccess;
+/**
+ * `POST /auth/logout` request body. `sessionId` may alternatively be derived from
+ * the access token (Team C's choice). Idempotent — revoking an already-revoked /
+ * unknown session still succeeds (no existence leak).
+ */
+export interface LogoutRequest {
+    readonly sessionId: string;
+}
+/**
+ * `POST /auth/logout` acknowledgement. The endpoint returns HTTP 204 (no body) on
+ * success; this type documents an OPTIONAL ack body if Team C prefers 200 — it
+ * carries NO secret and NO session detail (just a flag). Prefer 204 per spec §2.
+ */
+export interface LogoutAck {
+    readonly revoked: true;
+}
+//# sourceMappingURL=dto.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../../src/auth/dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9D,oBAAoB;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oBAAoB;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAMD,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAMlE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC;AAMzC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC;AAM7C;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB"}