@astram/guard 0.1.0

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

@@ -0,0 +1,79 @@
+import { type DynamicModule } from '@nestjs/common';
+import type { CoreDecisionAuthority } from '../enforcement/core-seam.js';
+import { type AppConfig } from '../config/app-config.js';
+/**
+ * DI token for the Core decision authority (the ADR-0001 single decision
+ * authority) that the enforcement guard consults. The consumer supplies the real
+ * `@astram/core` authority through {@link ShieldModule.forRoot}; when omitted the
+ * framework binds the fail-closed {@link stubDecisionAuthority} (deny-by-default),
+ * so a mis-wiring cannot silently open a door.
+ */
+export declare const SHIELD_DECISION_AUTHORITY: unique symbol;
+/**
+ * Options for {@link ShieldModule.forRoot}. Intentionally minimal (ADR-0023 §7 —
+ * no speculative abstraction): the consumer declares Shield through this ONE seam.
+ */
+export interface ShieldModuleOptions {
+    /**
+     * The Core decision authority (`@astram/core`'s `DecisionAuthority`) the global
+     * guard invokes for classified routes. Optional in this layer: omit it and the
+     * framework binds the fail-closed stub. A later Authorization layer makes this
+     * the real Core authority — the guard's call site does not change.
+     */
+    readonly decisionAuthority?: CoreDecisionAuthority;
+    /**
+     * Application config (port/environment/ADR-0018 pool budget). Omit to load from
+     * the environment via {@link loadAppConfig}. Supplied here so a consumer can
+     * inject computed config through the one seam rather than editing the framework.
+     */
+    readonly config?: AppConfig;
+}
+/** Async variant of {@link ShieldModuleOptions} (DI-computed config). */
+export interface ShieldModuleAsyncOptions {
+    /** Providers this factory injects (resolved by the host DI container). */
+    readonly inject?: readonly unknown[];
+    /** Factory returning {@link ShieldModuleOptions} (may be async). */
+    readonly useFactory: (...args: readonly unknown[]) => Promise<ShieldModuleOptions> | ShieldModuleOptions;
+    /** Modules exporting the injected providers. */
+    readonly imports?: readonly unknown[];
+}
+/**
+ * `ShieldModule` — the SINGLE registration seam (ADR-0023 §4).
+ *
+ * A consumer app declares Shield by importing `ShieldModule.forRoot({...})` ONCE
+ * in its root module. The framework — not the consumer — owns composition, and
+ * this is the SINGLE wiring path: `ShieldModule` COMPOSES the framework's internal
+ * modules via `imports` rather than re-declaring their providers, so each binding
+ * has exactly ONE definition (ADR-0023 §4 — one seam, no divergent path):
+ *
+ *  - {@link EnforcementModule} — the SOLE definition of the `APP_GUARD` →
+ *    {@link GlobalEnforcementGuard} binding (the global, deny-by-default
+ *    enforcement point, ADR-0002; covers EVERY route). `ShieldModule` never
+ *    re-binds `APP_GUARD` itself — it imports this module.
+ *  - {@link BootModule} — the {@link BootSequence} lifecycle hook, which runs the
+ *    ADR-0018 connection-pool budget assertion at boot (fail-closed).
+ *  - `APP_CONFIG` + `SHIELD_DECISION_AUTHORITY` — provided by `ShieldModule` here
+ *    so the ONE seam can honor caller-supplied `config`/`decisionAuthority`
+ *    (`ConfigModule`'s env-only `APP_CONFIG` is NOT composed, to avoid a second
+ *    provider for the same token). `SHIELD_DECISION_AUTHORITY` (the ADR-0001 single
+ *    decision authority) is the real `@astram/core` authority when supplied, else
+ *    the fail-closed stub.
+ *
+ * `@Global()` so its exported tokens are visible app-wide without re-importing.
+ */
+export declare class ShieldModule {
+    /** Register Shield with static options (the common path). */
+    static forRoot(options?: ShieldModuleOptions): DynamicModule;
+    /**
+     * Register Shield with DI-computed options (`forRootAsync`).
+     *
+     * STUB (ADR-0023): the async factory resolves {@link ShieldModuleOptions} at
+     * startup, then composes exactly as {@link forRoot} — same imported
+     * {@link EnforcementModule} (the ONE `APP_GUARD` binding) + {@link BootModule}.
+     * Only `APP_CONFIG`/`SHIELD_DECISION_AUTHORITY` are provided asynchronously; the
+     * guard/boot wiring is identical, so the fail-closed enforcement seam is
+     * unchanged whether config is static or computed.
+     */
+    static forRootAsync(options: ShieldModuleAsyncOptions): DynamicModule;
+}
+//# sourceMappingURL=shield.module.d.ts.map

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

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

