@astram/identity 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -4,7 +4,6 @@
  * the `identityObjects` array the engine registers. Physical names unchanged from the
  * app's originals (rename is a later sub-plan).
  */
-import type { ObjectTypeInput } from '@astram/engine';
 export { Company } from './company.object.js';
 export { User } from './user.object.js';
 export { Role } from './role.object.js';
@@ -15,6 +14,38 @@ export { MembershipPosting } from './membership-posting.object.js';
 export { CompanyDepartment } from './company-department.object.js';
 export { CompanyBranch } from './company-branch.object.js';
 export { identityMigrationsDir } from './migrations-dir.js';
-/** All identity objects, registered with the engine at boot (same set + order as before). */
-export declare const identityObjects: readonly ObjectTypeInput[];
+/**
+ * All identity objects, registered with the engine at boot (same set + order as before).
+ * Defined in the leaf module `./objects.js` (imported by BOTH this barrel and
+ * `./auth-facts-keys.ts`) so the auth-facts key projection has no module-init cycle.
+ */
+export { identityObjects } from './objects.js';
+/**
+ * The framework identity permission-key universe, projected from `identityObjects` via
+ * `@astram/guard`'s registry bridge. Pass these into
+ * `ShieldModule.forRoot({ auth: true, identityActionKeys, identityControlPlaneKeys })`
+ * so guard's auth-facts adapter can expand `identity:*` grants + union root's
+ * control-plane keys WITHOUT guard importing this package.
+ */
+export { identityAuthActionKeys, identityControlPlaneKeys } from './auth-facts-keys.js';
+/**
+ * The framework-owned identity FEATURE module (company/user/role CRUD). The consumer imports
+ * `IdentityFeatureModule.forRoot()` in one line alongside `ShieldModule.forRoot(...)` (ADR-0026);
+ * `forRoot()` self-wires the engine (`EngineModule.forRoot` over the app's APP_DB_* env), registers
+ * `identityObjects`, and mounts the CRUD controllers — no separate engine setup needed.
+ */
+export { IdentityFeatureModule } from './features/identity-feature.module.js';
+/**
+ * The record-tier authorization wiring: the lean grant-read pool factory + the helper that
+ * assembles `RecordAuthorizationInputs` for `ShieldModule.forRoot({ recordAuthorization })`.
+ * Once wired, `decide()` is real (the framework's record-tier adapters run over the identity
+ * app schema) instead of the deny-everything stub.
+ */
+export { createIdentityAuthzPool, buildIdentityRecordAuthorization, } from './features/authz/record-authorization.js';
+/**
+ * The ADR-0011 per-request session-facts reader (ALS hot path), re-exported so a consumer
+ * that wants to construct it directly (rather than via `buildIdentityRecordAuthorization`)
+ * can do so.
+ */
+export { AlsSessionFactsReader } from './features/authz/session-facts.reader.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAWtD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,6FAA6F;AAC7F,eAAO,MAAM,eAAe,EAAE,SAAS,eAAe,EAGrD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;GAIG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;GAMG;AACH,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAExF;;;;;GAKG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAE9E;;;;;GAKG;AACH,OAAO,EACL,uBAAuB,EACvB,gCAAgC,GACjC,MAAM,0CAA0C,CAAC;AAElD;;;;GAIG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC"}

package/dist/index.js

