@astram/guard 0.6.0 → 0.8.0

package/dist/config/app-config.js

@@ -1,14 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_REDIS_URL = exports.DEFAULT_DB_CONFIG = exports.SCHEMA_SVC_POOL_HARD_CAP = exports.DEFAULT_POOL_BUDGET = void 0;
+exports.DEFAULT_REDIS_URL = exports.DEFAULT_DB_CONFIG = exports.SCHEMA_SVC_POOL_HARD_CAP = exports.DEFAULT_POOL_BUDGET = exports.DEFAULT_REDIS_COMMAND_TIMEOUT_MS = exports.DEFAULT_LOGIN_IP_LIMIT = void 0;
+exports.isDevOrTestNodeEnv = isDevOrTestNodeEnv;
 exports.loadPoolBudget = loadPoolBudget;
 exports.loadDbConfig = loadDbConfig;
 exports.loadRedisConfig = loadRedisConfig;
 exports.loadSessionLifetimes = loadSessionLifetimes;
+exports.loadLoginIpLimit = loadLoginIpLimit;
 exports.loadRefreshHmacKey = loadRefreshHmacKey;
 exports.assertRefreshHmacKey = assertRefreshHmacKey;
 exports.loadAppConfig = loadAppConfig;
+exports.loadAppConfigAsync = loadAppConfigAsync;
 exports.evaluatePoolBudget = evaluatePoolBudget;
