@astram/guard 0.1.0

package/dist/config/app-config.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_SVC_POOL_HARD_CAP = exports.DEFAULT_POOL_BUDGET = void 0;
+exports.loadPoolBudget = loadPoolBudget;
+exports.loadAppConfig = loadAppConfig;
+exports.evaluatePoolBudget = evaluatePoolBudget;
+/** Documented MVP single-node defaults (see the class doc + my.cnf). */
+exports.DEFAULT_POOL_BUDGET = {
+    workers: 8,
+    maxConnections: 250,
+    headroom: 40,
+    perAccountMax: {
+        shield_core: 12,
+        shield_app_crud: 8,
+        shield_schema_svc: 1,
+    },
+};
+/** Upper bound the schema-service pool must never exceed (ADR-0018 §2: 1–2). */
+exports.SCHEMA_SVC_POOL_HARD_CAP = 2;
+function parsePort(raw, fallback) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isInteger(n) && n > 0 && n < 65_536 ? n : fallback;
+}
+function parseEnvironment(raw) {
+    if (raw === 'production' || raw === 'test')
+        return raw;
+    return 'development';
+}
+/**
+ * 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
+ * whether the RESULTING budget is valid, so parsing stays lenient + total.
+ */
+function parsePositiveInt(raw, fallback) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+/**
+ * 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
+ */
+function loadPoolBudget(env = process.env) {
+    return {
+        workers: parsePositiveInt(env.SHIELD_POOL_WORKERS, exports.DEFAULT_POOL_BUDGET.workers),
+        maxConnections: parsePositiveInt(env.SHIELD_DB_MAX_CONNECTIONS, exports.DEFAULT_POOL_BUDGET.maxConnections),
+        headroom: parsePositiveInt(env.SHIELD_POOL_HEADROOM, exports.DEFAULT_POOL_BUDGET.headroom),
+        perAccountMax: {
+            shield_core: parsePositiveInt(env.SHIELD_POOL_MAX_CORE, exports.DEFAULT_POOL_BUDGET.perAccountMax.shield_core),
+            shield_app_crud: parsePositiveInt(env.SHIELD_POOL_MAX_APP_CRUD, exports.DEFAULT_POOL_BUDGET.perAccountMax.shield_app_crud),
+            shield_schema_svc: parsePositiveInt(env.SHIELD_POOL_MAX_SCHEMA_SVC, exports.DEFAULT_POOL_BUDGET.perAccountMax.shield_schema_svc),
+        },
+    };
+}
+/**
+ * Build the {@link AppConfig} from `process.env` (or an injected env bag, for
+ * testability). Pure + side-effect-free so it is trivially unit-testable.
+ */
+function loadAppConfig(env = process.env) {
+    return {
+        port: parsePort(env.PORT, 3000),
+        environment: parseEnvironment(env.NODE_ENV),
+        pool: loadPoolBudget(env),
+    };
+}
+/**
+ * Evaluate a pool budget. Pure: no throwing, no I/O — the caller decides how to
+ * react (the boot assertion throws; tests inspect the fields).
+ */
+function evaluatePoolBudget(cfg) {
+    const perWorkerConnections = cfg.perAccountMax.shield_core +
+        cfg.perAccountMax.shield_app_crud +
+        cfg.perAccountMax.shield_schema_svc;
+    const runtimeConnections = cfg.workers * perWorkerConnections;
+    const requiredConnections = runtimeConnections + cfg.headroom;
+    const slack = cfg.maxConnections - requiredConnections;
+    return {
+        perWorkerConnections,
+        runtimeConnections,
+        requiredConnections,
+        slack,
+        withinBudget: requiredConnections <= cfg.maxConnections,
+        schemaSvcWithinHardCap: cfg.perAccountMax.shield_schema_svc <= exports.SCHEMA_SVC_POOL_HARD_CAP,
+    };
+}

package/dist/config/config.module.d.ts

@@ -0,0 +1,12 @@
+/** DI token for the resolved {@link AppConfig}. */
+export declare const APP_CONFIG: unique symbol;
+/**
+ * Minimal config module (Scaffold).
+ *
+ * Provides the resolved {@link AppConfig} under {@link APP_CONFIG} so any
+ * provider can inject it. `@Global()` so it need not be re-imported everywhere.
+ * A richer, validated config system replaces this in the Infrastructure layer.
+ */
+export declare class ConfigModule {
+}
+//# sourceMappingURL=config.module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.module.d.ts","sourceRoot":"","sources":["../../src/config/config.module.ts"],"names":[],"mappings":"AAGA,mDAAmD;AACnD,eAAO,MAAM,UAAU,eAAuB,CAAC;AAE/C;;;;;;GAMG;AACH,qBAUa,YAAY;CAAG"}