@@ -1,37 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.identityObjects = exports.identityMigrationsDir = exports.CompanyBranch = exports.CompanyDepartment = exports.MembershipPosting = exports.CompanyMembership = exports.Branch = exports.Department = exports.Role = exports.User = exports.Company = void 0;
-const company_object_js_1 = require("./company.object.js");
-const user_object_js_1 = require("./user.object.js");
-const role_object_js_1 = require("./role.object.js");
-const department_object_js_1 = require("./department.object.js");
-const branch_object_js_1 = require("./branch.object.js");
-const company_membership_object_js_1 = require("./company-membership.object.js");
-const membership_posting_object_js_1 = require("./membership-posting.object.js");
-const company_department_object_js_1 = require("./company-department.object.js");
-const company_branch_object_js_1 = require("./company-branch.object.js");
-var company_object_js_2 = require("./company.object.js");
-Object.defineProperty(exports, "Company", { enumerable: true, get: function () { return company_object_js_2.Company; } });
-var user_object_js_2 = require("./user.object.js");
-Object.defineProperty(exports, "User", { enumerable: true, get: function () { return user_object_js_2.User; } });
-var role_object_js_2 = require("./role.object.js");
-Object.defineProperty(exports, "Role", { enumerable: true, get: function () { return role_object_js_2.Role; } });
-var department_object_js_2 = require("./department.object.js");
-Object.defineProperty(exports, "Department", { enumerable: true, get: function () { return department_object_js_2.Department; } });
-var branch_object_js_2 = require("./branch.object.js");
-Object.defineProperty(exports, "Branch", { enumerable: true, get: function () { return branch_object_js_2.Branch; } });
-var company_membership_object_js_2 = require("./company-membership.object.js");
-Object.defineProperty(exports, "CompanyMembership", { enumerable: true, get: function () { return company_membership_object_js_2.CompanyMembership; } });
-var membership_posting_object_js_2 = require("./membership-posting.object.js");
-Object.defineProperty(exports, "MembershipPosting", { enumerable: true, get: function () { return membership_posting_object_js_2.MembershipPosting; } });
-var company_department_object_js_2 = require("./company-department.object.js");
-Object.defineProperty(exports, "CompanyDepartment", { enumerable: true, get: function () { return company_department_object_js_2.CompanyDepartment; } });
-var company_branch_object_js_2 = require("./company-branch.object.js");
-Object.defineProperty(exports, "CompanyBranch", { enumerable: true, get: function () { return company_branch_object_js_2.CompanyBranch; } });
+exports.AlsSessionFactsReader = exports.buildIdentityRecordAuthorization = exports.createIdentityAuthzPool = exports.IdentityFeatureModule = exports.identityControlPlaneKeys = exports.identityAuthActionKeys = exports.identityObjects = exports.identityMigrationsDir = exports.CompanyBranch = exports.CompanyDepartment = exports.MembershipPosting = exports.CompanyMembership = exports.Branch = exports.Department = exports.Role = exports.User = exports.Company = void 0;
+/**
+ * @astram/identity — the framework-owned identity + tenancy model.
+ * The 9 identity object classes (relocated from the consumer app in Sub-plan B) +
+ * the `identityObjects` array the engine registers. Physical names unchanged from the
+ * app's originals (rename is a later sub-plan).
+ */
+var company_object_js_1 = require("./company.object.js");
+Object.defineProperty(exports, "Company", { enumerable: true, get: function () { return company_object_js_1.Company; } });
+var user_object_js_1 = require("./user.object.js");
+Object.defineProperty(exports, "User", { enumerable: true, get: function () { return user_object_js_1.User; } });
+var role_object_js_1 = require("./role.object.js");
+Object.defineProperty(exports, "Role", { enumerable: true, get: function () { return role_object_js_1.Role; } });
+var department_object_js_1 = require("./department.object.js");
+Object.defineProperty(exports, "Department", { enumerable: true, get: function () { return department_object_js_1.Department; } });
+var branch_object_js_1 = require("./branch.object.js");
+Object.defineProperty(exports, "Branch", { enumerable: true, get: function () { return branch_object_js_1.Branch; } });
+var company_membership_object_js_1 = require("./company-membership.object.js");
+Object.defineProperty(exports, "CompanyMembership", { enumerable: true, get: function () { return company_membership_object_js_1.CompanyMembership; } });
+var membership_posting_object_js_1 = require("./membership-posting.object.js");
+Object.defineProperty(exports, "MembershipPosting", { enumerable: true, get: function () { return membership_posting_object_js_1.MembershipPosting; } });
+var company_department_object_js_1 = require("./company-department.object.js");
+Object.defineProperty(exports, "CompanyDepartment", { enumerable: true, get: function () { return company_department_object_js_1.CompanyDepartment; } });
+var company_branch_object_js_1 = require("./company-branch.object.js");
+Object.defineProperty(exports, "CompanyBranch", { enumerable: true, get: function () { return company_branch_object_js_1.CompanyBranch; } });
 var migrations_dir_js_1 = require("./migrations-dir.js");
 Object.defineProperty(exports, "identityMigrationsDir", { enumerable: true, get: function () { return migrations_dir_js_1.identityMigrationsDir; } });
