@astram/guard 0.1.1 → 0.3.0

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/connections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections.js","sourceRoot":"","sources":["../../src/auth/connections.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;;;;;;;;;;;;;AAkBH,oCAcC;AASD,8CAIC;AA3CD,2CAAkE;AAClE,sDAA6C;AAC7C,sDAA4B;AAG5B;;;;;;;;;;GAUG;AACH,SAAgB,YAAY,CAAC,MAAiB;IAC5C,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;IAC5B,OAAO,iBAAO,CAAC,UAAU,CAAC;QACxB,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,QAAQ,EAAE,EAAE,CAAC,QAAQ;QACrB,QAAQ,EAAE,EAAE,CAAC,QAAQ;QACrB,eAAe,EAAE,IAAI,CAAC,aAAa,CAAC,WAAW;QAC/C,4EAA4E;QAC5E,cAAc,EAAE,MAAM;QACtB,sEAAsE;QACtE,QAAQ,EAAE,GAAG;KACd,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,MAAiB;IACjD,iFAAiF;IACjF,2EAA2E;IAC3E,OAAO,IAAI,iBAAK,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;AACzF,CAAC;AAED;;;;;;GAMG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAEX;IACA;IAFnB,YACmB,IAAU,EACV,KAAY;QADZ,SAAI,GAAJ,IAAI,CAAM;QACV,UAAK,GAAL,KAAK,CAAO;IAC5B,CAAC;IAEJ,KAAK,CAAC,eAAe;QACnB,oEAAoE;QACpE,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,6EAA6E;QAC/E,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;QACjE,CAAC;IACH,CAAC;CACF,CAAA;AAnBY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;6CAIe,iBAAK;GAHpB,mBAAmB,CAmB/B"}

package/dist/auth/dto.d.ts