package/dist/module/shield.module.js

@@ -0,0 +1,108 @@
+"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 ShieldModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShieldModule = exports.SHIELD_DECISION_AUTHORITY = void 0;
+const common_1 = require("@nestjs/common");
+const core_seam_js_1 = require("../enforcement/core-seam.js");
+const enforcement_module_js_1 = require("../enforcement/enforcement.module.js");
+const boot_module_js_1 = require("../boot/boot.module.js");
+const config_module_js_1 = require("../config/config.module.js");
+const app_config_js_1 = require("../config/app-config.js");
+/**
+ * DI token for the Core decision authority (the ADR-0001 single decision
+ * authority) that the enforcement guard consults. The consumer supplies the real
+ * `@astram/core` authority through {@link ShieldModule.forRoot}; when omitted the
+ * framework binds the fail-closed {@link stubDecisionAuthority} (deny-by-default),
+ * so a mis-wiring cannot silently open a door.
+ */
+exports.SHIELD_DECISION_AUTHORITY = Symbol('SHIELD_DECISION_AUTHORITY');
+/**
+ * `ShieldModule` — the SINGLE registration seam (ADR-0023 §4).
+ *
+ * A consumer app declares Shield by importing `ShieldModule.forRoot({...})` ONCE
+ * in its root module. The framework — not the consumer — owns composition, and
+ * this is the SINGLE wiring path: `ShieldModule` COMPOSES the framework's internal
+ * modules via `imports` rather than re-declaring their providers, so each binding
+ * has exactly ONE definition (ADR-0023 §4 — one seam, no divergent path):
+ *
+ *  - {@link EnforcementModule} — the SOLE definition of the `APP_GUARD` →
+ *    {@link GlobalEnforcementGuard} binding (the global, deny-by-default
+ *    enforcement point, ADR-0002; covers EVERY route). `ShieldModule` never
+ *    re-binds `APP_GUARD` itself — it imports this module.
+ *  - {@link BootModule} — the {@link BootSequence} lifecycle hook, which runs the
+ *    ADR-0018 connection-pool budget assertion at boot (fail-closed).
+ *  - `APP_CONFIG` + `SHIELD_DECISION_AUTHORITY` — provided by `ShieldModule` here
+ *    so the ONE seam can honor caller-supplied `config`/`decisionAuthority`
+ *    (`ConfigModule`'s env-only `APP_CONFIG` is NOT composed, to avoid a second
+ *    provider for the same token). `SHIELD_DECISION_AUTHORITY` (the ADR-0001 single
+ *    decision authority) is the real `@astram/core` authority when supplied, else
+ *    the fail-closed stub.
+ *
+ * `@Global()` so its exported tokens are visible app-wide without re-importing.
+ */
+let ShieldModule = ShieldModule_1 = class ShieldModule {
+    /** Register Shield with static options (the common path). */
+    static forRoot(options = {}) {
+        const config = options.config ?? (0, app_config_js_1.loadAppConfig)();
+        return {
+            module: ShieldModule_1,
+            // Compose the framework modules — EnforcementModule holds the ONE APP_GUARD
+            // binding; BootModule holds the boot-sequence hook. No re-declaration here.
+            imports: [enforcement_module_js_1.EnforcementModule, boot_module_js_1.BootModule],
+            providers: [
+                { provide: config_module_js_1.APP_CONFIG, useValue: config },
+                {
+                    provide: exports.SHIELD_DECISION_AUTHORITY,
+                    useValue: options.decisionAuthority ?? core_seam_js_1.stubDecisionAuthority,
+                },
+            ],
+            exports: [config_module_js_1.APP_CONFIG, exports.SHIELD_DECISION_AUTHORITY],
+        };
+    }
+    /**
+     * Register Shield with DI-computed options (`forRootAsync`).
+     *
+     * STUB (ADR-0023): the async factory resolves {@link ShieldModuleOptions} at
+     * startup, then composes exactly as {@link forRoot} — same imported
+     * {@link EnforcementModule} (the ONE `APP_GUARD` binding) + {@link BootModule}.
+     * Only `APP_CONFIG`/`SHIELD_DECISION_AUTHORITY` are provided asynchronously; the
+     * guard/boot wiring is identical, so the fail-closed enforcement seam is
+     * unchanged whether config is static or computed.
+     */
+    static forRootAsync(options) {
+        const optionsToken = Symbol('SHIELD_MODULE_OPTIONS');
+        const asyncOptionsProvider = {
+            provide: optionsToken,
+            useFactory: options.useFactory,
+            inject: (options.inject ?? []),
+        };
+        const configProvider = {
+            provide: config_module_js_1.APP_CONFIG,
+            useFactory: (opts) => opts.config ?? (0, app_config_js_1.loadAppConfig)(),
+            inject: [optionsToken],
+        };
+        const authorityProvider = {
+            provide: exports.SHIELD_DECISION_AUTHORITY,
+            useFactory: (opts) => opts.decisionAuthority ?? core_seam_js_1.stubDecisionAuthority,
+            inject: [optionsToken],
+        };
+        return {
+            module: ShieldModule_1,
+            // Same single-path composition as forRoot (+ the caller's option imports).
+            imports: [enforcement_module_js_1.EnforcementModule, boot_module_js_1.BootModule, ...(options.imports ?? [])],
+            providers: [asyncOptionsProvider, configProvider, authorityProvider],
+            exports: [config_module_js_1.APP_CONFIG, exports.SHIELD_DECISION_AUTHORITY],
+        };
+    }
+};
+exports.ShieldModule = ShieldModule;
+exports.ShieldModule = ShieldModule = ShieldModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], ShieldModule);