-/** All identity objects, registered with the engine at boot (same set + order as before). */
-exports.identityObjects = [
-    company_object_js_1.Company, user_object_js_1.User, role_object_js_1.Role, department_object_js_1.Department, branch_object_js_1.Branch,
-    company_membership_object_js_1.CompanyMembership, membership_posting_object_js_1.MembershipPosting, company_department_object_js_1.CompanyDepartment, company_branch_object_js_1.CompanyBranch,
-];
+/**
+ * All identity objects, registered with the engine at boot (same set + order as before).
+ * Defined in the leaf module `./objects.js` (imported by BOTH this barrel and
+ * `./auth-facts-keys.ts`) so the auth-facts key projection has no module-init cycle.
+ */
+var objects_js_1 = require("./objects.js");
+Object.defineProperty(exports, "identityObjects", { enumerable: true, get: function () { return objects_js_1.identityObjects; } });
+/**
+ * The framework identity permission-key universe, projected from `identityObjects` via
+ * `@astram/guard`'s registry bridge. Pass these into
+ * `ShieldModule.forRoot({ auth: true, identityActionKeys, identityControlPlaneKeys })`
+ * so guard's auth-facts adapter can expand `identity:*` grants + union root's
+ * control-plane keys WITHOUT guard importing this package.
+ */
+var auth_facts_keys_js_1 = require("./auth-facts-keys.js");
+Object.defineProperty(exports, "identityAuthActionKeys", { enumerable: true, get: function () { return auth_facts_keys_js_1.identityAuthActionKeys; } });
+Object.defineProperty(exports, "identityControlPlaneKeys", { enumerable: true, get: function () { return auth_facts_keys_js_1.identityControlPlaneKeys; } });
+/**
+ * The framework-owned identity FEATURE module (company/user/role CRUD). The consumer imports
+ * `IdentityFeatureModule.forRoot()` in one line alongside `ShieldModule.forRoot(...)` (ADR-0026);
+ * `forRoot()` self-wires the engine (`EngineModule.forRoot` over the app's APP_DB_* env), registers
+ * `identityObjects`, and mounts the CRUD controllers — no separate engine setup needed.
+ */
+var identity_feature_module_js_1 = require("./features/identity-feature.module.js");
+Object.defineProperty(exports, "IdentityFeatureModule", { enumerable: true, get: function () { return identity_feature_module_js_1.IdentityFeatureModule; } });
+/**
+ * The record-tier authorization wiring: the lean grant-read pool factory + the helper that
+ * assembles `RecordAuthorizationInputs` for `ShieldModule.forRoot({ recordAuthorization })`.
+ * Once wired, `decide()` is real (the framework's record-tier adapters run over the identity
+ * app schema) instead of the deny-everything stub.
+ */
+var record_authorization_js_1 = require("./features/authz/record-authorization.js");
+Object.defineProperty(exports, "createIdentityAuthzPool", { enumerable: true, get: function () { return record_authorization_js_1.createIdentityAuthzPool; } });
+Object.defineProperty(exports, "buildIdentityRecordAuthorization", { enumerable: true, get: function () { return record_authorization_js_1.buildIdentityRecordAuthorization; } });
+/**
+ * The ADR-0011 per-request session-facts reader (ALS hot path), re-exported so a consumer
+ * that wants to construct it directly (rather than via `buildIdentityRecordAuthorization`)
+ * can do so.
+ */
+var session_facts_reader_js_1 = require("./features/authz/session-facts.reader.js");
+Object.defineProperty(exports, "AlsSessionFactsReader", { enumerable: true, get: function () { return session_facts_reader_js_1.AlsSessionFactsReader; } });

