@astram/guard 0.1.1 → 0.3.0

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

@@ -1,14 +1,21 @@
 import { type DynamicModule } from '@nestjs/common';
+import type { CredentialResolver, FactorVerifier } from '@astram/core';
+import type { RecordAuthorizationInputs } from '../authz/wire-record-authorization.js';
+import type { ProfileResolver } from '../auth/profile-resolver.js';
+import type { CredentialWriter } from '../auth/ports/credential-writer.js';
+import type { ResetTokenStore } from '../auth/ports/reset-token-store.js';
+import type { EmailSender } from '../auth/ports/email-sender.js';
+import type { RecoveryCodeStore } from '../auth/ports/recovery-code-store.js';
+import type { ProfileWriter } from '../auth/ports/profile-writer.js';
+import type { SessionSweeper } from '../auth/ports/session-sweeper.js';
+import type { MfaDeviceStore } from '../auth/ports/mfa-device-store.js';
+import type { AuditSink } from '../auth/ports/audit-sink.js';
+import type { SessionFactsProjector } from '../auth/ports/session-facts-projector.js';
 import type { CoreDecisionAuthority } from '../enforcement/core-seam.js';
 import { type AppConfig } from '../config/app-config.js';
-/**
- * DI token for the Core decision authority (the ADR-0001 single decision
- * authority) that the enforcement guard consults. The consumer supplies the real
- * `@astram/core` authority through {@link ShieldModule.forRoot}; when omitted the
- * framework binds the fail-closed {@link stubDecisionAuthority} (deny-by-default),
- * so a mis-wiring cannot silently open a door.
- */
-export declare const SHIELD_DECISION_AUTHORITY: unique symbol;
+import { SHIELD_DECISION_AUTHORITY } from './shield-tokens.js';
+export { SHIELD_DECISION_AUTHORITY };
+export type { RecordAuthorizationInputs } from '../authz/wire-record-authorization.js';
 /**
  * Options for {@link ShieldModule.forRoot}. Intentionally minimal (ADR-0023 §7 —
  * no speculative abstraction): the consumer declares Shield through this ONE seam.
@@ -21,12 +28,126 @@ export interface ShieldModuleOptions {
      * the real Core authority — the guard's call site does not change.
      */
     readonly decisionAuthority?: CoreDecisionAuthority;
+    /**
+     * ⛔ FRAMEWORK-OWNED RECORD-TIER WIRING (design §9, Phase 5 — the preferred path).
+     *
+     * Supply the PIECES the framework needs to build the real Core decision authority
+     * ITSELF, instead of a pre-built {@link decisionAuthority}. When present, ShieldModule
+     * INTERNALLY constructs the four record-tier adapters
+     * (`MariaDbRecordPermissionRuleAdapter` / `MariaDbRecordShareAdapter` /
+     * `MariaDbCrossTenantGrantAdapter` / `ManifestOperationAuthorityAdapter`) over the
+     * supplied `pool`/`operationManifest` and calls core's `createWiredDecisionAuthority`
+     * with them + the app-owned `permissionFacts` / `sessionFacts` / `registry`.
+     *
+     * The app supplies ONLY: the DB `pool`, the two app-owned ports (`permissionFacts`,
+     * `sessionFacts`), the module `registry`, and the operation-manifest DATA. It CANNOT
+     * supply — or weaken — the four record-tier read adapters: they are framework-owned and
+     * un-overridable BY CONSTRUCTION (a planted fail-open record adapter is impossible —
+     * the whole point of the "framework-owns-the-data-layer" initiative).
+     *
+     * MUTUALLY EXCLUSIVE with {@link decisionAuthority} — supplying BOTH is a misconfig and
+     * throws at registration. Supplying NEITHER binds the fail-closed stub (unchanged).
+     */
+    readonly recordAuthorization?: RecordAuthorizationInputs;
     /**
      * Application config (port/environment/ADR-0018 pool budget). Omit to load from
      * the environment via {@link loadAppConfig}. Supplied here so a consumer can
      * inject computed config through the one seam rather than editing the framework.
      */
     readonly config?: AppConfig;