+const core_1 = require("@astram/core");
+/** Plan D3 default: 50 failed logins per client IP per 15 minutes. */
+exports.DEFAULT_LOGIN_IP_LIMIT = {
+    maxAttempts: 50,
+    windowMs: 15 * 60 * 1000,
+};
+/** Default Redis per-command timeout (GAPS #7): the request path fails closed within ~2 s. */
+exports.DEFAULT_REDIS_COMMAND_TIMEOUT_MS = 2000;
 /** Documented MVP single-node defaults (see the class doc + my.cnf). */
 exports.DEFAULT_POOL_BUDGET = {
     workers: 8,
@@ -28,11 +39,27 @@ function parsePort(raw, fallback) {
     const n = Number.parseInt(raw, 10);
     return Number.isInteger(n) && n > 0 && n < 65_536 ? n : fallback;
 }
+/**
+ * The `environment` LABEL (logging / display). NOTE: it maps an UNSET `NODE_ENV` to
+ * `'development'`, so it must NEVER drive a security default — an unset env is not
+ * proof of a dev box. Security-relevant choices (e.g. the dev `LogEmailSender`, which
+ * prints live reset links) read the RAW `NODE_ENV` instead: see
+ * {@link isDevOrTestNodeEnv}.
+ */
 function parseEnvironment(raw) {
     if (raw === 'production' || raw === 'test')
         return raw;
     return 'development';
 }
+/**
+ * `true` ONLY when the RAW `NODE_ENV` is explicitly `'development'` or `'test'`.
+ * Unset, blank, `'production'`, `'staging'` or anything else ⇒ `false`. Used to gate
+ * dev-only defaults that would leak secrets in a real deployment (fail closed: an
+ * unset NODE_ENV is treated as "not dev").
+ */
+function isDevOrTestNodeEnv(raw) {
+    return raw === 'development' || raw === 'test';
+}
 /**
  * Parse a positive integer from env with a fallback. Returns the fallback for
  * missing/blank/non-integer/≤0 values — the boot assertion is the authority on
@@ -124,18 +151,19 @@ function loadDbConfig(env = process.env) {
  * documented default.
  */
 function loadRedisConfig(env = process.env) {
+    const commandTimeoutMs = parsePositiveInt(env.REDIS_COMMAND_TIMEOUT_MS, exports.DEFAULT_REDIS_COMMAND_TIMEOUT_MS);
     const explicit = env.REDIS_URL;
     if (explicit !== undefined && explicit.trim() !== '') {
-        return { url: explicit.trim() };
+        return { url: explicit.trim(), commandTimeoutMs };
     }
     const host = env.REDIS_HOST;
     const port = env.REDIS_PORT;
     if ((host !== undefined && host.trim() !== '') || (port !== undefined && port.trim() !== '')) {
         const h = parseString(host, 'localhost');
         const p = parsePort(port, 6379);
-        return { url: `redis://${h}:${p}` };
+        return { url: `redis://${h}:${p}`, commandTimeoutMs };
     }
-    return { url: exports.DEFAULT_REDIS_URL };
+    return { url: exports.DEFAULT_REDIS_URL, commandTimeoutMs };
 }
 /**
  * Build the optional {@link SessionLifetimeOverrides} from env. Every field is
@@ -160,6 +188,19 @@ function loadSessionLifetimes(env = process.env) {
         overrides.refreshAbsoluteCapMs = cap;
     return overrides;
 }
+/**
+ * Build the per-client-IP login failure limit from env (plan D3). Each field falls back
+ * to {@link DEFAULT_LOGIN_IP_LIMIT} when absent/blank/invalid.
+ * Field ↔ env name:
+ *   maxAttempts ← LOGIN_IP_MAX_FAILURES   (default 50)
+ *   windowMs    ← LOGIN_IP_WINDOW_MS      (default 900000 = 15 min)
+ */
+function loadLoginIpLimit(env = process.env) {
+    return {
+        maxAttempts: parsePositiveInt(env.LOGIN_IP_MAX_FAILURES, exports.DEFAULT_LOGIN_IP_LIMIT.maxAttempts),
+        windowMs: parsePositiveInt(env.LOGIN_IP_WINDOW_MS, exports.DEFAULT_LOGIN_IP_LIMIT.windowMs),
+    };
+}
 /**
  * Read the refresh-token HMAC key from env (raw; `''` when absent/blank). Total —
  * does NOT throw, so {@link loadAppConfig} stays boot-safe for a non-auth scaffold.
@@ -212,8 +253,29 @@ function loadAppConfig(env = process.env) {
         redis: loadRedisConfig(env),
         refreshHmacKey: loadRefreshHmacKey(env),
         lifetimes: loadSessionLifetimes(env),
+        loginIpLimit: loadLoginIpLimit(env),
     };
 }
+/**
+ * ADR-0032 secrets integration — build the {@link AppConfig} AFTER resolving any `secret-ref:<path>`
+ * env references via the injected `SecretsProvider`, so an app can hold only REFERENCES in its env
+ * (safe to commit/log) and the real credentials are fetched at boot.
+ *
+ * - With a `provider`: every `secret-ref:` value in `env` is resolved (fail-closed — a missing
+ *   reference aborts boot; a value is never logged), producing a resolved env the pure
+ *   {@link loadAppConfig} consumes unchanged.
+ * - Without a `provider`: identical to `loadAppConfig(env)` — literal env, unchanged behaviour
+ *   (backward compatible; references would pass through as literals, which fail loudly at connect
+ *   time rather than silently — the operator is expected to wire a provider when using references).
+ *
+ * The core resolver (`resolveSecretRefs`) does the work; this is the guard-side boot seam.
+ */
+async function loadAppConfigAsync(provider, env = process.env) {
+    if (provider === undefined)
+        return loadAppConfig(env);
+    const resolved = await (0, core_1.resolveSecretRefs)(env, provider);
+    return loadAppConfig(resolved);
+}
 /**
  * Evaluate a pool budget. Pure: no throwing, no I/O — the caller decides how to
  * react (the boot assertion throws; tests inspect the fields).

package/dist/encryption/local-kek-crypto.d.ts

@@ -0,0 +1,15 @@
+import type { CryptoPort, Dek, WrappedDek, Ciphertext } from '@astram/core';
+export declare class LocalKekCrypto implements CryptoPort {
+    #private;
+    /**
+     * @param kek the 32-byte Key Encryption Key (from a KMS/secrets-manager reference). MUST be
+     *   exactly 32 bytes. NEVER hard-code it; NEVER log it.
+     */
+    constructor(kek: Uint8Array);
+    generateDek(): Promise<Dek>;
+    wrapDek(dek: Dek, tenantId: string): Promise<WrappedDek>;
+    unwrapDek(wrapped: WrappedDek, tenantId: string): Promise<Dek>;
+    encrypt(plaintext: Uint8Array, dek: Dek, tenantId: string): Promise<Ciphertext>;
+    decrypt(ciphertext: Ciphertext, dek: Dek, tenantId: string): Promise<Uint8Array>;
+}
+//# sourceMappingURL=local-kek-crypto.d.ts.map