package/dist/config/config.module.js

@@ -0,0 +1,35 @@
+"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.ConfigModule = exports.APP_CONFIG = void 0;
+const common_1 = require("@nestjs/common");
+const app_config_js_1 = require("./app-config.js");
+/** DI token for the resolved {@link AppConfig}. */
+exports.APP_CONFIG = Symbol('APP_CONFIG');
+/**
+ * Minimal config module (Scaffold).
+ *
+ * Provides the resolved {@link AppConfig} under {@link APP_CONFIG} so any
+ * provider can inject it. `@Global()` so it need not be re-imported everywhere.
+ * A richer, validated config system replaces this in the Infrastructure layer.
+ */
+let ConfigModule = class ConfigModule {
+};
+exports.ConfigModule = ConfigModule;
+exports.ConfigModule = ConfigModule = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        providers: [
+            {
+                provide: exports.APP_CONFIG,
+                useFactory: () => (0, app_config_js_1.loadAppConfig)(),
+            },
+        ],
+        exports: [exports.APP_CONFIG],
+    })
+], ConfigModule);

package/dist/enforcement/classification.decorator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Route-classification metadata keys (ADR-0002).
+ *
+ * Every HTTP handler in Shield must carry a classification. The global
+ * enforcement guard (see {@link GlobalEnforcementGuard}) reads these keys and,
+ * for any route WITHOUT one, denies the request (deny-by-default). This is the
+ * structurally-unavoidable, fail-closed posture ADR-0002 mandates — present from
+ * day one, even though the Scaffold stub does not yet consult a real decision
+ * authority.
+ */
+export declare const CLASSIFICATION_METADATA: {
+    /** Marks a route as an explicit, code-reviewed public opt-out. */
+    readonly PUBLIC: "shield:classification:public";
+    /**
+     * Marks a route as classified against a permission/tier. In the Scaffold this
+     * is a placeholder value only — a LATER layer (ADR-0004 tiers, ADR-0012
+     * authoring) resolves it to a real decision. Its mere PRESENCE is what the
+     * stub guard checks: a classified route is "declared", an undeclared route is
+     * denied.
+     */
+    readonly CLASSIFIED: "shield:classification:classified";
+};
+/**
+ * `@Public()` — the explicit, deny-by-default opt-OUT (ADR-0002).
+ *
+ * A route marked `@Public()` is reachable without a classification. This is the
+ * ONLY sanctioned way to make a route publicly reachable; it is intended to be
+ * rare and code-reviewed. Everything not `@Public()` and not `@Classified()` is
+ * denied by the global guard.
+ */
+export declare const Public: () => MethodDecorator & ClassDecorator;
+/**
+ * `@Classified(...)` — declare a route's permission/tier classification.
+ *
+ * SCAFFOLD STUB: this only records that the route was classified; it does not
+ * yet gate on a real permission. A later authorization layer replaces the stub
+ * with an actual decision. Present here so business routes can be authored with
+ * the final API shape from the start.
+ */
+export declare const Classified: (classification: string) => MethodDecorator & ClassDecorator;
+//# sourceMappingURL=classification.decorator.d.ts.map

package/dist/enforcement/classification.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification.decorator.d.ts","sourceRoot":"","sources":["../../src/enforcement/classification.decorator.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB;IAClC,kEAAkE;;IAElE;;;;;;OAMG;;CAEK,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,QAAO,eAAe,GAAG,cACO,CAAC;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAI,gBAAgB,MAAM,KAAG,eAAe,GAAG,cACL,CAAC"}