@@ -0,0 +1,154 @@
+/**
+ * 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;
+    /**
+     * Set to `true` ONLY when the session was completed via a RECOVERY CODE at the
+     * `/auth/mfa` step (the lost-device escape hatch). Absent on every normal
+     * password / TOTP / refresh success, so those paths are byte-for-byte
+     * unaffected. The frontend keys off this to route the recovered session into
+     * the enforced re-enroll flow. Carries NO secret — a pure signal flag.
+     */
+    readonly mfaRecoveryUsed?: boolean;
+}
+/** `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'` (an authenticator code) or `'recovery_code'` (the lost-device escape
+ * hatch — a pre-issued single-use recovery code, verified in a separate branch,
+ * see `auth.controller.ts`). WebAuthn remains a contract slot only. `code` is the
+ * presented one-time code / recovery code. ⛔ `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 (`'totp'` or `'recovery_code'`). */
+    readonly factor: 'totp' | 'recovery_code';
+    /** The presented one-time code / recovery 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;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,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;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC;IAC1C,iEAAiE;IACjE,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"}

package/dist/auth/dto.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.js","sourceRoot":"","sources":["../../src/auth/dto.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/auth/pending-mfa-store.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Phase 0b Auth-surface — the **pending-MFA challenge store** backing
+ * `/auth/login` (mfa branch) → `/auth/mfa`.
+ *
+ * ── WHY THIS EXISTS ──────────────────────────────────────────────────────────
+ * The core `Authenticator` has NO separate "verify one more factor" entry point:
+ * `authenticate(hint, credentials[])` is the ONLY seam (see
+ * `../../core/authentication/authenticator.ts`). To COMPLETE an MFA login the
+ * controller must RE-CALL `authenticate(hint, [password, totp])` with BOTH the
+ * original password AND the freshly-presented TOTP code. So between the login that
+ * returned `mfa_required` and the `/auth/mfa` that finishes it, the server must
+ * hold the ORIGINAL `identityHint` + `password` (the "pending authentication").
+ *
+ * ── THE NON-FORGEABILITY DESIGN (the security decision) ──────────────────────
+ * The `challengeToken` handed to the client is a **cryptographically-random opaque
+ * handle** (`node:crypto.randomBytes`), NOT a signed/encrypted blob carrying the
+ * credentials. The pending `{ identityHint, password }` state lives ONLY
+ * server-side, keyed by that random token. Consequences:
+ *   • FORGERY-PROOF BY CONSTRUCTION — a hand-crafted token maps to no entry, so it
+ *     is rejected. There is no signature to strip, no payload to tamper with, and
+ *     the client is never given the credentials (even encrypted) to hold.
+ *   • SHORT-LIVED — each entry has an expiry (default 5 min). An expired handle is
+ *     treated as unknown (same generic 401 as a forged one — anti-enumeration).
+ *   • SINGLE-USE — `consume()` DELETES the entry as it reads it, so a
+ *     challengeToken cannot be replayed to brute-force TOTP codes indefinitely on
+ *     one handle. (A caller that fails still burns the handle → must re-login. This
+ *     is the built-in anti-brute-force cooldown for THIS layer; the resolver/engine
+ *     add no separate one.)
+ *   • NEVER LOGGED — the stored password + the token are never logged.
+ *
+ * TRADE-OFF (documented): server-side state is process-local (an in-memory `Map`).
+ * For the single-instance framework scope of Phase 0b this is correct and the
+ * safest option (the password never reaches the client). A multi-instance
+ * deployment would swap this `Map` for a shared TTL store (Redis) behind the SAME
+ * interface — the controller depends only on `store/consume`, not on the backing.
+ *
+ * ADR-0003 note: this file DOES use `node:crypto` (guard owns node builtins; core
+ * does not). It holds NO framework/HTTP coupling — a plain injectable class.
+ */
+/**
+ * A minimal server-side, single-use, TTL'd store of pending MFA challenges.
+ * Injected into the auth controller. Deliberately depends on nothing framework-y.
+ */
+export declare class PendingMfaStore {
+    private readonly ttlMs;
+    /** Clock (UTC epoch ms) — injectable for deterministic tests. */
+    private readonly nowMs;
+    private readonly pending;
+    constructor(ttlMs?: number, 
+    /** Clock (UTC epoch ms) — injectable for deterministic tests. */
+    nowMs?: () => number);
+    /**
+     * Store a pending authentication and return the opaque, unguessable
+     * `challengeToken` the client re-presents to `/auth/mfa`. The token carries NO
+     * information about the user — it is a random handle only.
+     */
+    store(identityHint: string, password: string): string;
+    /**
+     * Look up + SINGLE-USE consume a pending challenge. Returns the held credentials
+     * for a live, known token; `null` for an unknown, forged, or expired token (the
+     * controller maps `null` to the SAME generic 401 as a wrong code — no leak of
+     * WHY it failed). The entry is DELETED whether or not it was live, so a handle
+     * is never replayable.
+     */
+    consume(token: string): {
+        identityHint: string;
+        password: string;
+    } | null;
+    /** Drop expired entries so the map cannot grow unbounded from abandoned logins. */
+    private sweep;
+}
+//# sourceMappingURL=pending-mfa-store.d.ts.map

package/dist/auth/pending-mfa-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-mfa-store.d.ts","sourceRoot":"","sources":["../../src/auth/pending-mfa-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAmBH;;;GAGG;AACH,qBAAa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK;IALxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;gBAGxC,KAAK,GAAE,MAAuB;IAC/C,iEAAiE;IAChD,KAAK,GAAE,MAAM,MAAiB;IAGjD;;;;OAIG;IACH,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAWrD;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAWzE,mFAAmF;IACnF,OAAO,CAAC,KAAK;CAMd"}