package/dist/objects.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The framework identity object-type set — extracted here (rather than defined in
+ * `./index.ts`) so it can be imported WITHOUT a module-init cycle. `./auth-facts-keys.ts`
+ * builds the permission-key registry at module-eval time from this array; had it imported
+ * `identityObjects` from `./index.ts` (which re-exports `auth-facts-keys.ts`), the array
+ * could still be `undefined` when the bridge runs → a throw. Both `./index.ts` and
+ * `./auth-facts-keys.ts` import the array from THIS leaf module, which depends only on the
+ * object classes — so it is fully initialized before either consumer evaluates.
+ */
+import type { ObjectTypeInput } from '@astram/engine';
+/** All identity objects, registered with the engine at boot (same set + order as before). */
+export declare const identityObjects: readonly ObjectTypeInput[];
+//# sourceMappingURL=objects.d.ts.map

package/dist/objects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objects.d.ts","sourceRoot":"","sources":["../src/objects.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAatD,6FAA6F;AAC7F,eAAO,MAAM,eAAe,EAAE,SAAS,eAAe,EAIrD,CAAC"}

package/dist/objects.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityObjects = void 0;
+const company_object_js_1 = require("./company.object.js");
+const user_object_js_1 = require("./user.object.js");
+const role_object_js_1 = require("./role.object.js");
+const department_object_js_1 = require("./department.object.js");
+const branch_object_js_1 = require("./branch.object.js");
+const company_membership_object_js_1 = require("./company-membership.object.js");
+const membership_posting_object_js_1 = require("./membership-posting.object.js");
+const company_department_object_js_1 = require("./company-department.object.js");
+const company_branch_object_js_1 = require("./company-branch.object.js");
+const cross_tenant_grant_object_js_1 = require("./cross-tenant-grant.object.js");
+const shared_resource_object_js_1 = require("./shared-resource.object.js");
+/** All identity objects, registered with the engine at boot (same set + order as before). */
+exports.identityObjects = [
+    company_object_js_1.Company, user_object_js_1.User, role_object_js_1.Role, department_object_js_1.Department, branch_object_js_1.Branch,
+    company_membership_object_js_1.CompanyMembership, membership_posting_object_js_1.MembershipPosting, company_department_object_js_1.CompanyDepartment, company_branch_object_js_1.CompanyBranch,
+    cross_tenant_grant_object_js_1.CrossTenantGrant, shared_resource_object_js_1.SharedResource,
+];

package/dist/shared-resource.object.d.ts

@@ -0,0 +1,28 @@
+/**
+ * shared_resource — a MINIMAL, framework-owned `tenantScoped` demo object type.
+ *
+ * WHY IT EXISTS: it is the first (and currently only) `tenantScoped`/offerable type in the
+ * framework. All nine identity types are `system` (non-offerable, grant-governed), so the
+ * cross-tenant grant flow would have NOTHING to offer without an offerable resource type.
+ * `shared_resource` fills that gap so a cross-tenant grant has a real, shareable target.
+ *
+ * ACCESS: `{ tenantScoped: true, plane: 'data' }` — tenant business content, not
+ * administration. `tenantScoped` (mutually exclusive with `system`) means the engine
+ * enforces per-tenant isolation via the server-stamped `sr_tenant_id` column below; the
+ * engine's registry REQUIRES exactly one field with `trusted: 'tenantId'` for a
+ * tenantScoped type (else boot fails), which `tenantId` satisfies. `plane: 'data'` denies
+ * the capped root by construction — correct for a shareable business resource, since the
+ * cross-tenant flow reaches it through per-tenant admins, never root.
+ *
+ * TENANT ISOLATION IS SERVER-STAMPED: `sr_tenant_id` is `trusted: 'tenantId'` — the engine
+ * OVERWRITES it from the session's tenant on every write; a client can never forge it.
+ *
+ * Keep this tiny — its only job is to be an offerable type. Not a real business feature.
+ */
+export declare class SharedResource {
+    uuid: string;
+    /** Server-stamped tenant boundary (engine overwrites from the session; never client). */
+    tenantId: string;
+    label: string;
+}
+//# sourceMappingURL=shared-resource.object.d.ts.map

package/dist/shared-resource.object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-resource.object.d.ts","sourceRoot":"","sources":["../src/shared-resource.object.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAOa,cAAc;IAEzB,IAAI,EAAG,MAAM,CAAC;IAEd,yFAAyF;IAEzF,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;CAChB"}

package/dist/shared-resource.object.js