package/dist/session/crypto-adapters.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `@astram/guard` crypto + clock adapters for the Session engine PORTs.
+ *
+ * ADR-0003 (why HERE, not Core): these need `node:crypto` — a runtime capability
+ * Core (zero-dep, `types: []`, node-free) cannot import. Core defines the
+ * {@link TokenGenerator} / {@link RefreshTokenHasher} / {@link Clock} PORTs; these
+ * concretes are INJECTED into `createSessionAuthority(...)`.
+ *
+ * ⛔ SECURITY — none of these ever logs a token. `CryptoTokenGenerator` mints
+ * high-entropy opaque tokens; `Sha256RefreshTokenHasher` is a KEYED HMAC (a leaked
+ * DB cannot be brute-forced as cheaply as a bare digest) and is deterministic so
+ * `findRefreshByHash` matches.
+ */
+import type { Clock, RefreshTokenHasher, TokenGenerator } from '@astram/core';
+/** DI tokens the ShieldModule / a consumer binds the concretes under. */
+export declare const SHIELD_TOKEN_GENERATOR: unique symbol;
+export declare const SHIELD_REFRESH_HASHER: unique symbol;
+export declare const SHIELD_CLOCK: unique symbol;
+/**
+ * Opaque random-token minter (node:crypto `randomBytes`). 32 bytes = 256 bits of
+ * entropy, hex-encoded to a 64-char string (matches the CHAR(64) columns). The
+ * engine treats the result as opaque; it never parses it.
+ */
+export declare class CryptoTokenGenerator implements TokenGenerator {
+    private readonly byteLength;
+    constructor(byteLength?: number);
+    mint(): string;
+}
+/**
+ * Keyed HMAC-SHA-256 refresh-token hasher. Deterministic (same raw → same hash)
+ * so a lookup by hash matches, and keyed so an offline attacker with the DB but
+ * not the key cannot recompute hashes. Output is 64-char hex (CHAR(64)).
+ *
+ * ⛔ The `key` is a server secret (env/secrets-manager in prod). NEVER log the raw
+ * token or the key. A missing/empty key throws at construction (fail-closed: never
+ * silently downgrade to an unkeyed digest).
+ */
+export declare class Sha256RefreshTokenHasher implements RefreshTokenHasher {
+    private readonly key;
+    constructor(key: string);
+    hash(rawToken: string): string;
+}
+/** The real clock (UTC epoch ms via `Date.now`). */
+export declare class SystemClock implements Clock {
+    nowMs(): number;
+}
+/** Provider factories for wiring the crypto/clock adapters into a Nest container. */
+export declare function cryptoTokenGeneratorProvider(byteLength?: number): {
+    provide: symbol;
+    useValue: CryptoTokenGenerator;
+};
+export declare function refreshHasherProvider(key: string): {
+    provide: symbol;
+    useValue: Sha256RefreshTokenHasher;
+};
+export declare function systemClockProvider(): {
+    provide: symbol;
+    useValue: SystemClock;
+};
+//# sourceMappingURL=crypto-adapters.d.ts.map

