@astram/identity 0.1.0

package/dist/role.object.js

@@ -0,0 +1,42 @@
+"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.Role = void 0;
+const engine_1 = require("@astram/engine");
+const schema_1 = require("./schema");
+/** roles — global catalog. */
+let Role = class Role {
+    uuid;
+    name;
+    createdAt;
+};
+exports.Role = Role;
+__decorate([
+    (0, engine_1.Field)({ column: 'r_uuid', type: 'uuid', role: 'primaryKey' }),
+    __metadata("design:type", String)
+], Role.prototype, "uuid", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'r_name', type: 'string', required: true }),
+    __metadata("design:type", String)
+], Role.prototype, "name", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'r_created_at', type: 'timestamp' }),
+    __metadata("design:type", String)
+], Role.prototype, "createdAt", void 0);
+exports.Role = Role = __decorate([
+    (0, engine_1.ObjectType)({
+        typeKey: 'role',
+        table: 'roles',
+        schema: schema_1.SCHEMA,
+        access: { plane: 'control', system: true },
+    }),
+    (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'r_uuid' })
+], Role);

package/dist/schema.d.ts

@@ -0,0 +1,3 @@
+/** The physical schema every identity table lives in (single-source). */
+export declare const SCHEMA = "shield_app";
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,eAAO,MAAM,MAAM,eAAe,CAAC"}

package/dist/schema.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA = void 0;
+/** The physical schema every identity table lives in (single-source). */
+exports.SCHEMA = 'shield_app';

package/dist/user.object.d.ts

@@ -0,0 +1,13 @@
+/**
+ * users — the principal. `u_uuid` links to identity_credential.ic_principal_id
+ * (the hash lives framework-side). Users are not tenant-stamped (they belong to
+ * many companies via company_membership); scoping is via the membership, not a column.
+ */
+export declare class User {
+    uuid: string;
+    username: string;
+    email: string;
+    status: string;
+    createdAt: string;
+}
+//# sourceMappingURL=user.object.d.ts.map

package/dist/user.object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.object.d.ts","sourceRoot":"","sources":["../src/user.object.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAUa,IAAI;IAEf,IAAI,EAAG,MAAM,CAAC;IAGd,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;IAGf,MAAM,EAAG,MAAM,CAAC;IAGhB,SAAS,EAAG,MAAM,CAAC;CACpB"}

package/dist/user.object.js

@@ -0,0 +1,59 @@
+"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.User = void 0;
+const engine_1 = require("@astram/engine");
+const schema_1 = require("./schema");
+/**
+ * users — the principal. `u_uuid` links to identity_credential.ic_principal_id
+ * (the hash lives framework-side). Users are not tenant-stamped (they belong to
+ * many companies via company_membership); scoping is via the membership, not a column.
+ */
+let User = class User {
+    uuid;
+    username;
+    email;
+    status;
+    createdAt;
+};
+exports.User = User;
+__decorate([
+    (0, engine_1.Field)({ column: 'u_uuid', type: 'uuid', role: 'primaryKey' }),
+    __metadata("design:type", String)
+], User.prototype, "uuid", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'u_username', type: 'string', required: true, role: 'username' }),
+    __metadata("design:type", String)
+], User.prototype, "username", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'u_email', type: 'string' }),
+    __metadata("design:type", String)
+], User.prototype, "email", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'u_status', type: 'string', role: 'status' }),
+    __metadata("design:type", String)
+], User.prototype, "status", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'u_created_at', type: 'timestamp' }),
+    __metadata("design:type", String)
+], User.prototype, "createdAt", void 0);
+exports.User = User = __decorate([
+    (0, engine_1.ObjectType)({
+        typeKey: 'user',
+        table: 'users',
+        schema: schema_1.SCHEMA,
+        // plane:'control' — `user` is identity administration (the identity-administrator model: the
+        // capped root, the identity administrator, may list/read AND create/update/delete users). Uniform
+        // across all actions (read reclassified control 2026-07-16), so plane is per-type.
+        access: { plane: 'control', system: true },
+    }),
+    (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'u_uuid' })
+], User);

package/migrations/1710000000001-CreateIdentityOrgModel.cjs

