@astram/guard 0.4.0 → 0.5.0

package/migrations/1710000000006-CreateAuthzSchema.cjs

@@ -0,0 +1,53 @@
+/**
+ * Framework authz migration — the shield_authz backing tables (empty until now):
+ *   permission                — grantable permission-key catalog.
+ *   role_permission           — role→permission grants (exact OR wildcard key strings).
+ *   authz_permission_version  — per-tenant permission-version counter (ADR-0011 freshness).
+ *
+ * shield_authz is @astram/guard's OWN schema (its decision adapters read it). Shipped here
+ * (not @astram/identity) to keep the package boundary: identity owns the org model, guard owns
+ * authz. Literal column names (NOT in the @astram/identity object registry — no reflectObjectType).
+ * Idempotent (CREATE TABLE IF NOT EXISTS). No hard-coded UUIDs. Run by the DDL account.
+ */
+
+const SCHEMA = 'shield_authz';
+const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
+
+async function up({ query }) {
+  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).
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`permission\` (
+    perm_key         VARCHAR(191) NOT NULL,
+    perm_description VARCHAR(255) NULL,
+    perm_created_at  ${TS},
+    PRIMARY KEY (perm_key)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  // role_permission — role→permission grants (exact or wildcard key strings).
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`role_permission\` (
+    rp_uuid       VARCHAR(36)  NOT NULL,
+    rp_role_uuid  VARCHAR(36)  NOT NULL,
+    rp_perm_key   VARCHAR(191) NOT NULL,
+    rp_created_by VARCHAR(36)  NULL,
+    rp_created_at ${TS},
+    PRIMARY KEY (rp_uuid),
+    UNIQUE KEY uq_role_perm (rp_role_uuid, rp_perm_key),
+    INDEX idx_rp_role (rp_role_uuid)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  // authz_permission_version — per-tenant version counter (ADR-0011 freshness).
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`authz_permission_version\` (
+    apv_tenant_uuid VARCHAR(36) NOT NULL,
+    apv_version     BIGINT      NOT NULL DEFAULT 0,
+    PRIMARY KEY (apv_tenant_uuid)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  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 };

package/migrations/1710000000007-ExtendPermissionAndRolePermission.cjs

@@ -0,0 +1,66 @@
+/**
+ * Framework authz migration — extends the shield_authz.permission catalog + role_permission
+ * grant rows to the full column set the grant-admin service (Phase 4) needs.
+ *
+ * The framework's `1710000000006-CreateAuthzSchema` created `permission` with only
+ * (perm_key, perm_description, perm_created_at) and `role_permission` with
+ * (rp_uuid, rp_role_uuid, rp_perm_key, rp_created_by, rp_created_at). This migration is
+ * ADDITIVE — it never touches those existing columns — and brings `permission` up to
+ * astram3's catalog shape (perm_uuid/module/type_key/action/label/tier + perm_status for the
+ * MariaDbCatalogStore contract) and adds `rp_granted_by`/`rp_granted_at` to `role_permission`
+ * (the grant-admin service's own attribution columns, alongside the pre-existing rp_created_*).
+ *
+ * Idempotent: every ADD is `ADD COLUMN IF NOT EXISTS` (MariaDB-supported), so this is a clean
+ * no-op against a DB that already has these columns (e.g. astram4's live DB). `perm_uuid` is
+ * added as a plain nullable column — NOT a new primary key — since `permission` already has a
+ * populated PK (perm_key) and changing the PK of an existing table is out of scope here; the
+ * reconciler backfills perm_uuid + the other NOT NULL DEFAULT '' text columns with real values.
+ *
+ * Literal column names (NOT in the @astram/identity object registry — no reflectObjectType).
+ * Run by the DDL account.
+ */
+
+const SCHEMA = 'shield_authz';
+
+async function up({ query }) {
+  // 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`
+  );
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`permission\` ADD COLUMN IF NOT EXISTS perm_module VARCHAR(64) NOT NULL DEFAULT ''`
+  );
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`permission\` ADD COLUMN IF NOT EXISTS perm_type_key VARCHAR(64) NOT NULL DEFAULT ''`
+  );
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`permission\` ADD COLUMN IF NOT EXISTS perm_action VARCHAR(64) NOT NULL DEFAULT ''`
+  );
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`permission\` ADD COLUMN IF NOT EXISTS perm_label VARCHAR(191) NOT NULL DEFAULT ''`
+  );
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`permission\` ADD COLUMN IF NOT EXISTS perm_tier VARCHAR(32) NOT NULL DEFAULT 'gated'`
+  );
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`permission\` ADD COLUMN IF NOT EXISTS perm_status VARCHAR(16) NOT NULL DEFAULT 'active'`
+  );
+
+  // role_permission — add the grant-admin service's attribution columns (additive; rp_created_*
+  // from 006 stays untouched).
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`role_permission\` ADD COLUMN IF NOT EXISTS rp_granted_by CHAR(36) NULL`
+  );
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`role_permission\` ADD COLUMN IF NOT EXISTS rp_granted_at TIMESTAMP NULL`
+  );
+}
+
+async function down() {
+  // Documented NO-OP: dropping columns here would drop live catalog/grant-attribution data
+  // (perm_module/type_key/action/label/tier/status, rp_granted_by/rp_granted_at) with no safe
+  // way to reconstruct it. Reversal of this migration, if ever needed, must be a deliberate,
+  // reviewed follow-up migration — not an automatic DROP COLUMN in `down()`.
+}
+
+module.exports = { up, down };