package/dist/enforcement/classification.decorator.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Classified = exports.Public = exports.CLASSIFICATION_METADATA = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * Route-classification metadata keys (ADR-0002).
+ *
+ * Every HTTP handler in Shield must carry a classification. The global
+ * enforcement guard (see {@link GlobalEnforcementGuard}) reads these keys and,
+ * for any route WITHOUT one, denies the request (deny-by-default). This is the
+ * structurally-unavoidable, fail-closed posture ADR-0002 mandates — present from
+ * day one, even though the Scaffold stub does not yet consult a real decision
+ * authority.
+ */
+exports.CLASSIFICATION_METADATA = {
+    /** Marks a route as an explicit, code-reviewed public opt-out. */
+    PUBLIC: 'shield:classification:public',
+    /**
+     * Marks a route as classified against a permission/tier. In the Scaffold this
+     * is a placeholder value only — a LATER layer (ADR-0004 tiers, ADR-0012
+     * authoring) resolves it to a real decision. Its mere PRESENCE is what the
+     * stub guard checks: a classified route is "declared", an undeclared route is
+     * denied.
+     */
+    CLASSIFIED: 'shield:classification:classified',
+};
+/**
+ * `@Public()` — the explicit, deny-by-default opt-OUT (ADR-0002).
+ *
+ * A route marked `@Public()` is reachable without a classification. This is the
+ * ONLY sanctioned way to make a route publicly reachable; it is intended to be
+ * rare and code-reviewed. Everything not `@Public()` and not `@Classified()` is
+ * denied by the global guard.
+ */
+const Public = () => (0, common_1.SetMetadata)(exports.CLASSIFICATION_METADATA.PUBLIC, true);
+exports.Public = Public;
+/**
+ * `@Classified(...)` — declare a route's permission/tier classification.
+ *
+ * SCAFFOLD STUB: this only records that the route was classified; it does not
+ * yet gate on a real permission. A later authorization layer replaces the stub
+ * with an actual decision. Present here so business routes can be authored with
+ * the final API shape from the start.
+ */
+const Classified = (classification) => (0, common_1.SetMetadata)(exports.CLASSIFICATION_METADATA.CLASSIFIED, classification);
+exports.Classified = Classified;

package/dist/enforcement/core-seam.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Integration seam to @astram/core (ADR-0003).
+ *
+ * The NestJS layer is a THIN integration that CALLS the framework-agnostic Core;
+ * it contains no security logic itself. This module is the single, clearly-named
+ * place where the Core's decision authority is wired into the global enforcement
+ * guard.
+ *
+ * It imports REAL Core types from the published `@astram/core` package barrel —
+ * proving the ADR-0003 integration seam compiles against the actual Core
+ * contract (`DecisionAuthority`, `Decision`, `Principal`). These are TYPE-ONLY
+ * imports, so this layer takes on no runtime dependency on Core internals yet.
+ *
+ * The Scaffold guard does NOT consult a real authority yet (ADR-0002: the stub
+ * below only proves deny-by-default). When the Authorization layer lands, wire
+ * the Core `DecisionAuthority` in here — the guard code above this seam is
+ * unchanged.
+ */
+import type { DecisionAuthority as CoreDecisionAuthority, Decision as CoreDecision, Principal } from '@astram/core';
+/** Re-export the Core contracts this layer wires against, for local consumers. */
+export type { CoreDecisionAuthority, CoreDecision, Principal };
+/**
+ * The fail-closed default effect (ADR-0002): if a decision cannot be rendered,
+ * the system denies. Mirrors the Core `Decision.effect` vocabulary.
+ */
+export type Effect = 'allow' | 'deny';
+/**
+ * Fail-closed placeholder authority for the Scaffold.
+ *
+ * SCAFFOLD STUB: returns a `deny_by_default` `Decision` for every classified
+ * route so that "classified but not yet backed by a real policy" cannot silently
+ * open a door. `@Public()` routes never reach this — they are the explicit,
+ * code-reviewed opt-out handled by the guard before any authority is consulted.
+ *
+ * Typed as the full Core `DecisionAuthority` so it stays a true drop-in if the
+ * interface grows — replacing it with the real Core authority later is a
+ * one-line swap in the guard's DI.
+ */
+export declare const stubDecisionAuthority: CoreDecisionAuthority;
+//# sourceMappingURL=core-seam.d.ts.map

package/dist/enforcement/core-seam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-seam.d.ts","sourceRoot":"","sources":["../../src/enforcement/core-seam.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,EACV,iBAAiB,IAAI,qBAAqB,EAC1C,QAAQ,IAAI,YAAY,EACxB,SAAS,EACV,MAAM,cAAc,CAAC;AAEtB,kFAAkF;AAClF,YAAY,EAAE,qBAAqB,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,EAAE,qBAInC,CAAC"}

