@astram/guard 0.13.0 → 0.15.0

package/dist/storage/storage.providers.js

@@ -0,0 +1,104 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORAGE_EXPORTS = void 0;
+exports.storageProviders = storageProviders;
+/**
+ * `ShieldModule` providers for the `storage` option (FILE_STORAGE SPEC §6):
+ * - `SHIELD_OBJECT_STORE`: the given `ObjectStore`, an `S3ObjectStore` built from
+ *   `OBJECT_STORAGE_*` (`'env'`; `null` when `OBJECT_STORAGE_BUCKET` is unset), or `null` when
+ *   the option is absent (the `makeAuditSinkProvider` null-binding pattern; callers answer 501).
+ * - `SHIELD_FILE_INGEST`: core `createFileIngest` over `NodeSha256Digest`, with the `xlsx`
+ *   profile (its cap set from `OBJECT_STORAGE_MAX_BYTES` under `'env'`). Always bound.
+ * - `ObjectStoreBootCheck`: registered only when the option is given (fail-closed ping at boot).
+ *
+ * `S3ObjectStore` (and so `@aws-sdk/client-s3`) is loaded lazily, only for `'env'` with a bucket.
+ */
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@astram/core");
+const app_config_js_1 = require("../config/app-config.js");
+const boot_secrets_js_1 = require("../secrets/boot-secrets.js");
+const shield_tokens_js_1 = require("../module/shield-tokens.js");
+const node_sha256_digest_js_1 = require("./node-sha256-digest.js");
+const object_store_boot_check_js_1 = require("./object-store-boot-check.js");
+/** The tokens `ShieldModule` exports app-wide for the storage option. */
+exports.STORAGE_EXPORTS = [shield_tokens_js_1.SHIELD_OBJECT_STORE, shield_tokens_js_1.SHIELD_FILE_INGEST];
+const STORE_METHODS = ['put', 'get', 'head', 'delete', 'ping'];
+/** Build the storage providers for one `ShieldModule` registration (see the file header). */
+function storageProviders(storage) {
+    if (storage !== undefined && storage !== 'env') {
+        const s = storage;
+        if (STORE_METHODS.some((m) => typeof s?.[m] !== 'function')) {
+            throw new Error("ShieldModule: `storage` must be an ObjectStore (put/get/head/delete/ping) or 'env'");
+        }
+    }
+    const configToken = Symbol('SHIELD_OBJECT_STORAGE_CONFIG');
+    return [
+        {
+            provide: configToken,
+            useFactory: () => storage === 'env'
+                ? ((0, app_config_js_1.loadObjectStorageConfig)(process.env, {
+                    resolvedFromSecretRef: boot_secrets_js_1.wasResolvedFromSecretRef,
+                }) ?? null)
+                : null,
+        },
+        {
+            provide: shield_tokens_js_1.SHIELD_OBJECT_STORE,
+            useFactory: async (config) => {
+                if (storage === undefined)
+                    return null;
+                if (storage !== 'env')
+                    return storage;
+                if (config === null)
+                    return null;
+                const { S3ObjectStore } = await Promise.resolve().then(() => __importStar(require('./s3-object-store.js')));
+                return new S3ObjectStore(config);
+            },
+            inject: [configToken],
+        },
+        {
+            provide: shield_tokens_js_1.SHIELD_FILE_INGEST,
+            useFactory: (config) => (0, core_1.createFileIngest)({
+                digest: new node_sha256_digest_js_1.NodeSha256Digest(),
+                newId: node_crypto_1.randomUUID,
+                profiles: {
+                    xlsx: config ? { ...core_1.XLSX_PROFILE, maxBytes: config.maxBytes } : core_1.XLSX_PROFILE,
+                },
+            }),
+            inject: [configToken],
+        },
+        ...(storage !== undefined ? [object_store_boot_check_js_1.ObjectStoreBootCheck] : []),
+    ];
+}

package/migrations/1710000000006-CreateAuthzSchema.cjs

@@ -10,10 +10,19 @@
  * Idempotent (CREATE TABLE IF NOT EXISTS). No hard-coded UUIDs. Run by the DDL account.
  */
 
-const SCHEMA = 'shield_authz';
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['48b8c9616c73a05ad030cfbfeb8b9e447d74f59804dbd7d3d26850df16d9e07e'];
+
 const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
 
-async function up({ query }) {
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`CREATE SCHEMA IF NOT EXISTS \`${SCHEMA}\` DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 
   // permission — the grantable key catalog (perm_key is the stable identity).
@@ -44,10 +53,12 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`role_permission\``);
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`authz_permission_version\``);
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`permission\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000007-ExtendPermissionAndRolePermission.cjs

@@ -20,9 +20,17 @@
  * Run by the DDL account.
  */
 
-const SCHEMA = 'shield_authz';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['7c6733f7acb8dfc8ddc32d79aa3e19df1a424802d87e2a18c2b109a7a0b07f5d'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   // permission — add the catalog columns astram3's MariaDbCatalogStore contract expects.
   await query(
     `ALTER TABLE \`${SCHEMA}\`.\`permission\` ADD COLUMN IF NOT EXISTS perm_uuid VARCHAR(36) NULL`