package/dist/auth/pending-mfa-store.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Phase 0b Auth-surface — the **pending-MFA challenge store** backing
+ * `/auth/login` (mfa branch) → `/auth/mfa`.
+ *
+ * ── WHY THIS EXISTS ──────────────────────────────────────────────────────────
+ * The core `Authenticator` has NO separate "verify one more factor" entry point:
+ * `authenticate(hint, credentials[])` is the ONLY seam (see
+ * `../../core/authentication/authenticator.ts`). To COMPLETE an MFA login the
+ * controller must RE-CALL `authenticate(hint, [password, totp])` with BOTH the
+ * original password AND the freshly-presented TOTP code. So between the login that
+ * returned `mfa_required` and the `/auth/mfa` that finishes it, the server must
+ * hold the ORIGINAL `identityHint` + `password` (the "pending authentication").
+ *
+ * ── THE NON-FORGEABILITY DESIGN (the security decision) ──────────────────────
+ * The `challengeToken` handed to the client is a **cryptographically-random opaque
+ * handle** (`node:crypto.randomBytes`), NOT a signed/encrypted blob carrying the
+ * credentials. The pending `{ identityHint, password }` state lives ONLY
+ * server-side, keyed by that random token. Consequences:
+ *   • FORGERY-PROOF BY CONSTRUCTION — a hand-crafted token maps to no entry, so it
+ *     is rejected. There is no signature to strip, no payload to tamper with, and
+ *     the client is never given the credentials (even encrypted) to hold.
+ *   • SHORT-LIVED — each entry has an expiry (default 5 min). An expired handle is
+ *     treated as unknown (same generic 401 as a forged one — anti-enumeration).
+ *   • SINGLE-USE — `consume()` DELETES the entry as it reads it, so a
+ *     challengeToken cannot be replayed to brute-force TOTP codes indefinitely on
+ *     one handle. (A caller that fails still burns the handle → must re-login. This
+ *     is the built-in anti-brute-force cooldown for THIS layer; the resolver/engine
+ *     add no separate one.)
+ *   • NEVER LOGGED — the stored password + the token are never logged.
+ *
+ * TRADE-OFF (documented): server-side state is process-local (an in-memory `Map`).
+ * For the single-instance framework scope of Phase 0b this is correct and the
+ * safest option (the password never reaches the client). A multi-instance
+ * deployment would swap this `Map` for a shared TTL store (Redis) behind the SAME
+ * interface — the controller depends only on `store/consume`, not on the backing.
+ *
+ * ADR-0003 note: this file DOES use `node:crypto` (guard owns node builtins; core
+ * does not). It holds NO framework/HTTP coupling — a plain injectable class.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PendingMfaStore = void 0;
+const node_crypto_1 = require("node:crypto");
+/** Default challenge lifetime — short, per spec §2 ("a short TTL"). */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+/** How many random bytes back a challenge handle (256-bit, url-safe hex → 64 chars). */
+const TOKEN_BYTES = 32;
+/**
+ * A minimal server-side, single-use, TTL'd store of pending MFA challenges.
+ * Injected into the auth controller. Deliberately depends on nothing framework-y.
+ */
+class PendingMfaStore {
+    ttlMs;
+    nowMs;
+    pending = new Map();
+    constructor(ttlMs = DEFAULT_TTL_MS, 
+    /** Clock (UTC epoch ms) — injectable for deterministic tests. */
+    nowMs = Date.now) {
+        this.ttlMs = ttlMs;
+        this.nowMs = nowMs;
+    }
+    /**
+     * Store a pending authentication and return the opaque, unguessable
+     * `challengeToken` the client re-presents to `/auth/mfa`. The token carries NO
+     * information about the user — it is a random handle only.
+     */
+    store(identityHint, password) {
+        this.sweep();
+        const token = (0, node_crypto_1.randomBytes)(TOKEN_BYTES).toString('hex');
+        this.pending.set(token, {
+            identityHint,
+            password,
+            expiresAtMs: this.nowMs() + this.ttlMs,
+        });
+        return token;
+    }
+    /**
+     * Look up + SINGLE-USE consume a pending challenge. Returns the held credentials
+     * for a live, known token; `null` for an unknown, forged, or expired token (the
+     * controller maps `null` to the SAME generic 401 as a wrong code — no leak of
+     * WHY it failed). The entry is DELETED whether or not it was live, so a handle
+     * is never replayable.
+     */
+    consume(token) {
+        if (typeof token !== 'string' || token.length === 0)
+            return null;
+        const entry = this.pending.get(token);
+        // Single-use: remove on read regardless of validity (a spent/expired handle
+        // can never be retried → forces a fresh login, the anti-brute-force cooldown).
+        this.pending.delete(token);
+        if (entry === undefined)
+            return null;
+        if (this.nowMs() >= entry.expiresAtMs)
+            return null;
+        return { identityHint: entry.identityHint, password: entry.password };
+    }
+    /** Drop expired entries so the map cannot grow unbounded from abandoned logins. */
+    sweep() {
+        const now = this.nowMs();
+        for (const [token, entry] of this.pending) {
+            if (now >= entry.expiresAtMs)
+                this.pending.delete(token);
+        }
+    }
+}
+exports.PendingMfaStore = PendingMfaStore;