package/dist/enforcement/core-seam.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Integration seam to @astram/core (ADR-0003).
+ *
+ * The NestJS layer is a THIN integration that CALLS the framework-agnostic Core;
+ * it contains no security logic itself. This module is the single, clearly-named
+ * place where the Core's decision authority is wired into the global enforcement
+ * guard.
+ *
+ * It imports REAL Core types from the published `@astram/core` package barrel —
+ * proving the ADR-0003 integration seam compiles against the actual Core
+ * contract (`DecisionAuthority`, `Decision`, `Principal`). These are TYPE-ONLY
+ * imports, so this layer takes on no runtime dependency on Core internals yet.
+ *
+ * The Scaffold guard does NOT consult a real authority yet (ADR-0002: the stub
+ * below only proves deny-by-default). When the Authorization layer lands, wire
+ * the Core `DecisionAuthority` in here — the guard code above this seam is
+ * unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stubDecisionAuthority = void 0;
+/**
+ * Fail-closed placeholder authority for the Scaffold.
+ *
+ * SCAFFOLD STUB: returns a `deny_by_default` `Decision` for every classified
+ * route so that "classified but not yet backed by a real policy" cannot silently
+ * open a door. `@Public()` routes never reach this — they are the explicit,
+ * code-reviewed opt-out handled by the guard before any authority is consulted.
+ *
+ * Typed as the full Core `DecisionAuthority` so it stays a true drop-in if the
+ * interface grows — replacing it with the real Core authority later is a
+ * one-line swap in the guard's DI.
+ */
+exports.stubDecisionAuthority = {
+    decide() {
+        return Promise.resolve({ effect: 'deny', reason: 'deny_by_default' });
+    },
+};

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

@@ -0,0 +1,18 @@
+/**
+ * The SOLE definition of the global `APP_GUARD` binding (ADR-0002).
+ *
+ * Registering {@link GlobalEnforcementGuard} as an `APP_GUARD` makes it apply to
+ * EVERY route across the whole application — it is impossible to opt a route out
+ * of enforcement by omission. The only sanctioned opt-out is the explicit,
+ * code-reviewed `@Public()` decorator. This is the "one global mechanism through
+ * which all requests pass" ADR-0002 mandates.
+ *
+ * INTERNAL — this module is NOT public API and is NOT exported from the package
+ * barrel. It is composed internally by {@link ShieldModule.forRoot} (the ONE
+ * registration seam, ADR-0023 §4); consumers must NOT import it directly. Keeping
+ * this the single `APP_GUARD` definition (instead of re-inlining it in
+ * `ShieldModule`) guarantees exactly one wiring path for the guard.
+ */
+export declare class EnforcementModule {
+}
+//# sourceMappingURL=enforcement.module.d.ts.map

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

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

package/dist/enforcement/enforcement.module.js

@@ -0,0 +1,40 @@
+"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.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");
+/**
+ * The SOLE definition of the global `APP_GUARD` binding (ADR-0002).
+ *
+ * Registering {@link GlobalEnforcementGuard} as an `APP_GUARD` makes it apply to
+ * EVERY route across the whole application — it is impossible to opt a route out
+ * of enforcement by omission. The only sanctioned opt-out is the explicit,
+ * code-reviewed `@Public()` decorator. This is the "one global mechanism through
+ * which all requests pass" ADR-0002 mandates.
+ *
+ * INTERNAL — this module is NOT public API and is NOT exported from the package
+ * barrel. It is composed internally by {@link ShieldModule.forRoot} (the ONE
+ * registration seam, ADR-0023 §4); consumers must NOT import it directly. Keeping
+ * this the single `APP_GUARD` definition (instead of re-inlining it in
+ * `ShieldModule`) guarantees exactly one wiring path for the guard.
+ */
+let EnforcementModule = class EnforcementModule {
+};
+exports.EnforcementModule = EnforcementModule;
+exports.EnforcementModule = EnforcementModule = __decorate([
+    (0, common_1.Module)({
+        providers: [
+            {
+                provide: core_1.APP_GUARD,
+                useClass: global_enforcement_guard_js_1.GlobalEnforcementGuard,
+            },
+        ],
+    })
+], EnforcementModule);

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

