@astram/guard 0.6.0 → 0.8.0

package/dist/secrets/encrypted-file-secrets.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptedFileSecretsProvider = void 0;
+/**
+ * `EncryptedFileSecretsProvider` — the reference {@link SecretsProvider} adapter (ADR-0032). An
+ * on-box secrets store where every secret is ENCRYPTED AT REST (AES-256-GCM under the box KEK, via
+ * the ADR-0031 `CryptoPort`), so the file on disk is ciphertext — not a plaintext `.env` password.
+ *
+ * This is the dev + air-gapped / single-box backend (what astram-infra's box uses). Vault / AWS
+ * Secrets Manager / GCP Secret Manager implement the SAME `SecretsProvider` and drop in later
+ * (Rule of Three) — no consumer change.
+ *
+ * SECURITY: never logs a secret value. `resolve` fails closed (throws SecretNotFoundError on an
+ * absent path — never returns ''). The store file is written 0600. The value is bound to its path
+ * as AEAD AAD, so a ciphertext for one path can't be replayed under another.
+ *
+ * Store format (JSON): { "<path>": { "version": n, "ciphertext": "<base64>" }, ... }
+ * The ciphertext is the CryptoPort AES-GCM sealing of the secret value, AAD = the secret path.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const core_1 = require("@astram/core");
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+class EncryptedFileSecretsProvider {
+    #file;
+    #crypto;
+    #dek;
+    /**
+     * @param file  path to the encrypted store file (created 0600 on first write).
+     * @param crypto  the ADR-0031 CryptoPort (AES-GCM); the SAME box KEK protects secrets + DEKs.
+     * @param dek  the data key used to encrypt secret values. Provisioned/managed by the caller (a
+     *   dedicated secrets DEK, wrapped by the KEK) — it is NEVER written to the store in plaintext.
+     */
+    constructor(file, crypto, dek) {
+        this.#file = file;
+        this.#crypto = crypto;
+        this.#dek = dek;
+    }
+    async resolve(path) {
+        const store = this.#read();
+        const entry = store[path];
+        if (!entry)
+            throw new core_1.SecretNotFoundError(path);
+        // AAD = path (bound), so a ciphertext moved to another path fails to decrypt.
+        const plain = await this.#crypto.decrypt(fromB64(entry.ciphertext), this.#dek, path);
+        return dec.decode(plain);
+    }
+    async store(path, value) {
+        return this.#write(path, value, /*rotate*/ false);
+    }
+    async rotate(path, newValue) {
+        return this.#write(path, newValue, /*rotate*/ true);
+    }
+    async currentVersion(path) {
+        return this.#read()[path]?.version ?? 0;
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    async #write(path, value, _rotate) {
+        const store = this.#read();
+        const ct = await this.#crypto.encrypt(enc.encode(value), this.#dek, path);
+        const version = (store[path]?.version ?? 0) + 1;
+        store[path] = { version, ciphertext: toB64(ct) };
+        this.#persist(store);
+        return version;
+    }
+    #read() {
+        if (!(0, node_fs_1.existsSync)(this.#file))
+            return {};
+        try {
+            const raw = (0, node_fs_1.readFileSync)(this.#file, 'utf8');
+            return raw.trim() === '' ? {} : JSON.parse(raw);
+        }
+        catch {
+            // A corrupt store must NOT silently become empty (that would erase secrets); fail loud.
+            throw new Error(`secrets store is unreadable/corrupt: ${this.#file}`);
+        }
+    }
+    #persist(store) {
+        const dir = (0, node_path_1.dirname)(this.#file);
+        if (!(0, node_fs_1.existsSync)(dir))
+            (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+        (0, node_fs_1.writeFileSync)(this.#file, JSON.stringify(store, null, 2), { mode: 0o600 });
+        try {
+            (0, node_fs_1.chmodSync)(this.#file, 0o600);
+        }
+        catch {
+            /* best-effort on platforms without chmod */
+        }
+    }
+}
+exports.EncryptedFileSecretsProvider = EncryptedFileSecretsProvider;
+function toB64(b) {
+    return Buffer.from(b).toString('base64');
+}
+function fromB64(s) {
+    return new Uint8Array(Buffer.from(s, 'base64'));
+}

package/dist/session/hot-revoking-session-record-store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `HotRevokingSessionRecordStore` — a decorator on `SHIELD_SESSION_RECORD_STORE`
+ * (security hardening M-A).
+ *
+ * WHY: core's `SessionAuthority` revokes through the durable store only — the refresh
+ * reuse-kill (`revokeLineage`) and the absolute-cap / logout path (`revokeSession`) mark
+ * MariaDB rows revoked, but the guard's per-request path reads Redis alone (invariant #12)
+ * and never consults MariaDB. Without this decorator a stolen-and-replayed refresh token
+ * kills the lineage durably while the live access token keeps working until its TTL.
+ *
+ * WHAT: after a durable revoke SUCCEEDS, unbind the affected sessions in Redis
+ * (`SessionTokenBinder.unbindSession` drops the session-claims liveness entry, so every
+ * access token of the session is denied on its next request). Durable first; a durable
+ * failure propagates and nothing is unbound. The Redis step is best-effort: a failure there
+ * never fails the durable revoke, and the exposure is bounded by the access TTL (#8).
+ *
+ * No core change: the port is decorated, not extended. The lineage → session lookup is a
+ * guard-side read on the durable adapter ({@link LineageSessionLookup}).
+ */
+import type { CreateSessionInput, InsertRefreshInput, RefreshTokenRecord, SessionRecord, SessionRecordStore } from '@astram/core';
+/** The Redis side of a revoke (the token binder implements it). */
+export interface SessionHotRevoker {
+    unbindSession(sessionId: string): Promise<void>;
+}
+/** Resolve the sessions a refresh lineage belongs to (a lifecycle-time durable read). */
+export interface LineageSessionLookup {
+    sessionIdsForLineage(lineageId: string): Promise<string[]>;
+}
+export declare class HotRevokingSessionRecordStore implements SessionRecordStore {
+    private readonly inner;
+    private readonly hot;
+    private readonly lineages;
+    constructor(inner: SessionRecordStore, hot: SessionHotRevoker, lineages: LineageSessionLookup);
+    createSession(input: CreateSessionInput): Promise<SessionRecord>;
+    insertRefreshRecord(input: InsertRefreshInput): Promise<RefreshTokenRecord>;
+    findRefreshByHash(tokenHash: string): Promise<RefreshTokenRecord | null>;
+    findSessionById(sessionId: string): Promise<SessionRecord | null>;
+    markRotatedIfActive(refreshId: string): Promise<boolean>;
+    markRevoked(refreshId: string): Promise<void>;
+    /** Durable lineage kill, then unbind every session of the lineage in Redis. */
+    revokeLineage(lineageId: string): Promise<void>;
+    /** Durable session revoke, then unbind it in Redis. */
+    revokeSession(sessionId: string): Promise<void>;
+    private unbind;
+}
+//# sourceMappingURL=hot-revoking-session-record-store.d.ts.map

package/dist/session/hot-revoking-session-record-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot-revoking-session-record-store.d.ts","sourceRoot":"","sources":["../../src/session/hot-revoking-session-record-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAEtB,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED,yFAAyF;AACzF,MAAM,WAAW,oBAAoB;IACnC,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5D;AAED,qBAAa,6BAA8B,YAAW,kBAAkB;IAEpE,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAFR,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,oBAAoB;IAGjD,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAIhE,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI3E,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAIxE,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAIjE,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,+EAA+E;IACzE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrD,uDAAuD;IACjD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAKvC,MAAM;CAOrB"}

package/dist/session/hot-revoking-session-record-store.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HotRevokingSessionRecordStore = void 0;
+class HotRevokingSessionRecordStore {
+    inner;
+    hot;
+    lineages;
+    constructor(inner, hot, lineages) {
+        this.inner = inner;
+        this.hot = hot;
+        this.lineages = lineages;
+    }
+    createSession(input) {
+        return this.inner.createSession(input);
+    }
+    insertRefreshRecord(input) {
+        return this.inner.insertRefreshRecord(input);
+    }
+    findRefreshByHash(tokenHash) {
+        return this.inner.findRefreshByHash(tokenHash);
+    }
+    findSessionById(sessionId) {
+        return this.inner.findSessionById(sessionId);
+    }
+    markRotatedIfActive(refreshId) {
+        return this.inner.markRotatedIfActive(refreshId);
+    }
+    markRevoked(refreshId) {
+        return this.inner.markRevoked(refreshId);
+    }
+    /** Durable lineage kill, then unbind every session of the lineage in Redis. */
+    async revokeLineage(lineageId) {
+        await this.inner.revokeLineage(lineageId);
+        let sessionIds = [];
+        try {
+            sessionIds = await this.lineages.sessionIdsForLineage(lineageId);
+        }
+        catch {
+            return; // best-effort: bounded by the access TTL (#8).
+        }
+        for (const sessionId of sessionIds)
+            await this.unbind(sessionId);
+    }
+    /** Durable session revoke, then unbind it in Redis. */
+    async revokeSession(sessionId) {
+        await this.inner.revokeSession(sessionId);
+        await this.unbind(sessionId);
+    }
+    async unbind(sessionId) {
+        try {
+            await this.hot.unbindSession(sessionId);
+        }
+        catch {
+            // best-effort: never fail a durable revoke on a Redis blip.
+        }
+    }
+}
+exports.HotRevokingSessionRecordStore = HotRevokingSessionRecordStore;

package/dist/session/index.d.ts

@@ -12,6 +12,8 @@
  * 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 { RedisHotSessionStore, SHIELD_HOT_SESSION_STORE } from './redis-hot-session-store.js';
+export { HotRevokingSessionRecordStore, type SessionHotRevoker, type LineageSessionLookup, } from './hot-revoking-session-record-store.js';
+export { SHIELD_SESSION_LIFETIMES, ROTATE_GRACE_MS, DEFAULT_ACCESS_TTL_MS, accessBindingTtlMs, } from './session-lifetimes.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

@@ -1 +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"}
+{"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,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAE9F,OAAO,EACL,6BAA6B,EAC7B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAEhC,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

@@ -13,13 +13,20 @@
  * 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;
+exports.SHIELD_CLOCK = exports.SHIELD_REFRESH_HASHER = exports.SHIELD_TOKEN_GENERATOR = exports.systemClockProvider = exports.refreshHasherProvider = exports.cryptoTokenGeneratorProvider = exports.SystemClock = exports.Sha256RefreshTokenHasher = exports.CryptoTokenGenerator = exports.accessBindingTtlMs = exports.DEFAULT_ACCESS_TTL_MS = exports.ROTATE_GRACE_MS = exports.SHIELD_SESSION_LIFETIMES = exports.HotRevokingSessionRecordStore = 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 hot_revoking_session_record_store_js_1 = require("./hot-revoking-session-record-store.js");
+Object.defineProperty(exports, "HotRevokingSessionRecordStore", { enumerable: true, get: function () { return hot_revoking_session_record_store_js_1.HotRevokingSessionRecordStore; } });
+var session_lifetimes_js_1 = require("./session-lifetimes.js");
+Object.defineProperty(exports, "SHIELD_SESSION_LIFETIMES", { enumerable: true, get: function () { return session_lifetimes_js_1.SHIELD_SESSION_LIFETIMES; } });
+Object.defineProperty(exports, "ROTATE_GRACE_MS", { enumerable: true, get: function () { return session_lifetimes_js_1.ROTATE_GRACE_MS; } });
+Object.defineProperty(exports, "DEFAULT_ACCESS_TTL_MS", { enumerable: true, get: function () { return session_lifetimes_js_1.DEFAULT_ACCESS_TTL_MS; } });
+Object.defineProperty(exports, "accessBindingTtlMs", { enumerable: true, get: function () { return session_lifetimes_js_1.accessBindingTtlMs; } });
 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; } });

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

@@ -43,6 +43,12 @@ export declare class MariaDbSessionRecordStore implements SessionRecordStore {
      * session in a lineage. One transaction so the kill is all-or-nothing.
      */
     revokeLineage(lineageId: string): Promise<void>;
+    /**
+     * The session ids a refresh lineage belongs to (normally exactly one). Read at a
+     * lifecycle event (after a reuse-kill) by `HotRevokingSessionRecordStore` to unbind
+     * those sessions in Redis — never on the per-request path.
+     */
+    sessionIdsForLineage(lineageId: string): Promise<string[]>;
     revokeSession(sessionId: string): Promise<void>;
     /** Run `fn` in a transaction, releasing the connection either way. */
     private withTx;

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

@@ -1 +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"}
+{"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;IAuBhE,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;IAiBrD;;;;OAIG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ1D,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAarD,sEAAsE;YACxD,MAAM;CAiBrB"}

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

@@ -56,7 +56,13 @@ class MariaDbSessionRecordStore {
     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]);
+       VALUES (?, ?, ?, 'active', ?, ?)`, [
+            input.sessionId,
+            input.principalId,
+            input.tenantId,
+            input.issuedAtMs,
+            input.absoluteExpiresAtMs,
+        ]);
         return {
             sessionId: input.sessionId,
             principalId: input.principalId,
@@ -131,6 +137,15 @@ class MariaDbSessionRecordStore {
          )`, [lineageId]);
         });
     }