package/dist/session/crypto-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-adapters.d.ts","sourceRoot":"","sources":["../../src/session/crypto-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9E,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,eAAmC,CAAC;AACvE,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AACrE,eAAO,MAAM,YAAY,eAAyB,CAAC;AAEnD;;;;GAIG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,SAAK;IAE5C,IAAI,IAAI,MAAM;CAIf;AAED;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,YAAW,kBAAkB;IACjE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,GAAG,EAAE,MAAM;IASvB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAI/B;AAED,oDAAoD;AACpD,qBAAa,WAAY,YAAW,KAAK;IACvC,KAAK,IAAI,MAAM;CAGhB;AAED,qFAAqF;AACrF,wBAAgB,4BAA4B,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,oBAAoB,CAAC;CAChC,CAEA;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,wBAAwB,CAAC;CACpC,CAEA;AAED,wBAAgB,mBAAmB,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CAEhF"}

package/dist/session/crypto-adapters.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * `@astram/guard` crypto + clock adapters for the Session engine PORTs.
+ *
+ * ADR-0003 (why HERE, not Core): these need `node:crypto` — a runtime capability
+ * Core (zero-dep, `types: []`, node-free) cannot import. Core defines the
+ * {@link TokenGenerator} / {@link RefreshTokenHasher} / {@link Clock} PORTs; these
+ * concretes are INJECTED into `createSessionAuthority(...)`.
+ *
+ * ⛔ SECURITY — none of these ever logs a token. `CryptoTokenGenerator` mints
+ * high-entropy opaque tokens; `Sha256RefreshTokenHasher` is a KEYED HMAC (a leaked
+ * DB cannot be brute-forced as cheaply as a bare digest) and is deterministic so
+ * `findRefreshByHash` matches.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SystemClock = exports.Sha256RefreshTokenHasher = exports.CryptoTokenGenerator = exports.SHIELD_CLOCK = exports.SHIELD_REFRESH_HASHER = exports.SHIELD_TOKEN_GENERATOR = void 0;
+exports.cryptoTokenGeneratorProvider = cryptoTokenGeneratorProvider;
+exports.refreshHasherProvider = refreshHasherProvider;
+exports.systemClockProvider = systemClockProvider;
+const node_crypto_1 = require("node:crypto");
+/** DI tokens the ShieldModule / a consumer binds the concretes under. */
+exports.SHIELD_TOKEN_GENERATOR = Symbol('SHIELD_TOKEN_GENERATOR');
+exports.SHIELD_REFRESH_HASHER = Symbol('SHIELD_REFRESH_HASHER');
+exports.SHIELD_CLOCK = Symbol('SHIELD_CLOCK');
+/**
+ * Opaque random-token minter (node:crypto `randomBytes`). 32 bytes = 256 bits of
+ * entropy, hex-encoded to a 64-char string (matches the CHAR(64) columns). The
+ * engine treats the result as opaque; it never parses it.
+ */
+class CryptoTokenGenerator {
+    byteLength;
+    constructor(byteLength = 32) {
+        this.byteLength = byteLength;
+    }
+    mint() {
+        // 256-bit unguessable token. Hex so it is URL/DB-safe and fixed-width.
+        return (0, node_crypto_1.randomBytes)(this.byteLength).toString('hex');
+    }
+}
+exports.CryptoTokenGenerator = CryptoTokenGenerator;
+/**
+ * Keyed HMAC-SHA-256 refresh-token hasher. Deterministic (same raw → same hash)
+ * so a lookup by hash matches, and keyed so an offline attacker with the DB but
+ * not the key cannot recompute hashes. Output is 64-char hex (CHAR(64)).
+ *
+ * ⛔ The `key` is a server secret (env/secrets-manager in prod). NEVER log the raw
+ * token or the key. A missing/empty key throws at construction (fail-closed: never
+ * silently downgrade to an unkeyed digest).
+ */
+class Sha256RefreshTokenHasher {
+    key;
+    constructor(key) {
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new Error('Sha256RefreshTokenHasher: a non-empty HMAC key is required (fail-closed — never unkeyed)');
+        }
+        this.key = Buffer.from(key, 'utf8');
+    }
+    hash(rawToken) {
+        // HMAC-SHA-256 → 64-char hex. Deterministic; never logs the input.
+        return (0, node_crypto_1.createHmac)('sha256', this.key).update(rawToken, 'utf8').digest('hex');
+    }
+}
+exports.Sha256RefreshTokenHasher = Sha256RefreshTokenHasher;
+/** The real clock (UTC epoch ms via `Date.now`). */
+class SystemClock {
+    nowMs() {
+        return Date.now();
+    }
+}
+exports.SystemClock = SystemClock;
+/** Provider factories for wiring the crypto/clock adapters into a Nest container. */
+function cryptoTokenGeneratorProvider(byteLength) {
+    return { provide: exports.SHIELD_TOKEN_GENERATOR, useValue: new CryptoTokenGenerator(byteLength) };
+}
+function refreshHasherProvider(key) {
+    return { provide: exports.SHIELD_REFRESH_HASHER, useValue: new Sha256RefreshTokenHasher(key) };
+}
+function systemClockProvider() {
+    return { provide: exports.SHIELD_CLOCK, useValue: new SystemClock() };
+}