@@ -0,0 +1,63 @@
+"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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SharedResource = void 0;
+const engine_1 = require("@astram/engine");
+const schema_1 = require("./schema");
+/**
+ * shared_resource — a MINIMAL, framework-owned `tenantScoped` demo object type.
+ *
+ * WHY IT EXISTS: it is the first (and currently only) `tenantScoped`/offerable type in the
+ * framework. All nine identity types are `system` (non-offerable, grant-governed), so the
+ * cross-tenant grant flow would have NOTHING to offer without an offerable resource type.
+ * `shared_resource` fills that gap so a cross-tenant grant has a real, shareable target.
+ *
+ * ACCESS: `{ tenantScoped: true, plane: 'data' }` — tenant business content, not
+ * administration. `tenantScoped` (mutually exclusive with `system`) means the engine
+ * enforces per-tenant isolation via the server-stamped `sr_tenant_id` column below; the
+ * engine's registry REQUIRES exactly one field with `trusted: 'tenantId'` for a
+ * tenantScoped type (else boot fails), which `tenantId` satisfies. `plane: 'data'` denies
+ * the capped root by construction — correct for a shareable business resource, since the
+ * cross-tenant flow reaches it through per-tenant admins, never root.
+ *
+ * TENANT ISOLATION IS SERVER-STAMPED: `sr_tenant_id` is `trusted: 'tenantId'` — the engine
+ * OVERWRITES it from the session's tenant on every write; a client can never forge it.
+ *
+ * Keep this tiny — its only job is to be an offerable type. Not a real business feature.
+ */
+let SharedResource = class SharedResource {
+    uuid;
+    /** Server-stamped tenant boundary (engine overwrites from the session; never client). */
+    tenantId;
+    label;
+};
+exports.SharedResource = SharedResource;
+__decorate([
+    (0, engine_1.Field)({ column: 'sr_uuid', type: 'uuid', role: 'primaryKey' }),
+    __metadata("design:type", String)
+], SharedResource.prototype, "uuid", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'sr_tenant_id', type: 'uuid', trusted: 'tenantId' }),
+    __metadata("design:type", String)
+], SharedResource.prototype, "tenantId", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'sr_label', type: 'string', required: true }),
+    __metadata("design:type", String)
+], SharedResource.prototype, "label", void 0);
+exports.SharedResource = SharedResource = __decorate([
+    (0, engine_1.ObjectType)({
+        typeKey: 'shared_resource',
+        table: 'shared_resource',
+        schema: schema_1.SCHEMA,
+        access: { tenantScoped: true, plane: 'data' },
+    }),
+    (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'sr_uuid' })
+], SharedResource);

package/migrations/1710000000010-CreateAuditLog.cjs

@@ -0,0 +1,42 @@
+/**
+ * Framework audit migration — the `audit_log` table (ADR-0014's `shield_audit`
+ * security schema), the append-only sink the @astram/engine pipe's mandatory
+ * audit stage writes to (via MariaDbAuditSink). No existing framework migration
+ * creates `shield_audit` (guard's 1710000000006 creates `shield_authz`, a
+ * DIFFERENT schema) — this migration owns both the schema and the table.
+ *
+ * Columns mirror the MariaDbAuditSink INSERT exactly (al_* prefix): al_uuid,
+ * al_type, al_occurred_at_ms, al_actor_id, al_tenant_id, al_action_key,
+ * al_resource_json, al_decision_json, al_attributes_json. Append-only by
+ * convention — the engine only ever INSERTs; there is no update/delete path
+ * in the adapter. Ported from astram3's frozen
+ * server/migrations/1720000000002-CreateAuditLog.js. Idempotent.
+ */
+
+const SCHEMA = 'shield_audit';
+
+async function up({ query }) {
+  await query(`CREATE SCHEMA IF NOT EXISTS \`${SCHEMA}\` DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`audit_log\` (
+    al_uuid            VARCHAR(36)  NOT NULL,
+    al_type            VARCHAR(64)  NOT NULL,
+    al_occurred_at_ms  BIGINT       NOT NULL,
+    al_actor_id        VARCHAR(64)  NOT NULL,
+    al_tenant_id       VARCHAR(64)  NOT NULL,
+    al_action_key      VARCHAR(64)  NULL,
+    al_resource_json   JSON         NULL,
+    al_decision_json   JSON         NULL,
+    al_attributes_json JSON         NULL,
+    PRIMARY KEY (al_uuid),
+    INDEX idx_audit_actor (al_actor_id),
+    INDEX idx_audit_tenant (al_tenant_id),
+    INDEX idx_audit_time (al_occurred_at_ms)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`audit_log\``);
+}
+
+module.exports = { up, down };

