@astram/guard 0.13.0 → 0.15.0

package/dist/secrets/boot-secrets.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBootSecrets = resolveBootSecrets;
+exports.wasResolvedFromSecretRef = wasResolvedFromSecretRef;
+exports.createSecretsProviderFromEnv = createSecretsProviderFromEnv;
+exports.assertNoUnresolvedSecretRefs = assertNoUnresolvedSecretRefs;
+/**
+ * Boot-time `secret-ref:` resolution (ADR-0032; FILE_STORAGE SPEC §5 L-N, §13).
+ *
+ * - {@link resolveBootSecrets}: called first in the app's `main.ts`, before `AppModule` is loaded,
+ *   so every `forRoot` and direct env reader sees resolved values. Resolves every `secret-ref:` env
+ *   value via core `resolveSecretRefs` and writes the results back into `process.env` for those
+ *   keys only, and only once every reference has resolved (no partial write-back).
+ * - {@link createSecretsProviderFromEnv}: builds the configured {@link SecretsProvider} from the
+ *   `SECRETS_*` variables (`none` | `encrypted-file`; `vault` reserved).
+ * - {@link assertNoUnresolvedSecretRefs}: synchronous backstop at every `loadAppConfig()` call site.
+ *
+ * SECURITY (Shield #1, #10): fail closed on every bad variable, file, key or reference. Errors name
+ * env variable names (and, for a failed resolution, the reference path); never a value, a key
+ * byte or file contents. Nothing is logged.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const core_1 = require("@astram/core");
+const local_kek_crypto_js_1 = require("../encryption/local-kek-crypto.js");
+const encrypted_file_secrets_js_1 = require("./encrypted-file-secrets.js");
+/** AEAD additional data the secrets DEK is wrapped under. */
+const SECRETS_DEK_AAD = 'shield:secrets';
+const KEK_BYTES = 32;
+/** Env keys whose value is still a `secret-ref:` reference. */
+function refKeys(env) {
+    return Object.keys(env).filter((k) => (0, core_1.isSecretRef)(env[k]));
+}
+/**
+ * Resolve every `secret-ref:` value in `process.env` in place. No references and no provider
+ * configured: no-op. Idempotent (a second call finds no references).
+ */
+async function resolveBootSecrets(options = {}) {
+    const env = process.env;
+    const provider = options.provider ?? createSecretsProviderFromEnv(env);
+    const keys = refKeys(env);
+    if (keys.length === 0)
+        return;
+    if (!provider) {
+        throw new Error(`secret-ref: values are set but no secrets provider is configured ` +
+            `(SECRETS_PROVIDER is unset or 'none'); env keys: ${keys.join(', ')}`);
+    }
+    // Core resolves into a NEW bag and throws on the first failure (key + path, never a value),
+    // so process.env is only touched once every reference has resolved.
+    const resolved = await (0, core_1.resolveSecretRefs)(env, provider);
+    for (const key of keys) {
+        const value = resolved[key];
+        env[key] = value;
+        if (value !== undefined)
+            resolvedFromRef.set(key, fingerprint(value));
+    }
+}
+/**
+ * Env key -> keyed fingerprint of the value {@link resolveBootSecrets} wrote for it. The value
+ * itself is never kept: an HMAC-SHA256 under a random per-process key (so the fingerprint cannot
+ * be checked against guesses outside this process).
+ */
+const resolvedFromRef = new Map();
+const FINGERPRINT_KEY = (0, node_crypto_1.randomBytes)(32);
+function fingerprint(value) {
+    return (0, node_crypto_1.createHmac)('sha256', FINGERPRINT_KEY).update(value, 'utf8').digest('hex');
+}
+/**
+ * `true` when `key`'s CURRENT value in `env` (default `process.env`) is the value
+ * {@link resolveBootSecrets} resolved from a `secret-ref:` at boot (FILE_STORAGE SPEC §5 F:
+ * credentials outside development/test must be references, never literals). A value changed
+ * after resolution (e.g. a literal written over it) is `false`. No value is kept, only a keyed
+ * fingerprint.
+ */
+function wasResolvedFromSecretRef(key, env = process.env) {
+    const recorded = resolvedFromRef.get(key);
+    const current = env[key];
+    if (recorded === undefined || typeof current !== 'string')
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(Buffer.from(recorded, 'hex'), Buffer.from(fingerprint(current), 'hex'));
+}
+/**
+ * Build the {@link SecretsProvider} named by `SECRETS_PROVIDER`. Returns `undefined` for `none`
+ * or unset. Throws (naming the variable only) on an unknown value, `vault`, an unset, missing or
+ * unreadable file, a corrupt store, a KEK that is not 32 bytes, or a DEK that does not unwrap
+ * under the KEK.
+ */
+function createSecretsProviderFromEnv(env) {
+    const kind = (env.SECRETS_PROVIDER ?? '').trim();
+    if (kind === '' || kind === 'none')
+        return undefined;
+    if (kind === 'vault') {
+        throw new Error(`SECRETS_PROVIDER 'vault' is not supported yet (use 'none' or 'encrypted-file')`);
+    }
+    if (kind !== 'encrypted-file') {
+        throw new Error(`SECRETS_PROVIDER has an unknown value (expected 'none' or 'encrypted-file')`);
+    }
+    const storeFile = requirePath(env, 'SECRETS_FILE');
+    const kekFile = requirePath(env, 'SECRETS_KEK_FILE');
+    const dekFile = requirePath(env, 'SECRETS_DEK_FILE');
+    // SPEC §13: a missing, unreadable or corrupt store aborts boot naming SECRETS_FILE, even when
+    // no env value references it yet (a misconfigured provider is never silently empty).
+    checkStoreFile(storeFile);
+    const kek = readKeyFile(kekFile, 'SECRETS_KEK_FILE');
+    if (kek.length !== KEK_BYTES) {
+        throw new Error(`SECRETS_KEK_FILE must hold exactly ${KEK_BYTES} raw bytes`);
+    }
+    const crypto = new local_kek_crypto_js_1.LocalKekCrypto(new Uint8Array(kek));
+    kek.fill(0);
+    const wrapped = readKeyFile(dekFile, 'SECRETS_DEK_FILE');
+    let dek;
+    try {
+        dek = crypto.unwrapDekSync(new Uint8Array(wrapped), SECRETS_DEK_AAD);
+    }
+    catch {
+        throw new Error(`SECRETS_DEK_FILE could not be unwrapped with the key in SECRETS_KEK_FILE ` +
+            `(wrong KEK, wrong wrap context or a corrupt file)`);
+    }
+    return new encrypted_file_secrets_js_1.EncryptedFileSecretsProvider(storeFile, crypto, dek);
+}
+/**
+ * Synchronous backstop: throws if any env value still starts with `secret-ref:` (the app did not
+ * call {@link resolveBootSecrets} before building modules). Lists env key names only.
+ */
+function assertNoUnresolvedSecretRefs(env) {
+    const keys = refKeys(env);
+    if (keys.length === 0)
+        return;
+    throw new Error(`unresolved secret references in env keys: ${keys.join(', ')}. ` +
+        `Call resolveBootSecrets() in main.ts before loading AppModule.`);
+}
+function requirePath(env, name) {
+    const value = env[name]?.trim();
+    if (!value)
+        throw new Error(`${name} must be set when SECRETS_PROVIDER is 'encrypted-file'`);
+    return value;
+}
+/**
+ * The store must exist, be readable and hold a JSON object of `{ version, ciphertext }` entries
+ * (an empty file is an empty store). Errors name `SECRETS_FILE` and an errno code only, never
+ * the path's contents.
+ */
+function checkStoreFile(path) {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(path, 'utf8');
+    }
+    catch (e) {
+        const code = e.code;
+        throw new Error(`SECRETS_FILE could not be read${code ? ` (${code})` : ''}`);
+    }
+    if (raw.trim() === '')
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        parsed = undefined;
+    }
+    const isEntry = (v) => typeof v === 'object' &&
+        v !== null &&
+        Number.isInteger(v.version) &&
+        typeof v.ciphertext === 'string';
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        Array.isArray(parsed) ||
+        !Object.values(parsed).every(isEntry)) {
+        throw new Error('SECRETS_FILE is not a valid secrets store (corrupt or wrong format)');
+    }
+}
+function readKeyFile(path, name) {
+    try {
+        return (0, node_fs_1.readFileSync)(path);
+    }
+    catch (e) {
+        const code = e.code;
+        throw new Error(`${name} could not be read${code ? ` (${code})` : ''}`);
+    }
+}

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