@@ -0,0 +1,31 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+/**
+ * Global, fail-closed enforcement guard (ADR-0002).
+ *
+ * This guard is the SINGLE, structurally-unavoidable point every request passes
+ * through. It is bound as an `APP_GUARD` through the ONE registration seam,
+ * `ShieldModule.forRoot()` (which composes the internal `EnforcementModule` that
+ * holds the sole binding) — NOT opt-in per controller — so no endpoint can escape
+ * it. Its posture is **deny-by-default**:
+ *
+ *   - A route marked `@Public()`      → ALLOWED (explicit, code-reviewed opt-out).
+ *   - A route marked `@Classified()`  → allowed to PROCEED in the Scaffold stub
+ *       (a LATER layer will consult the real Core `DecisionAuthority` here; see
+ *       {@link ../enforcement/core-seam.ts}). Its presence proves the route was
+ *       declared.
+ *   - A route with NO classification  → DENIED (403). A forgotten declaration
+ *       locks the door instead of opening it.
+ *
+ * SCAFFOLD SCOPE: this does not yet perform real authorization. It only proves
+ * the fail-closed, globally-unavoidable, deny-by-default seam exists from day
+ * one. When the Authorization layer lands, the `@Classified` branch calls the
+ * Core decision authority (wired via the core-seam) — the deny-by-default
+ * structure here does not change.
+ */
+export declare class GlobalEnforcementGuard implements CanActivate {
+    private readonly reflector;
+    constructor(reflector: Reflector);
+    canActivate(context: ExecutionContext): boolean;
+}
+//# sourceMappingURL=global-enforcement.guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"global-enforcement.guard.d.ts","sourceRoot":"","sources":["../../src/enforcement/global-enforcement.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAkC,MAAM,gBAAgB,CAAC;AAC/F,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBACa,sBAAuB,YAAW,WAAW;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,SAAS;IAEjD,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;CAsChD"}

package/dist/enforcement/global-enforcement.guard.js

