@astram/guard 0.1.0 → 0.2.0

package/dist/auth/auth.controller.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Phase 0b Auth-surface — the framework-owned **`/auth/*` HTTP controllers**
+ * (spec §2). A consumer app gets login + MFA + refresh + logout FOR FREE by
+ * importing `ShieldModule.forRoot()` (which imports `AuthModule`); it writes no
+ * auth code. All four routes are `@Public()` (ADR-0002): they run BEFORE the
+ * caller has a session, so the global deny-by-default guard must NOT gate them.
+ *
+ * This controller is a THIN transport shim over the two composed core engines
+ * (`SHIELD_AUTHENTICATOR` / `SHIELD_SESSION_AUTHORITY`, from Team B). It holds NO
+ * business logic beyond mapping engine outcomes → HTTP status + the frozen DTO
+ * shapes (`./dto.ts`). Every security invariant is enforced here per the DTO
+ * header + the spec:
+ *
+ * ── OUTCOME → HTTP STATUS MAP (the security contract) ────────────────────────
+ *   login authenticated        → 200  SessionSuccess { session(no-secret), tokens }
+ *   login mfa_required          → 200  MfaChallengeResponse { mfaRequired, challengeToken }
+ *   login invalid_credentials   → 401  GENERIC   ← unknown-user AND wrong-password IDENTICAL
+ *   login auth_unavailable      → 503  RETRYABLE ← transient blip is NOT a credential deny
+ *   mfa   success               → 200  SessionSuccess
+ *   mfa   wrong/expired/forged   → 401  GENERIC   ← indistinguishable from a bad code
+ *   mfa   auth_unavailable      → 503  RETRYABLE
+ *   refresh ok                  → 200  SessionSuccess (new tokens, rotated session)
+ *   refresh reuse/invalid       → 401  GENERIC   session_rejected (lineage-kill is the engine's)
+ *   logout                      → 204  (idempotent; unknown/already-revoked → still 204)
+ *
+ * ── ANTI-ENUMERATION ── login + mfa failures are a SINGLE generic 401 with an
+ *   identical body (`{ error: 'invalid_credentials' }`) whether the user is
+ *   unknown, the password is wrong, or the factor is wrong/expired. The core
+ *   authenticator's decoy-verify already equalizes timing; this layer never adds a
+ *   distinguishing field/status.
+ *
+ * ── NO SECRET LEAK ── no password, hash, TOTP secret, raw token (beyond the two a
+ *   success legitimately mints), or challenge internal ever appears in a body or a
+ *   log. Request bodies are NEVER logged. The `SessionView` mapped from the core
+ *   `Session` carries no secret by construction.
+ *
+ * ── TRANSIENT ≠ DENY (ADR-0016) ── a transient `authentication_unavailable` from
+ *   the authenticator becomes a RETRYABLE 503, never a 401 — a dependency blip must
+ *   not look like (or trigger the client to treat it as) a credential failure.
+ *   ⚠ ENGINE-SEAM LIMIT on /auth/refresh: the core `SessionAuthority.rotate`
+ *   collapses BOTH a terminal deny AND a transient store outage into one
+ *   `SessionRejectedError` (its top-level fail-closed catch — see
+ *   session-authority.ts). From THIS seam the two are indistinguishable, so refresh
+ *   maps the generic reject to 401. Surfacing a retryable-503 on a refresh-time
+ *   store outage would require the engine to expose a transient signal it does not
+ *   today — flagged to the architect as a possible core-API gap (NOT worked around
+ *   here; we do not invent a core API).
+ *
+ * ADR-0023: composition is the framework's job — this controller only CONSUMES the
+ * composed engines via DI tokens; it never news-up an engine or an adapter.
+ */
+import type { Authenticator, SessionAuthority } from '@astram/core';
+import { PendingMfaStore } from './pending-mfa-store.js';
+import type { LoginRequest, LoginResponse, LogoutRequest, MfaRequest, RefreshRequest, SessionSuccess } from './dto.js';
+/**
+ * The framework-owned auth endpoints. Registered into `AuthModule`'s `controllers`
+ * by the integration owner / Team B (this controller is EXPORTED for that purpose;
+ * it does NOT edit auth.module.ts itself). Depends on the two composed engines +
+ * the pending-MFA store (provided alongside it).
+ */
+export declare class AuthController {
+    private readonly authenticator;
+    private readonly sessionAuthority;
+    private readonly pendingMfa;
+    constructor(authenticator: Authenticator, sessionAuthority: SessionAuthority, pendingMfa: PendingMfaStore);
+    /**
+     * `POST /auth/login` — verify a password credential and either establish a
+     * session, issue an MFA challenge, deny generically, or signal a transient
+     * outage. NEVER logs the request body.
+     */
+    login(body: LoginRequest): Promise<LoginResponse>;
+    /**
+     * `POST /auth/mfa` — complete a pending MFA login. Consumes the single-use
+     * challenge handle (unknown/expired/forged → same generic 401 as a bad code),
+     * then RE-RUNS `authenticate(hint, [password, totp])` with the presented code
+     * (the authenticator has no standalone factor-verify seam — the full attempt IS
+     * the verify). Success → establish + tokens.
+     */
+    mfa(body: MfaRequest): Promise<SessionSuccess>;
+    /**
+     * `POST /auth/refresh` — rotate the refresh token. Reuse/invalid/expired →
+     * generic 401 (`session_rejected`; the engine already killed the lineage,
+     * ADR-0015). ⚠ See the class header: the engine's rotate collapses a transient
+     * store outage into the SAME reject, so refresh cannot emit the ADR-0016 503 from
+     * this seam today (flagged core-API gap).
+     */
+    refresh(body: RefreshRequest): Promise<SessionSuccess>;
+    /**
+     * `POST /auth/logout` — revoke the session. Idempotent + leak-free: revoking an
+     * unknown or already-revoked session still returns 204 (the engine's `revoke`
+     * swallows and returns void either way), so existence is never revealed.
+     */
+    logout(body: LogoutRequest): Promise<void>;
+    /**
+     * Establish a session for an authenticated principal, mapping the engine's
+     * generic `SessionRejectedError` (a malformed principal or a store outage at
+     * establish time) to a generic 401. We never surface a session-establish failure
+     * as a distinct, enumerable outcome.
+     */
+    private establishOrReject;
+}
+//# sourceMappingURL=auth.controller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.controller.d.ts","sourceRoot":"","sources":["../../src/auth/auth.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAWH,OAAO,KAAK,EACV,aAAa,EAKb,gBAAgB,EAEjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,cAAc,EACd,cAAc,EAEf,MAAM,UAAU,CAAC;AAqElB;;;;;GAKG;AACH,qBACa,cAAc;IAGvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAE9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAHV,aAAa,EAAE,aAAa,EAE5B,gBAAgB,EAAE,gBAAgB,EAClC,UAAU,EAAE,eAAe;IAG9C;;;;OAIG;IAIG,KAAK,CAAS,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAgC/D;;;;;;OAMG;IAIG,GAAG,CAAS,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;IAkC5D;;;;;;OAMG;IAIG,OAAO,CAAS,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAapE;;;;OAIG;IAIG,MAAM,CAAS,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxD;;;;;OAKG;YACW,iBAAiB;CAOhC"}

package/dist/auth/auth.controller.js

@@ -0,0 +1,313 @@
+"use strict";
+/**
+ * Phase 0b Auth-surface — the framework-owned **`/auth/*` HTTP controllers**
+ * (spec §2). A consumer app gets login + MFA + refresh + logout FOR FREE by
+ * importing `ShieldModule.forRoot()` (which imports `AuthModule`); it writes no
+ * auth code. All four routes are `@Public()` (ADR-0002): they run BEFORE the
+ * caller has a session, so the global deny-by-default guard must NOT gate them.
+ *
+ * This controller is a THIN transport shim over the two composed core engines
+ * (`SHIELD_AUTHENTICATOR` / `SHIELD_SESSION_AUTHORITY`, from Team B). It holds NO
+ * business logic beyond mapping engine outcomes → HTTP status + the frozen DTO
+ * shapes (`./dto.ts`). Every security invariant is enforced here per the DTO
+ * header + the spec:
+ *
+ * ── OUTCOME → HTTP STATUS MAP (the security contract) ────────────────────────
+ *   login authenticated        → 200  SessionSuccess { session(no-secret), tokens }
+ *   login mfa_required          → 200  MfaChallengeResponse { mfaRequired, challengeToken }
+ *   login invalid_credentials   → 401  GENERIC   ← unknown-user AND wrong-password IDENTICAL
+ *   login auth_unavailable      → 503  RETRYABLE ← transient blip is NOT a credential deny
+ *   mfa   success               → 200  SessionSuccess
+ *   mfa   wrong/expired/forged   → 401  GENERIC   ← indistinguishable from a bad code
+ *   mfa   auth_unavailable      → 503  RETRYABLE
+ *   refresh ok                  → 200  SessionSuccess (new tokens, rotated session)
+ *   refresh reuse/invalid       → 401  GENERIC   session_rejected (lineage-kill is the engine's)
+ *   logout                      → 204  (idempotent; unknown/already-revoked → still 204)
+ *
+ * ── ANTI-ENUMERATION ── login + mfa failures are a SINGLE generic 401 with an
+ *   identical body (`{ error: 'invalid_credentials' }`) whether the user is
+ *   unknown, the password is wrong, or the factor is wrong/expired. The core
+ *   authenticator's decoy-verify already equalizes timing; this layer never adds a
+ *   distinguishing field/status.
+ *
+ * ── NO SECRET LEAK ── no password, hash, TOTP secret, raw token (beyond the two a
+ *   success legitimately mints), or challenge internal ever appears in a body or a
+ *   log. Request bodies are NEVER logged. The `SessionView` mapped from the core
+ *   `Session` carries no secret by construction.
+ *
+ * ── TRANSIENT ≠ DENY (ADR-0016) ── a transient `authentication_unavailable` from
+ *   the authenticator becomes a RETRYABLE 503, never a 401 — a dependency blip must
+ *   not look like (or trigger the client to treat it as) a credential failure.
+ *   ⚠ ENGINE-SEAM LIMIT on /auth/refresh: the core `SessionAuthority.rotate`
+ *   collapses BOTH a terminal deny AND a transient store outage into one
+ *   `SessionRejectedError` (its top-level fail-closed catch — see
+ *   session-authority.ts). From THIS seam the two are indistinguishable, so refresh
+ *   maps the generic reject to 401. Surfacing a retryable-503 on a refresh-time
+ *   store outage would require the engine to expose a transient signal it does not
+ *   today — flagged to the architect as a possible core-API gap (NOT worked around
+ *   here; we do not invent a core API).
+ *
+ * ADR-0023: composition is the framework's job — this controller only CONSUMES the
+ * composed engines via DI tokens; it never news-up an engine or an adapter.
+ */
+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 __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthController = void 0;
+const common_1 = require("@nestjs/common");
+const classification_decorator_js_1 = require("../enforcement/classification.decorator.js");
+const tokens_js_1 = require("./tokens.js");
+const pending_mfa_store_js_1 = require("./pending-mfa-store.js");
+/**
+ * The core `Authenticator`'s generic transient reason (see authenticator.ts —
+ * `REASON_AUTH_UNAVAILABLE`). A `rejected` result carrying THIS reason is the
+ * ADR-0016 transient signal → 503; any OTHER rejected reason is a credential deny
+ * → generic 401.
+ */
+const REASON_AUTH_UNAVAILABLE = 'authentication_unavailable';
+/**
+ * The SINGLE generic body for EVERY login/mfa/refresh failure. Deliberately
+ * non-distinguishing (anti-enumeration): unknown user, wrong password, wrong/
+ * expired/forged factor, and a rejected refresh ALL return this identical body.
+ * Carries NO reason detail that could leak which check failed.
+ */
+const GENERIC_AUTH_FAILURE = Object.freeze({ error: 'invalid_credentials' });
+/** The generic retryable body for a transient dependency outage (ADR-0016). */
+const RETRYABLE_BODY = Object.freeze({ error: 'authentication_unavailable' });
+/** Throw the generic 401 (indistinguishable across all credential-failure paths). */
+function genericUnauthorized() {
+    throw new common_1.HttpException(GENERIC_AUTH_FAILURE, common_1.HttpStatus.UNAUTHORIZED);
+}
+/** Throw the retryable 503 (transient — NOT a deny; the client may retry). */
+function retryableUnavailable() {
+    throw new common_1.HttpException(RETRYABLE_BODY, common_1.HttpStatus.SERVICE_UNAVAILABLE);
+}
+/**
+ * Map a core `Session` → the client-safe {@link SessionView}. Copies ONLY the
+ * non-secret lifecycle fields the DTO allows — there is no token/hash on `Session`
+ * to begin with, but this explicit projection guarantees no future `Session` field
+ * leaks into a response body by accident.
+ */
+function toSessionView(session) {
+    return {
+        sessionId: session.sessionId,
+        principalId: session.principalId,
+        tenantId: session.tenantId,
+        status: session.status,
+        issuedAtMs: session.issuedAtMs,
+        expiresAtMs: session.expiresAtMs,
+    };
+}
+/** Map a core `SessionEstablishment` → the {@link SessionSuccess} success body. */
+function toSessionSuccess(est) {
+    return {
+        session: toSessionView(est.session),
+        tokens: {
+            accessToken: est.tokens.accessToken,
+            refreshToken: est.tokens.refreshToken,
+        },
+    };
+}
+/** Build the password credential the authenticator expects. */
+function passwordCredential(password) {
+    return { factor: 'password', payload: { password } };
+}
+/** Build the TOTP credential the authenticator's factor verifier expects (payload.code). */
+function totpCredential(code) {
+    return { factor: 'totp', payload: { code } };
+}
+/**
+ * The framework-owned auth endpoints. Registered into `AuthModule`'s `controllers`
+ * by the integration owner / Team B (this controller is EXPORTED for that purpose;
+ * it does NOT edit auth.module.ts itself). Depends on the two composed engines +
+ * the pending-MFA store (provided alongside it).
+ */
+let AuthController = class AuthController {
+    authenticator;
+    sessionAuthority;
+    pendingMfa;
+    constructor(authenticator, sessionAuthority, pendingMfa) {
+        this.authenticator = authenticator;
+        this.sessionAuthority = sessionAuthority;
+        this.pendingMfa = pendingMfa;
+    }
+    /**
+     * `POST /auth/login` — verify a password credential and either establish a
+     * session, issue an MFA challenge, deny generically, or signal a transient
+     * outage. NEVER logs the request body.
+     */
+    async login(body) {
+        const identityHint = typeof body?.identityHint === 'string' ? body.identityHint : '';
+        const password = typeof body?.password === 'string' ? body.password : '';
+        const result = await this.authenticator.authenticate(identityHint, [passwordCredential(password)]);
+        if (result.outcome === 'authenticated') {
+            const principal = requirePrincipal(result);
+            const est = await this.establishOrReject(principal);
+            return toSessionSuccess(est);
+        }
+        if (result.outcome === 'mfa_required') {
+            // Password verified, a second factor is outstanding. Hold the pending
+            // credentials server-side and hand back an OPAQUE, unforgeable challenge
+            // handle. NO session yet. The handle carries nothing about the user.
+            const challengeToken = this.pendingMfa.store(identityHint, password);
+            return { mfaRequired: true, challengeToken };
+        }
+        // outcome === 'rejected'. Distinguish ONLY transient-vs-deny (never which
+        // credential failed): a transient dependency blip is a retryable 503, anything
+        // else is the generic 401.
+        if (result.reason === REASON_AUTH_UNAVAILABLE) {
+            retryableUnavailable();
+        }
+        genericUnauthorized();
+    }
+    /**
+     * `POST /auth/mfa` — complete a pending MFA login. Consumes the single-use
+     * challenge handle (unknown/expired/forged → same generic 401 as a bad code),
+     * then RE-RUNS `authenticate(hint, [password, totp])` with the presented code
+     * (the authenticator has no standalone factor-verify seam — the full attempt IS
+     * the verify). Success → establish + tokens.
+     */
+    async mfa(body) {
+        const challengeToken = typeof body?.challengeToken === 'string' ? body.challengeToken : '';
+        const code = typeof body?.code === 'string' ? body.code : '';
+        // Phase 0b: only 'totp' is real. A body claiming another factor cannot be
+        // satisfied → treat as a generic failure (no leak of "unsupported factor").
+        const factor = body?.factor;
+        // Consume the pending challenge (single-use). A miss (unknown/forged/expired)
+        // is indistinguishable from a wrong code — generic 401, no leak.
+        const pending = this.pendingMfa.consume(challengeToken);
+        if (pending === null || factor !== 'totp') {
+            genericUnauthorized();
+        }
+        const result = await this.authenticator.authenticate(pending.identityHint, [passwordCredential(pending.password), totpCredential(code)]);
+        if (result.outcome === 'authenticated') {
+            const principal = requirePrincipal(result);
+            const est = await this.establishOrReject(principal);
+            return toSessionSuccess(est);
+        }
+        // Anything else (wrong code → rejected; still-outstanding → mfa_required) is a
+        // failure. A transient blip is retryable; everything else is a generic 401.
+        // (A repeat mfa_required here means the code did not satisfy the factor.)
+        if (result.reason === REASON_AUTH_UNAVAILABLE) {
+            retryableUnavailable();
+        }
+        genericUnauthorized();
+    }
+    /**
+     * `POST /auth/refresh` — rotate the refresh token. Reuse/invalid/expired →
+     * generic 401 (`session_rejected`; the engine already killed the lineage,
+     * ADR-0015). ⚠ See the class header: the engine's rotate collapses a transient
+     * store outage into the SAME reject, so refresh cannot emit the ADR-0016 503 from
+     * this seam today (flagged core-API gap).
+     */
+    async refresh(body) {
+        const refreshToken = typeof body?.refreshToken === 'string' ? body.refreshToken : '';
+        try {
+            const est = await this.sessionAuthority.rotate(refreshToken);
+            return toSessionSuccess(est);
+        }
+        catch {
+            // The engine throws only its generic SessionRejectedError (reuse, invalid,
+            // expiry, or a swallowed store outage — all indistinguishable here). Map to a
+            // generic 401; never leak which, never echo the token.
+            genericUnauthorized();
+        }
+    }
+    /**
+     * `POST /auth/logout` — revoke the session. Idempotent + leak-free: revoking an
+     * unknown or already-revoked session still returns 204 (the engine's `revoke`
+     * swallows and returns void either way), so existence is never revealed.
+     */
+    async logout(body) {
+        const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : '';
+        // `revoke` is void + best-effort-idempotent by contract; it never throws a
+        // resource-existence signal. We still guard against an unexpected throw so a
+        // logout never 500s (which could itself be an existence oracle).
+        try {
+            await this.sessionAuthority.revoke(sessionId);
+        }
+        catch {
+            // Swallow — logout is idempotent + must not leak. 204 regardless.
+        }
+    }
+    /**
+     * Establish a session for an authenticated principal, mapping the engine's
+     * generic `SessionRejectedError` (a malformed principal or a store outage at
+     * establish time) to a generic 401. We never surface a session-establish failure
+     * as a distinct, enumerable outcome.
+     */
+    async establishOrReject(principal) {
+        try {
+            return await this.sessionAuthority.establish(principal);
+        }
+        catch {
+            genericUnauthorized();
+        }
+    }
+};
+exports.AuthController = AuthController;
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('login'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "login", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('mfa'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "mfa", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('refresh'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "refresh", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('logout'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AuthController.prototype, "logout", null);
+exports.AuthController = AuthController = __decorate([
+    (0, common_1.Controller)('auth'),
+    __param(0, (0, common_1.Inject)(tokens_js_1.SHIELD_AUTHENTICATOR)),
+    __param(1, (0, common_1.Inject)(tokens_js_1.SHIELD_SESSION_AUTHORITY)),
+    __metadata("design:paramtypes", [Object, Object, pending_mfa_store_js_1.PendingMfaStore])
+], AuthController);
+/**
+ * Narrow an `authenticated` result to its guaranteed principal. The core engine
+ * populates `principal` ONLY on `outcome === 'authenticated'`; this asserts that
+ * invariant so a missing principal fails closed (generic 401) rather than
+ * establishing a session for `undefined`.
+ */
+function requirePrincipal(result) {
+    const principal = result.principal;
+    if (principal === undefined || principal === null) {
+        genericUnauthorized();
+    }
+    return principal;
+}

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

@@ -0,0 +1,104 @@
+/**
+ * `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.
+ */
+import { type DynamicModule } from '@nestjs/common';
+import type { CredentialResolver, HmacSha1 } from '@astram/core';
+/**
+ * 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.
+ */
+export declare const hmacSha1: HmacSha1;
+/**
+ * Options for {@link AuthModule.forRoot} — registration-time collaborators the
+ * consumer plugs through {@link ShieldModule.forRoot}.
+ */
+export interface AuthModuleOptions {
+    /**
+     * OPTIONAL custom credential resolver (the store login checks against). Omit →
+     * the framework's default {@link MariaDbCredentialResolver} (reads
+     * `shield_identity.identity_credential`). Supply a consumer implementation of the
+     * core `CredentialResolver` port to authenticate against your OWN user/identity
+     * schema. Only meaningful here (AuthModule is only imported under `auth: true`).
+     */
+    readonly credentialResolver?: CredentialResolver;
+}
+/**
+ * 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.
+ */
+export declare 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?: AuthModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=auth.module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../../src/auth/auth.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,EAAU,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAa3E,OAAO,KAAK,EAGV,kBAAkB,EAOlB,QAAQ,EACT,MAAM,cAAc,CAAC;AA+BtB;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,QACqE,CAAC;AAiL7F;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CAClD;AAED;;;;;;GAMG;AACH,qBACa,UAAU;IACrB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,iBAAsB,GAAG,aAAa;CA8B/D"}