@astram/guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @astram/guard — the enforcement gate + NestJS adapters
+
+The **enforcement gate + thin NestJS integration** for the Astram framework — the
+shippable glue a consumer app installs (it runs on / integrates with NestJS). Per
+[ADR-0023](../../docs/Shield/ADR/0023-framework-model-publishable-core.md)
+this is **framework code, owned + locked**, not consumer-editable: it lives in the
+consumer's `node_modules`, and upgrades flow through `npm update`. It depends on
+[`@astram/core`](../core) (the framework-agnostic kernel) and PEER-depends on the
+host's NestJS runtime.
+
+## What's in here
+
+| Piece                     | File                                          | Purpose                                                                                                                   |
+| ------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **`ShieldModule`**        | `src/module/shield.module.ts`                 | The **one registration seam** — `forRoot()` / `forRootAsync()`. Consumers import it once; the framework owns composition. |
+| Global enforcement guard  | `src/enforcement/global-enforcement.guard.ts` | The deny-by-default `APP_GUARD` (ADR-0002) every route traverses.                                                         |
+| Classification decorators | `src/enforcement/classification.decorator.ts` | `@Public()` / `@Classified()` — the consumer authors these on controllers.                                                |
+| Core seam                 | `src/enforcement/core-seam.ts`                | Type-only import of `@astram/core`'s `DecisionAuthority` (ADR-0003) + the fail-closed stub.                               |
+| Boot-pool assertion       | `src/boot/boot-sequence.ts`                   | ADR-0018 connection-pool budget check at boot (fail-closed).                                                              |
+| App config                | `src/config/app-config.ts`                    | Port / environment / ADR-0018 pool budget (env loader, pure).                                                             |
+
+## The registration seam (ADR-0023 §4)
+
+A consumer app wires Astram with a **single import** in its root module — it never
+edits the framework:
+
+```ts
+import { Module } from '@nestjs/common';
+import { ShieldModule } from '@astram/guard';
+
+@Module({
+  imports: [
+    ShieldModule.forRoot(), // fail-closed stub authority; env-loaded config
+    // ShieldModule.forRoot({ decisionAuthority, config }) to supply the real Core authority
+  ],
+  controllers: [/* the consumer's feature controllers */],
+})
+export class AppModule {}
+```
+
+`forRoot()` binds:
+
+- **`GlobalEnforcementGuard` as `APP_GUARD`** → the global, structurally-unavoidable,
+  deny-by-default enforcement point (ADR-0002). `@Public()` is the only opt-out;
+  an unclassified route is **denied (403)**.
+- The resolved **`AppConfig`** (under `APP_CONFIG`) + the **`BootSequence`** hook,
+  which runs the **ADR-0018** pool-budget assertion at boot (aborts on violation).
+- The **Core decision authority** (under `SHIELD_DECISION_AUTHORITY`) — the real
+  `@astram/core` authority when supplied via `forRoot({ decisionAuthority })`, else
+  the fail-closed **stub** (deny-by-default), so a mis-wiring cannot open a door.
+
+`forRootAsync({ useFactory, inject, imports })` is the DI-computed variant (a stub
+in this layer): the factory resolves the same options at startup; the guard/boot
+wiring is identical.
+
+## Peer dependencies (ADR-0023 §2)
+
+`@astram/guard` **peer-depends** on the host runtime so the consumer owns exactly
+one copy (a single `reflect-metadata` singleton / DI injector):
+
+```
+@nestjs/common ^11 · @nestjs/core ^11 · reflect-metadata ^0.2 · rxjs ^7
+```
+
+These are also `devDependencies` here so the package compiles + tests locally.
+`@astram/core` is a real (workspace) **dependency**.
+
+## Commands
+
+```bash
+pnpm --filter @astram/guard build   # tsc -p tsconfig.build.json (emits dist + .d.ts)
+pnpm --filter @astram/guard lint    # eslint
+pnpm --filter @astram/guard test    # vitest run (guard unit + boot-pool + forRoot e2e)
+```
+
+## Notes
+
+- **CommonJS** locally (`"type": "commonjs"`) for the NestJS decorator +
+  `reflect-metadata` DI model. The repo root and `@astram/core` stay ESM/NodeNext;
+  the override is scoped to this package (see `tsconfig.json`).
+- The core seam imports the REAL `@astram/core` **barrel** (type-only) — Core's
+  `exports` map exposes only `"."`, so subpath imports fail Node resolution. This
+  package's tsconfig clears the base `paths` so `@astram/core` resolves through the
+  node_modules workspace symlink to Core's built `dist`.