@@ -19,11 +19,18 @@
  */
 import type { Pool } from 'mariadb';
 import type { CreateSessionInput, InsertRefreshInput, RefreshTokenRecord, SessionRecord, SessionRecordStore } from '@astram/core';
+import { type FrameworkSchemaNames } from '../config/framework-schema-names.js';
 /** 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);
+    /** `<identity>`.`session`, resolved at construction (lifecycle writes only, ADR-0013). */
+    private readonly sessionTable;
+    /** `<identity>`.`refresh_token`. */
+    private readonly refreshTable;
+    constructor(pool: Pool, 
+    /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
+    schemas?: FrameworkSchemaNames);
     createSession(input: CreateSessionInput): Promise<SessionRecord>;
     insertRefreshRecord(input: InsertRefreshInput): Promise<RefreshTokenRecord>;
     findRefreshByHash(tokenHash: string): Promise<RefreshTokenRecord | null>;

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;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"}
+{"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;AAEtB,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,qCAAqC,CAAC;AAE7C,6CAA6C;AAC7C,eAAO,MAAM,2BAA2B,eAAwC,CAAC;AAmDjF,qBAAa,yBAA0B,YAAW,kBAAkB;IAOhE,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,oCAAoC;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGnB,IAAI,EAAE,IAAI;IAC3B,yFAAyF;IACzF,OAAO,CAAC,EAAE,oBAAoB;IAO1B,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

@@ -20,6 +20,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MariaDbSessionRecordStore = exports.SHIELD_SESSION_RECORD_STORE = void 0;
+const framework_schema_names_js_1 = require("../config/framework-schema-names.js");
 /** 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. */
@@ -50,11 +51,20 @@ function mapRefresh(r) {
 }
 class MariaDbSessionRecordStore {
     pool;
-    constructor(pool) {
+    /** `<identity>`.`session`, resolved at construction (lifecycle writes only, ADR-0013). */
+    sessionTable;
+    /** `<identity>`.`refresh_token`. */
+    refreshTable;
+    constructor(pool, 
+    /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
+    schemas) {
         this.pool = pool;
+        const identity = (0, framework_schema_names_js_1.schemaNamesAtConstruction)(schemas).identity;
+        this.sessionTable = (0, framework_schema_names_js_1.qualifiedTableName)(identity, 'session');
+        this.refreshTable = (0, framework_schema_names_js_1.qualifiedTableName)(identity, 'refresh_token');
     }
     async createSession(input) {
-        await this.pool.query(`INSERT INTO shield_identity.session
+        await this.pool.query(`INSERT INTO ${this.sessionTable}
          (s_session_id, s_principal_id, s_tenant_id, s_status, s_issued_at_ms, s_absolute_expires_at_ms)
        VALUES (?, ?, ?, 'active', ?, ?)`, [
             input.sessionId,
@@ -73,7 +83,7 @@ class MariaDbSessionRecordStore {
         };
     }
     async insertRefreshRecord(input) {
-        await this.pool.query(`INSERT INTO shield_identity.refresh_token
+        await this.pool.query(`INSERT INTO ${this.refreshTable}
          (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', ?, ?)`, [
@@ -97,12 +107,12 @@ class MariaDbSessionRecordStore {
         };
     }
     async findRefreshByHash(tokenHash) {
-        const rows = (await this.pool.query(`SELECT * FROM shield_identity.refresh_token WHERE rt_token_hash = ? LIMIT 1`, [tokenHash]));
+        const rows = (await this.pool.query(`SELECT * FROM ${this.refreshTable} 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 rows = (await this.pool.query(`SELECT * FROM ${this.sessionTable} WHERE s_session_id = ? LIMIT 1`, [sessionId]));
         const row = rows[0];
         return row ? mapSession(row) : null;
     }
@@ -115,12 +125,12 @@ class MariaDbSessionRecordStore {
      * 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'
+        const res = (await this.pool.query(`UPDATE ${this.refreshTable} 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'
+        await this.pool.query(`UPDATE ${this.refreshTable} SET rt_status = 'revoked'
        WHERE rt_refresh_id = ?`, [refreshId]);
     }
     /**
@@ -129,11 +139,11 @@ class MariaDbSessionRecordStore {
      */
     async revokeLineage(lineageId) {
         await this.withTx(async (conn) => {
-            await conn.query(`UPDATE shield_identity.refresh_token SET rt_status = 'revoked'
+            await conn.query(`UPDATE ${this.refreshTable} SET rt_status = 'revoked'
          WHERE rt_lineage_id = ?`, [lineageId]);
-            await conn.query(`UPDATE shield_identity.session SET s_status = 'revoked'
+            await conn.query(`UPDATE ${this.sessionTable} SET s_status = 'revoked'
          WHERE s_session_id IN (
-           SELECT DISTINCT rt_session_id FROM shield_identity.refresh_token WHERE rt_lineage_id = ?
+           SELECT DISTINCT rt_session_id FROM ${this.refreshTable} WHERE rt_lineage_id = ?
          )`, [lineageId]);
         });
     }
@@ -143,13 +153,13 @@ class MariaDbSessionRecordStore {
      * 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]));
+        const rows = (await this.pool.query(`SELECT DISTINCT rt_session_id FROM ${this.refreshTable} 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]);
-            await conn.query(`UPDATE shield_identity.refresh_token SET rt_status = 'revoked' WHERE rt_session_id = ?`, [sessionId]);
+            await conn.query(`UPDATE ${this.sessionTable} SET s_status = 'revoked' WHERE s_session_id = ?`, [sessionId]);
+            await conn.query(`UPDATE ${this.refreshTable} SET rt_status = 'revoked' WHERE rt_session_id = ?`, [sessionId]);
         });
     }
     /** Run `fn` in a transaction, releasing the connection either way. */

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

@@ -15,6 +15,7 @@
  * Every read error propagates: the caller fails closed.
  */
 import type { Pool } from 'mariadb';
+import { type FrameworkSchemaNames } from '../config/framework-schema-names.js';
 /** 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. */
@@ -35,7 +36,13 @@ export interface SessionRestrictionStore {
 }
 export declare class MariaDbSessionRestrictionStore implements SessionRestrictionStore {
     private readonly pool;
-    constructor(pool: Pool);
+    /** `<identity>`.`session`. */
+    private readonly sessionTable;
+    /** `<app>`.`users`. */
+    private readonly usersTable;
+    constructor(pool: Pool, 
+    /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
+    schemas?: FrameworkSchemaNames);
     markMustReenroll(sessionId: string): Promise<void>;
     clearMustReenroll(sessionId: string): Promise<void>;
     rebuildFacts(sessionId: string, principalId: string): Promise<SessionRebuildFacts>;

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

@@ -1 +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"}
+{"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;AACpC,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,qCAAqC,CAAC;AAE7C,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;IAO1E,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB,8BAA8B;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,uBAAuB;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGjB,IAAI,EAAE,IAAI;IAC3B,yFAAyF;IACzF,OAAO,CAAC,EAAE,oBAAoB;IAO1B,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

@@ -1,26 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MariaDbSessionRestrictionStore = void 0;
+const framework_schema_names_js_1 = require("../config/framework-schema-names.js");
 /** MariaDB `ER_NO_SUCH_TABLE`. */
 const ER_NO_SUCH_TABLE = 1146;
 class MariaDbSessionRestrictionStore {
     pool;
-    constructor(pool) {
+    /** `<identity>`.`session`. */
+    sessionTable;
+    /** `<app>`.`users`. */
+    usersTable;
+    constructor(pool, 
+    /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
+    schemas) {
         this.pool = pool;
+        const s = (0, framework_schema_names_js_1.schemaNamesAtConstruction)(schemas);
+        this.sessionTable = (0, framework_schema_names_js_1.qualifiedTableName)(s.identity, 'session');
+        this.usersTable = (0, framework_schema_names_js_1.qualifiedTableName)(s.app, 'users');
     }
     async markMustReenroll(sessionId) {
-        await this.pool.query('UPDATE `shield_identity`.`session` SET s_must_reenroll = 1 WHERE s_session_id = ?', [sessionId]);
+        await this.pool.query(`UPDATE ${this.sessionTable} 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]);
+        await this.pool.query(`UPDATE ${this.sessionTable} 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]));
+        const rows = (await this.pool.query(`SELECT s_must_reenroll FROM ${this.sessionTable} 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]));
+            const users = (await this.pool.query(`SELECT u_status FROM ${this.usersTable} WHERE u_uuid = ? LIMIT 1`, [principalId]));
             if (users[0] !== undefined)
                 accountActive = users[0].u_status === 'active';
         }

package/dist/storage/file-intake.interceptor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `FileIntake(options)` (FILE_STORAGE SPEC §5 G, §13): one multipart file, checked, then handed
+ * to the route handler.
+ *
+ *   @Classified({ typeKey: 'stored_file', action: 'create' })
+ *   @UseInterceptors(FileIntake({ field: 'file', profile: 'xlsx' }))
+ *
+ * - Interceptors run after guards, so the global guard has decided (and a denied caller is
+ *   refused) before any multipart byte is read (Shield #1, #3). A request with no principal is
+ *   refused here too, before parsing.
+ * - Parsing wraps `@nestjs/platform-express` `FileInterceptor` with multer's memory storage
+ *   (no module-level `MulterModule` options apply: no disk storage, no consumer file filter) and
+ *   limits `{ files: 1, fileSize: maxBytes + 1, fields: 0, parts: 2 }` and `defParamCharset:
+ *   'utf8'`. `maxBytes` defaults to the bound profile's configured cap (`OBJECT_STORAGE_MAX_BYTES`
+ *   under `storage: 'env'`); an explicit smaller `maxBytes` wins; never above 50 MiB.
+ * - Then `SHIELD_FILE_INGEST` checks the bytes (size, extension, declared type, magic) with the
+ *   tenant from the session (`req.principal.tenantId`, never the request body).
+ * - Errors are mapped here, at the source: 400 / 413 / 415 `HttpException`s carrying a fixed
+ *   reason code. The file name, field name and bytes are never echoed (Shield #10).
+ * - On success the request carries `req[FILE_INTAKE_REQUEST_KEY] = { file, bytes }` for
+ *   `FilesService.store`; multer's raw `req.file` (unsanitised name) is removed.
+ */
+import { type NestInterceptor, type Type } from '@nestjs/common';
+import { type FileRejectionReason, type IngestedFile } from '@astram/core';
+/** The HTTP reason codes `FileIntake` answers with: the core reasons plus `bad_request`. */
+export type FileIntakeRejectionReason = FileRejectionReason | 'bad_request';
+/** Options for {@link FileIntake}. */
+export interface FileIntakeOptions {
+    /** The multipart field that carries the file. */
+    readonly field: string;
+    /** A profile name known to `SHIELD_FILE_INGEST` (e.g. `'xlsx'`). */
+    readonly profile: string;
+    /**
+     * Lower multipart byte cap for this route (at most 50 MiB). Default: the profile's configured
+     * cap on `SHIELD_FILE_INGEST` (`OBJECT_STORAGE_MAX_BYTES` under `storage: 'env'`, else 10 MiB);
+     * a larger value than the profile cap is lowered to it. The parser stops at `maxBytes + 1`;
+     * the profile's own cap still applies in the ingest check.
+     */
+    readonly maxBytes?: number;
+}
+/** What {@link FileIntake} attaches to the request for `FilesService.store`. */
+export interface FileIntakeResult {
+    /** Server-built metadata (storage key, sha256, canonical type, size, sanitised name). */
+    readonly file: IngestedFile;
+    /** The exact bytes that were checked. */
+    readonly bytes: Uint8Array;
+}
+/** The request property {@link FileIntake} sets to a {@link FileIntakeResult}. */
+export declare const FILE_INTAKE_REQUEST_KEY = "shieldFileIntake";
+/** Fallback multipart cap (10 MiB, SPEC §10) when the bound ingest cannot report a profile cap. */
+export declare const FILE_INTAKE_DEFAULT_MAX_BYTES: number;
+/** Build the intake interceptor for one route (see the file header). Throws at boot on bad options. */
+export declare function FileIntake(options: FileIntakeOptions): Type<NestInterceptor>;
+//# sourceMappingURL=file-intake.interceptor.d.ts.map

package/dist/storage/file-intake.interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-intake.interceptor.d.ts","sourceRoot":"","sources":["../../src/storage/file-intake.interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAWL,KAAK,eAAe,EACpB,KAAK,IAAI,EACV,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAMtB,4FAA4F;AAC5F,MAAM,MAAM,yBAAyB,GAAG,mBAAmB,GAAG,aAAa,CAAC;AAE5E,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,mGAAmG;AACnG,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAuH9D,uGAAuG;AACvG,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC,eAAe,CAAC,CAkF5E"}