package/dist/auth/pending-mfa-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-mfa-store.js","sourceRoot":"","sources":["../../src/auth/pending-mfa-store.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;;;AAEH,6CAA0C;AAW1C,uEAAuE;AACvE,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAErC,wFAAwF;AACxF,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB;;;GAGG;AACH,MAAa,eAAe;IAIP;IAEA;IALF,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE3D,YACmB,QAAgB,cAAc;IAC/C,iEAAiE;IAChD,QAAsB,IAAI,CAAC,GAAG;QAF9B,UAAK,GAAL,KAAK,CAAyB;QAE9B,UAAK,GAAL,KAAK,CAAyB;IAC9C,CAAC;IAEJ;;;;OAIG;IACH,KAAK,CAAC,YAAoB,EAAE,QAAgB;QAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,IAAA,yBAAW,EAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE;YACtB,YAAY;YACZ,QAAQ;YACR,WAAW,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK;SACvC,CAAC,CAAC;QACH,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,KAAa;QACnB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACjE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,4EAA4E;QAC5E,+EAA+E;QAC/E,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACrC,IAAI,IAAI,CAAC,KAAK,EAAE,IAAI,KAAK,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QACnD,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;IACxE,CAAC;IAED,mFAAmF;IAC3E,KAAK;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC1C,IAAI,GAAG,IAAI,KAAK,CAAC,WAAW;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;CACF;AAlDD,0CAkDC"}

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

@@ -0,0 +1,42 @@
+/**
+ * `PersistenceModule` — the ONE place live infra connections are created (spec
+ * §4). Provides the live `mariadb` {@link Pool} ({@link SHIELD_DB_POOL}) and the
+ * live `ioredis` client ({@link SHIELD_REDIS}) from {@link AppConfig}, with
+ * graceful shutdown. Everything auth persists (sessions, credentials, hot state)
+ * flows through these two connections.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Team B (connection + composition) OWNS this file. The two factories create the
+ * real driver objects; the {@link ConnectionLifecycle} provider (a class Nest
+ * invokes `onModuleDestroy` on) closes them on shutdown — a value provider is not
+ * itself lifecycle-aware, so the teardown lives in that holder (see
+ * `connections.ts`). Both connections are exported so AuthModule can inject the
+ * pool (credential resolver + session record store) and the redis (hot store).
+ *
+ *   SHIELD_DB_POOL  — {@link createDbPool}: `mariadb.createPool` for the
+ *     `shield_core` account from `config.db`, `connectionLimit` from the ADR-0018
+ *     budget (`config.pool.perAccountMax.shield_core`). NOT a duplicate pool knob.
+ *   SHIELD_REDIS    — {@link createRedisClient}: `new Redis(config.redis.url)`
+ *     (ioredis). The hot tier (ADR-0013).
+ *
+ * Neither factory reads the HMAC key (that is the session/hasher composition in
+ * AuthModule). A blank `db.password` is allowed — it fails LOUD at connect time,
+ * which is correct for a runtime credential. Nothing here logs a credential.
+ *
+ * ⛔ OPT-IN: like AuthModule, this module opens LIVE connections, so it must only
+ * be imported when a deployment actually wants auth (AuthModule imports it). An
+ * enforcement-only app that never imports AuthModule never opens a pool/redis and
+ * keeps the no-`.env` boot. See auth.module.ts for the opt-in mechanism.
+ *
+ * ADR-0003: the real `mariadb`/`ioredis` live in guard (Core stays zero-dep).
+ */
+import { type DynamicModule } from '@nestjs/common';
+/**
+ * The persistence module. `forRoot()` returns the two connection providers (both
+ * exported so AuthModule can inject them) plus the shutdown holder. Opt-in: only
+ * imported when auth is wired.
+ */
+export declare class PersistenceModule {
+    static forRoot(): DynamicModule;
+}
+//# sourceMappingURL=persistence.module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.module.d.ts","sourceRoot":"","sources":["../../src/auth/persistence.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAU,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AA0C3E;;;;GAIG;AACH,qBACa,iBAAiB;IAC5B,MAAM,CAAC,OAAO,IAAI,aAAa;CAOhC"}