package/dist/authentication/argon2id-password-hasher.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `Argon2idPasswordHasher` — the concrete {@link PasswordHasher} for
+ * `@astram/guard`, backed by the `argon2` package (Argon2id).
+ *
+ * ADR-0003 (why this lives HERE, not in Core): `@astram/core` is ZERO runtime
+ * dependencies — the load-bearing invariant. Argon2id needs the `argon2` npm
+ * package + its native binding, so the concrete hasher ships in this integration
+ * package and is INJECTED into `@astram/core`'s `createAuthenticator({ hasher })`.
+ * Core defines only the `PasswordHasher` PORT; nothing about argon2 crosses the
+ * ADR-0003 boundary.
+ *
+ * SECURITY — never logs the plaintext or the hash (they are transient inputs). A
+ * malformed stored hash resolves `false` (not a throw) so the engine's
+ * verification path stays fail-closed rather than surfacing a raw error.
+ */
+import type { PasswordHasher } from '@astram/core';
+/**
+ * Tuned Argon2id parameters (sane server defaults; OWASP-aligned baseline). A
+ * deployment can override via the constructor if its hardware profile differs;
+ * changing them does not change the ENCODED hash's self-describing header, so
+ * older hashes still verify.
+ *
+ * - `memoryCost` 19456 KiB (19 MiB) — the OWASP "m=19456, t=2, p=1" baseline.
+ * - `timeCost` 2 iterations.
+ * - `parallelism` 1 lane.
+ */
+export interface Argon2idParams {
+    readonly memoryCost?: number;
+    readonly timeCost?: number;
+    readonly parallelism?: number;
+}
+/** The DI token consumers/ShieldModule bind the concrete hasher under. */
+export declare const SHIELD_PASSWORD_HASHER: unique symbol;
+/**
+ * Argon2id implementation of the Core {@link PasswordHasher} PORT. Injectable —
+ * bind it under {@link SHIELD_PASSWORD_HASHER} and hand it to
+ * `createAuthenticator({ hasher })`.
+ */
+export declare class Argon2idPasswordHasher implements PasswordHasher {
+    private readonly options;
+    constructor(params?: Argon2idParams);
+    /** Hash a plaintext into an encoded, self-describing Argon2id hash string. */
+    hash(plaintext: string): Promise<string>;
+    /**
+     * Verify a plaintext against an encoded Argon2id hash. Runs in constant time
+     * w.r.t. the digest (argon2's own comparison). A malformed/unparseable hash
+     * resolves `false` (fail-closed) instead of throwing.
+     */
+    verify(hash: string, plaintext: string): Promise<boolean>;
+}
+/**
+ * Provider factory for wiring the Argon2id hasher into a Nest DI container under
+ * {@link SHIELD_PASSWORD_HASHER}. Kept minimal (ADR-0023 §7): a plain provider,
+ * not a whole module — the consumer includes it where it composes the
+ * authenticator. Exported so `ShieldModule` (or a consumer) can bind it.
+ */
+export declare function argon2idHasherProvider(params?: Argon2idParams): {
+    provide: symbol;
+    useValue: Argon2idPasswordHasher;
+};
+//# sourceMappingURL=argon2id-password-hasher.d.ts.map

package/dist/authentication/argon2id-password-hasher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argon2id-password-hasher.d.ts","sourceRoot":"","sources":["../../src/authentication/argon2id-password-hasher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAQD,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,eAAmC,CAAC;AAEvE;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;gBAEnD,MAAM,GAAE,cAAmB;IASvC,8EAA8E;IACxE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK9C;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAQhE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAE,cAAmB,GAAG;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,sBAAsB,CAAC;CAClC,CAKA"}