@@ -63,4 +71,4 @@ async function down() {
   // reviewed follow-up migration — not an automatic DROP COLUMN in `down()`.
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000008-CreateAccessBundleTables.cjs

@@ -14,9 +14,17 @@
  * Idempotent (CREATE TABLE IF NOT EXISTS). Structural (no tenant gate). Run by the DDL account.
  */
 
-const SCHEMA = 'shield_authz';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['7537d160c1ce7890e2ddb29333fd48ca4a13c3d191af85e8bff601d41245488f'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`access_bundle\` (
     ab_uuid        CHAR(36)     NOT NULL,
     ab_key         VARCHAR(120) NOT NULL,
@@ -40,10 +48,12 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   // FK order: drop the child (access_bundle_permission) before the parent (access_bundle).
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`access_bundle_permission\``);
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`access_bundle\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000009-CreateRecordPermissionRule.cjs

@@ -25,10 +25,19 @@
  * drops the table. Run by the DDL account.
  */
 
-const SCHEMA = 'shield_authz';
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['0e28b8f4682dea265dbd399d153f29c3f42c80e826dbe8bc5cbd3319fbdc4db3'];
+
 const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
 
-async function up({ query }) {
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`record_permission_rule\` (
     rpr_uuid          VARCHAR(36)  NOT NULL,
     rpr_policy_uuid   VARCHAR(36)  NULL,             -- groups a guided policy's AND-composed condition-rows; NULL = legacy/unconditional single-row rule
@@ -49,8 +58,10 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`record_permission_rule\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000014-CreateRecordShare.cjs

@@ -19,10 +19,19 @@
  * account. No FK to `record_permission_rule` — the two tables are independent.
  */
 
-const SCHEMA = 'shield_authz';
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['434236fcd1ef4c73a419674ebd757ce889a25c39744acb4db365a93c5230a844'];
+
 const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
 
-async function up({ query }) {
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`record_share\` (
     rs_uuid          VARCHAR(36)  NOT NULL,
     rs_tenant_uuid   VARCHAR(36)  NOT NULL,        -- the tenant the shared record belongs to
@@ -42,8 +51,10 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`record_share\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000015-CreateScopeClosure.cjs

@@ -27,9 +27,17 @@
  * the Application schema).
  */
 
-const SCHEMA = 'shield_authz';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['91be11b8677118a50f8a786c967cc2643ab4d5db48b5847acb57560634ab4591'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`scope_closure\` (
     ancestor_uuid    VARCHAR(36) NOT NULL,   -- a node (company) in the hierarchy
     descendant_uuid  VARCHAR(36) NOT NULL,   -- a node at or below the ancestor (self = depth 0)
@@ -39,8 +47,10 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`scope_closure\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000016-AlterCompanyParentFkRestrict.cjs

@@ -21,14 +21,21 @@
  * timestamp); `...016` sorts strictly after `...001`, so `companies` + its FK already exist.
  */
 
-const SCHEMA = 'shield_app';
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['4af1a570fa1e9d161bcac25087866baf1a3783e88df06db40f0a91be4ee590b4'];
+
 const TABLE = 'companies';
 const FK = 'FK_companies_parent';
 const COL = 'c_parent_uuid';
 const PK = 'c_uuid';
 
 /** True if a FK constraint of this name exists on the table (idempotency guard). */
-async function fkExists(query) {
+async function fkExists(query, SCHEMA) {
   const rows = await query(
     `SELECT 1
        FROM information_schema.TABLE_CONSTRAINTS
@@ -42,15 +49,17 @@ async function fkExists(query) {
   return Array.isArray(rows) && rows.length > 0;
 }
 
-async function dropFkIfPresent(query) {
-  if (await fkExists(query)) {
+async function dropFkIfPresent(query, SCHEMA) {
+  if (await fkExists(query, SCHEMA)) {
     await query(`ALTER TABLE \`${SCHEMA}\`.\`${TABLE}\` DROP FOREIGN KEY \`${FK}\``);
   }
 }
 
-async function up({ query }) {
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   // Drop the existing SET NULL FK (if present), re-add it as RESTRICT.
-  await dropFkIfPresent(query);
+  await dropFkIfPresent(query, SCHEMA);
   await query(
     `ALTER TABLE \`${SCHEMA}\`.\`${TABLE}\`
        ADD CONSTRAINT \`${FK}\` FOREIGN KEY (\`${COL}\`)
@@ -58,9 +67,11 @@ async function up({ query }) {
   );
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   // Restore the original SET NULL behavior.
-  await dropFkIfPresent(query);
+  await dropFkIfPresent(query, SCHEMA);
   await query(
     `ALTER TABLE \`${SCHEMA}\`.\`${TABLE}\`
        ADD CONSTRAINT \`${FK}\` FOREIGN KEY (\`${COL}\`)
@@ -68,4 +79,4 @@ async function down({ query }) {
   );
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000017-CreateServiceAccountKey.cjs

@@ -15,9 +15,17 @@
  * `down` drops the table. Run by the DDL account.
  */
 
-const SCHEMA = 'shield_authz';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['8c591ca61982f183ba26fb2ce6df2f56068333713654ca1b1e27a70d5e6101e2'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   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
@@ -34,8 +42,10 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`service_account_key\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guard",
-  "version": "0.13.0",
+  "version": "0.15.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",
@@ -32,21 +32,29 @@
     "access": "public"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "3.1142.0",
     "argon2": "^0.41.1",
     "ioredis": "^5.4.1",
     "mariadb": "^3.5.4",
-    "@astram/core": "1.5.0",
-    "@astram/engine": "0.6.0"
+    "@astram/core": "1.7.0",
+    "@astram/engine": "0.8.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",
     "@nestjs/core": "^11",
+    "@nestjs/platform-express": "^11",
     "reflect-metadata": "^0.2",
     "rxjs": "^7"
   },
+  "peerDependenciesMeta": {
+    "@nestjs/platform-express": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0",
     "@nestjs/testing": "^11.0.0",
     "@types/node": "^22.0.0",
     "@types/supertest": "^6.0.2",