package/dist/encryption/local-kek-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-kek-crypto.d.ts","sourceRoot":"","sources":["../../src/encryption/local-kek-crypto.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO5E,qBAAa,cAAe,YAAW,UAAU;;IAG/C;;;OAGG;gBACS,GAAG,EAAE,UAAU;IAOrB,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC;IAI3B,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAIxD,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAI9D,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAI/E,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CA2BvF"}

package/dist/encryption/local-kek-crypto.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalKekCrypto = void 0;
+/**
+ * `LocalKekCrypto` — a reference {@link CryptoPort} adapter (ADR-0031). Real AES-256-GCM AEAD for
+ * data + DEK-wrapping, with the KEK held as a local secret (from a secrets-manager reference /
+ * env). This is the dev + air-gapped / single-box adapter (what astram-infra's box can use); the
+ * AWS-KMS / GCP-KMS / Vault-Transit adapters implement the SAME port and swap in on demand
+ * (Rule of Three).
+ *
+ * SECURITY:
+ *  - AES-256-GCM (authenticated): a 96-bit random nonce per operation; the 128-bit tag is verified
+ *    on decrypt; the `tenantId` is bound as ADDITIONAL AUTHENTICATED DATA (AAD) so a ciphertext for
+ *    tenant A cannot be decrypted as tenant B (the core's cross-tenant guard, enforced in crypto).
+ *  - DEK wrapping uses the SAME AEAD under the KEK, with the tenantId as AAD — a wrapped DEK is
+ *    bound to its tenant.
+ *  - The KEK is 32 bytes, provided at construction (never hard-coded, never logged). Losing it makes
+ *    all wrapped DEKs (hence all data) unrecoverable — it belongs in a KMS/secrets-manager.
+ *  - NEVER logs a plaintext, a DEK, or the KEK.
+ *
+ * Self-describing output layout (both encrypt + wrap): [1B version][12B nonce][16B tag][ciphertext].
+ */
+const node_crypto_1 = require("node:crypto");
+const VERSION = 1;
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+const DEK_LEN = 32; // AES-256
+class LocalKekCrypto {
+    #kek;
+    /**
+     * @param kek the 32-byte Key Encryption Key (from a KMS/secrets-manager reference). MUST be
+     *   exactly 32 bytes. NEVER hard-code it; NEVER log it.
+     */
+    constructor(kek) {
+        if (kek.length !== DEK_LEN) {
+            throw new Error(`KEK must be ${DEK_LEN} bytes (got ${kek.length}).`);
+        }
+        this.#kek = Buffer.from(kek);
+    }
+    async generateDek() {
+        return new Uint8Array((0, node_crypto_1.randomBytes)(DEK_LEN));
+    }
+    async wrapDek(dek, tenantId) {
+        return this.#seal(this.#kek, Buffer.from(dek), tenantId);
+    }
+    async unwrapDek(wrapped, tenantId) {
+        return new Uint8Array(this.#open(this.#kek, Buffer.from(wrapped), tenantId));
+    }
+    async encrypt(plaintext, dek, tenantId) {
+        return this.#seal(Buffer.from(dek), Buffer.from(plaintext), tenantId);
+    }
+    async decrypt(ciphertext, dek, tenantId) {
+        return new Uint8Array(this.#open(Buffer.from(dek), Buffer.from(ciphertext), tenantId));
+    }
+    // ── AES-256-GCM seal/open, tenantId bound as AAD ──────────────────────────
+    #seal(key, plaintext, tenantId) {
+        const nonce = (0, node_crypto_1.randomBytes)(NONCE_LEN);
+        const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', key, nonce);
+        cipher.setAAD(Buffer.from(tenantId, 'utf8'));
+        const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return new Uint8Array(Buffer.concat([Buffer.from([VERSION]), nonce, tag, body]));
+    }
+    #open(key, sealed, tenantId) {
+        if (sealed.length < 1 + NONCE_LEN + TAG_LEN)
+            throw new Error('ciphertext too short / malformed');
+        if (sealed[0] !== VERSION)
+            throw new Error(`unsupported ciphertext version ${sealed[0]}`);
+        const nonce = sealed.subarray(1, 1 + NONCE_LEN);
+        const tag = sealed.subarray(1 + NONCE_LEN, 1 + NONCE_LEN + TAG_LEN);
+        const body = sealed.subarray(1 + NONCE_LEN + TAG_LEN);
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, nonce);
+        decipher.setAAD(Buffer.from(tenantId, 'utf8'));
+        decipher.setAuthTag(tag);
+        // .final() THROWS on a tag/AAD mismatch — the fail-closed guarantee the core relies on.
+        return Buffer.concat([decipher.update(body), decipher.final()]);
+    }
+}
+exports.LocalKekCrypto = LocalKekCrypto;

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