package/dist/session/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@astram/guard` Session adapters barrel (ADR-0003 / ADR-0013).
+ *
+ * The concrete implementations of the Core Session PORTs — the real IO/crypto that
+ * keeps `@astram/core` zero-dep:
+ *   - {@link MariaDbSessionRecordStore} — durable session/refresh records (mariadb);
+ *   - {@link RedisHotSessionStore}      — hot per-request state (ioredis);
+ *   - {@link CryptoTokenGenerator}      — opaque token minter (node:crypto);
+ *   - {@link Sha256RefreshTokenHasher}  — keyed HMAC-SHA-256 refresh hasher;
+ *   - {@link SystemClock}               — real UTC clock.
+ *
+ * A consumer wires these + `createSessionAuthority(...)` from `@astram/core`.
+ */
+export { MariaDbSessionRecordStore, SHIELD_SESSION_RECORD_STORE, } from './mariadb-session-record-store.js';
+export { RedisHotSessionStore, SHIELD_HOT_SESSION_STORE, } from './redis-hot-session-store.js';
+export { CryptoTokenGenerator, Sha256RefreshTokenHasher, SystemClock, cryptoTokenGeneratorProvider, refreshHasherProvider, systemClockProvider, SHIELD_TOKEN_GENERATOR, SHIELD_REFRESH_HASHER, SHIELD_CLOCK, } from './crypto-adapters.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,WAAW,EACX,4BAA4B,EAC5B,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,GACb,MAAM,sBAAsB,CAAC"}

package/dist/session/index.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * `@astram/guard` Session adapters barrel (ADR-0003 / ADR-0013).
+ *
+ * The concrete implementations of the Core Session PORTs — the real IO/crypto that
+ * keeps `@astram/core` zero-dep:
+ *   - {@link MariaDbSessionRecordStore} — durable session/refresh records (mariadb);
+ *   - {@link RedisHotSessionStore}      — hot per-request state (ioredis);
+ *   - {@link CryptoTokenGenerator}      — opaque token minter (node:crypto);
+ *   - {@link Sha256RefreshTokenHasher}  — keyed HMAC-SHA-256 refresh hasher;
+ *   - {@link SystemClock}               — real UTC clock.
+ *
+ * A consumer wires these + `createSessionAuthority(...)` from `@astram/core`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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 = void 0;
+var mariadb_session_record_store_js_1 = require("./mariadb-session-record-store.js");
+Object.defineProperty(exports, "MariaDbSessionRecordStore", { enumerable: true, get: function () { return mariadb_session_record_store_js_1.MariaDbSessionRecordStore; } });
+Object.defineProperty(exports, "SHIELD_SESSION_RECORD_STORE", { enumerable: true, get: function () { return mariadb_session_record_store_js_1.SHIELD_SESSION_RECORD_STORE; } });
+var redis_hot_session_store_js_1 = require("./redis-hot-session-store.js");
+Object.defineProperty(exports, "RedisHotSessionStore", { enumerable: true, get: function () { return redis_hot_session_store_js_1.RedisHotSessionStore; } });
+Object.defineProperty(exports, "SHIELD_HOT_SESSION_STORE", { enumerable: true, get: function () { return redis_hot_session_store_js_1.SHIELD_HOT_SESSION_STORE; } });
+var crypto_adapters_js_1 = require("./crypto-adapters.js");
+Object.defineProperty(exports, "CryptoTokenGenerator", { enumerable: true, get: function () { return crypto_adapters_js_1.CryptoTokenGenerator; } });
+Object.defineProperty(exports, "Sha256RefreshTokenHasher", { enumerable: true, get: function () { return crypto_adapters_js_1.Sha256RefreshTokenHasher; } });
+Object.defineProperty(exports, "SystemClock", { enumerable: true, get: function () { return crypto_adapters_js_1.SystemClock; } });
+Object.defineProperty(exports, "cryptoTokenGeneratorProvider", { enumerable: true, get: function () { return crypto_adapters_js_1.cryptoTokenGeneratorProvider; } });
+Object.defineProperty(exports, "refreshHasherProvider", { enumerable: true, get: function () { return crypto_adapters_js_1.refreshHasherProvider; } });
+Object.defineProperty(exports, "systemClockProvider", { enumerable: true, get: function () { return crypto_adapters_js_1.systemClockProvider; } });
+Object.defineProperty(exports, "SHIELD_TOKEN_GENERATOR", { enumerable: true, get: function () { return crypto_adapters_js_1.SHIELD_TOKEN_GENERATOR; } });
+Object.defineProperty(exports, "SHIELD_REFRESH_HASHER", { enumerable: true, get: function () { return crypto_adapters_js_1.SHIELD_REFRESH_HASHER; } });
+Object.defineProperty(exports, "SHIELD_CLOCK", { enumerable: true, get: function () { return crypto_adapters_js_1.SHIELD_CLOCK; } });

package/dist/session/mariadb-session-record-store.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `MariaDbSessionRecordStore` — the concrete durable {@link SessionRecordStore}
+ * for `@astram/guard`, backed by the `mariadb` connector against the Layer-2
+ * `shield_identity`.`session` / `shield_identity`.`refresh_token` tables
+ * (infra/mariadb/init/20-session-tables.sql).
+ *
+ * ADR-0003 (why HERE, not Core): the `mariadb` driver is a real runtime
+ * dependency; Core defines only the PORT. This adapter is INJECTED into
+ * `createSessionAuthority({ recordStore })`.
+ *
+ * ADR-0013/0014: written/read ONLY at lifecycle events (login/refresh/logout/admin
+ * revoke) — the per-request hot path never calls this. It authenticates as the
+ * runtime `shield_core` account, which holds DML (no DDL) on `shield_identity` —
+ * the containment model is untouched.
+ *
+ * ⛔ SECURITY — only ever receives + persists a token HASH (never a raw token).
+ * `revokeLineage` is the reuse kill-switch: it revokes EVERY refresh record + the
+ * session in a lineage in one transaction.
+ */
+import type { Pool } from 'mariadb';
+import type { CreateSessionInput, InsertRefreshInput, RefreshTokenRecord, SessionRecord, SessionRecordStore } from '@astram/core';
+/** The DI token the store is bound under. */
+export declare const SHIELD_SESSION_RECORD_STORE: unique symbol;
+export declare class MariaDbSessionRecordStore implements SessionRecordStore {
+    private readonly pool;
+    constructor(pool: Pool);
+    createSession(input: CreateSessionInput): Promise<SessionRecord>;
+    insertRefreshRecord(input: InsertRefreshInput): Promise<RefreshTokenRecord>;
+    findRefreshByHash(tokenHash: string): Promise<RefreshTokenRecord | null>;
+    findSessionById(sessionId: string): Promise<SessionRecord | null>;
+    /**
+     * ⛔ ATOMIC ROTATION CLAIM (compare-and-set). The DB is the true arbiter: a
+     * conditional UPDATE that flips `active → rotated` ONLY when still active, and we
+     * return `affectedRows === 1` — exactly the caller that performed the transition.
+     * Under concurrency, two callers issue the same UPDATE; the storage engine
+     * serializes them, so ONE gets `affectedRows === 1` (the winner) and the other
+     * gets `0` (row already 'rotated' → loser). This makes rotation single-winner.
+     */
+    markRotatedIfActive(refreshId: string): Promise<boolean>;
+    markRevoked(refreshId: string): Promise<void>;
+    /**
+     * ⛔ THE REUSE KILL-SWITCH — atomically revoke EVERY refresh record AND the
+     * session in a lineage. One transaction so the kill is all-or-nothing.
+     */
+    revokeLineage(lineageId: string): Promise<void>;
+    revokeSession(sessionId: string): Promise<void>;
+    /** Run `fn` in a transaction, releasing the connection either way. */
+    private withTx;
+}
+//# sourceMappingURL=mariadb-session-record-store.d.ts.map

package/dist/session/mariadb-session-record-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-session-record-store.d.ts","sourceRoot":"","sources":["../../src/session/mariadb-session-record-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,SAAS,CAAC;AACpD,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAGtB,6CAA6C;AAC7C,eAAO,MAAM,2BAA2B,eAAwC,CAAC;AAmDjF,qBAAa,yBAA0B,YAAW,kBAAkB;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEjC,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAiBhE,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA4B3E,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IASxE,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IASvE;;;;;;;OAOG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASxD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD;;;OAGG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB/C,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAarD,sEAAsE;YACxD,MAAM;CAiBrB"}

package/dist/session/mariadb-session-record-store.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * `MariaDbSessionRecordStore` — the concrete durable {@link SessionRecordStore}
+ * for `@astram/guard`, backed by the `mariadb` connector against the Layer-2
+ * `shield_identity`.`session` / `shield_identity`.`refresh_token` tables
+ * (infra/mariadb/init/20-session-tables.sql).
+ *
+ * ADR-0003 (why HERE, not Core): the `mariadb` driver is a real runtime
+ * dependency; Core defines only the PORT. This adapter is INJECTED into
+ * `createSessionAuthority({ recordStore })`.
+ *
+ * ADR-0013/0014: written/read ONLY at lifecycle events (login/refresh/logout/admin
+ * revoke) — the per-request hot path never calls this. It authenticates as the
+ * runtime `shield_core` account, which holds DML (no DDL) on `shield_identity` —
+ * the containment model is untouched.
+ *
+ * ⛔ SECURITY — only ever receives + persists a token HASH (never a raw token).
+ * `revokeLineage` is the reuse kill-switch: it revokes EVERY refresh record + the
+ * session in a lineage in one transaction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbSessionRecordStore = exports.SHIELD_SESSION_RECORD_STORE = void 0;
+/** The DI token the store is bound under. */
+exports.SHIELD_SESSION_RECORD_STORE = Symbol('SHIELD_SESSION_RECORD_STORE');
+/** BIGINT columns can arrive as string; normalize to number safely. */
+function toNum(v) {
+    return typeof v === 'number' ? v : Number(v);
+}
+function mapSession(r) {
+    return {
+        sessionId: r.s_session_id,
+        principalId: r.s_principal_id,
+        tenantId: r.s_tenant_id,
+        status: r.s_status,
+        issuedAtMs: toNum(r.s_issued_at_ms),
+        absoluteExpiresAtMs: toNum(r.s_absolute_expires_at_ms),
+    };
+}
+function mapRefresh(r) {
+    return {
+        refreshId: r.rt_refresh_id,
+        sessionId: r.rt_session_id,
+        lineageId: r.rt_lineage_id,
+        prevRefreshId: r.rt_prev_refresh_id,
+        tokenHash: r.rt_token_hash,
+        status: r.rt_status,
+        issuedAtMs: toNum(r.rt_issued_at_ms),
+        idleExpiresAtMs: toNum(r.rt_idle_expires_at_ms),
+    };
+}
+class MariaDbSessionRecordStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async createSession(input) {
+        await this.pool.query(`INSERT INTO shield_identity.session
+         (s_session_id, s_principal_id, s_tenant_id, s_status, s_issued_at_ms, s_absolute_expires_at_ms)
+       VALUES (?, ?, ?, 'active', ?, ?)`, [input.sessionId, input.principalId, input.tenantId, input.issuedAtMs, input.absoluteExpiresAtMs]);
+        return {
+            sessionId: input.sessionId,
+            principalId: input.principalId,
+            tenantId: input.tenantId,
+            status: 'active',
+            issuedAtMs: input.issuedAtMs,
+            absoluteExpiresAtMs: input.absoluteExpiresAtMs,
+        };
+    }
+    async insertRefreshRecord(input) {
+        await this.pool.query(`INSERT INTO shield_identity.refresh_token
+         (rt_refresh_id, rt_session_id, rt_lineage_id, rt_prev_refresh_id,
+          rt_token_hash, rt_status, rt_issued_at_ms, rt_idle_expires_at_ms)
+       VALUES (?, ?, ?, ?, ?, 'active', ?, ?)`, [
+            input.refreshId,
+            input.sessionId,
+            input.lineageId,
+            input.prevRefreshId,
+            input.tokenHash, // ⛔ HASH only — never a raw token.
+            input.issuedAtMs,
+            input.idleExpiresAtMs,
+        ]);
+        return {
+            refreshId: input.refreshId,
+            sessionId: input.sessionId,
+            lineageId: input.lineageId,
+            prevRefreshId: input.prevRefreshId,
+            tokenHash: input.tokenHash,
+            status: 'active',
+            issuedAtMs: input.issuedAtMs,
+            idleExpiresAtMs: input.idleExpiresAtMs,
+        };
+    }
+    async findRefreshByHash(tokenHash) {
+        const rows = (await this.pool.query(`SELECT * FROM shield_identity.refresh_token WHERE rt_token_hash = ? LIMIT 1`, [tokenHash]));
+        const row = rows[0];
+        return row ? mapRefresh(row) : null;
+    }
+    async findSessionById(sessionId) {
+        const rows = (await this.pool.query(`SELECT * FROM shield_identity.session WHERE s_session_id = ? LIMIT 1`, [sessionId]));
+        const row = rows[0];
+        return row ? mapSession(row) : null;
+    }
+    /**
+     * ⛔ ATOMIC ROTATION CLAIM (compare-and-set). The DB is the true arbiter: a
+     * conditional UPDATE that flips `active → rotated` ONLY when still active, and we
+     * return `affectedRows === 1` — exactly the caller that performed the transition.
+     * Under concurrency, two callers issue the same UPDATE; the storage engine
+     * serializes them, so ONE gets `affectedRows === 1` (the winner) and the other
+     * gets `0` (row already 'rotated' → loser). This makes rotation single-winner.
+     */
+    async markRotatedIfActive(refreshId) {
+        const res = (await this.pool.query(`UPDATE shield_identity.refresh_token SET rt_status = 'rotated'
+       WHERE rt_refresh_id = ? AND rt_status = 'active'`, [refreshId]));
+        return res?.affectedRows === 1;
+    }
+    async markRevoked(refreshId) {
+        await this.pool.query(`UPDATE shield_identity.refresh_token SET rt_status = 'revoked'
+       WHERE rt_refresh_id = ?`, [refreshId]);
+    }
+    /**
+     * ⛔ THE REUSE KILL-SWITCH — atomically revoke EVERY refresh record AND the
+     * session in a lineage. One transaction so the kill is all-or-nothing.
+     */
+    async revokeLineage(lineageId) {
+        await this.withTx(async (conn) => {
+            await conn.query(`UPDATE shield_identity.refresh_token SET rt_status = 'revoked'
+         WHERE rt_lineage_id = ?`, [lineageId]);
+            await conn.query(`UPDATE shield_identity.session SET s_status = 'revoked'
+         WHERE s_session_id IN (
+           SELECT DISTINCT rt_session_id FROM shield_identity.refresh_token WHERE rt_lineage_id = ?
+         )`, [lineageId]);
+        });
+    }
+    async revokeSession(sessionId) {
+        await this.withTx(async (conn) => {
+            await conn.query(`UPDATE shield_identity.session SET s_status = 'revoked' WHERE s_session_id = ?`, [sessionId]);
+            await conn.query(`UPDATE shield_identity.refresh_token SET rt_status = 'revoked' WHERE rt_session_id = ?`, [sessionId]);
+        });
+    }
+    /** Run `fn` in a transaction, releasing the connection either way. */
+    async withTx(fn) {
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            await fn(conn);
+            await conn.commit();
+        }
+        catch (err) {
+            try {
+                await conn.rollback();
+            }
+            catch {
+                // rollback best-effort; surface the original error below.
+            }
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+    }
+}
+exports.MariaDbSessionRecordStore = MariaDbSessionRecordStore;

package/dist/session/redis-hot-session-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `RedisHotSessionStore` — the concrete hot {@link HotSessionStore} for
+ * `@astram/guard`, backed by `ioredis` against the Layer-2 Redis (ADR-0013 hot
+ * tier). Serves the per-request read path and is (re)populated at lifecycle events.
+ *
+ * ADR-0003 (why HERE, not Core): `ioredis` is a real runtime dependency; Core
+ * defines only the PORT. Injected into `createSessionAuthority({ hotStore })` and
+ * used by the free `readHotSession(hotStore, id)` per-request path.
+ *
+ * ⛔ THE CRITICAL CONTRACT (ADR-0013/0016): `getHotSession` MUST distinguish
+ *   - `{ kind: 'found', state }` — a live hot record,
+ *   - `{ kind: 'absent' }`       — Redis is UP and simply has no such key (a miss),
+ *   - `{ kind: 'unavailable' }`  — Redis CANNOT answer (down/timeout/refused).
+ * The engine fails CLOSED on `unavailable` and NEVER falls back to the durable
+ * tier. Conflating unavailable→absent would fail open on a blip; conflating
+ * absent→unavailable would log users out on a normal miss. So we catch connection
+ * errors and map ONLY those to `unavailable`; a clean `null` GET reply is `absent`.
+ */
+import type Redis from 'ioredis';
+import type { HotSessionOutcome, HotSessionState, HotSessionStore } from '@astram/core';
+/** The DI token the store is bound under. */
+export declare const SHIELD_HOT_SESSION_STORE: unique symbol;
+export declare class RedisHotSessionStore implements HotSessionStore {
+    private readonly redis;
+    constructor(redis: Redis);
+    putHotSession(key: string, state: HotSessionState, ttlMs: number): Promise<void>;
+    getHotSession(key: string): Promise<HotSessionOutcome>;
+    deleteHotSession(key: string): Promise<void>;
+}
+//# sourceMappingURL=redis-hot-session-store.d.ts.map

package/dist/session/redis-hot-session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-hot-session-store.d.ts","sourceRoot":"","sources":["../../src/session/redis-hot-session-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAExF,6CAA6C;AAC7C,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAgC3E,qBAAa,oBAAqB,YAAW,eAAe;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,KAAK;IAEnC,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOhF,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAyBtD,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQnD"}