package/migrations/1710000000011-CreateCrossTenantGrant.cjs

@@ -0,0 +1,66 @@
+/**
+ * Framework authz migration — the `shield_authz.cross_tenant_grant` table (ADR-0009). One row
+ * = one explicit, consented, scoped grant that lets a GRANTEE tenant's principal reach into
+ * the OWNING tenant's object type (or a single record) for a bounded set of actions, until an
+ * expiry. Guard's `CrossTenantGrantWriter` (offer/accept/revoke) and
+ * `MariaDbCrossTenantGrantAdapter` (findActiveGrant) READ + WRITE this table via
+ * `SHIELD_CROSS_TENANT_GRANT_WRITER` / `SHIELD_CROSS_TENANT_GRANT_PORT` — no existing framework
+ * migration created it (a framework-ownership gap, like `audit_log` before it). The schema
+ * `shield_authz` already exists (guard's 1710000000006-CreateAuthzSchema.cjs creates it) — this
+ * migration does NOT recreate the schema, only the table.
+ *
+ *   • Lifecycle bound (who may offer/accept/revoke) lives in code (CrossTenantGrantWriter); this
+ *     table is pure storage.
+ *   • A grant is ACTIVE only when `ctg_status = 'accepted'` AND `ctg_revoked_at IS NULL` AND
+ *     `ctg_expires_at_ms > <now-epoch-ms>` — exactly what the adapter's findActiveGrant filters on.
+ *   • ⚠️ `ctg_expires_at_ms` is a BIGINT epoch-ms (NOT a TIMESTAMP): compared to a BOUND integer
+ *     clock value, so expiry is timezone-immune (mirrors the reset-token store's
+ *     `prt_expires_at_ms` precedent).
+ *   • `ctg_allowed_actions` is a JSON array of action-key strings — the hard, non-wildcard,
+ *     non-empty action ceiling enforced at offer time.
+ *   • `ctg_offered_by` records the owning-tenant admin who offered (who-may-grant audit trail).
+ *
+ * Columns + `idx_ctg_lookup` ported from astram3's frozen
+ * server/migrations/1720000000040-CreateCrossTenantGrant.js; `idx_ctg_grantee` folded in from
+ * astram3's frozen server/migrations/1720000000070-AddCtgGranteeIndex.js (astram3 split the
+ * grantee-side index across a later migration — the framework creates the table + both indexes
+ * in one). Idempotent (`CREATE TABLE IF NOT EXISTS`). No hard-coded UUIDs. `down()` drops the
+ * table. Timestamp 1710000000011 sorts after audit (...010) and before the dev seed (...099).
+ */
+
+const SCHEMA = 'shield_authz';
+const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
+
+async function up({ query }) {
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`cross_tenant_grant\` (
+    ctg_uuid                VARCHAR(36)  NOT NULL,                 -- PK (grant uuid)
+    ctg_owning_tenant_uuid  VARCHAR(36)  NOT NULL,                 -- tenant whose data is reached into / who consents
+    ctg_grantee_tenant_uuid VARCHAR(36)  NOT NULL,                 -- tenant reaching in
+    ctg_grantee_kind        VARCHAR(16)  NOT NULL,                 -- 'user' | 'role' (in the grantee tenant)
+    ctg_grantee_uuid        VARCHAR(36)  NOT NULL,                 -- the specific user/role uuid
+    ctg_type_key            VARCHAR(64)  NOT NULL,                 -- object type the grant covers
+    ctg_scope               VARCHAR(16)  NOT NULL,                 -- 'object_type' | 'record'
+    ctg_record_uuid         VARCHAR(36)  NULL,                     -- set iff scope='record'
+    ctg_allowed_actions     JSON         NOT NULL,                 -- hard ceiling: JSON array of action keys (non-wildcard, non-empty)
+    ctg_status              VARCHAR(16)  NOT NULL DEFAULT 'offered', -- 'offered' | 'accepted' | 'revoked' (activates only on 'accepted')
+    ctg_offered_by          VARCHAR(36)  NOT NULL,                 -- the owning-tenant admin who offered (who-may-grant audit)
+    ctg_expires_at_ms       BIGINT       NOT NULL,                 -- mandatory FUTURE expiry, epoch-ms (BIGINT — timezone-immune)
+    ctg_created_at          ${TS},
+    ctg_accepted_at         TIMESTAMP(0) NULL,                     -- stamped on accept (audit ts; not security-compared)
+    ctg_revoked_at          TIMESTAMP(0) NULL,                     -- stamped on revoke, NULL sentinel = not revoked (either side)
+    PRIMARY KEY (ctg_uuid),
+    -- The findActiveGrant lookup path: (owning tenant, type, grantee, status) narrows to a
+    -- grantee's active grants for an object type fast.
+    INDEX idx_ctg_lookup (ctg_owning_tenant_uuid, ctg_type_key, ctg_grantee_uuid, ctg_status),
+    -- The grantee-side lookup path: "the offers sitting in MY tenant's inbox" —
+    -- WHERE ctg_grantee_tenant_uuid = ? AND ctg_status = 'offered' AND ctg_expires_at_ms > ?.
+    -- idx_ctg_lookup is owning-tenant-first and does not serve a grantee-tenant-first scan.
+    INDEX idx_ctg_grantee (ctg_grantee_tenant_uuid, ctg_status, ctg_expires_at_ms)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`cross_tenant_grant\``);
+}
+
+module.exports = { up, down };