@@ -1 +1 @@
-{"version":3,"file":"enforcement.module.d.ts","sourceRoot":"","sources":["../../src/enforcement/enforcement.module.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,qBAQa,iBAAiB;CAAG"}
+{"version":3,"file":"enforcement.module.d.ts","sourceRoot":"","sources":["../../src/enforcement/enforcement.module.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,qBAgBa,iBAAiB;CAAG"}

package/dist/enforcement/enforcement.module.js

@@ -10,6 +10,7 @@ exports.EnforcementModule = void 0;
 const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs/core");
 const global_enforcement_guard_js_1 = require("./global-enforcement.guard.js");
+const engine_error_filter_js_1 = require("./engine-error.filter.js");
 /**
  * The SOLE definition of the global `APP_GUARD` binding (ADR-0002).
  *
@@ -35,6 +36,14 @@ exports.EnforcementModule = EnforcementModule = __decorate([
                 provide: core_1.APP_GUARD,
                 useClass: global_enforcement_guard_js_1.GlobalEnforcementGuard,
             },
+            // The framework-wide engine error → HTTP mapping (security hardening Phase 1C): an engine
+            // deny / validation / unavailable error from any consumer controller answers 403 / 400 /
+            // 503 instead of 500. Bound here, beside the one APP_GUARD, so forRoot and forRootAsync
+            // (which both compose this module) register it exactly once.
+            {
+                provide: core_1.APP_FILTER,
+                useClass: engine_error_filter_js_1.EngineErrorFilter,
+            },
         ],
     })
 ], EnforcementModule);

package/dist/enforcement/engine-error.filter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * EngineErrorFilter — the framework-wide mapping of `@astram/engine` errors to HTTP
+ * (security hardening Phase 1C). Registered ONCE as a global `APP_FILTER` by
+ * `ShieldModule.forRoot` / `forRootAsync`.
+ *
+ * A consumer feature controller that writes through `RecordsService` sees the engine's typed,
+ * fail-closed errors. Unmapped, Nest answered every one of them with a 500. This filter answers:
+ *
+ *   AuthorizationDeniedError (incl. ADR-0034 `create_outside_write_scope`) → 403
+ *   ValidationError                                                       → 400
+ *   EngineUnavailableError                                                → 503
+ *
+ * with FIXED, id-free messages (ADR-0012): the engine's own message carries reason codes, record
+ * ids and detail meant for logs, never for clients. There is deliberately no 404 mapping: the
+ * engine has no not-found error, because a missing or other-tenant row is folded into a deny so
+ * that it cannot be probed (`fetch-record.ts`).
+ *
+ * ── WHAT IT LEAVES ALONE ───────────────────────────────────────────────────────────────────
+ * `@Catch` lists only {@link EngineHttpMappableError}, so Nest hands this filter nothing else:
+ * `HttpException`s, `CapabilityNotSupportedError` / `RegistrationError` (framework gaps and
+ * misconfiguration — a 500 is right), and every non-engine error keep Nest's default handling and
+ * any consumer filter. Controller/method filters and interceptors run first, so identity's
+ * `IdentityErrorInterceptor` maps its routes before this filter is consulted.
+ *
+ * ── WHY STRUCTURAL MATCHING (not `instanceof` the engine classes) ──────────────────────────────
+ * Guard depends on `@astram/engine`, but this file is statically imported by `shield.module.ts`,
+ * whose own compiled output is kept free of runtime engine/core requires (see its header). A
+ * structural match also keeps working when a consumer's tree holds two copies of
+ * `@astram/engine` (version skew), where `instanceof` silently fails and the 500 returns. An
+ * error matches only when ALL hold: it is an `Error`, its prototype chain contains a class named
+ * `EngineError` (the engine's base), its `name` is one of the three classes above (the engine
+ * sets `name = new.target.name`), and it carries that class's field (`reason` / `field`). A
+ * third-party error that merely shares a name is not mapped.
+ */
+import { type ArgumentsHost } from '@nestjs/common';
+import { BaseExceptionFilter } from '@nestjs/core';
+type EngineErrorKind = 'denied' | 'invalid' | 'unavailable';
+/** Classify an engine error this filter maps, or `null` for anything else. */
+export declare function classifyEngineError(err: unknown): EngineErrorKind | null;
+/**
+ * The `@Catch` target: Nest selects a filter with `exception instanceof <target>`, and
+ * `Symbol.hasInstance` makes that the structural {@link classifyEngineError} test.
+ */
+export declare class EngineHttpMappableError {
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * Map an engine error to the HTTP exception the framework answers with, or return it unchanged
+ * when it is not a mapped engine error. Exported for unit tests and for callers mapping by hand.
+ */
+export declare function toEngineHttpError(err: unknown): unknown;
+/** The global filter: answers a mapped engine error through Nest's own HttpException reply. */
+export declare class EngineErrorFilter extends BaseExceptionFilter {
+    catch(exception: unknown, host: ArgumentsHost): void;
+}
+export {};
+//# sourceMappingURL=engine-error.filter.d.ts.map

package/dist/enforcement/engine-error.filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-error.filter.d.ts","sourceRoot":"","sources":["../../src/enforcement/engine-error.filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,KAAK,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAa5D,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAaxE;AAED;;;GAGG;AACH,qBAAa,uBAAuB;IAClC,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;CAGrD;AAKD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAsBvD;AAED,+FAA+F;AAC/F,qBACa,iBAAkB,SAAQ,mBAAmB;IAC/C,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;CAG9D"}

package/dist/enforcement/engine-error.filter.js

@@ -0,0 +1,118 @@
+"use strict";
+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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EngineErrorFilter = exports.EngineHttpMappableError = void 0;
+exports.classifyEngineError = classifyEngineError;
+exports.toEngineHttpError = toEngineHttpError;
+/**
+ * EngineErrorFilter — the framework-wide mapping of `@astram/engine` errors to HTTP
+ * (security hardening Phase 1C). Registered ONCE as a global `APP_FILTER` by
+ * `ShieldModule.forRoot` / `forRootAsync`.
+ *
+ * A consumer feature controller that writes through `RecordsService` sees the engine's typed,
+ * fail-closed errors. Unmapped, Nest answered every one of them with a 500. This filter answers:
+ *
+ *   AuthorizationDeniedError (incl. ADR-0034 `create_outside_write_scope`) → 403
+ *   ValidationError                                                       → 400
+ *   EngineUnavailableError                                                → 503
+ *
+ * with FIXED, id-free messages (ADR-0012): the engine's own message carries reason codes, record
+ * ids and detail meant for logs, never for clients. There is deliberately no 404 mapping: the
+ * engine has no not-found error, because a missing or other-tenant row is folded into a deny so
+ * that it cannot be probed (`fetch-record.ts`).
+ *
+ * ── WHAT IT LEAVES ALONE ───────────────────────────────────────────────────────────────────
+ * `@Catch` lists only {@link EngineHttpMappableError}, so Nest hands this filter nothing else:
+ * `HttpException`s, `CapabilityNotSupportedError` / `RegistrationError` (framework gaps and
+ * misconfiguration — a 500 is right), and every non-engine error keep Nest's default handling and
+ * any consumer filter. Controller/method filters and interceptors run first, so identity's
+ * `IdentityErrorInterceptor` maps its routes before this filter is consulted.
+ *
+ * ── WHY STRUCTURAL MATCHING (not `instanceof` the engine classes) ──────────────────────────────
+ * Guard depends on `@astram/engine`, but this file is statically imported by `shield.module.ts`,
+ * whose own compiled output is kept free of runtime engine/core requires (see its header). A
+ * structural match also keeps working when a consumer's tree holds two copies of
+ * `@astram/engine` (version skew), where `instanceof` silently fails and the 500 returns. An
+ * error matches only when ALL hold: it is an `Error`, its prototype chain contains a class named
+ * `EngineError` (the engine's base), its `name` is one of the three classes above (the engine
+ * sets `name = new.target.name`), and it carries that class's field (`reason` / `field`). A
+ * third-party error that merely shares a name is not mapped.
+ */
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+/** True when `err`'s prototype chain contains the engine's `EngineError` base class. */
+function isEngineFamily(err) {
+    let proto = Object.getPrototypeOf(err);
+    while (proto !== null && proto !== Error.prototype && proto !== Object.prototype) {
+        const ctor = proto.constructor;
+        if (ctor?.name === 'EngineError')
+            return true;
+        proto = Object.getPrototypeOf(proto);
+    }
+    return false;
+}
+/** Classify an engine error this filter maps, or `null` for anything else. */
+function classifyEngineError(err) {
+    if (!(err instanceof Error) || !isEngineFamily(err))
+        return null;
+    const fields = err;
+    switch (err.name) {
+        case 'AuthorizationDeniedError':
+            return typeof fields.reason === 'string' ? 'denied' : null;
+        case 'ValidationError':
+            return typeof fields.field === 'string' ? 'invalid' : null;
+        case 'EngineUnavailableError':
+            return 'unavailable';
+        default:
+            return null;
+    }
+}
+/**
+ * The `@Catch` target: Nest selects a filter with `exception instanceof <target>`, and
+ * `Symbol.hasInstance` makes that the structural {@link classifyEngineError} test.
+ */
+class EngineHttpMappableError {
+    static [Symbol.hasInstance](value) {
+        return classifyEngineError(value) !== null;
+    }
+}
+exports.EngineHttpMappableError = EngineHttpMappableError;
+/** A field name safe to echo (a declared column-style identifier); anything else is not echoed. */
+const ECHOABLE_FIELD = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+/**
+ * Map an engine error to the HTTP exception the framework answers with, or return it unchanged
+ * when it is not a mapped engine error. Exported for unit tests and for callers mapping by hand.
+ */
+function toEngineHttpError(err) {
+    if (err instanceof common_1.HttpException)
+        return err;
+    switch (classifyEngineError(err)) {
+        case 'denied':
+            return err.reason === 'create_outside_write_scope'
+                ? new common_1.ForbiddenException('You cannot create this record: it is outside the organisations you manage.')
+                : new common_1.ForbiddenException('You do not have access to perform this action.');
+        case 'invalid': {
+            const field = err.field;
+            return new common_1.BadRequestException(ECHOABLE_FIELD.test(field) ? `Invalid value for '${field}'.` : 'Invalid input.');
+        }
+        case 'unavailable':
+            return new common_1.ServiceUnavailableException('This operation is temporarily unavailable. Try again.');
+        default:
+            return err;
+    }
+}
+/** The global filter: answers a mapped engine error through Nest's own HttpException reply. */
+let EngineErrorFilter = class EngineErrorFilter extends core_1.BaseExceptionFilter {
+    catch(exception, host) {
+        super.catch(toEngineHttpError(exception), host);
+    }
+};
+exports.EngineErrorFilter = EngineErrorFilter;
+exports.EngineErrorFilter = EngineErrorFilter = __decorate([
+    (0, common_1.Catch)(EngineHttpMappableError)
+], EngineErrorFilter);

package/dist/enforcement/global-enforcement.guard.d.ts

@@ -1,7 +1,9 @@
 import { CanActivate, ExecutionContext } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import type { CoreDecisionAuthority } from './core-seam.js';
-import type { SessionTokenBinder } from '../request-auth/session-token-binder.js';
+import { type SessionTokenBinder } from '../request-auth/session-token-binder.js';
+import type { ServiceAuthenticator } from '@astram/core';
+import type { ScopeSubtreeResolver } from '../auth/ports/scope-subtree-resolver.js';
 /**
  * Global, fail-closed enforcement guard (ADR-0002) — now with REAL request
  * authorization for classified routes.
@@ -33,9 +35,36 @@ export declare class GlobalEnforcementGuard implements CanActivate {
     private readonly reflector;
     private readonly decisionAuthority?;
     private readonly tokenBinder?;
-    constructor(reflector: Reflector, decisionAuthority?: CoreDecisionAuthority | undefined, tokenBinder?: SessionTokenBinder | undefined);
+    private readonly serviceAuth?;
+    private readonly scopeSubtreeResolver?;
+    constructor(reflector: Reflector, decisionAuthority?: CoreDecisionAuthority | undefined, tokenBinder?: SessionTokenBinder | undefined, serviceAuth?: ServiceAuthenticator | undefined, scopeSubtreeResolver?: (ScopeSubtreeResolver | null) | undefined);
     canActivate(context: ExecutionContext): Promise<boolean>;
     /** The real authorization path for a classified route (fail-closed throughout). */
     private authorizeClassified;
+    /**
+     * Write gate 5's reloaded grants and the live roles onto the session binding (ADR-0035). Session
+     * bindings only: a service-account key has no binding (its roles and scope are read live per
+     * request by the key store). Best-effort and conditional (same session, same tenant, fresher
+     * facts, `XX`): a miss or a Redis error only means the next request reloads again.
+     */
+    private rebindReloadedGrants;
+    /**
+     * Re-derive the session's scope subtree after gate 5 reloaded facts at `reloadedVersion`
+     * (security hardening Phase 1C). Identity bumps a tenant's permission version when a company is
+     * created, moved or deleted under it, so a reload at a version newer than the bound subtree's
+     * stamp means the subtree may be stale: resolve it again with the SAME resolver login uses,
+     * rebind it (token + session entries) and return the principal the handler should see.
+     *
+     * Off the hot path: runs only for a session binding that carries a subtree, with a resolver
+     * wired, and a reload NEWER than its stamp (or no stamp yet — once, then stamped). That is the
+     * only DB read added (one closure query), and only on a version change.
+     *
+     * FAIL-CLOSED, NON-WIDENING: a resolver error, a non-array or an EMPTY result →
+     * {@link SUBTREE_REDERIVE_FAILED}: the bound subtree stays (never replaced by a guess, never
+     * widened), the stamp is not advanced, the reloaded facts are not cached (ADR-0035), and the next
+     * request reloads and retries. `null` = no re-derive was due. A failed Redis rebind still returns the fresh principal for this request
+     * (the DB answer is authoritative); the next reload retries the rebind.
+     */
+    private rederiveSubtreeOnVersionMove;
 }
 //# sourceMappingURL=global-enforcement.guard.d.ts.map

package/dist/enforcement/global-enforcement.guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"global-enforcement.guard.d.ts","sourceRoot":"","sources":["../../src/enforcement/global-enforcement.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,gBAAgB,EAMjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAOzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAQlF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBACa,sBAAuB,YAAW,WAAW;IAEtD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAG1B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IAGnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;gBANZ,SAAS,EAAE,SAAS,EAGpB,iBAAiB,CAAC,EAAE,qBAAqB,YAAA,EAGzC,WAAW,CAAC,EAAE,kBAAkB,YAAA;IAG7C,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAuC9D,mFAAmF;YACrE,mBAAmB;CA0FlC"}
+{"version":3,"file":"global-enforcement.guard.d.ts","sourceRoot":"","sources":["../../src/enforcement/global-enforcement.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,gBAAgB,EAMjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAOzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAK5D,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAA2B,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAOlF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAoBpF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBACa,sBAAuB,YAAW,WAAW;IAEtD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAG1B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IAGnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAM7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAM7B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC;gBAlBrB,SAAS,EAAE,SAAS,EAGpB,iBAAiB,CAAC,EAAE,qBAAqB,YAAA,EAGzC,WAAW,CAAC,EAAE,kBAAkB,YAAA,EAMhC,WAAW,CAAC,EAAE,oBAAoB,YAAA,EAMlC,oBAAoB,CAAC,GAAE,oBAAoB,GAAG,IAAI,aAAA;IAG/D,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAuC9D,mFAAmF;YACrE,mBAAmB;IAyIjC;;;;;OAKG;YACW,oBAAoB;IAuBlC;;;;;;;;;;;;;;;;OAgBG;YACW,4BAA4B;CA8C3C"}