package/dist/authentication/argon2id-password-hasher.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * `Argon2idPasswordHasher` — the concrete {@link PasswordHasher} for
+ * `@astram/guard`, backed by the `argon2` package (Argon2id).
+ *
+ * ADR-0003 (why this lives HERE, not in Core): `@astram/core` is ZERO runtime
+ * dependencies — the load-bearing invariant. Argon2id needs the `argon2` npm
+ * package + its native binding, so the concrete hasher ships in this integration
+ * package and is INJECTED into `@astram/core`'s `createAuthenticator({ hasher })`.
+ * Core defines only the `PasswordHasher` PORT; nothing about argon2 crosses the
+ * ADR-0003 boundary.
+ *
+ * SECURITY — never logs the plaintext or the hash (they are transient inputs). A
+ * malformed stored hash resolves `false` (not a throw) so the engine's
+ * verification path stays fail-closed rather than surfacing a raw error.
+ */
+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 __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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Argon2idPasswordHasher = exports.SHIELD_PASSWORD_HASHER = void 0;
+exports.argon2idHasherProvider = argon2idHasherProvider;
+const argon2 = __importStar(require("argon2"));
+const DEFAULT_PARAMS = {
+    memoryCost: 19_456,
+    timeCost: 2,
+    parallelism: 1,
+};
+/** The DI token consumers/ShieldModule bind the concrete hasher under. */
+exports.SHIELD_PASSWORD_HASHER = Symbol('SHIELD_PASSWORD_HASHER');
+/**
+ * Argon2id implementation of the Core {@link PasswordHasher} PORT. Injectable —
+ * bind it under {@link SHIELD_PASSWORD_HASHER} and hand it to
+ * `createAuthenticator({ hasher })`.
+ */
+class Argon2idPasswordHasher {
+    options;
+    constructor(params = {}) {
+        this.options = {
+            type: argon2.argon2id,
+            memoryCost: params.memoryCost ?? DEFAULT_PARAMS.memoryCost,
+            timeCost: params.timeCost ?? DEFAULT_PARAMS.timeCost,
+            parallelism: params.parallelism ?? DEFAULT_PARAMS.parallelism,
+        };
+    }
+    /** Hash a plaintext into an encoded, self-describing Argon2id hash string. */
+    async hash(plaintext) {
+        // argon2 generates a fresh random salt per call and embeds it in the output.
+        return argon2.hash(plaintext, this.options);
+    }
+    /**
+     * Verify a plaintext against an encoded Argon2id hash. Runs in constant time
+     * w.r.t. the digest (argon2's own comparison). A malformed/unparseable hash
+     * resolves `false` (fail-closed) instead of throwing.
+     */
+    async verify(hash, plaintext) {
+        try {
+            return await argon2.verify(hash, plaintext);
+        }
+        catch {
+            // An unparseable hash (or a decode error) is NOT a match — never a leak.
+            return false;
+        }
+    }
+}
+exports.Argon2idPasswordHasher = Argon2idPasswordHasher;
+/**
+ * Provider factory for wiring the Argon2id hasher into a Nest DI container under
+ * {@link SHIELD_PASSWORD_HASHER}. Kept minimal (ADR-0023 §7): a plain provider,
+ * not a whole module — the consumer includes it where it composes the
+ * authenticator. Exported so `ShieldModule` (or a consumer) can bind it.
+ */
+function argon2idHasherProvider(params = {}) {
+    return {
+        provide: exports.SHIELD_PASSWORD_HASHER,
+        useValue: new Argon2idPasswordHasher(params),
+    };
+}

package/dist/boot/boot-sequence.d.ts