package/migrations/1710000000012-SeedCrossTenantGrantPerms.cjs

@@ -0,0 +1,86 @@
+/**
+ * Framework authz migration — grant-authority seed for cross-tenant grants. `cross_tenant_grant`'s
+ * three permission keys (`identity:cross_tenant_grant:{share,accept,revoke}` — module key is
+ * 'identity', see `@astram/guard`'s `identity/identity-actions.ts`'s `MODULE_KEY`) are the
+ * data-driven authority for the offer/accept/revoke lifecycle — `decide()` gates them exactly like
+ * every other object-type action, now that `cross_tenant_grant` is a registered object type
+ * (`packages/identity/src/cross-tenant-grant.object.ts` + `identityObjects`).
+ *
+ * WHAT THIS MIGRATION DOES vs WHAT IT DOESN'T:
+ *   - It DOES NOT insert the 3 rows into `shield_authz.permission` (the catalog). The boot
+ *     catalog reconciler auto-inserts an ACTIVE catalog row for every action the registry
+ *     declares — and `cross_tenant_grant` is now registered, so the 3 keys appear in the catalog
+ *     automatically the first time the app boots after this ships. No manual catalog seed needed.
+ *   - It DOES grant the 3 new keys to every role that CURRENTLY holds coarse identity-admin
+ *     authority, so an existing admin role doesn't lose the ability to offer/accept/revoke the
+ *     moment this ships: a role counts as "identity admin" iff it holds any of
+ *     `identity:company:update` | `identity:company:delete` | `identity:company:*` |
+ *     `identity:*` | `identity` (mirrors astram3's deleted `DbGrantAuthorityResolver`'s
+ *     `COMPANY_ADMIN_KEYS` set, matched by EXACT string — the same wildcards `expandGrantKeys`
+ *     treats as coarse admin grants). This also ensures the framework's dev seed
+ *     (`1710000000099-SeedDevIdentity.cjs`, which grants its role `identity:*`) gets the 3 keys
+ *     automatically, so the seeded admin can offer/accept/revoke out of the box. Resolved by
+ *     `rp_perm_key` STRING MATCH against `role_permission` — no hardcoded uuids, no assumption
+ *     about which named roles exist on a given tenant.
+ *
+ * Idempotent: SELECT-before-INSERT via NOT EXISTS on the natural key (rp_role_uuid, rp_perm_key)
+ * — re-running inserts ZERO new rows. `down()` deletes only the 3 keys' grants (by key), leaving
+ * every other role_permission row untouched.
+ *
+ * Ported from astram3's frozen `server/migrations/1720000000080-SeedCrossTenantGrantPerms.js`.
+ * Timestamp 1710000000012 sorts strictly after the ctg DDL (...011) and before the dev seed
+ * (...099) — no dependency ordering concern (this migration only reads/writes `role_permission`,
+ * a table created by guard's 1710000000006-CreateAuthzSchema.cjs, and does not depend on the
+ * `cross_tenant_grant` object type's runtime registration — the catalog row for these keys is
+ * optional at grant-write time; `role_permission` has no FK to `permission`).
+ */
+
+const AUTHZ = 'shield_authz';
+const MODULE = 'identity';
+const TYPE_KEY = 'cross_tenant_grant';
+const NEW_ACTIONS = ['share', 'accept', 'revoke'];
+const NEW_KEYS = NEW_ACTIONS.map((a) => `${MODULE}:${TYPE_KEY}:${a}`);
+
+/** Coarse identity-admin keys — matched by exact string, mirroring astram3's deleted
+ *  `DbGrantAuthorityResolver`'s `COMPANY_ADMIN_KEYS`. */
+const OLD_ADMIN_KEYS = [
+  'identity:company:update',
+  'identity:company:delete',
+  'identity:company:*',
+  'identity:*',
+  'identity',
+];
+
+async function up({ query }) {
+  // Every DISTINCT role currently holding ANY of the coarse identity-admin keys.
+  const oldAdminKeyPlaceholders = OLD_ADMIN_KEYS.map(() => '?').join(', ');
+  const adminRoles = await query(
+    `SELECT DISTINCT rp_role_uuid AS role_uuid
+       FROM \`${AUTHZ}\`.\`role_permission\`
+      WHERE rp_perm_key IN (${oldAdminKeyPlaceholders})`,
+    [...OLD_ADMIN_KEYS],
+  );
+
+  for (const { role_uuid: roleUuid } of adminRoles) {
+    for (const key of NEW_KEYS) {
+      await query(
+        `INSERT INTO \`${AUTHZ}\`.\`role_permission\` (rp_uuid, rp_role_uuid, rp_perm_key)
+         SELECT UUID(), ?, ?
+          WHERE NOT EXISTS (
+            SELECT 1 FROM \`${AUTHZ}\`.\`role_permission\`
+             WHERE rp_role_uuid = ? AND rp_perm_key = ?)`,
+        [roleUuid, key, roleUuid, key],
+      );
+    }
+  }
+}
+
+async function down({ query }) {
+  const keyPlaceholders = NEW_KEYS.map(() => '?').join(', ');
+  await query(
+    `DELETE FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_perm_key IN (${keyPlaceholders})`,
+    [...NEW_KEYS],
+  );
+}
+
+module.exports = { up, down };