@@ -0,0 +1,100 @@
+/**
+ * Framework identity migration — the org/identity core in `shield_app`.
+ *
+ * Creates companies (the tenant), users (the principal; login hash lives in
+ * shield_identity.identity_credential), and the global catalogs roles/departments/
+ * branches. Final shape — NO legacy junctions (user_companies/user_company_roles/
+ * company_roles/user_departments/user_branches are never created; the first-class
+ * membership model is created by 1710000000002).
+ *
+ * Framework-owned (relocated from astram3 migration 1720000000001 + the superuser flag
+ * from 1720000000007). Table/column names are read from the @astram/identity object
+ * registry so the DDL and runtime queries share one source of truth. Idempotent
+ * (IF NOT EXISTS). No hardcoded uuids. Schema is qualified explicitly (shield_app).
+ */
+const { Company, User, Role, Department, Branch } = require('@astram/identity');
+const { columnForRole, reflectObjectType } = require('@astram/engine');
+
+const SCHEMA = 'shield_app';
+const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
+
+// Reflect the @ObjectType/@Field metadata off each decorated class into its registration
+// (`{ typeKey, table, fields, primaryKey, access }`) ONCE — `columnForRole`/`.table` read
+// this registration, not the raw class (the class itself carries no static `.table`).
+const CompanyReg = reflectObjectType(Company);
+const UserReg = reflectObjectType(User);
+const RoleReg = reflectObjectType(Role);
+const DepartmentReg = reflectObjectType(Department);
+const BranchReg = reflectObjectType(Branch);
+
+// Resolve a column by role from a reflected object registration (single source of truth).
+const col = (reg, role) => columnForRole(reg, role);
+
+async function up({ query }) {
+  // companies (the tenant) — hierarchy + type + status.
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${CompanyReg.table}\` (
+    ${col(CompanyReg, 'primaryKey')} VARCHAR(36)  NOT NULL,
+    c_name        VARCHAR(200) NOT NULL,
+    c_parent_uuid VARCHAR(36)  NULL,
+    c_type        VARCHAR(50)  NOT NULL DEFAULT 'standard',
+    ${col(CompanyReg, 'status')}   VARCHAR(20)  NOT NULL DEFAULT 'active',
+    c_created_at  ${TS},
+    PRIMARY KEY (${col(CompanyReg, 'primaryKey')}),
+    INDEX idx_companies_parent (c_parent_uuid),
+    INDEX idx_companies_status (${col(CompanyReg, 'status')}),
+    CONSTRAINT FK_companies_parent FOREIGN KEY (c_parent_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${CompanyReg.table}\` (${col(CompanyReg, 'primaryKey')}) ON DELETE SET NULL
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  // users (the principal). u_is_platform_superuser is the capped-root source of truth
+  // (read by the app policy layer via SQL, not an object field) — created here so the
+  // framework owns the column, DEFAULT 0.
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${UserReg.table}\` (
+    ${col(UserReg, 'primaryKey')} VARCHAR(36)  NOT NULL,
+    ${col(UserReg, 'username')}   VARCHAR(150) NOT NULL,
+    u_email      VARCHAR(255) NULL,
+    ${col(UserReg, 'status')}     VARCHAR(20)  NOT NULL DEFAULT 'active',
+    u_created_at ${TS},
+    u_is_platform_superuser TINYINT(1) NOT NULL DEFAULT 0,
+    PRIMARY KEY (${col(UserReg, 'primaryKey')}),
+    UNIQUE KEY IDX_users_username (${col(UserReg, 'username')}),
+    INDEX idx_users_status (${col(UserReg, 'status')})
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  // roles — global catalog.
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${RoleReg.table}\` (
+    ${col(RoleReg, 'primaryKey')} VARCHAR(36)  NOT NULL,
+    r_name       VARCHAR(150) NOT NULL,
+    r_created_at ${TS},
+    PRIMARY KEY (${col(RoleReg, 'primaryKey')}),
+    UNIQUE KEY IDX_roles_name (r_name)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  // departments — global catalog.
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${DepartmentReg.table}\` (
+    ${col(DepartmentReg, 'primaryKey')} VARCHAR(36)  NOT NULL,
+    d_name       VARCHAR(150) NOT NULL,
+    d_created_at ${TS},
+    PRIMARY KEY (${col(DepartmentReg, 'primaryKey')}),
+    UNIQUE KEY IDX_departments_name (d_name)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  // branches — global catalog.
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${BranchReg.table}\` (
+    ${col(BranchReg, 'primaryKey')} VARCHAR(36)  NOT NULL,
+    b_name       VARCHAR(150) NOT NULL,
+    b_created_at ${TS},
+    PRIMARY KEY (${col(BranchReg, 'primaryKey')}),
+    UNIQUE KEY IDX_branches_name (b_name)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  // Reverse dependency order — membership tables (1710000000002) drop first via their
+  // own down(); here drop the catalogs + principal + tenant.
+  for (const t of [BranchReg.table, DepartmentReg.table, RoleReg.table, UserReg.table, CompanyReg.table]) {
+    await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`${t}\``);
+  }
+}
+
+module.exports = { up, down };