@@ -0,0 +1,76 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GlobalEnforcementGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const classification_decorator_js_1 = require("./classification.decorator.js");
+/**
+ * Global, fail-closed enforcement guard (ADR-0002).
+ *
+ * This guard is the SINGLE, structurally-unavoidable point every request passes
+ * through. It is bound as an `APP_GUARD` through the ONE registration seam,
+ * `ShieldModule.forRoot()` (which composes the internal `EnforcementModule` that
+ * holds the sole binding) — NOT opt-in per controller — so no endpoint can escape
+ * it. Its posture is **deny-by-default**:
+ *
+ *   - A route marked `@Public()`      → ALLOWED (explicit, code-reviewed opt-out).
+ *   - A route marked `@Classified()`  → allowed to PROCEED in the Scaffold stub
+ *       (a LATER layer will consult the real Core `DecisionAuthority` here; see
+ *       {@link ../enforcement/core-seam.ts}). Its presence proves the route was
+ *       declared.
+ *   - A route with NO classification  → DENIED (403). A forgotten declaration
+ *       locks the door instead of opening it.
+ *
+ * SCAFFOLD SCOPE: this does not yet perform real authorization. It only proves
+ * the fail-closed, globally-unavoidable, deny-by-default seam exists from day
+ * one. When the Authorization layer lands, the `@Classified` branch calls the
+ * Core decision authority (wired via the core-seam) — the deny-by-default
+ * structure here does not change.
+ */
+let GlobalEnforcementGuard = class GlobalEnforcementGuard {
+    reflector;
+    constructor(reflector) {
+        this.reflector = reflector;
+    }
+    canActivate(context) {
+        // Only HTTP requests are classified here. Non-HTTP contexts (if ever added)
+        // must be handled explicitly rather than silently allowed.
+        if (context.getType() !== 'http') {
+            throw new common_1.ForbiddenException('Shield enforcement: non-HTTP execution context is not classified (deny-by-default).');
+        }
+        const handler = context.getHandler();
+        const controller = context.getClass();
+        // 1. Explicit public opt-out wins. Method-level OR class-level @Public().
+        const isPublic = this.reflector.getAllAndOverride(classification_decorator_js_1.CLASSIFICATION_METADATA.PUBLIC, [
+            handler,
+            controller,
+        ]);
+        if (isPublic === true) {
+            return true;
+        }
+        // 2. Classified route → declared. Scaffold stub lets it proceed (a real
+        //    decision authority is wired in a later layer via the core-seam).
+        const classification = this.reflector.getAllAndOverride(classification_decorator_js_1.CLASSIFICATION_METADATA.CLASSIFIED, [handler, controller]);
+        if (typeof classification === 'string' && classification.length > 0) {
+            return true;
+        }
+        // 3. No classification at all → DENY (ADR-0002 deny-by-default / fail-closed).
+        throw new common_1.ForbiddenException('Shield enforcement: this route carries no access classification. ' +
+            'It is denied by default (ADR-0002). Mark it @Public() to opt out, or ' +
+            '@Classified(...) to declare its permission.');
+    }
+};
+exports.GlobalEnforcementGuard = GlobalEnforcementGuard;
+exports.GlobalEnforcementGuard = GlobalEnforcementGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.Reflector])
+], GlobalEnforcementGuard);

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@astram/guard` — the thin NestJS integration for the Shield framework
+ * (ADR-0023 §1, ADR-0003).
+ *
+ * This is the shippable, consumer-INSTALLED framework glue: the global
+ * deny-by-default enforcement guard (ADR-0002), its `@Public()`/`@Classified()`
+ * classification decorators, the ADR-0018 boot-pool assertion, and the ONE
+ * registration seam — {@link ShieldModule}`.forRoot()` / `.forRootAsync()`.
+ *
+ * A consumer app depends on this package and `@astram/core`, imports
+ * `ShieldModule.forRoot({...})` once, and builds features in its own editable
+ * `src/`. It never edits the framework; upgrades flow through `npm update`.
+ *
+ * Depends on `@astram/core` (workspace); PEER-depends on `@nestjs/common`,
+ * `@nestjs/core`, `reflect-metadata`, `rxjs` so the host owns one copy of each.
+ */
+export { ShieldModule, SHIELD_DECISION_AUTHORITY, type ShieldModuleOptions, type ShieldModuleAsyncOptions, } from './module/shield.module.js';
+export { Public, Classified, CLASSIFICATION_METADATA, } from './enforcement/classification.decorator.js';
+export { GlobalEnforcementGuard } from './enforcement/global-enforcement.guard.js';
+export { stubDecisionAuthority, type Effect, type CoreDecisionAuthority, type CoreDecision, type Principal, } from './enforcement/core-seam.js';
+export { Argon2idPasswordHasher, argon2idHasherProvider, SHIELD_PASSWORD_HASHER, type Argon2idParams, } from './authentication/argon2id-password-hasher.js';
+export { MariaDbSessionRecordStore, SHIELD_SESSION_RECORD_STORE, RedisHotSessionStore, SHIELD_HOT_SESSION_STORE, CryptoTokenGenerator, Sha256RefreshTokenHasher, SystemClock, cryptoTokenGeneratorProvider, refreshHasherProvider, systemClockProvider, SHIELD_TOKEN_GENERATOR, SHIELD_REFRESH_HASHER, SHIELD_CLOCK, } from './session/index.js';
+export { BootSequence, assertPoolBudget } from './boot/boot-sequence.js';
+export { APP_CONFIG } from './config/config.module.js';
+export { loadAppConfig, loadPoolBudget, evaluatePoolBudget, DEFAULT_POOL_BUDGET, SCHEMA_SVC_POOL_HARD_CAP, type AppConfig, type PoolBudgetConfig, type PoolBudgetEvaluation, type RuntimeAccountPools, } from './config/app-config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACL,YAAY,EACZ,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,MAAM,EACN,UAAU,EACV,uBAAuB,GACxB,MAAM,2CAA2C,CAAC;AAUnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAKnF,OAAO,EACL,qBAAqB,EACrB,KAAK,MAAM,EACX,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,4BAA4B,CAAC;AAMpC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,cAAc,GACpB,MAAM,8CAA8C,CAAC;AAOtD,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,wBAAwB,EACxB,WAAW,EACX,4BAA4B,EAC5B,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAOzE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EACL,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,GACzB,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * `@astram/guard` — the thin NestJS integration for the Shield framework
+ * (ADR-0023 §1, ADR-0003).
+ *
+ * This is the shippable, consumer-INSTALLED framework glue: the global
+ * deny-by-default enforcement guard (ADR-0002), its `@Public()`/`@Classified()`
+ * classification decorators, the ADR-0018 boot-pool assertion, and the ONE
+ * registration seam — {@link ShieldModule}`.forRoot()` / `.forRootAsync()`.
+ *
+ * A consumer app depends on this package and `@astram/core`, imports
+ * `ShieldModule.forRoot({...})` once, and builds features in its own editable
+ * `src/`. It never edits the framework; upgrades flow through `npm update`.
+ *
+ * Depends on `@astram/core` (workspace); PEER-depends on `@nestjs/common`,
+ * `@nestjs/core`, `reflect-metadata`, `rxjs` so the host owns one copy of each.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_SVC_POOL_HARD_CAP = exports.DEFAULT_POOL_BUDGET = exports.evaluatePoolBudget = exports.loadPoolBudget = exports.loadAppConfig = exports.APP_CONFIG = exports.assertPoolBudget = exports.BootSequence = exports.SHIELD_CLOCK = exports.SHIELD_REFRESH_HASHER = exports.SHIELD_TOKEN_GENERATOR = exports.systemClockProvider = exports.refreshHasherProvider = exports.cryptoTokenGeneratorProvider = exports.SystemClock = exports.Sha256RefreshTokenHasher = exports.CryptoTokenGenerator = exports.SHIELD_HOT_SESSION_STORE = exports.RedisHotSessionStore = exports.SHIELD_SESSION_RECORD_STORE = exports.MariaDbSessionRecordStore = exports.SHIELD_PASSWORD_HASHER = exports.argon2idHasherProvider = exports.Argon2idPasswordHasher = exports.stubDecisionAuthority = exports.GlobalEnforcementGuard = exports.CLASSIFICATION_METADATA = exports.Classified = exports.Public = exports.SHIELD_DECISION_AUTHORITY = exports.ShieldModule = void 0;
+// The single registration seam.
+var shield_module_js_1 = require("./module/shield.module.js");
+Object.defineProperty(exports, "ShieldModule", { enumerable: true, get: function () { return shield_module_js_1.ShieldModule; } });
+Object.defineProperty(exports, "SHIELD_DECISION_AUTHORITY", { enumerable: true, get: function () { return shield_module_js_1.SHIELD_DECISION_AUTHORITY; } });
+// Route classification (the consumer authors these on its controllers).
+var classification_decorator_js_1 = require("./enforcement/classification.decorator.js");
+Object.defineProperty(exports, "Public", { enumerable: true, get: function () { return classification_decorator_js_1.Public; } });
+Object.defineProperty(exports, "Classified", { enumerable: true, get: function () { return classification_decorator_js_1.Classified; } });
+Object.defineProperty(exports, "CLASSIFICATION_METADATA", { enumerable: true, get: function () { return classification_decorator_js_1.CLASSIFICATION_METADATA; } });
+// The global enforcement guard (framework-owned; exported so the enforcement
+// point is inspectable/testable, not so consumers re-wire it).
+//
+// NOTE: `EnforcementModule` / `BootModule` / `ConfigModule` are DELIBERATELY NOT
+// exported. `ShieldModule.forRoot()` is the ONE registration seam and composes
+// them internally (EnforcementModule holds the SOLE `APP_GUARD` binding). Exposing
+// them would let a consumer import a module that independently re-binds `APP_GUARD`
+// — a second, divergent wiring path that contradicts ADR-0023 §4 ("one seam").
+var global_enforcement_guard_js_1 = require("./enforcement/global-enforcement.guard.js");
+Object.defineProperty(exports, "GlobalEnforcementGuard", { enumerable: true, get: function () { return global_enforcement_guard_js_1.GlobalEnforcementGuard; } });
+// The Core integration seam (ADR-0003): the decision-authority contract this
+// layer wires against, plus the fail-closed stub used until a real authority is
+// supplied through `ShieldModule.forRoot`.
+var core_seam_js_1 = require("./enforcement/core-seam.js");
+Object.defineProperty(exports, "stubDecisionAuthority", { enumerable: true, get: function () { return core_seam_js_1.stubDecisionAuthority; } });
+// The Authentication crypto adapter (ADR-0003): the concrete Argon2id
+// `PasswordHasher` implementation lives HERE (real `argon2` dependency) and is
+// injected into `@astram/core`'s `createAuthenticator({ hasher })` — Core stays
+// zero-dep. The DI token + provider factory wire it into a Nest container.
+var argon2id_password_hasher_js_1 = require("./authentication/argon2id-password-hasher.js");
+Object.defineProperty(exports, "Argon2idPasswordHasher", { enumerable: true, get: function () { return argon2id_password_hasher_js_1.Argon2idPasswordHasher; } });
+Object.defineProperty(exports, "argon2idHasherProvider", { enumerable: true, get: function () { return argon2id_password_hasher_js_1.argon2idHasherProvider; } });
+Object.defineProperty(exports, "SHIELD_PASSWORD_HASHER", { enumerable: true, get: function () { return argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER; } });
+// The Session storage/crypto adapters (ADR-0003 / ADR-0013): the concrete durable
+// (MariaDB) + hot (Redis) stores, the node:crypto token generator, the keyed HMAC
+// refresh hasher, and the system clock — all implementing `@astram/core`'s Session
+// PORTs and injected into `createSessionAuthority(...)`. Core stays zero-dep; the
+// real `mariadb` / `ioredis` / `node:crypto` live here.
+var index_js_1 = require("./session/index.js");
+Object.defineProperty(exports, "MariaDbSessionRecordStore", { enumerable: true, get: function () { return index_js_1.MariaDbSessionRecordStore; } });
+Object.defineProperty(exports, "SHIELD_SESSION_RECORD_STORE", { enumerable: true, get: function () { return index_js_1.SHIELD_SESSION_RECORD_STORE; } });
+Object.defineProperty(exports, "RedisHotSessionStore", { enumerable: true, get: function () { return index_js_1.RedisHotSessionStore; } });
+Object.defineProperty(exports, "SHIELD_HOT_SESSION_STORE", { enumerable: true, get: function () { return index_js_1.SHIELD_HOT_SESSION_STORE; } });
+Object.defineProperty(exports, "CryptoTokenGenerator", { enumerable: true, get: function () { return index_js_1.CryptoTokenGenerator; } });
+Object.defineProperty(exports, "Sha256RefreshTokenHasher", { enumerable: true, get: function () { return index_js_1.Sha256RefreshTokenHasher; } });
+Object.defineProperty(exports, "SystemClock", { enumerable: true, get: function () { return index_js_1.SystemClock; } });
+Object.defineProperty(exports, "cryptoTokenGeneratorProvider", { enumerable: true, get: function () { return index_js_1.cryptoTokenGeneratorProvider; } });
+Object.defineProperty(exports, "refreshHasherProvider", { enumerable: true, get: function () { return index_js_1.refreshHasherProvider; } });
+Object.defineProperty(exports, "systemClockProvider", { enumerable: true, get: function () { return index_js_1.systemClockProvider; } });
+Object.defineProperty(exports, "SHIELD_TOKEN_GENERATOR", { enumerable: true, get: function () { return index_js_1.SHIELD_TOKEN_GENERATOR; } });
+Object.defineProperty(exports, "SHIELD_REFRESH_HASHER", { enumerable: true, get: function () { return index_js_1.SHIELD_REFRESH_HASHER; } });
+Object.defineProperty(exports, "SHIELD_CLOCK", { enumerable: true, get: function () { return index_js_1.SHIELD_CLOCK; } });
+// Boot infrastructure (ADR-0018 connection-pool budget assertion). `BootModule`
+// itself is NOT exported — it is composed internally by `ShieldModule.forRoot()`.
+var boot_sequence_js_1 = require("./boot/boot-sequence.js");
+Object.defineProperty(exports, "BootSequence", { enumerable: true, get: function () { return boot_sequence_js_1.BootSequence; } });
+Object.defineProperty(exports, "assertPoolBudget", { enumerable: true, get: function () { return boot_sequence_js_1.assertPoolBudget; } });
+// Application config surface (port / environment / ADR-0018 pool budget). The
+// consumer skeleton reads `loadAppConfig()` for its HTTP port; the boot assertion
+// validates the pool budget. The `APP_CONFIG` DI token is exported; `ConfigModule`
+// (its env-only provider) is NOT — `ShieldModule` provides `APP_CONFIG` itself so
+// the one seam can honor caller-supplied config.
+var config_module_js_1 = require("./config/config.module.js");
+Object.defineProperty(exports, "APP_CONFIG", { enumerable: true, get: function () { return config_module_js_1.APP_CONFIG; } });
+var app_config_js_1 = require("./config/app-config.js");
+Object.defineProperty(exports, "loadAppConfig", { enumerable: true, get: function () { return app_config_js_1.loadAppConfig; } });
+Object.defineProperty(exports, "loadPoolBudget", { enumerable: true, get: function () { return app_config_js_1.loadPoolBudget; } });
+Object.defineProperty(exports, "evaluatePoolBudget", { enumerable: true, get: function () { return app_config_js_1.evaluatePoolBudget; } });
+Object.defineProperty(exports, "DEFAULT_POOL_BUDGET", { enumerable: true, get: function () { return app_config_js_1.DEFAULT_POOL_BUDGET; } });
+Object.defineProperty(exports, "SCHEMA_SVC_POOL_HARD_CAP", { enumerable: true, get: function () { return app_config_js_1.SCHEMA_SVC_POOL_HARD_CAP; } });