package/migrations/1710000000013-CreateSharedResource.cjs

@@ -0,0 +1,30 @@
+/**
+ * Framework migration — the `shield_app`.`shared_resource` table.
+ *
+ * `shared_resource` is the framework's minimal `tenantScoped`/offerable demo object type
+ * (see `src/shared-resource.object.ts`): the first offerable resource so cross-tenant
+ * grants have something to offer (all nine identity types are `system`/non-offerable).
+ *
+ * Columns EXACTLY mirror the @ObjectType's declared @Field columns (entity↔migration sync
+ * is absolute): sr_uuid (PK), sr_tenant_id (trusted:'tenantId', server-stamped), sr_label.
+ * The `shield_app` schema already exists (created by 1710000000001) — this migration owns
+ * only the table, not the schema. Idempotent (IF NOT EXISTS); down() drops the table.
+ */
+
+const SCHEMA = 'shield_app';
+
+async function up({ query }) {
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`shared_resource\` (
+    sr_uuid      VARCHAR(36)  NOT NULL,
+    sr_tenant_id VARCHAR(36)  NOT NULL,
+    sr_label     VARCHAR(255) NOT NULL,
+    PRIMARY KEY (sr_uuid),
+    INDEX idx_sr_tenant (sr_tenant_id)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`shared_resource\``);
+}
+
+module.exports = { up, down };