package/migrations/1710000000002-CreateMembershipAndPostings.cjs

@@ -0,0 +1,111 @@
+/**
+ * Framework identity migration — first-class membership + postings + company junctions
+ * in `shield_app`. Runs AFTER 1710000000001 (needs users/companies/roles/dept/branch).
+ *
+ * company_membership — the membership card (active-tenant pointer via cm_is_active).
+ * membership_posting — the time-bounded role+dept?+branch? assignment. The effective
+ *   window is BIGINT epoch-ms (mp_effective_from_ms/until_ms) — final shape, timezone-
+ *   immune (relocated from astram3 -005 + -050). company_departments/company_branches —
+ *   tenant-scoped catalog junctions (from -001).
+ *
+ * Framework-owned. Names from the @astram/identity registry. Idempotent. No uuids.
+ */
+const {
+  Company, User, Role, Department, Branch,
+  CompanyMembership, MembershipPosting, CompanyDepartment, CompanyBranch,
+} = require('@astram/identity');
+const { columnForRole, reflectObjectType } = require('@astram/engine');
+
+const SCHEMA = 'shield_app';
+const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
+
+// The decorated classes carry NO static `.table` — @ObjectType/@Field metadata is read
+// via reflectObjectType() into a registration ({ typeKey, table, fields, primaryKey }).
+// columnForRole + the table name both read that registration, NOT the raw class. Reflect
+// each once at module scope. (Task 3 hit this: `Company.table` is undefined on the class.)
+const CompanyReg = reflectObjectType(Company);
+const UserReg = reflectObjectType(User);
+const RoleReg = reflectObjectType(Role);
+const DepartmentReg = reflectObjectType(Department);
+const BranchReg = reflectObjectType(Branch);
+const CompanyMembershipReg = reflectObjectType(CompanyMembership);
+const MembershipPostingReg = reflectObjectType(MembershipPosting);
+const CompanyDepartmentReg = reflectObjectType(CompanyDepartment);
+const CompanyBranchReg = reflectObjectType(CompanyBranch);
+const col = (reg, role) => columnForRole(reg, role);
+
+async function up({ query }) {
+  // company_membership — first-class membership + active-tenant pointer.
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${CompanyMembershipReg.table}\` (
+    ${col(CompanyMembershipReg, 'primaryKey')} VARCHAR(36) NOT NULL,
+    cm_user_uuid    VARCHAR(36) NOT NULL,
+    cm_company_uuid VARCHAR(36) NOT NULL,
+    ${col(CompanyMembershipReg, 'active')} TINYINT(1) NOT NULL DEFAULT 0,
+    ${col(CompanyMembershipReg, 'status')} VARCHAR(20) NOT NULL DEFAULT 'active',
+    cm_created_at   ${TS},
+    cm_created_by   VARCHAR(36) NULL,
+    PRIMARY KEY (${col(CompanyMembershipReg, 'primaryKey')}),
+    UNIQUE KEY IDX_cm_user_company (cm_user_uuid, cm_company_uuid),
+    INDEX idx_cm_company (cm_company_uuid),
+    INDEX idx_cm_active (cm_user_uuid, ${col(CompanyMembershipReg, 'active')}),
+    CONSTRAINT FK_cm_user FOREIGN KEY (cm_user_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${UserReg.table}\` (${col(UserReg, 'primaryKey')}) ON DELETE CASCADE,
+    CONSTRAINT FK_cm_company FOREIGN KEY (cm_company_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${CompanyReg.table}\` (${col(CompanyReg, 'primaryKey')}) ON DELETE CASCADE
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  // membership_posting — time-bounded role assignment, epoch-ms window (final shape).
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${MembershipPostingReg.table}\` (
+    ${col(MembershipPostingReg, 'primaryKey')} VARCHAR(36) NOT NULL,
+    mp_membership_uuid VARCHAR(36) NOT NULL,
+    mp_role_uuid       VARCHAR(36) NOT NULL,
+    mp_department_uuid VARCHAR(36) NULL,
+    mp_branch_uuid     VARCHAR(36) NULL,
+    ${col(MembershipPostingReg, 'effectiveFrom')}  BIGINT NULL,
+    ${col(MembershipPostingReg, 'effectiveUntil')} BIGINT NULL,
+    mp_created_at      ${TS},
+    mp_created_by      VARCHAR(36) NULL,
+    PRIMARY KEY (${col(MembershipPostingReg, 'primaryKey')}),
+    UNIQUE KEY IDX_mp_unique (mp_membership_uuid, mp_role_uuid, mp_department_uuid, mp_branch_uuid),
+    INDEX idx_mp_membership (mp_membership_uuid),
+    INDEX idx_mp_role (mp_role_uuid),
+    CONSTRAINT FK_mp_membership FOREIGN KEY (mp_membership_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${CompanyMembershipReg.table}\` (${col(CompanyMembershipReg, 'primaryKey')}) ON DELETE CASCADE,
+    CONSTRAINT FK_mp_role FOREIGN KEY (mp_role_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${RoleReg.table}\` (${col(RoleReg, 'primaryKey')}) ON DELETE CASCADE,
+    CONSTRAINT FK_mp_department FOREIGN KEY (mp_department_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${DepartmentReg.table}\` (${col(DepartmentReg, 'primaryKey')}) ON DELETE SET NULL,
+    CONSTRAINT FK_mp_branch FOREIGN KEY (mp_branch_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${BranchReg.table}\` (${col(BranchReg, 'primaryKey')}) ON DELETE SET NULL
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  // company_departments — tenant-scoped department catalog junction.
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${CompanyDepartmentReg.table}\` (
+    cd_company_uuid    VARCHAR(36) NOT NULL,
+    cd_department_uuid VARCHAR(36) NOT NULL,
+    PRIMARY KEY (cd_company_uuid, cd_department_uuid),
+    CONSTRAINT FK_cd_company FOREIGN KEY (cd_company_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${CompanyReg.table}\` (${col(CompanyReg, 'primaryKey')}) ON DELETE CASCADE,
+    CONSTRAINT FK_cd_department FOREIGN KEY (cd_department_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${DepartmentReg.table}\` (${col(DepartmentReg, 'primaryKey')}) ON DELETE CASCADE
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+
+  // company_branches — tenant-scoped branch catalog junction.
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${CompanyBranchReg.table}\` (
+    cb_company_uuid VARCHAR(36) NOT NULL,
+    cb_branch_uuid  VARCHAR(36) NOT NULL,
+    PRIMARY KEY (cb_company_uuid, cb_branch_uuid),
+    CONSTRAINT FK_cb_company FOREIGN KEY (cb_company_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${CompanyReg.table}\` (${col(CompanyReg, 'primaryKey')}) ON DELETE CASCADE,
+    CONSTRAINT FK_cb_branch FOREIGN KEY (cb_branch_uuid)
+      REFERENCES \`${SCHEMA}\`.\`${BranchReg.table}\` (${col(BranchReg, 'primaryKey')}) ON DELETE CASCADE
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  for (const t of [MembershipPostingReg.table, CompanyBranchReg.table, CompanyDepartmentReg.table, CompanyMembershipReg.table]) {
+    await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`${t}\``);
+  }
+}
+
+module.exports = { up, down };