+    /**
+     * The session ids a refresh lineage belongs to (normally exactly one). Read at a
+     * lifecycle event (after a reuse-kill) by `HotRevokingSessionRecordStore` to unbind
+     * those sessions in Redis — never on the per-request path.
+     */
+    async sessionIdsForLineage(lineageId) {
+        const rows = (await this.pool.query(`SELECT DISTINCT rt_session_id FROM shield_identity.refresh_token WHERE rt_lineage_id = ?`, [lineageId]));
+        return rows.map((r) => r.rt_session_id);
+    }
     async revokeSession(sessionId) {
         await this.withTx(async (conn) => {
             await conn.query(`UPDATE shield_identity.session SET s_status = 'revoked' WHERE s_session_id = ?`, [sessionId]);

package/dist/session/session-lifetimes.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The ONE place the guard reads the resolved session lifetimes (ADR-0015) and derives the
+ * Redis binding TTLs from them (security hardening #8, plan decision D7).
+ *
+ *  - {@link SHIELD_SESSION_LIFETIMES} — the resolved, validated {@link SessionLifetimeConfig}
+ *    (core `resolveLifetimes(config.lifetimes)`). The composed `SessionAuthority`, the token
+ *    binder and the auth controller all read this one value, so the lifetime maths is never
+ *    duplicated or allowed to drift.
+ *  - {@link accessBindingTtlMs} — the access-token binding TTL:
+ *    `clamp(session.expiresAtMs − now, 1, accessTtlMs)`. Used on login AND refresh. The old
+ *    refresh formula (`expiresAtMs − issuedAtMs`) grew with the session's age, so a token
+ *    minted on day 10 lived ~10 days.
+ *  - {@link ROTATE_GRACE_MS} — how long the PREVIOUS access token stays bound after a
+ *    refresh rotates it (in-flight requests are not cut off), then it expires.
+ */
+import type { SessionLifetimeConfig } from '@astram/core';
+/** DI token for the resolved {@link SessionLifetimeConfig}. */
+export declare const SHIELD_SESSION_LIFETIMES: unique symbol;
+/** ADR-0015 default access-token TTL — the fallback when no lifetimes are injected. */
+export declare const DEFAULT_ACCESS_TTL_MS: number;
+/** Grace for the previous access token after a refresh rotates it (plan decision D7). */
+export declare const ROTATE_GRACE_MS = 30000;
+/**
+ * The access-binding TTL: the time left until the session's access expiry, never below
+ * 1 ms and never above the configured access TTL. A non-finite input collapses to 1 ms
+ * (fail closed: the binding expires immediately rather than living indefinitely).
+ */
+export declare function accessBindingTtlMs(sessionExpiresAtMs: number, nowMs: number, accessTtlMs: number): number;
+export type { SessionLifetimeConfig };
+//# sourceMappingURL=session-lifetimes.d.ts.map

package/dist/session/session-lifetimes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lifetimes.d.ts","sourceRoot":"","sources":["../../src/session/session-lifetimes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,+DAA+D;AAC/D,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAEpD,yFAAyF;AACzF,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,MAAM,EAC1B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR;AAED,YAAY,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/session/session-lifetimes.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROTATE_GRACE_MS = exports.DEFAULT_ACCESS_TTL_MS = exports.SHIELD_SESSION_LIFETIMES = void 0;
+exports.accessBindingTtlMs = accessBindingTtlMs;
+/** DI token for the resolved {@link SessionLifetimeConfig}. */
+exports.SHIELD_SESSION_LIFETIMES = Symbol('SHIELD_SESSION_LIFETIMES');
+/** ADR-0015 default access-token TTL — the fallback when no lifetimes are injected. */
+exports.DEFAULT_ACCESS_TTL_MS = 15 * 60 * 1000;
+/** Grace for the previous access token after a refresh rotates it (plan decision D7). */
+exports.ROTATE_GRACE_MS = 30_000;
+/**
+ * The access-binding TTL: the time left until the session's access expiry, never below
+ * 1 ms and never above the configured access TTL. A non-finite input collapses to 1 ms
+ * (fail closed: the binding expires immediately rather than living indefinitely).
+ */
+function accessBindingTtlMs(sessionExpiresAtMs, nowMs, accessTtlMs) {
+    const remaining = Math.floor(sessionExpiresAtMs - nowMs);
+    if (!Number.isFinite(remaining) || !Number.isFinite(accessTtlMs))
+        return 1;
+    return Math.min(Math.max(remaining, 1), Math.max(Math.floor(accessTtlMs), 1));
+}

package/dist/session/session-restriction-store.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Durable session restrictions (security hardening Phase 3 part B review P1, ADR-0035 §3).
+ *
+ * The refresh-time silent recovery rebuilds a lost Redis binding from DURABLE state. It must never
+ * mint more authority than the session had, so two facts that used to live only in Redis are read
+ * from MariaDB here:
+ *  - the session's RE-ENROLL restriction (`shield_identity.session.s_must_reenroll`, identity
+ *    migration 1710000000019): set at a recovery-code login, cleared when a fresh MFA device is
+ *    confirmed. A restricted session rebuilds `mustReenroll: true` and never root;
+ *  - the ACCOUNT STATUS (`shield_app.users.u_status`, the identity org table the default profile
+ *    resolver already reads): disabling a user does not revoke its sessions, so a disabled user
+ *    gets no rebuild.
+ *
+ * Lifecycle-time reads only (login, refresh rebuild, device confirm) — never on the request path.
+ * Every read error propagates: the caller fails closed.
+ */
+import type { Pool } from 'mariadb';
+/** What the refresh rebuild needs to know about a session and its principal. */
+export interface SessionRebuildFacts {
+    /** The session was opened by a recovery-code login and is not yet re-secured. */
+    readonly mustReenroll: boolean;
+    /**
+     * `false` when the principal's account row exists and is not `active`. `true` when it is active
+     * or when no `shield_app.users` table exists (a guard-only app that keeps users elsewhere).
+     */
+    readonly accountActive: boolean;
+}
+export interface SessionRestrictionStore {
+    /** Persist the re-enroll restriction on the durable session (recovery-code login). Throws on error. */
+    markMustReenroll(sessionId: string): Promise<void>;
+    /** Lift it (a fresh device was confirmed). Throws on error. */
+    clearMustReenroll(sessionId: string): Promise<void>;
+    /** Read the restriction + account status for a rebuild. Throws on error (→ no rebuild). */
+    rebuildFacts(sessionId: string, principalId: string): Promise<SessionRebuildFacts>;
+}
+export declare class MariaDbSessionRestrictionStore implements SessionRestrictionStore {
+    private readonly pool;
+    constructor(pool: Pool);
+    markMustReenroll(sessionId: string): Promise<void>;
+    clearMustReenroll(sessionId: string): Promise<void>;
+    rebuildFacts(sessionId: string, principalId: string): Promise<SessionRebuildFacts>;
+}
+//# sourceMappingURL=session-restriction-store.d.ts.map

package/dist/session/session-restriction-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-restriction-store.d.ts","sourceRoot":"","sources":["../../src/session/session-restriction-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,uGAAuG;IACvG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,+DAA+D;IAC/D,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,2FAA2F;IAC3F,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACpF;AAKD,qBAAa,8BAA+B,YAAW,uBAAuB;IAChE,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEjC,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlD,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAqBzF"}

package/dist/session/session-restriction-store.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbSessionRestrictionStore = void 0;
+/** MariaDB `ER_NO_SUCH_TABLE`. */
+const ER_NO_SUCH_TABLE = 1146;
+class MariaDbSessionRestrictionStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async markMustReenroll(sessionId) {
+        await this.pool.query('UPDATE `shield_identity`.`session` SET s_must_reenroll = 1 WHERE s_session_id = ?', [sessionId]);
+    }
+    async clearMustReenroll(sessionId) {
+        await this.pool.query('UPDATE `shield_identity`.`session` SET s_must_reenroll = 0 WHERE s_session_id = ?', [sessionId]);
+    }
+    async rebuildFacts(sessionId, principalId) {
+        const rows = (await this.pool.query('SELECT s_must_reenroll FROM `shield_identity`.`session` WHERE s_session_id = ? LIMIT 1', [sessionId]));
+        // No row → treat as restricted (the caller also re-reads the session and refuses a missing one).
+        const mustReenroll = rows[0] === undefined || Number(rows[0].s_must_reenroll) !== 0;
+        let accountActive = true;
+        try {
+            const users = (await this.pool.query('SELECT u_status FROM `shield_app`.`users` WHERE u_uuid = ? LIMIT 1', [principalId]));
+            if (users[0] !== undefined)
+                accountActive = users[0].u_status === 'active';
+        }
+        catch (err) {
+            // Only an absent org table means "this app keeps no users here"; any other error fails closed.
+            if (err.errno !== ER_NO_SUCH_TABLE)
+                throw err;
+        }
+        return { mustReenroll, accountActive };
+    }
+}
+exports.MariaDbSessionRestrictionStore = MariaDbSessionRestrictionStore;

package/migrations/1710000000017-CreateServiceAccountKey.cjs

@@ -0,0 +1,41 @@
+/**
+ * Framework authz migration — `shield_authz.service_account_key`: the HASH-ONLY store of
+ * service-account API keys (ADR-0033). One row = one KEY VERSION of one service account; the
+ * account presents `ask_<sak_account_id>_<secret>` and the engine verifies `<secret>` against
+ * `sak_secret_hash` (Argon2id) — the raw secret is NEVER stored, logged, or re-fetchable.
+ *
+ * This table is the physical backing of `packages/guard/src/authentication/mariadb-api-key-store.ts`
+ * (`MariaDbApiKeyStore`): its columns MUST match that adapter's SELECT/INSERT/UPDATE EXACTLY
+ * (rule 30 — the store is the source of truth). Rotation INSERTs a new `(account, version)` row;
+ * `getByAccountId` returns the highest version; `revoke` stamps `sak_revoked_at_ms` on all of an
+ * account's rows. A revoked/expired key fails closed at authenticate time.
+ *
+ * Schema `shield_authz` is created by `1710000000006-CreateAuthzSchema.cjs` — NOT recreated here.
+ * Idempotent (CREATE TABLE IF NOT EXISTS). No hard-coded UUIDs, no seed (keys are admin-issued).
+ * `down` drops the table. Run by the DDL account.
+ */
+
+const SCHEMA = 'shield_authz';
+
+async function up({ query }) {
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`service_account_key\` (
+    sak_account_id     VARCHAR(36)  NOT NULL,          -- the <accountId> inside the ask_ key (= service_account.sa_id)
+    sak_version        INT          NOT NULL,          -- monotonic per account; rotation bumps it
+    sak_tenant_id      VARCHAR(36)  NOT NULL,          -- server-stamped; tenant the key is bound to
+    sak_scope_subtree  JSON         NOT NULL,          -- reachable node ids for the key's Principal (least privilege)
+    sak_role_ids       JSON         NOT NULL,          -- roles the key's Principal holds
+    sak_secret_hash    VARCHAR(255) NOT NULL,          -- Argon2id hash of the secret — NEVER the plaintext
+    sak_expires_at_ms  BIGINT       NULL,              -- absolute expiry (epoch-ms); NULL = non-expiring (discouraged)
+    sak_revoked_at_ms  BIGINT       NULL,              -- set on revoke (epoch-ms); a revoked key fails closed
+    sak_created_at_ms  BIGINT       NOT NULL,          -- issue time (epoch-ms)
+    PRIMARY KEY (sak_account_id, sak_version),
+    INDEX idx_sak_account (sak_account_id),
+    INDEX idx_sak_tenant (sak_tenant_id)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`service_account_key\``);
+}
+
+module.exports = { up, down };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guard",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "MIT",
   "description": "Astram framework — the enforcement guard + real-world adapters (the 'hands'). One global deny-by-default gate every request passes through (ADR-0002), classification decorators, boot-pool assertion (ADR-0018), the forRoot() registration seam, and the DB/Redis/crypto adapters that connect the sealed core to a real backend. Depends on @astram/core (ADR-0003, ADR-0023).",
   "type": "commonjs",
@@ -24,8 +24,8 @@
     "argon2": "^0.41.1",
     "ioredis": "^5.4.1",
     "mariadb": "^3.4.0",
-    "@astram/engine": "0.2.0",
-    "@astram/core": "1.2.0"
+    "@astram/core": "1.4.0",
+    "@astram/engine": "0.4.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",