@@ -0,0 +1,43 @@
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import { type AppConfig, type PoolBudgetConfig } from '../config/app-config.js';
+/**
+ * Boot sequence extension point (Infrastructure layer — ADR-0018).
+ *
+ * Nest calls {@link onApplicationBootstrap} once, after all modules are
+ * initialized and before the HTTP server starts accepting traffic. This is the
+ * seam where boot-time assertions attach.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * ADR-0018 connection-pool assertion (FILLED).
+ * {@link assertConnectionPoolReady} computes the connection budget
+ *   workers × Σ(per-account runtime pool max) + headroom ≤ maxConnections
+ * and THROWS (fail-closed, abort boot) on violation, so a pool config that
+ * would exceed MariaDB's `max_connections` is caught at boot, never under load.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+export declare class BootSequence implements OnApplicationBootstrap {
+    private readonly config;
+    constructor(config: AppConfig);
+    onApplicationBootstrap(): Promise<void>;
+    /**
+     * ADR-0018: assert the configured connection-pool budget fits under the DB
+     * `max_connections` ceiling BEFORE the app serves traffic. THROWS on
+     * violation so boot aborts (fail-closed on config, ADR-0018 §3).
+     *
+     * Pure computation over {@link AppConfig.pool}; no DB I/O — the ceiling is a
+     * declared invariant validated against the DB's deliberately-set value, not
+     * probed live. (Live pool health-probing can attach here later without
+     * changing this contract.)
+     */
+    private assertConnectionPoolReady;
+}
+/**
+ * Validate a {@link PoolBudgetConfig} against the ADR-0018 budget. Exported so
+ * unit tests can assert the throw/no-throw contract directly without booting
+ * the whole Nest app.
+ *
+ * @throws Error (fail-closed) when the required connections exceed
+ *   `maxConnections`, or when the schema-service pool exceeds its hard cap.
+ */
+export declare function assertPoolBudget(cfg: PoolBudgetConfig): void;
+//# sourceMappingURL=boot-sequence.d.ts.map

package/dist/boot/boot-sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-sequence.d.ts","sourceRoot":"","sources":["../../src/boot/boot-sequence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAEjF,OAAO,EAAsB,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEpG;;;;;;;;;;;;;;GAcG;AACH,qBACa,YAAa,YAAW,sBAAsB;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAE5D,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK7C;;;;;;;;;OASG;YACW,yBAAyB;CAIxC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAuB5D"}

package/dist/boot/boot-sequence.js

@@ -0,0 +1,90 @@
+"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;
+};
+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.BootSequence = void 0;
+exports.assertPoolBudget = assertPoolBudget;
+const common_1 = require("@nestjs/common");
+const config_module_js_1 = require("../config/config.module.js");
+const app_config_js_1 = require("../config/app-config.js");
+/**
+ * Boot sequence extension point (Infrastructure layer — ADR-0018).
+ *
+ * Nest calls {@link onApplicationBootstrap} once, after all modules are
+ * initialized and before the HTTP server starts accepting traffic. This is the
+ * seam where boot-time assertions attach.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * ADR-0018 connection-pool assertion (FILLED).
+ * {@link assertConnectionPoolReady} computes the connection budget
+ *   workers × Σ(per-account runtime pool max) + headroom ≤ maxConnections
+ * and THROWS (fail-closed, abort boot) on violation, so a pool config that
+ * would exceed MariaDB's `max_connections` is caught at boot, never under load.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+let BootSequence = class BootSequence {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async onApplicationBootstrap() {
+        await this.assertConnectionPoolReady();
+        // Future boot-time assertions attach here (each fail-closed).
+    }
+    /**
+     * ADR-0018: assert the configured connection-pool budget fits under the DB
+     * `max_connections` ceiling BEFORE the app serves traffic. THROWS on
+     * violation so boot aborts (fail-closed on config, ADR-0018 §3).
+     *
+     * Pure computation over {@link AppConfig.pool}; no DB I/O — the ceiling is a
+     * declared invariant validated against the DB's deliberately-set value, not
+     * probed live. (Live pool health-probing can attach here later without
+     * changing this contract.)
+     */
+    async assertConnectionPoolReady() {
+        assertPoolBudget(this.config.pool);
+        return Promise.resolve();
+    }
+};
+exports.BootSequence = BootSequence;
+exports.BootSequence = BootSequence = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(config_module_js_1.APP_CONFIG)),
+    __metadata("design:paramtypes", [Object])
+], BootSequence);
+/**
+ * Validate a {@link PoolBudgetConfig} against the ADR-0018 budget. Exported so
+ * unit tests can assert the throw/no-throw contract directly without booting
+ * the whole Nest app.
+ *
+ * @throws Error (fail-closed) when the required connections exceed
+ *   `maxConnections`, or when the schema-service pool exceeds its hard cap.
+ */
+function assertPoolBudget(cfg) {
+    const e = (0, app_config_js_1.evaluatePoolBudget)(cfg);
+    if (!e.schemaSvcWithinHardCap) {
+        throw new Error('[ADR-0018] connection-pool assertion FAILED (fail-closed): ' +
+            `shield_schema_svc pool max is ${cfg.perAccountMax.shield_schema_svc}, ` +
+            'which exceeds the hard cap of 2. DDL is rare + serialized per tenant ' +
+            '(ADR-0014 §7) — keep this pool tiny (1–2).');
+    }
+    if (!e.withinBudget) {
+        throw new Error('[ADR-0018] connection-pool assertion FAILED (fail-closed): required ' +
+            `connections ${e.requiredConnections} exceed max_connections ` +
+            `${cfg.maxConnections}. Budget = workers(${cfg.workers}) × ` +
+            `Σ(per-account pool max)(${e.perWorkerConnections}) + headroom(` +
+            `${cfg.headroom}) = ${e.requiredConnections} > ${cfg.maxConnections}. ` +
+            'Reduce a per-account pool cap, the worker count, or raise ' +
+            'max_connections (and MariaDB my.cnf) to restore the budget.');
+    }
+}