package/migrations/1710000000003-CreateIdentityCredential.cjs

@@ -0,0 +1,58 @@
+/**
+ * Framework identity migration — the identity_credential table (the login
+ * credential store) in `shield_identity`.
+ *
+ * Relocates the DDL from the retired Docker init-SQL file
+ * `infra/mariadb/init/30-identity-credential.sql` into a proper framework
+ * migration. `shield_identity` is a CORE security schema, NOT shield_app —
+ * login credentials are authentication data, structurally out of reach of the
+ * application accounts (ADR-0014). `shield_core` already holds DML
+ * (SELECT/INSERT/UPDATE/DELETE) on shield_identity (10-accounts-grants.sql),
+ * so the MariaDbCredentialResolver can SELECT this table with no new grant.
+ *
+ * ⛔ SECURITY: only the Argon2id ENCODED hash is stored — never a plaintext
+ * password. TOTP secrets are NOT stored here — the multi-device MFA model
+ * keeps each authenticator's secret in `shield_identity.mfa_device` (created
+ * by 1710000000005).
+ *
+ * This migration carries the CREATE TABLE only — the alice/bob/carol
+ * test-fixture seed rows that lived alongside this DDL in the init-SQL file
+ * are NOT reproduced here; they are re-homed as a dev-only seed in a later
+ * migration.
+ *
+ * NOT in the @astram/identity object registry (engine-internal auth table) —
+ * literal column names, no reflectObjectType, no @astram/identity import.
+ * Idempotent (CREATE TABLE IF NOT EXISTS).
+ */
+
+const SCHEMA = 'shield_identity';
+
+async function up({ query }) {
+  // identity_credential — one row per login principal. Resolved by
+  // ic_identity_hint (username/email) at login. ic_password_hash is the
+  // Argon2id encoded hash the engine verifies against. Whether the principal
+  // must also satisfy a TOTP second factor is derived from their CONFIRMED
+  // shield_identity.mfa_device rows (multi-device MFA), not a column here.
+  await query(
+    `CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`identity_credential\` (
+      \`ic_identity_hint\`  VARCHAR(255) NOT NULL,
+      \`ic_password_hash\`  VARCHAR(255) NOT NULL,
+      \`ic_principal_id\`   VARCHAR(255) NOT NULL,
+      \`ic_tenant_id\`      VARCHAR(255) NOT NULL,
+      \`ic_roles\`          JSON         NOT NULL,
+      \`ic_created_at_ms\`  BIGINT       NOT NULL,
+      \`ic_updated_at_ms\`  BIGINT       NOT NULL,
+      PRIMARY KEY (\`ic_identity_hint\`),
+      -- The login lookup is \`WHERE ic_identity_hint = ? LIMIT 1\`; the PK already
+      -- makes the hint the unique lookup key. A redundant UNIQUE index is stated
+      -- explicitly for the contract's "UNIQUE on ic_identity_hint" invariant.
+      UNIQUE KEY \`IDX_identity_credential_hint\` (\`ic_identity_hint\`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+  );
+}
+
+async function down({ query }) {
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`identity_credential\``);
+}
+
+module.exports = { up, down };