package/migrations/1710000000008-CreateAccessBundleTables.cjs

@@ -0,0 +1,49 @@
+/**
+ * Framework authz migration — the access-bundle backing tables in shield_authz:
+ *   access_bundle             — developer-declared, admin-grantable named permission bundles
+ *                               (reconciled from @AccessBundle specs, never seeded here)
+ *   access_bundle_permission  — bundle→atomic-key resolution rows
+ *
+ * A bundle expands to its atomic `role_permission` keys at grant time; these tables hold only
+ * the catalog (the declared bundles + their key sets). No seed rows, no hard-coded UUIDs —
+ * bundles are reconciled at boot from the collected declarations.
+ *
+ * Ported from astram3 `server/migrations/1720000000018-CreateAccessBundleTables.js` (read-only
+ * reference — column set, keys, and FK match exactly).
+ *
+ * Idempotent (CREATE TABLE IF NOT EXISTS). Structural (no tenant gate). Run by the DDL account.
+ */
+
+const SCHEMA = 'shield_authz';
+
+async function up({ query }) {
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`access_bundle\` (
+    ab_uuid        CHAR(36)     NOT NULL,
+    ab_key         VARCHAR(120) NOT NULL,
+    ab_module      VARCHAR(60)  NOT NULL,
+    ab_label       VARCHAR(200) NOT NULL,
+    ab_description VARCHAR(500) NULL,
+    ab_status      VARCHAR(16)  NOT NULL DEFAULT 'active',
+    PRIMARY KEY (ab_uuid),
+    UNIQUE KEY UQ_access_bundle_module_key (ab_module, ab_key)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`access_bundle_permission\` (
+    abp_uuid        CHAR(36)     NOT NULL,
+    abp_bundle_uuid CHAR(36)     NOT NULL,
+    abp_perm_key    VARCHAR(200) NOT NULL,
+    PRIMARY KEY (abp_uuid),
+    UNIQUE KEY UQ_abp_bundle_key (abp_bundle_uuid, abp_perm_key),
+    CONSTRAINT FK_access_bundle_permission_bundle
+      FOREIGN KEY (abp_bundle_uuid) REFERENCES \`${SCHEMA}\`.\`access_bundle\` (ab_uuid)
+      ON DELETE CASCADE
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  // 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guard",
-  "version": "0.4.0",
+  "version": "0.5.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",
@@ -13,7 +13,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "migrations"
   ],
   "sideEffects": false,
   "publishConfig": {
@@ -23,7 +24,8 @@
     "argon2": "^0.41.1",
     "ioredis": "^5.4.1",
     "mariadb": "^3.4.0",
-    "@astram/core": "1.0.0"
+    "@astram/core": "1.0.0",
+    "@astram/engine": "0.1.3"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",