package/dist/boot/boot.module.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Registers the {@link BootSequence} lifecycle hook (Scaffold).
+ * Holds the named extension point where the ADR-0018 connection-pool assertion
+ * attaches in a later layer.
+ */
+export declare class BootModule {
+}
+//# sourceMappingURL=boot.module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"boot.module.d.ts","sourceRoot":"","sources":["../../src/boot/boot.module.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAGa,UAAU;CAAG"}

package/dist/boot/boot.module.js

@@ -0,0 +1,24 @@
+"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.BootModule = void 0;
+const common_1 = require("@nestjs/common");
+const boot_sequence_js_1 = require("./boot-sequence.js");
+/**
+ * Registers the {@link BootSequence} lifecycle hook (Scaffold).
+ * Holds the named extension point where the ADR-0018 connection-pool assertion
+ * attaches in a later layer.
+ */
+let BootModule = class BootModule {
+};
+exports.BootModule = BootModule;
+exports.BootModule = BootModule = __decorate([
+    (0, common_1.Module)({
+        providers: [boot_sequence_js_1.BootSequence],
+    })
+], BootModule);

package/dist/config/app-config.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Application configuration for the NestJS integration layer.
+ *
+ * The Scaffold shipped a deliberately-tiny loader (port + environment). The
+ * Infrastructure layer (this file) extends it with the ADR-0018 connection-pool
+ * budget: per-account pool caps, the app worker count, headroom, and the DB
+ * `maxConnections` ceiling. All are read from the environment with documented
+ * defaults and performs NO I/O — pure + side-effect-free so it stays trivially
+ * unit-testable, and so the boot-time budget assertion can validate it before
+ * the app serves traffic (fail-closed on config, ADR-0018 §3).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ADR-0018 budget (the invariant this config feeds):
+ *   workers × Σ(per-account RUNTIME pool max) + headroom ≤ maxConnections
+ *
+ * "Runtime" pools are the pools each PM2 cluster worker holds open: shield_core,
+ * shield_app_crud, shield_schema_svc. The deploy/ops accounts (migrate, backup,
+ * monitor) are short-lived, NOT per-worker, and are covered by `headroom`.
+ * shield_schema_svc stays TINY (DDL is rare + serialized per tenant, ADR-0014 §7).
+ *
+ * Defaults below agree byte-for-byte with infra/mariadb/conf.d/my.cnf
+ * (max_connections=250) and the local docker-compose substrate:
+ *   8 × (12 + 8 + 1) + 40 = 208 ≤ 250  ✓
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export interface AppConfig {
+    /** HTTP port the Nest app listens on. */
+    readonly port: number;
+    /** Runtime environment label (for logging / conditional wiring). */
+    readonly environment: 'development' | 'test' | 'production';
+    /** ADR-0018 connection-pool budget (validated at boot, fail-closed). */
+    readonly pool: PoolBudgetConfig;
+}
+/**
+ * The ADR-0018 connection-pool budget surface. Every field is configurable per
+ * deployment/edition via env; the defaults are the MVP single-node values that
+ * match the local substrate.
+ */
+export interface PoolBudgetConfig {
+    /**
+     * PM2 cluster worker count (≈ 1 per vCPU on the app host). Each worker holds
+     * its OWN independent set of runtime pools — pools are not shared across
+     * workers (ADR-0018 context).
+     */
+    readonly workers: number;
+    /**
+     * MariaDB `max_connections` ceiling this app must fit under. Set deliberately
+     * (NOT the 151 default) and must equal the DB server's configured value.
+     */
+    readonly maxConnections: number;
+    /**
+     * Reserved connections NOT consumed by per-worker runtime pools: admin
+     * sessions + the short-lived deploy/ops accounts (migrate/backup/monitor).
+     */
+    readonly headroom: number;
+    /** Per-account RUNTIME pool caps (multiplied by `workers` in the budget). */
+    readonly perAccountMax: RuntimeAccountPools;
+}
+/**
+ * Per-account maximum pool sizes for the RUNTIME accounts (the ones each worker
+ * opens). Keyed by the exact MariaDB account name so the budget math and the
+ * grant matrix line up 1:1.
+ */
+export interface RuntimeAccountPools {
+    /** shield_core — DML across all schemas, hot path: the main pool. */
+    readonly shield_core: number;
+    /** shield_app_crud — application DML load. */
+    readonly shield_app_crud: number;
+    /** shield_schema_svc — DDL only, rare + serialized: keep TINY (1–2). */
+    readonly shield_schema_svc: number;
+}
+/** Documented MVP single-node defaults (see the class doc + my.cnf). */
+export declare const DEFAULT_POOL_BUDGET: PoolBudgetConfig;
+/** Upper bound the schema-service pool must never exceed (ADR-0018 §2: 1–2). */
+export declare const SCHEMA_SVC_POOL_HARD_CAP = 2;
+/**
+ * Build the {@link PoolBudgetConfig} from env with documented defaults.
+ * Field ↔ env name:
+ *   workers                       ← SHIELD_POOL_WORKERS
+ *   maxConnections                ← SHIELD_DB_MAX_CONNECTIONS
+ *   headroom                      ← SHIELD_POOL_HEADROOM
+ *   perAccountMax.shield_core     ← SHIELD_POOL_MAX_CORE
+ *   perAccountMax.shield_app_crud ← SHIELD_POOL_MAX_APP_CRUD
+ *   perAccountMax.shield_schema_svc ← SHIELD_POOL_MAX_SCHEMA_SVC
+ */
+export declare function loadPoolBudget(env?: NodeJS.ProcessEnv): PoolBudgetConfig;
+/**
+ * Build the {@link AppConfig} from `process.env` (or an injected env bag, for
+ * testability). Pure + side-effect-free so it is trivially unit-testable.
+ */
+export declare function loadAppConfig(env?: NodeJS.ProcessEnv): AppConfig;
+/** Result of evaluating a {@link PoolBudgetConfig} against the ADR-0018 budget. */
+export interface PoolBudgetEvaluation {
+    /** Σ(per-account runtime pool max) for a single worker. */
+    readonly perWorkerConnections: number;
+    /** workers × perWorkerConnections — total runtime connections at full load. */
+    readonly runtimeConnections: number;
+    /** runtimeConnections + headroom — what must fit under maxConnections. */
+    readonly requiredConnections: number;
+    /** maxConnections − requiredConnections (negative ⇒ over budget). */
+    readonly slack: number;
+    /** True iff requiredConnections ≤ maxConnections. */
+    readonly withinBudget: boolean;
+    /** True iff shield_schema_svc pool ≤ {@link SCHEMA_SVC_POOL_HARD_CAP}. */
+    readonly schemaSvcWithinHardCap: boolean;
+}
+/**
+ * Evaluate a pool budget. Pure: no throwing, no I/O — the caller decides how to
+ * react (the boot assertion throws; tests inspect the fields).
+ */
+export declare function evaluatePoolBudget(cfg: PoolBudgetConfig): PoolBudgetEvaluation;
+//# sourceMappingURL=app-config.d.ts.map

package/dist/config/app-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-config.d.ts","sourceRoot":"","sources":["../../src/config/app-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,aAAa,GAAG,MAAM,GAAG,YAAY,CAAC;IAC5D,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,wEAAwE;IACxE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,EAAE,gBASjC,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAwB1C;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAuBrF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,CAM7E;AAMD,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,GAAG,oBAAoB,CAgB9E"}