+    /**
+     * ⛔ OPT-IN: the framework-owned login → session auth surface (Phase 0b — the
+     * `/auth/*` endpoints + the composed `Authenticator` / `SessionAuthority`).
+     *
+     * DEFAULT `false` (ABSENT): an enforcement-only app does NOT import
+     * {@link AuthModule} — so it never opens a MariaDB pool / Redis client, never
+     * fires the fail-closed `assertRefreshHmacKey` gate, and keeps the no-`.env`
+     * boot promised by `create-astram-app`. `ShieldModule.forRoot()` composes with
+     * a blank refresh-HMAC key and no live connection (enforcement-only).
+     *
+     * `true`: imports {@link AuthModule.forRoot} (which pulls the live connections +
+     * composes the authenticator + session authority + registers the four `/auth/*`
+     * routes) and re-exports {@link SHIELD_AUTHENTICATOR} / {@link SHIELD_SESSION_AUTHORITY}
+     * app-wide. An auth-enabled app fails LOUD at boot if `SHIELD_REFRESH_HMAC_KEY`
+     * is blank — auth can never compose unkeyed.
+     */
+    readonly auth?: boolean;
+    /**
+     * OPTIONAL custom credential resolver (the store login checks against). Omit →
+     * the framework's default `MariaDbCredentialResolver` (reads
+     * `shield_identity.identity_credential`). Supply a consumer implementation of the
+     * core `CredentialResolver` port to authenticate against your OWN user/identity
+     * schema (e.g. a multi-tenant users+roles model) WITHOUT editing the framework.
+     *
+     * Only consulted when `auth: true` (a no-op without it — no AuthModule composes,
+     * so no resolver is wired). The seam swaps the STORE only: a supplied resolver
+     * still flows through the SAME composed authenticator (anti-enumeration decoy
+     * verify, MFA, no-secret-leak). A resolver returning `null` = unknown principal
+     * (generic 401); throwing = fail-closed transient — exactly the default contract.
+     */
+    readonly credentialResolver?: CredentialResolver;
+    /**
+     * OPTIONAL current-user profile resolver backing `GET /auth/me`. Omit → `/auth/me`
+     * returns an honest 501 (the framework is agnostic to your ORG schema, so it cannot
+     * name the user/company/roles without your tables). Supply an implementation of the
+     * {@link ProfileResolver} port to return the signed-in user's display profile
+     * (names, never UUIDs). Only consulted when `auth: true`.
+     */
+    readonly profileResolver?: ProfileResolver;
+    /**
+     * OPTIONAL account/credential-surface seams (forgot/reset, change-password, MFA
+     * enrollment, profile edit). Each is threaded straight through to
+     * {@link AuthModule.forRoot} (bound under its token, or `null` when absent → the
+     * route returns 501). Only consulted when `auth: true`. Supply a consumer
+     * implementation of the matching `@astram/guard` port to enable the route.
+     */
+    readonly credentialWriter?: CredentialWriter;
+    readonly resetTokenStore?: ResetTokenStore;
+    readonly emailSender?: EmailSender;
+    readonly recoveryCodeStore?: RecoveryCodeStore;
+    readonly profileWriter?: ProfileWriter;
+    readonly sessionSweeper?: SessionSweeper;
+    /**
+     * OPTIONAL auth-surface audit sink — see {@link AuthModuleOptions.auditSink}.
+     * Threaded straight through to {@link AuthModule.forRoot} (bound under its token, or
+     * `null` when absent → the recovery-login audit no-ops). Only consulted when
+     * `auth: true`.
+     */
+    readonly auditSink?: AuditSink;
+    /**
+     * OPTIONAL multi-device MFA store — see {@link AuthModuleOptions.mfaDeviceStore}.
+     * Threaded straight through to {@link AuthModule.forRoot} (bound under its token,
+     * or `null` when absent → the device routes 501). Only consulted when `auth: true`.
+     */
+    readonly mfaDeviceStore?: MfaDeviceStore;
+    /**
+     * OPTIONAL login `totp` verifier override — see {@link AuthModuleOptions.totpVerifier}.
+     * Threaded straight through to {@link AuthModule.forRoot} (replaces the default
+     * single-secret verifier in the composed authenticator; absent → the default). A
+     * consumer plugs an OR-matching multi-device verifier here. Only consulted when
+     * `auth: true`.
+     */
+    readonly totpVerifier?: FactorVerifier;
+    /**
+     * OPTIONAL root allowlist — the server-side, trusted set of canonical
+     * principal ids (user uuids) that ARE roots. Threaded straight through
+     * to {@link AuthModule.forRoot} → `createIdentityBroker({ internalRootIds })`.
+     * ROOT SAFETY: this is the ONLY way a login mints a root (the
+     * Internal identity adapter keys the trusted signal off THIS list, never off a
+     * claim). Omit → `[]` → default-deny (nobody is a root). Only consulted when
+     * `auth: true`.
+     */
+    readonly rootIds?: readonly string[];
+    /**
+     * OPTIONAL eager session-facts projector (ADR-0011) — see
+     * {@link AuthModuleOptions.sessionFactsProjector}. Threaded straight through to
+     * {@link AuthModule.forRoot} (bound under {@link SHIELD_SESSION_FACTS_PROJECTOR}, or
+     * `null` when absent → the auth controller omits `cachedFacts` and gate 5 DB-reloads
+     * every request, today's behavior). When supplied, login/refresh cache the principal's
+     * coarse grants on the session binding so gate 5 serves them from the request's
+     * `cachedFacts`. Only consulted when `auth: true`.
+     */
+    readonly sessionFactsProjector?: SessionFactsProjector;
 }
 /** Async variant of {@link ShieldModuleOptions} (DI-computed config). */
 export interface ShieldModuleAsyncOptions {
@@ -36,6 +157,80 @@ export interface ShieldModuleAsyncOptions {
     readonly useFactory: (...args: readonly unknown[]) => Promise<ShieldModuleOptions> | ShieldModuleOptions;
     /** Modules exporting the injected providers. */
     readonly imports?: readonly unknown[];
+    /**
+     * ⛔ OPT-IN auth (see {@link ShieldModuleOptions.auth}). STATIC here (not part of
+     * the async factory result): whether an app wires the auth surface is a
+     * deployment-topology decision known at REGISTRATION time, and a NestJS
+     * `DynamicModule.imports` list is composed statically — it cannot depend on the
+     * async-resolved `ShieldModuleOptions`. So the flag lives on the async-options
+     * object directly, gating the {@link AuthModule} import + engine re-exports
+     * exactly like {@link forRoot}. DEFAULT `false` (no auth → no live connection →
+     * no-`.env` boot preserved).
+     */
+    readonly auth?: boolean;
+    /**
+     * OPTIONAL custom credential resolver — see {@link ShieldModuleOptions.credentialResolver}.
+     * STATIC here (like {@link auth}, NOT part of the async factory result): the
+     * resolver instance is a registration-time collaborator threaded into the
+     * statically-composed {@link AuthModule} import, so it cannot depend on the
+     * async-resolved options. Only consulted when `auth: true`.
+     */
+    readonly credentialResolver?: CredentialResolver;
+    /**
+     * OPTIONAL current-user profile resolver — see {@link ShieldModuleOptions.profileResolver}.
+     * STATIC here (like {@link credentialResolver}): a registration-time collaborator
+     * threaded into the statically-composed {@link AuthModule} import. Only consulted
+     * when `auth: true`.
+     */
+    readonly profileResolver?: ProfileResolver;
+    /**
+     * OPTIONAL account/credential-surface seams — see
+     * {@link ShieldModuleOptions.credentialWriter} et al. STATIC here (like the other
+     * seams): registration-time collaborators threaded into the statically-composed
+     * {@link AuthModule} import, so they cannot depend on the async-resolved options.
+     * Only consulted when `auth: true`.
+     */
+    readonly credentialWriter?: CredentialWriter;
+    readonly resetTokenStore?: ResetTokenStore;
+    readonly emailSender?: EmailSender;
+    readonly recoveryCodeStore?: RecoveryCodeStore;
+    readonly profileWriter?: ProfileWriter;
+    readonly sessionSweeper?: SessionSweeper;
+    /**
+     * OPTIONAL auth-surface audit sink — see {@link ShieldModuleOptions.auditSink}.
+     * STATIC here (like the other seams): a registration-time collaborator threaded into
+     * the statically-composed {@link AuthModule} import. Only consulted when `auth: true`.
+     */
+    readonly auditSink?: AuditSink;
+    /**
+     * OPTIONAL multi-device MFA store — see {@link ShieldModuleOptions.mfaDeviceStore}.
+     * STATIC here (like the other seams): a registration-time collaborator threaded into
+     * the statically-composed {@link AuthModule} import. Only consulted when `auth: true`.
+     */
+    readonly mfaDeviceStore?: MfaDeviceStore;
+    /**
+     * OPTIONAL login `totp` verifier override — see {@link ShieldModuleOptions.totpVerifier}.
+     * STATIC here (like the other seams): a registration-time collaborator threaded into
+     * the statically-composed {@link AuthModule} import. Only consulted when `auth: true`.
+     */
+    readonly totpVerifier?: FactorVerifier;
+    /**
+     * OPTIONAL root allowlist — see {@link ShieldModuleOptions.rootIds}.
+     * STATIC here (like the other seams): a registration-time collaborator threaded into
+     * the statically-composed {@link AuthModule} import (it is passed to the broker at
+     * authenticator-composition time, not part of the async factory result). A consumer
+     * that must COMPUTE the list at boot (e.g. read it from a DB) uses `forRootAsync`'s
+     * `useFactory` to build the whole options object — the resolved `rootIds` is
+     * then threaded exactly like the static case. Only consulted when `auth: true`.
+     */
+    readonly rootIds?: readonly string[];
+    /**
+     * OPTIONAL eager session-facts projector — see {@link ShieldModuleOptions.sessionFactsProjector}.
+     * STATIC here (like the other seams): a registration-time collaborator threaded into the
+     * statically-composed {@link AuthModule} import, so it cannot depend on the async-resolved
+     * options. Only consulted when `auth: true`.
+     */
+    readonly sessionFactsProjector?: SessionFactsProjector;
 }
 /**
  * `ShieldModule` — the SINGLE registration seam (ADR-0023 §4).

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

@@ -1 +1 @@
-{"version":3,"file":"shield.module.d.ts","sourceRoot":"","sources":["../../src/module/shield.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AACnF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAKzE,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAE7E;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED,yEAAyE;AACzE,MAAM,WAAW,wBAAwB;IACvC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,CACnB,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,KACxB,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;IACxD,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAEa,YAAY;IACvB,6DAA6D;IAC7D,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,mBAAwB,GAAG,aAAa;IAkBhE;;;;;;;;;OASG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,wBAAwB,GAAG,aAAa;CA8BtE"}
+{"version":3,"file":"shield.module.d.ts","sourceRoot":"","sources":["../../src/module/shield.module.ts"],"names":[],"mappings":"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"}

package/dist/module/shield.module.js

@@ -1,27 +1,130 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var ShieldModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShieldModule = exports.SHIELD_DECISION_AUTHORITY = void 0;
 const common_1 = require("@nestjs/common");
+const node_url_1 = require("node:url");
 const core_seam_js_1 = require("../enforcement/core-seam.js");
 const enforcement_module_js_1 = require("../enforcement/enforcement.module.js");
 const boot_module_js_1 = require("../boot/boot.module.js");
 const config_module_js_1 = require("../config/config.module.js");
 const app_config_js_1 = require("../config/app-config.js");
+// Static import is SAFE: auth.module.ts top-level-imports @astram/core as TYPES
+// only (it loads core's ESM factory VALUES lazily inside its async provider
+// factories — see auth.module.ts loadCore()). So pulling AuthModule here does NOT
+// trigger a runtime `require('@astram/core')`; the opt-in gate below still ensures
+// the enforcement-only path never INSTANTIATES it (no live pool/Redis, no HMAC
+// gate, no core load).
+const auth_module_js_1 = require("../auth/auth.module.js");
+// The `SHIELD_DECISION_AUTHORITY` token now lives in `./shield-tokens.js` so the
+// enforcement guard can import it without a cycle (guard → token → ShieldModule →
+// EnforcementModule → guard). Re-exported here to keep the public import path stable.
+const shield_tokens_js_1 = require("./shield-tokens.js");
+Object.defineProperty(exports, "SHIELD_DECISION_AUTHORITY", { enumerable: true, get: function () { return shield_tokens_js_1.SHIELD_DECISION_AUTHORITY; } });
+/**
+ * A `Function`-wrapped dynamic `import()` that survives the CommonJS **build** — the same
+ * shim as auth.module.ts's `evalImport`. Under `module: commonjs`, `tsc` would rewrite a
+ * literal `import()` into `require(...)`; routing through the `Function` constructor keeps
+ * a genuine native `import()` in the emitted dist so this file's OWN compiled output stays
+ * free of a top-level `require('../authz/wire-record-authorization.js')` (→ core). We pass
+ * the file's absolute URL (resolved off `__dirname` in the CJS dist / `import.meta.url`
+ * would not exist here) so the eval'd import has a base to resolve against.
+ */
+const evalImport = new Function('specifier', 'return import(specifier);');
+let cachedRecordAuthApi;
 /**
- * DI token for the Core decision authority (the ADR-0001 single decision
- * authority) that the enforcement guard consults. The consumer supplies the real
- * `@astram/core` authority through {@link ShieldModule.forRoot}; when omitted the
- * framework binds the fail-closed {@link stubDecisionAuthority} (deny-by-default),
- * so a mis-wiring cannot silently open a door.
+ * Lazily load the framework's record-authorization builder. Invoked ONLY inside the
+ * `SHIELD_DECISION_AUTHORITY` async factory when a consumer supplies
+ * `recordAuthorization` — NEVER at module top-level. The target file value-imports
+ * `@astram/core` + the four adapter classes, so deferring its load keeps a runtime
+ * `require('@astram/core')` OUT of THIS module's (the enforcement-only) load path.
+ *
+ * TWO strategies, mirroring auth.module.ts's `loadCore`, so it works in BOTH runtimes:
+ *  1. A plain dynamic `import()` — native under vitest/SWC (source path).
+ *  2. On failure (the tsc-built CJS dist downlevels #1 to a throwing `require` when the
+ *     transitive `@astram/core` ESM cannot be `require`d in that context), the
+ *     {@link evalImport} `Function`-wrapped native `import()` resolved off `__dirname`.
  */
-exports.SHIELD_DECISION_AUTHORITY = Symbol('SHIELD_DECISION_AUTHORITY');
+async function loadBuildRecordAuthorization() {
+    if (cachedRecordAuthApi === undefined) {
+        try {
+            cachedRecordAuthApi = (await Promise.resolve().then(() => __importStar(require('../authz/wire-record-authorization.js'))));
+        }
+        catch {
+            // Built-dist fallback (the CJS dist path — see evalImport). `__dirname` is defined
+            // in the emitted CJS module; resolve the compiled sibling relative to it and import
+            // it as a file:// URL so Node's CJS→ESM interop loads it (and its ESM-only core dep).
+            const base = (0, node_url_1.pathToFileURL)(`${__dirname}/../authz/wire-record-authorization.js`).href;
+            cachedRecordAuthApi = (await evalImport(base));
+        }
+    }
+    return cachedRecordAuthApi.buildRecordAuthorization;
+}
+/**
+ * Resolve the `SHIELD_DECISION_AUTHORITY` VALUE from the caller's options (the ONE seam,
+ * ADR-0023 — only how its value is PRODUCED changes here). Precedence + mutual exclusion:
+ *
+ *  - `recordAuthorization` PRESENT → the framework builds the REAL wired authority itself
+ *    (the four record-tier adapters constructed inside guard, un-overridable). This is the
+ *    Phase-5 path: the app can no longer supply or weaken those adapters.
+ *  - `decisionAuthority` PRESENT (legacy passthrough) → bind the caller's pre-built
+ *    authority verbatim (kept for other consumers / back-compat).
+ *  - BOTH present → MISCONFIG: throw a clear error (they are mutually exclusive).
+ *  - NEITHER → the fail-closed {@link stubDecisionAuthority} (unchanged fallback).
+ *
+ * Async because the `recordAuthorization` path lazy-loads the (core-touching) builder.
+ */
+async function resolveDecisionAuthority(options) {
+    if (options.recordAuthorization && options.decisionAuthority) {
+        throw new Error('ShieldModule: `recordAuthorization` and `decisionAuthority` are mutually exclusive — ' +
+            'supply the record-authorization inputs (pool + app ports + registry) so the framework ' +
+            'builds the decision authority, OR a pre-built `decisionAuthority`, but not both.');
+    }
+    if (options.recordAuthorization) {
+        const build = await loadBuildRecordAuthorization();
+        return build(options.recordAuthorization);
+    }
+    return options.decisionAuthority ?? core_seam_js_1.stubDecisionAuthority;
+}
 /**
  * `ShieldModule` — the SINGLE registration seam (ADR-0023 §4).
  *
@@ -50,19 +153,80 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
     /** Register Shield with static options (the common path). */
     static forRoot(options = {}) {
         const config = options.config ?? (0, app_config_js_1.loadAppConfig)();
+        // Build the opt-in AuthModule ONCE so the SAME DynamicModule instance is both
+        // imported (composes) and re-exported (propagates its exported engine tokens
+        // app-wide through the @Global ShieldModule). Re-exporting the two Symbols
+        // directly is NOT valid Nest — a module may only re-export a whole imported
+        // module (or a token IT provides), so we export the AuthModule dynamic module.
+        // When auth is opted in, thread the consumer's optional credentialResolver into
+        // AuthModule (it binds the supplied instance under SHIELD_CREDENTIAL_RESOLVER;
+        // omitted → the default MariaDb store, unchanged). Without auth the resolver is
+        // irrelevant (no AuthModule composes) — a documented no-op.
+        const authModule = options.auth
+            ? auth_module_js_1.AuthModule.forRoot(
+            // Only pass a property when the consumer supplied one — under
+            // `exactOptionalPropertyTypes`, an explicit `undefined` is not assignable
+            // to an optional field; a spread keeps it truly absent so AuthModule falls
+            // back to its defaults (MariaDb credential store; 501 /auth/me).
+            {
+                ...(options.credentialResolver
+                    ? { credentialResolver: options.credentialResolver }
+                    : {}),
+                ...(options.profileResolver
+                    ? { profileResolver: options.profileResolver }
+                    : {}),
+                // The account/credential-surface seams — same spread-when-present rule
+                // (an explicit `undefined` is not assignable under
+                // exactOptionalPropertyTypes; absent → AuthModule binds `null` → 501).
+                ...(options.credentialWriter ? { credentialWriter: options.credentialWriter } : {}),
+                ...(options.resetTokenStore ? { resetTokenStore: options.resetTokenStore } : {}),
+                ...(options.emailSender ? { emailSender: options.emailSender } : {}),
+                ...(options.recoveryCodeStore ? { recoveryCodeStore: options.recoveryCodeStore } : {}),
+                ...(options.profileWriter ? { profileWriter: options.profileWriter } : {}),
+                ...(options.sessionSweeper ? { sessionSweeper: options.sessionSweeper } : {}),
+                ...(options.auditSink ? { auditSink: options.auditSink } : {}),
+                ...(options.mfaDeviceStore ? { mfaDeviceStore: options.mfaDeviceStore } : {}),
+                ...(options.totpVerifier ? { totpVerifier: options.totpVerifier } : {}),
+                ...(options.rootIds ? { rootIds: options.rootIds } : {}),
+                ...(options.sessionFactsProjector
+                    ? { sessionFactsProjector: options.sessionFactsProjector }
+                    : {}),
+            })
+            : undefined;
         return {
             module: ShieldModule_1,
             // Compose the framework modules — EnforcementModule holds the ONE APP_GUARD
             // binding; BootModule holds the boot-sequence hook. No re-declaration here.
-            imports: [enforcement_module_js_1.EnforcementModule, boot_module_js_1.BootModule],
+            // AuthModule is OPT-IN (options.auth === true): only then does the app open a
+            // live pool/Redis + fire the fail-closed HMAC gate. Absent/false → the
+            // enforcement-only no-`.env` boot survives untouched.
+            imports: [enforcement_module_js_1.EnforcementModule, boot_module_js_1.BootModule, ...(authModule ? [authModule] : [])],
             providers: [
                 { provide: config_module_js_1.APP_CONFIG, useValue: config },
                 {
-                    provide: exports.SHIELD_DECISION_AUTHORITY,
-                    useValue: options.decisionAuthority ?? core_seam_js_1.stubDecisionAuthority,
+                    // Async factory: the `recordAuthorization` path lazy-loads the (core-touching)
+                    // builder — see resolveDecisionAuthority. The legacy `decisionAuthority` +
+                    // stub paths resolve synchronously but flow through the same one seam. Both
+                    // supplied → throws (mutual exclusion).
+                    provide: shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
+                    useFactory: () => resolveDecisionAuthority({
+                        ...(options.recordAuthorization
+                            ? { recordAuthorization: options.recordAuthorization }
+                            : {}),
+                        ...(options.decisionAuthority
+                            ? { decisionAuthority: options.decisionAuthority }
+                            : {}),
+                    }),
                 },
             ],
-            exports: [config_module_js_1.APP_CONFIG, exports.SHIELD_DECISION_AUTHORITY],
+            // Re-export the composed AuthModule app-wide ONLY when auth is opted in — its
+            // own `exports` (SHIELD_AUTHENTICATOR / SHIELD_SESSION_AUTHORITY) then become
+            // visible to a consumer's controllers/services via the @Global seam.
+            exports: [
+                config_module_js_1.APP_CONFIG,
+                shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
+                ...(authModule ? [authModule] : []),
+            ],
         };
     }
     /**
@@ -88,16 +252,70 @@ let ShieldModule = ShieldModule_1 = class ShieldModule {
             inject: [optionsToken],
         };
         const authorityProvider = {
-            provide: exports.SHIELD_DECISION_AUTHORITY,
-            useFactory: (opts) => opts.decisionAuthority ?? core_seam_js_1.stubDecisionAuthority,
+            provide: shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
+            // Same one-seam resolution as forRoot, over the async-resolved options: the
+            // `recordAuthorization` path (the app hands pool + app ports + registry — computed
+            // in its useFactory from the injected registrations) has the framework build the
+            // real wired authority; `decisionAuthority` is the legacy passthrough; both →
+            // throws; neither → stub. Async because the record path lazy-loads the builder.
+            useFactory: (opts) => resolveDecisionAuthority({
+                ...(opts.recordAuthorization ? { recordAuthorization: opts.recordAuthorization } : {}),
+                ...(opts.decisionAuthority ? { decisionAuthority: opts.decisionAuthority } : {}),
+            }),
             inject: [optionsToken],
         };
+        // Same one-instance opt-in AuthModule as forRoot (imported + re-exported).
+        // `credentialResolver` is STATIC on the async options (like `auth`) — a
+        // registration-time collaborator, threaded straight through here.
+        const authModule = options.auth
+            ? auth_module_js_1.AuthModule.forRoot(
+            // Only pass a property when the consumer supplied one — under
+            // `exactOptionalPropertyTypes`, an explicit `undefined` is not assignable
+            // to an optional field; a spread keeps it truly absent so AuthModule falls
+            // back to its defaults (MariaDb credential store; 501 /auth/me).
+            {
+                ...(options.credentialResolver
+                    ? { credentialResolver: options.credentialResolver }
+                    : {}),
+                ...(options.profileResolver
+                    ? { profileResolver: options.profileResolver }
+                    : {}),
+                // The account/credential-surface seams — same spread-when-present rule
+                // (an explicit `undefined` is not assignable under
+                // exactOptionalPropertyTypes; absent → AuthModule binds `null` → 501).
+                ...(options.credentialWriter ? { credentialWriter: options.credentialWriter } : {}),
+                ...(options.resetTokenStore ? { resetTokenStore: options.resetTokenStore } : {}),
+                ...(options.emailSender ? { emailSender: options.emailSender } : {}),
+                ...(options.recoveryCodeStore ? { recoveryCodeStore: options.recoveryCodeStore } : {}),
+                ...(options.profileWriter ? { profileWriter: options.profileWriter } : {}),
+                ...(options.sessionSweeper ? { sessionSweeper: options.sessionSweeper } : {}),
+                ...(options.auditSink ? { auditSink: options.auditSink } : {}),
+                ...(options.mfaDeviceStore ? { mfaDeviceStore: options.mfaDeviceStore } : {}),
+                ...(options.totpVerifier ? { totpVerifier: options.totpVerifier } : {}),
+                ...(options.rootIds ? { rootIds: options.rootIds } : {}),
+                ...(options.sessionFactsProjector
+                    ? { sessionFactsProjector: options.sessionFactsProjector }
+                    : {}),
+            })
+            : undefined;
         return {
             module: ShieldModule_1,
             // Same single-path composition as forRoot (+ the caller's option imports).
-            imports: [enforcement_module_js_1.EnforcementModule, boot_module_js_1.BootModule, ...(options.imports ?? [])],
+            // AuthModule is OPT-IN via the STATIC `options.auth` flag (see the interface
+            // doc — the imports list is composed statically, so auth cannot be gated on
+            // the async-resolved options).
+            imports: [
+                enforcement_module_js_1.EnforcementModule,
+                boot_module_js_1.BootModule,
+                ...(authModule ? [authModule] : []),
+                ...(options.imports ?? []),
+            ],
             providers: [asyncOptionsProvider, configProvider, authorityProvider],
-            exports: [config_module_js_1.APP_CONFIG, exports.SHIELD_DECISION_AUTHORITY],
+            exports: [
+                config_module_js_1.APP_CONFIG,
+                shield_tokens_js_1.SHIELD_DECISION_AUTHORITY,
+                ...(authModule ? [authModule] : []),
+            ],
         };
     }
 };

package/dist/module/shield.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shield.module.js","sourceRoot":"","sources":["../../src/module/shield.module.ts"],"names":[],"mappings":"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"}

package/dist/request-auth/request-principal.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Request-principal resolution — extract the bearer access token from an HTTP
+ * request and resolve it (via the {@link SessionTokenBinder}) to a `Principal`,
+ * fail-closed. This is the request-auth read path the enforcement guard uses for
+ * `@Classified` routes before calling `decide()`.
+ *
+ * The `Principal` is rebuilt from the bound claims. We deliberately do NOT re-run
+ * the Core identity broker here (which would apply the root allowlist and could
+ * mint a root from an id) — instead we reconstruct a plain, non-root
+ * Principal from the exact claims captured at login. `isRoot` is set to
+ * `false` on the request path unless the binding explicitly recorded it (it is
+ * captured from the login-time Principal, so a genuinely-root login stays
+ * root; a normal login can never become one on a later request).
+ */
+import type { Principal } from '@astram/core';
+import type { SessionTokenBinder, BoundPrincipalClaims } from './session-token-binder.js';
+/** Extract a bearer token from an `Authorization: Bearer <token>` header. */
+export declare function extractBearerToken(authorizationHeader: unknown): string | null;
+/**
+ * Rebuild a `Principal` from bound claims (validated). `isRoot` is read
+ * from the binding (captured at login), NEVER inferred — a normal user cannot become
+ * a root on the request path.
+ */
+export declare function principalFromClaims(claims: BoundPrincipalClaims): Principal | null;
+/**
+ * Resolve an HTTP request's bearer token to a `Principal`, or `null` (fail-closed)
+ * when there is no token, no binding, or the binding is malformed.
+ */
+export declare function resolveRequestPrincipal(authorizationHeader: unknown, binder: SessionTokenBinder): Promise<Principal | null>;
+/**
+ * Resolve an HTTP request's bearer token to BOTH a `Principal` AND the raw
+ * {@link BoundPrincipalClaims}, or `null` (fail-closed) — the same read path as
+ * {@link resolveRequestPrincipal}, but it also surfaces the claims the `Principal`
+ * projection drops (notably `mustReenroll` and `sessionId`). The enforcement guard
+ * uses this so it can read `claims.mustReenroll` to apply the enforced-re-enroll gate
+ * while still attaching the resolved `Principal` for `decide()`.
+ */
+export declare function resolveRequestAuth(authorizationHeader: unknown, binder: SessionTokenBinder): Promise<{
+    principal: Principal;
+    claims: BoundPrincipalClaims;
+} | null>;
+//# sourceMappingURL=request-principal.d.ts.map

package/dist/request-auth/request-principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-principal.d.ts","sourceRoot":"","sources":["../../src/request-auth/request-principal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAK1F,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,mBAAmB,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAoBlF;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,mBAAmB,EAAE,OAAO,EAC5B,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAM3B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,mBAAmB,EAAE,OAAO,EAC5B,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GAAG,IAAI,CAAC,CAQxE"}