package/migrations/1710000000004-CreateSessionTables.cjs

@@ -0,0 +1,79 @@
+/**
+ * Framework identity migration — durable SESSION + REFRESH-TOKEN tables
+ * (ADR-0013 hybrid storage, ADR-0015 lifetimes + rotation lineage + reuse
+ * detection) in `shield_identity`.
+ *
+ * Relocates the DDL from the retired Docker init-SQL file
+ * `infra/mariadb/init/20-session-tables.sql` into a proper framework
+ * migration. `shield_identity` is a CORE security schema, NOT shield_app —
+ * session/refresh state is authentication data, structurally out of reach of
+ * the application accounts (ADR-0014). `shield_core` already holds DML on
+ * shield_identity (10-accounts-grants.sql), so these tables are
+ * readable/writable by the Session engine's MariaDbSessionRecordStore with no
+ * new grant.
+ *
+ * ⛔ SECURITY: the refresh token itself is NEVER stored — only its keyed HASH
+ * (HMAC-SHA-256, hashed by the app before insert). rt_token_hash holds the hash.
+ *
+ * `session` is created FIRST — `refresh_token` carries FK_refresh_token_session
+ * referencing session(s_session_id), so the parent must exist before the child.
+ *
+ * NOT in the @astram/identity object registry (engine-internal auth tables) —
+ * literal column names, no reflectObjectType, no @astram/identity import.
+ * Idempotent (CREATE TABLE IF NOT EXISTS).
+ */
+
+const SCHEMA = 'shield_identity';
+
+async function up({ query }) {
+  // session — the authoritative session record (written at login; read/updated
+  // at refresh + revocation). s_absolute_expires_at_ms anchors the ADR-0015
+  // absolute cap (from login, never reset). Status ∈ active|rotated|revoked|expired.
+  await query(
+    `CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`session\` (
+      \`s_session_id\`             CHAR(64)     NOT NULL,
+      \`s_principal_id\`           VARCHAR(255) NOT NULL,
+      \`s_tenant_id\`              VARCHAR(255) NOT NULL,
+      \`s_status\`                 ENUM('active','rotated','revoked','expired') NOT NULL DEFAULT 'active',
+      \`s_issued_at_ms\`           BIGINT       NOT NULL,
+      \`s_absolute_expires_at_ms\` BIGINT       NOT NULL,
+      PRIMARY KEY (\`s_session_id\`),
+      KEY \`IDX_session_principal\` (\`s_tenant_id\`, \`s_principal_id\`),
+      KEY \`IDX_session_status\`    (\`s_status\`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+  );
+
+  // refresh_token — one row per minted refresh token, chained by rotation lineage
+  // (ADR-0013/0015). rt_token_hash = the KEYED HASH (never the raw token).
+  // rt_lineage_id chains every rotation of one login; rt_prev_refresh_id points at
+  // the record this one superseded (NULL for the first). Reuse detection = a lookup
+  // by hash that finds a NON-active row → revoke the whole rt_lineage_id.
+  await query(
+    `CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`refresh_token\` (
+      \`rt_refresh_id\`        CHAR(64)     NOT NULL,
+      \`rt_session_id\`        CHAR(64)     NOT NULL,
+      \`rt_lineage_id\`        CHAR(64)     NOT NULL,
+      \`rt_prev_refresh_id\`   CHAR(64)     NULL,
+      \`rt_token_hash\`        CHAR(64)     NOT NULL,
+      \`rt_status\`            ENUM('active','rotated','revoked','expired') NOT NULL DEFAULT 'active',
+      \`rt_issued_at_ms\`      BIGINT       NOT NULL,
+      \`rt_idle_expires_at_ms\` BIGINT      NOT NULL,
+      PRIMARY KEY (\`rt_refresh_id\`),
+      -- Lookup by hash is the hot rotate path; unique so one hash resolves one record.
+      UNIQUE KEY \`IDX_refresh_token_hash\` (\`rt_token_hash\`),
+      KEY \`IDX_refresh_lineage\` (\`rt_lineage_id\`),
+      KEY \`IDX_refresh_session\` (\`rt_session_id\`),
+      CONSTRAINT \`FK_refresh_token_session\`
+        FOREIGN KEY (\`rt_session_id\`) REFERENCES \`${SCHEMA}\`.\`session\` (\`s_session_id\`)
+        ON DELETE CASCADE
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+  );
+}
+
+async function down({ query }) {
+  // Child before parent — refresh_token FK-references session.
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`refresh_token\``);
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`session\``);
+}
+
+module.exports = { up, down };

