@astram/guard 0.1.0 → 0.2.0

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/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/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"}

package/dist/auth/persistence.module.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * `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).
+ */
+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 PersistenceModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersistenceModule = void 0;
+const common_1 = require("@nestjs/common");
+const config_module_js_1 = require("../config/config.module.js");
+const tokens_js_1 = require("./tokens.js");
+const connections_js_1 = require("./connections.js");
+/**
+ * The live MariaDB pool provider. Creates the ONE `shield_core` pool from config
+ * via {@link createDbPool}. `inject: [APP_CONFIG]` so the factory sees the resolved
+ * config. Teardown is handled by {@link ConnectionLifecycle}.
+ */
+const dbPoolProvider = {
+    provide: tokens_js_1.SHIELD_DB_POOL,
+    useFactory: (config) => (0, connections_js_1.createDbPool)(config),
+    inject: [config_module_js_1.APP_CONFIG],
+};
+/**
+ * The live Redis client provider. Creates the ONE hot-tier client from
+ * `config.redis.url` via {@link createRedisClient}. Teardown via
+ * {@link ConnectionLifecycle}.
+ */
+const redisProvider = {
+    provide: tokens_js_1.SHIELD_REDIS,
+    useFactory: (config) => (0, connections_js_1.createRedisClient)(config),
+    inject: [config_module_js_1.APP_CONFIG],
+};
+/**
+ * The lifecycle holder — injects the two connections and closes them on shutdown
+ * (`onModuleDestroy`). A value-provider connection gets no lifecycle callback, so
+ * this class is where graceful teardown happens.
+ */
+const lifecycleProvider = {
+    provide: connections_js_1.ConnectionLifecycle,
+    useFactory: (pool, redis) => new connections_js_1.ConnectionLifecycle(pool, redis),
+    inject: [tokens_js_1.SHIELD_DB_POOL, tokens_js_1.SHIELD_REDIS],
+};
+/**
+ * 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.
+ */
+let PersistenceModule = PersistenceModule_1 = class PersistenceModule {
+    static forRoot() {
+        return {
+            module: PersistenceModule_1,
+            providers: [dbPoolProvider, redisProvider, lifecycleProvider],
+            exports: [tokens_js_1.SHIELD_DB_POOL, tokens_js_1.SHIELD_REDIS],
+        };
+    }
+};
+exports.PersistenceModule = PersistenceModule;
+exports.PersistenceModule = PersistenceModule = PersistenceModule_1 = __decorate([
+    (0, common_1.Module)({})
+], PersistenceModule);

package/dist/auth/tokens.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Phase 0b Auth-surface **DI provider tokens** — the shared injection seams the
+ * three parallel teams bind/consume so they never collide (ADR-0023: composition
+ * is the framework's job; these are the framework's internal wiring points).
+ *
+ * ⛔ FROZEN by this prelude. Team B (composition) PROVIDES these; Team A
+ * (credential store) provides the resolver behind {@link SHIELD_CREDENTIAL_RESOLVER};
+ * Team C (`/auth` controllers) CONSUMES {@link SHIELD_AUTHENTICATOR} +
+ * {@link SHIELD_SESSION_AUTHORITY}. Do not rename these Symbols — a rename is a
+ * breaking change to every team's wiring.
+ *
+ * NOTE — some session/hasher adapters already ship their OWN tokens in
+ * `@astram/guard` (`SHIELD_PASSWORD_HASHER`, `SHIELD_SESSION_RECORD_STORE`,
+ * `SHIELD_HOT_SESSION_STORE`, `SHIELD_TOKEN_GENERATOR`, `SHIELD_REFRESH_HASHER`,
+ * `SHIELD_CLOCK`). Those stay the canonical tokens for those adapters. This file
+ * adds ONLY the NEW seams Phase 0b introduces: the live connections
+ * ({@link SHIELD_DB_POOL} / {@link SHIELD_REDIS}), the credential resolver, and the
+ * two COMPOSED engines ({@link SHIELD_AUTHENTICATOR} / {@link SHIELD_SESSION_AUTHORITY}).
+ * {@link SHIELD_PASSWORD_HASHER} is re-exported from the argon2 adapter for
+ * convenience so a team can import every auth-relevant token from one module.
+ *
+ * ADR-0003: no framework/DB/crypto imports here — just Symbols (+ one re-export).
+ */
+export { SHIELD_PASSWORD_HASHER } from '../authentication/argon2id-password-hasher.js';
+/**
+ * The ONE live `mariadb` `Pool` (the `shield_core` account — DML on
+ * `shield_identity`, ADR-0013/0014). **Provided by Team B** (the persistence
+ * factory — the single place a live DB connection is created). **Consumed by**
+ * the {@link SHIELD_CREDENTIAL_RESOLVER} factory and the
+ * {@link SHIELD_SESSION_RECORD_STORE} factory. Disposed on app shutdown.
+ */
+export declare const SHIELD_DB_POOL: unique symbol;
+/**
+ * The ONE live `ioredis` client (the hot session tier, ADR-0013). **Provided by
+ * Team B** (the persistence factory). **Consumed by** the
+ * {@link SHIELD_HOT_SESSION_STORE} factory. Disposed on app shutdown.
+ */
+export declare const SHIELD_REDIS: unique symbol;
+/**
+ * The `CredentialResolver` (core port) that resolves an identity hint →
+ * `ResolvedCredential | null`. **Provided by Team A** (the
+ * `MariaDbCredentialResolver`, injected with {@link SHIELD_DB_POOL}). **Consumed
+ * by** the {@link SHIELD_AUTHENTICATOR} factory (Team B) as
+ * `createAuthenticator({ resolver })`.
+ */
+export declare const SHIELD_CREDENTIAL_RESOLVER: unique symbol;
+/**
+ * The composed `Authenticator` (core engine) — `createAuthenticator({ hasher,
+ * resolver, identityBroker, factorVerifiers:[totp] })`. **Provided by Team B**
+ * (the AuthModule factory). **Consumed by** Team C's `/auth/login` +
+ * `/auth/mfa` controllers.
+ */
+export declare const SHIELD_AUTHENTICATOR: unique symbol;
+/**
+ * The composed `SessionAuthority` (core engine) — `createSessionAuthority({
+ * recordStore, hotStore, tokenGenerator, refreshHasher, clock, lifetimes })`.
+ * **Provided by Team B** (the AuthModule factory). **Consumed by** Team C's
+ * `/auth/login` (establish), `/auth/refresh` (rotate), `/auth/logout` (revoke),
+ * and `/auth/mfa` (establish after factor).
+ */
+export declare const SHIELD_SESSION_AUTHORITY: unique symbol;
+//# sourceMappingURL=tokens.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/auth/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,YAAY,eAAyB,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC"}

package/dist/auth/tokens.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Phase 0b Auth-surface **DI provider tokens** — the shared injection seams the
+ * three parallel teams bind/consume so they never collide (ADR-0023: composition
+ * is the framework's job; these are the framework's internal wiring points).
+ *
+ * ⛔ FROZEN by this prelude. Team B (composition) PROVIDES these; Team A
+ * (credential store) provides the resolver behind {@link SHIELD_CREDENTIAL_RESOLVER};
+ * Team C (`/auth` controllers) CONSUMES {@link SHIELD_AUTHENTICATOR} +
+ * {@link SHIELD_SESSION_AUTHORITY}. Do not rename these Symbols — a rename is a
+ * breaking change to every team's wiring.
+ *
+ * NOTE — some session/hasher adapters already ship their OWN tokens in
+ * `@astram/guard` (`SHIELD_PASSWORD_HASHER`, `SHIELD_SESSION_RECORD_STORE`,
+ * `SHIELD_HOT_SESSION_STORE`, `SHIELD_TOKEN_GENERATOR`, `SHIELD_REFRESH_HASHER`,
+ * `SHIELD_CLOCK`). Those stay the canonical tokens for those adapters. This file
+ * adds ONLY the NEW seams Phase 0b introduces: the live connections
+ * ({@link SHIELD_DB_POOL} / {@link SHIELD_REDIS}), the credential resolver, and the
+ * two COMPOSED engines ({@link SHIELD_AUTHENTICATOR} / {@link SHIELD_SESSION_AUTHORITY}).
+ * {@link SHIELD_PASSWORD_HASHER} is re-exported from the argon2 adapter for
+ * convenience so a team can import every auth-relevant token from one module.
+ *
+ * ADR-0003: no framework/DB/crypto imports here — just Symbols (+ one re-export).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHIELD_SESSION_AUTHORITY = exports.SHIELD_AUTHENTICATOR = exports.SHIELD_CREDENTIAL_RESOLVER = exports.SHIELD_REDIS = exports.SHIELD_DB_POOL = exports.SHIELD_PASSWORD_HASHER = void 0;
+var argon2id_password_hasher_js_1 = require("../authentication/argon2id-password-hasher.js");
+Object.defineProperty(exports, "SHIELD_PASSWORD_HASHER", { enumerable: true, get: function () { return argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER; } });
+/**
+ * The ONE live `mariadb` `Pool` (the `shield_core` account — DML on
+ * `shield_identity`, ADR-0013/0014). **Provided by Team B** (the persistence
+ * factory — the single place a live DB connection is created). **Consumed by**
+ * the {@link SHIELD_CREDENTIAL_RESOLVER} factory and the
+ * {@link SHIELD_SESSION_RECORD_STORE} factory. Disposed on app shutdown.
+ */
+exports.SHIELD_DB_POOL = Symbol('SHIELD_DB_POOL');
+/**
+ * The ONE live `ioredis` client (the hot session tier, ADR-0013). **Provided by
+ * Team B** (the persistence factory). **Consumed by** the
+ * {@link SHIELD_HOT_SESSION_STORE} factory. Disposed on app shutdown.
+ */
+exports.SHIELD_REDIS = Symbol('SHIELD_REDIS');
+/**
+ * The `CredentialResolver` (core port) that resolves an identity hint →
+ * `ResolvedCredential | null`. **Provided by Team A** (the
+ * `MariaDbCredentialResolver`, injected with {@link SHIELD_DB_POOL}). **Consumed
+ * by** the {@link SHIELD_AUTHENTICATOR} factory (Team B) as
+ * `createAuthenticator({ resolver })`.
+ */
+exports.SHIELD_CREDENTIAL_RESOLVER = Symbol('SHIELD_CREDENTIAL_RESOLVER');
+/**
+ * The composed `Authenticator` (core engine) — `createAuthenticator({ hasher,
+ * resolver, identityBroker, factorVerifiers:[totp] })`. **Provided by Team B**
+ * (the AuthModule factory). **Consumed by** Team C's `/auth/login` +
+ * `/auth/mfa` controllers.
+ */
+exports.SHIELD_AUTHENTICATOR = Symbol('SHIELD_AUTHENTICATOR');
+/**
+ * The composed `SessionAuthority` (core engine) — `createSessionAuthority({
+ * recordStore, hotStore, tokenGenerator, refreshHasher, clock, lifetimes })`.
+ * **Provided by Team B** (the AuthModule factory). **Consumed by** Team C's
+ * `/auth/login` (establish), `/auth/refresh` (rotate), `/auth/logout` (revoke),
+ * and `/auth/mfa` (establish after factor).
+ */
+exports.SHIELD_SESSION_AUTHORITY = Symbol('SHIELD_SESSION_AUTHORITY');

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

@@ -0,0 +1,96 @@
+/**
+ * `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.
+ */
+import type { Pool } from 'mariadb';
+import type { CredentialResolver, ResolvedCredential } from '@astram/core';
+/** DI token for the resolver — re-exported from the shared auth tokens module. */
+export { SHIELD_CREDENTIAL_RESOLVER } from '../auth/tokens.js';
+/**
+ * The concrete MariaDB-backed {@link CredentialResolver}. Constructed with the
+ * live `shield_core` {@link Pool} (via {@link SHIELD_CREDENTIAL_RESOLVER}'s
+ * factory, which injects {@link SHIELD_DB_POOL}). Stateless per call apart from
+ * the injected pool.
+ *
+ * ⛔ SKELETON: `resolve()` throws until Team A implements the SELECT above.
+ */
+export declare class MariaDbCredentialResolver implements CredentialResolver {
+    private readonly pool;
+    constructor(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.
+     */
+    resolve(identityHint: string): Promise<ResolvedCredential | null>;
+}
+//# sourceMappingURL=mariadb-credential-resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-credential-resolver.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-credential-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EACV,kBAAkB,EAElB,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAEtB,kFAAkF;AAClF,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAwD/D;;;;;;;GAOG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEvC;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAgCxE"}