package/migrations/1710000000005-CreateMfaAndTokenSurface.cjs

@@ -0,0 +1,88 @@
+/**
+ * Framework identity migration — the MFA-device + forgot/reset + MFA-recovery
+ * tables in `shield_identity`: mfa_device, password_reset_token,
+ * mfa_recovery_code.
+ *
+ * Relocates the DDL from astram3 migrations 1720000000004
+ * (CreateMfaDeviceTable) and 1720000000003 (CreateCredentialSurfaceTables)
+ * into framework migrations. All three live in the shield_identity credential
+ * schema (ADR-0014) alongside identity_credential: device secrets,
+ * reset-token hashes, and recovery-code hashes are authentication data that
+ * belongs in the secure framework schema, not the app's org tables. The
+ * runtime shield_core account has DML there, so the consumer's port impls
+ * (MfaDeviceStore / ResetTokenStore / RecoveryCodeStore) INSERT/UPDATE/DELETE
+ * with no extra grant.
+ *
+ * Columns:
+ *  - mfa_device: one row per enrolled authenticator device. md_secret is this
+ *    device's OWN base32 TOTP secret (each device has a distinct secret; login
+ *    matches ANY confirmed device via the consumer's OR-verifier).
+ *    md_confirmed_at_ms NULL = pending (never satisfies login, self-pruned on
+ *    the next begin); set = active. md_last_used_at_ms best-effort stamped
+ *    when a code from this device passes. PK on md_id; index by principal for
+ *    the per-user list/verify.
+ *  - password_reset_token: framework hands a SHA-256 HASH of the raw token
+ *    (never the raw token); TTL enforced on consume via prt_expires_at_ms;
+ *    single-use marked by prt_consumed_at_ms. PK on the hash (one row per
+ *    issued token); index by principal for invalidate-all.
+ *  - mfa_recovery_code: one row per Argon2-hashed one-time recovery code; PK
+ *    (principal, hash) so replaceAll wipes-then-inserts cleanly; single-use
+ *    marked by mrc_consumed_at_ms.
+ *
+ * This clean DDL never created the retired single-secret `ic_totp_secret`
+ * column on identity_credential (the multi-device model stores every TOTP
+ * secret in mfa_device from the start here), so — unlike the astram3 source
+ * migration — there is no DROP COLUMN step to reproduce.
+ *
+ * NOT in the @astram/identity object registry (engine-internal auth tables) —
+ * literal column names, no reflectObjectType, no @astram/identity import.
+ * Idempotent (CREATE TABLE IF NOT EXISTS).
+ */
+
+const SCHEMA = 'shield_identity';
+
+async function up({ query }) {
+  await query(
+    `CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`mfa_device\` (
+      md_id              VARCHAR(36)  NOT NULL,
+      md_principal_id    VARCHAR(255) NOT NULL,
+      md_name            VARCHAR(120) NOT NULL,
+      md_secret          VARCHAR(255) NOT NULL,
+      md_created_at_ms   BIGINT       NOT NULL,
+      md_last_used_at_ms BIGINT       NULL,
+      md_confirmed_at_ms BIGINT       NULL,
+      PRIMARY KEY (md_id),
+      INDEX idx_md_principal (md_principal_id)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+  );
+
+  await query(
+    `CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`password_reset_token\` (
+      prt_token_hash     VARCHAR(255) NOT NULL,
+      prt_principal_id   VARCHAR(255) NOT NULL,
+      prt_expires_at_ms  BIGINT       NOT NULL,
+      prt_consumed_at_ms BIGINT       NULL,
+      prt_created_at_ms  BIGINT       NOT NULL,
+      PRIMARY KEY (prt_token_hash),
+      INDEX idx_prt_principal (prt_principal_id)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+  );
+
+  await query(
+    `CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`mfa_recovery_code\` (
+      mrc_principal_id   VARCHAR(255) NOT NULL,
+      mrc_code_hash      VARCHAR(255) NOT NULL,
+      mrc_consumed_at_ms BIGINT       NULL,
+      mrc_created_at_ms  BIGINT       NOT NULL,
+      PRIMARY KEY (mrc_principal_id, mrc_code_hash)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+  );
+}
+
+async function down({ query }) {
+  for (const t of ['mfa_recovery_code', 'password_reset_token', 'mfa_device']) {
+    await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`${t}\``);
+  }
+}
+
+module.exports = { up, down };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@astram/identity",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Astram framework — the framework-owned identity + tenancy model. Hosts the identity @ObjectType classes (user, company, membership, posting), framework-authored identity migrations, and the identity resolver. Top of the dependency graph: depends on @astram/engine (for @ObjectType/@Field decorators) + @astram/guard / @astram/core (for the auth ports).",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "migrations"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@astram/core": "1.0.0",
+    "@astram/engine": "0.1.0",
+    "@astram/guard": "0.3.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11",
+    "@nestjs/core": "^11",
+    "reflect-metadata": "^0.2",
+    "rxjs": "^7"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/testing": "^11.0.0",
+    "@types/node": "^22.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "typescript": "^5.7.0",
+    "unplugin-swc": "^1.5.1",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "test": "vitest run"
+  }
+}