@astram/identity 0.7.2 → 0.8.0

package/dist/features/identity-feature.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAYL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AA6FxB;;;;;;GAMG;AACH,wBAAgB,0CAA0C,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAUnF;AAiBD;;;;;;;;;;GAUG;AACH,qBACa,qBAAqB;IAChC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,EACb,OAAO,EACP,YAAiB,GAClB,GAAE;QACD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;KACtC,GAAG,aAAa;CA8dvB"}
+{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAYL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AA+FxB;;;;;;GAMG;AACH,wBAAgB,0CAA0C,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAUnF;AAiBD;;;;;;;;;;GAUG;AACH,qBACa,qBAAqB;IAChC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,EACb,OAAO,EACP,YAAiB,GAClB,GAAE;QACD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;KACtC,GAAG,aAAa;CAoevB"}

package/dist/features/identity-feature.module.js

@@ -21,6 +21,7 @@ const company_hierarchy_service_js_1 = require("./company/company-hierarchy.serv
 const role_service_js_1 = require("./role/role.service.js");
 const role_controller_js_1 = require("./role/role.controller.js");
 const user_service_js_1 = require("./user/user.service.js");
+const email_address_changer_token_js_1 = require("./user/email-address-changer.token.js");
 const user_controller_js_1 = require("./user/user.controller.js");
 const membership_controller_js_1 = require("./membership/membership.controller.js");
 const membership_service_js_1 = require("./membership/membership.service.js");
@@ -475,6 +476,12 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
                 org_catalog_service_js_1.OrgCatalogService,
                 record_resolver_js_1.RecordResolverService,
                 { provide: posting_version_bump_js_1.POSTING_VERSION_BUMP, useValue: postingVersionBump },
+                // Phase 12 (KI #14): the admin email change goes through guard's ONE email-change helper
+                // (collision refusal + login-hint follow in one transaction), over the shared authz pool.
+                {
+                    provide: email_address_changer_token_js_1.IDENTITY_EMAIL_ADDRESS_CHANGER,
+                    useValue: new guard_1.MariaDbEmailAddressChanger(authzPool),
+                },
                 // ADR-0035 (GAPS #6): attach the guard's Redis permission-version cache to the ONE shared
                 // bumper, so every committed bump (postings, grants, hierarchy) is published to Redis,
                 // where gate 5 reads it. Provided by the auth surface under `auth: true` (through the

package/dist/features/user/email-address-changer.token.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DI token for the administrator path's email changer (security hardening Phase 12, KI #14):
+ * guard's `MariaDbEmailAddressChanger`, built by `IdentityFeatureModule.forRoot()` over the ONE
+ * shared authz pool and injected into `UserService`. It is the same class guard's
+ * `POST /auth/confirm-email` uses, so the collision and login-hint rules never drift.
+ */
+export declare const IDENTITY_EMAIL_ADDRESS_CHANGER: unique symbol;
+//# sourceMappingURL=email-address-changer.token.d.ts.map

package/dist/features/user/email-address-changer.token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-address-changer.token.d.ts","sourceRoot":"","sources":["../../../src/features/user/email-address-changer.token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,eAA2C,CAAC"}

package/dist/features/user/email-address-changer.token.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_EMAIL_ADDRESS_CHANGER = void 0;
+/**
+ * DI token for the administrator path's email changer (security hardening Phase 12, KI #14):
+ * guard's `MariaDbEmailAddressChanger`, built by `IdentityFeatureModule.forRoot()` over the ONE
+ * shared authz pool and injected into `UserService`. It is the same class guard's
+ * `POST /auth/confirm-email` uses, so the collision and login-hint rules never drift.
+ */
+exports.IDENTITY_EMAIL_ADDRESS_CHANGER = Symbol('IDENTITY_EMAIL_ADDRESS_CHANGER');

package/dist/features/user/user.service.d.ts

@@ -1,6 +1,6 @@
 import { RecordsService, type RecordId } from '@astram/engine';
 import type { Principal } from '@astram/core';
-import { type EmailSender, type ResetTokenStore, type SessionSweeper } from '@astram/guard';
+import { type EmailAddressChanger, type EmailSender, type ResetTokenStore, type SessionSweeper } from '@astram/guard';
 import { type PostingVersionBump } from '../membership/posting-version-bump.js';
 import { type ListParams } from '../shared/list-query.js';
 import { GrantCeiling } from '../authz/grant-ceiling.js';
@@ -23,6 +23,11 @@ export interface UserPatch {
  *   - an email change burns the target's outstanding password-reset tokens BEFORE the change and
  *     notifies the OLD address after it (best-effort), when guard's reset-token store and email
  *     sender are wired (`ShieldModule.forRoot({ auth: true })`).
+ *   - Phase 12 (KI #14): the email itself is written through guard's ONE email-change helper
+ *     (`MariaDbEmailAddressChanger`, the same one `POST /auth/confirm-email` uses): canonical
+ *     address (trim → NFKC → lower-case), collision refusal (409) and login-hint follow in ONE
+ *     transaction, the user's pending self-service tokens burned in it, and an audit row in the
+ *     engine's shape written on that transaction (fail closed). Not wired → the change is refused.
  */
 export declare class UserService {
     private readonly records;
@@ -31,8 +36,11 @@ export declare class UserService {
     private readonly emailSender?;
     private readonly sessions?;
     private readonly versionBump?;
+    private readonly emailAddresses?;
     private readonly logger;
-    constructor(records: RecordsService, ceiling: GrantCeiling, resetTokens?: (ResetTokenStore | null) | undefined, emailSender?: (EmailSender | null) | undefined, sessions?: (SessionSweeper | null) | undefined, versionBump?: (PostingVersionBump | null) | undefined);
+    /** The engine's audit sink, used on the email helper's transaction (no pool of its own). */
+    private readonly emailAudit;
+    constructor(records: RecordsService, ceiling: GrantCeiling, resetTokens?: (ResetTokenStore | null) | undefined, emailSender?: (EmailSender | null) | undefined, sessions?: (SessionSweeper | null) | undefined, versionBump?: (PostingVersionBump | null) | undefined, emailAddresses?: (EmailAddressChanger | null) | undefined);
     /**
      * Create a user. With `companyUuid`, the user is created AND attached (one active membership) in
      * ONE transaction — the onboarding path for a non-root admin, whose membership create is checked
@@ -48,6 +56,14 @@ export declare class UserService {
     getUser(uuid: string): Promise<import("@astram/engine").RecordView | null>;
     /** Update a user (whitelisted patch; username/email/status changes need dominance — class doc). */
     updateUser(actor: Principal, uuid: string, patch: UserPatch): Promise<void>;
+    /**
+     * Phase 12 (KI #14): write a dominated user's new (canonical) email through guard's
+     * email-change helper — ONE transaction that locks the user and credential rows, refuses a
+     * collision with another user's email or login hint (→ 409), moves the login hint when it
+     * equalled the old email, burns the user's pending self-service tokens, and writes the audit row
+     * (engine shape, fail closed). Reset links are burned BEFORE (a failure aborts the change).
+     */
+    private changeEmail;
     /**
      * After a status change (security hardening Phase 3): bump every tenant the user is a member of
      * (the next request reloads its grants: none while disabled, back when re-enabled), and, when the

package/dist/features/user/user.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.service.d.ts","sourceRoot":"","sources":["../../../src/features/user/user.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAMzD,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,qBACa,WAAW;IAIpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAGxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IACY,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAMtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAK1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAnB/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;gBAGpC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY,EAGrB,WAAW,CAAC,GAAE,eAAe,GAAG,IAAI,aAAA,EACK,WAAW,CAAC,GAAE,WAAW,GAAG,IAAI,aAAA,EAMzE,QAAQ,CAAC,GAAE,cAAc,GAAG,IAAI,aAAA,EAKhC,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA;IAG1D;;;;OAIG;IACG,UAAU,CACd,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAC5D,OAAO,CAAC,QAAQ,CAAC;IAcpB,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,mGAAmG;IAC7F,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCjF;;;;;;;;;OASG;YACW,iBAAiB;IAY/B,uDAAuD;IACjD,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/D,6FAA6F;YAC/E,kBAAkB;CAkBjC"}
+{"version":3,"file":"user.service.d.ts","sourceRoot":"","sources":["../../../src/features/user/user.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAOL,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAWzD,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,WAAW;IAMpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAGxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IACY,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAMtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAK1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAI7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAzBlC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,4FAA4F;IAC5F,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;gBAGpC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY,EAGrB,WAAW,CAAC,GAAE,eAAe,GAAG,IAAI,aAAA,EACK,WAAW,CAAC,GAAE,WAAW,GAAG,IAAI,aAAA,EAMzE,QAAQ,CAAC,GAAE,cAAc,GAAG,IAAI,aAAA,EAKhC,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA,EAIvC,cAAc,CAAC,GAAE,mBAAmB,GAAG,IAAI,aAAA;IAG9D;;;;OAIG;IACG,UAAU,CACd,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAC5D,OAAO,CAAC,QAAQ,CAAC;IAcpB,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,mGAAmG;IAC7F,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCjF;;;;;;OAMG;YACW,WAAW;IAmCzB;;;;;;;;;OASG;YACW,iBAAiB;IAY/B,uDAAuD;IACjD,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/D,6FAA6F;YAC/E,kBAAkB;CAkBjC"}

package/dist/features/user/user.service.js

@@ -21,6 +21,7 @@ const posting_version_bump_js_1 = require("../membership/posting-version-bump.js
 const list_query_js_1 = require("../shared/list-query.js");
 const grant_ceiling_js_1 = require("../authz/grant-ceiling.js");
 const identity_errors_js_1 = require("../shared/identity-errors.js");
+const email_address_changer_token_js_1 = require("./email-address-changer.token.js");
 const USER_SEARCH_FIELDS = ['username', 'email'];
 const USER_SORT_FIELDS = ['username', 'email', 'status', 'createdAt'];
 /**
@@ -36,6 +37,11 @@ const USER_SORT_FIELDS = ['username', 'email', 'status', 'createdAt'];
  *   - an email change burns the target's outstanding password-reset tokens BEFORE the change and
  *     notifies the OLD address after it (best-effort), when guard's reset-token store and email
  *     sender are wired (`ShieldModule.forRoot({ auth: true })`).
+ *   - Phase 12 (KI #14): the email itself is written through guard's ONE email-change helper
+ *     (`MariaDbEmailAddressChanger`, the same one `POST /auth/confirm-email` uses): canonical
+ *     address (trim → NFKC → lower-case), collision refusal (409) and login-hint follow in ONE
+ *     transaction, the user's pending self-service tokens burned in it, and an audit row in the
+ *     engine's shape written on that transaction (fail closed). Not wired → the change is refused.
  */
 let UserService = UserService_1 = class UserService {
     records;
@@ -44,14 +50,18 @@ let UserService = UserService_1 = class UserService {
     emailSender;
     sessions;
     versionBump;
+    emailAddresses;
     logger = new common_1.Logger(UserService_1.name);
-    constructor(records, ceiling, resetTokens, emailSender, sessions, versionBump) {
+    /** The engine's audit sink, used on the email helper's transaction (no pool of its own). */
+    emailAudit = new engine_1.MariaDbAuditSink({});
+    constructor(records, ceiling, resetTokens, emailSender, sessions, versionBump, emailAddresses) {
         this.records = records;
         this.ceiling = ceiling;
         this.resetTokens = resetTokens;
         this.emailSender = emailSender;
         this.sessions = sessions;
         this.versionBump = versionBump;
+        this.emailAddresses = emailAddresses;
     }
     /**
      * Create a user. With `companyUuid`, the user is created AND attached (one active membership) in
@@ -91,23 +101,26 @@ let UserService = UserService_1 = class UserService {
         if (usernameChanged)
             fields.username = patch.username;
         const oldEmail = typeof current.fields.email === 'string' ? current.fields.email : '';
-        const emailChanged = typeof patch?.email === 'string' && patch.email !== oldEmail;
+        // Phase 12 (A5): the address is canonicalised once; that value is compared, checked and written.
+        const newEmail = typeof patch?.email === 'string' ? (0, guard_1.canonicalEmail)(patch.email) : undefined;
+        const emailChanged = newEmail !== undefined && newEmail !== (0, guard_1.canonicalEmail)(oldEmail);
+        if (emailChanged && !(0, guard_1.isEmailShaped)(newEmail)) {
+            throw new identity_errors_js_1.IdentityBadRequestError('Enter a valid email address.');
+        }
         const statusChanged = typeof patch?.status === 'string' && patch.status !== current.fields.status;
         // A request for a non-active status ALWAYS runs the follow-up (Phase 3 review P1), even when
         // the stored status already matches: re-sending "disable" repairs a disable whose bump or
         // session revoke failed earlier (idempotent).
         const wantsInactive = typeof patch?.status === 'string' && patch.status !== 'active';
-        if (emailChanged)
-            fields.email = patch.email;
         if (statusChanged)
             fields.status = patch.status;
         if (usernameChanged || emailChanged || statusChanged || wantsInactive) {
             await this.ceiling.assertDominates(actor, uuid);
         }
+        // The email first (the step most likely to be refused, 409), through the ONE helper.
+        if (emailChanged)
+            await this.changeEmail(actor, uuid, newEmail);
         if (Object.keys(fields).length > 0) {
-            // Burn outstanding reset links BEFORE the address changes (a failure aborts the change).
-            if (emailChanged && this.resetTokens)
-                await this.resetTokens.invalidateAllForPrincipal(uuid);
             await this.records.update('user', uuid, { fields });
         }
         if (statusChanged || wantsInactive)
@@ -115,6 +128,49 @@ let UserService = UserService_1 = class UserService {
         if (emailChanged && oldEmail)
             await this.notifyEmailChanged(oldEmail);
     }
+    /**
+     * Phase 12 (KI #14): write a dominated user's new (canonical) email through guard's
+     * email-change helper — ONE transaction that locks the user and credential rows, refuses a
+     * collision with another user's email or login hint (→ 409), moves the login hint when it
+     * equalled the old email, burns the user's pending self-service tokens, and writes the audit row
+     * (engine shape, fail closed). Reset links are burned BEFORE (a failure aborts the change).
+     */
+    async changeEmail(actor, uuid, newEmail) {
+        const changer = this.emailAddresses;
+        if (changer == null) {
+            // Fail closed: never an unchecked write that could collide or strand the login hint.
+            throw new Error('UserService: no email-address changer is wired; email changes are refused');
+        }
+        if (this.resetTokens)
+            await this.resetTokens.invalidateAllForPrincipal(uuid);
+        const outcome = await changer.change({
+            principalId: uuid,
+            newEmail,
+            withinTransaction: async (query, result) => {
+                const event = {
+                    type: 'admin_action',
+                    occurredAtMs: Date.now(),
+                    actorId: actor.id,
+                    tenantId: actor.tenantId,
+                    action: { key: 'update' },
+                    resource: { level: 'record', typeKey: 'user', tenantId: actor.tenantId, recordId: uuid },
+                    attributes: {
+                        op: 'update',
+                        typeKey: 'user',
+                        fields: ['email'],
+                        newEmail: (0, guard_1.maskEmail)(newEmail),
+                        loginHintMoved: result.hintMoved,
+                    },
+                };
+                await this.emailAudit.record(event, (sql, params) => query(sql, params));
+            },
+        });
+        if (outcome.status === 'unavailable') {
+            throw new identity_errors_js_1.IdentityConflictError('That email address is already in use.');
+        }
+        if (outcome.status !== 'changed')
+            throw new identity_errors_js_1.IdentityNotFoundError('User not found.');
+    }
     /**
      * After a status change (security hardening Phase 3): bump every tenant the user is a member of
      * (the next request reloads its grants: none while disabled, back when re-enabled), and, when the
@@ -178,6 +234,8 @@ exports.UserService = UserService = UserService_1 = __decorate([
     __param(4, (0, common_1.Inject)(guard_1.SHIELD_SESSION_SWEEPER)),
     __param(5, (0, common_1.Optional)()),
     __param(5, (0, common_1.Inject)(posting_version_bump_js_1.POSTING_VERSION_BUMP)),
+    __param(6, (0, common_1.Optional)()),
+    __param(6, (0, common_1.Inject)(email_address_changer_token_js_1.IDENTITY_EMAIL_ADDRESS_CHANGER)),
     __metadata("design:paramtypes", [engine_1.RecordsService,
-        grant_ceiling_js_1.GrantCeiling, Object, Object, Object, Object])
+        grant_ceiling_js_1.GrantCeiling, Object, Object, Object, Object, Object])
 ], UserService);

package/migrations/1710000000020-CreateEmailChangeToken.cjs

@@ -0,0 +1,62 @@
+/**
+ * Framework identity migration — `shield_identity.email_change_token` (security hardening
+ * Phase 12, KI #14: verified self-service email change).
+ *
+ * `PATCH /account/profile` with a new email no longer writes `shield_app.users.u_email`; it
+ * stores a single-use, 30-minute token here and mails a confirm link to the NEW address.
+ * `POST /auth/confirm-email` consumes the token and applies the change.
+ *
+ * Columns:
+ *  - ect_token_hash: SHA-256 hex of the raw token (the raw token is never stored). PK, and
+ *    stated UNIQUE explicitly (A11).
+ *  - ect_principal_id: the user (`shield_app.users.u_uuid`). FK with ON DELETE CASCADE so a
+ *    deleted user leaves no pending change behind. The type matches the parent exactly
+ *    (VARCHAR(36), utf8mb4 / utf8mb4_unicode_ci) — InnoDB refuses an FK across mismatched
+ *    string types or collations.
+ *  - ect_new_email: the canonical new address (trim, NFKC, lower-case; A5).
+ *  - ect_old_email: the user's email at request time (A3): confirm refuses when the current
+ *    email no longer equals it (an admin or another flow changed it meanwhile).
+ *  - ect_session_id: the requesting session (`session.s_session_id` is CHAR(64)); confirm keeps
+ *    it and revokes every other session of the user (A7). No FK: a revoked/pruned session must
+ *    not block or cascade the token.
+ *  - ect_tenant_id: the requesting session's tenant (same type as `session.s_tenant_id`). The
+ *    confirm step may run with no session, so its audit rows take the tenant from here
+ *    (`shield_audit.audit_log.al_tenant_id` is NOT NULL).
+ *  - ect_expires_at_ms / ect_consumed_at_ms / ect_created_at_ms: TTL, single use, audit time.
+ *    The expiry index serves the cleanup that runs on every insert (A11).
+ *
+ * The runtime `shield_core` account already holds DML on `shield_identity.*` (no new grant).
+ * NOT in the @astram/identity object registry (engine-internal auth table) — literal column
+ * names. Idempotent (CREATE TABLE IF NOT EXISTS / DROP TABLE IF EXISTS).
+ */
+
+const SCHEMA = 'shield_identity';
+
+async function up({ query }) {
+  await query(
+    `CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`email_change_token\` (
+      ect_token_hash     VARCHAR(64)  NOT NULL,
+      ect_principal_id   VARCHAR(36)  NOT NULL,
+      ect_new_email      VARCHAR(255) NOT NULL,
+      ect_old_email      VARCHAR(255) NULL,
+      ect_session_id     CHAR(64)     NOT NULL,
+      ect_tenant_id      VARCHAR(255) NOT NULL,
+      ect_expires_at_ms  BIGINT       NOT NULL,
+      ect_consumed_at_ms BIGINT       NULL,
+      ect_created_at_ms  BIGINT       NOT NULL,
+      PRIMARY KEY (ect_token_hash),
+      UNIQUE KEY UQ_ect_token_hash (ect_token_hash),
+      INDEX idx_ect_principal (ect_principal_id),
+      INDEX idx_ect_expires (ect_expires_at_ms),
+      CONSTRAINT FK_email_change_token_user
+        FOREIGN KEY (ect_principal_id) REFERENCES \`shield_app\`.\`users\` (u_uuid)
+        ON DELETE CASCADE
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
+  );
+}
+
+async function down({ query }) {
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`email_change_token\``);
+}
+
+module.exports = { up, down };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/identity",
-  "version": "0.7.2",
+  "version": "0.8.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",
@@ -36,8 +36,8 @@
   },
   "dependencies": {
     "mariadb": "^3.5.4",
+    "@astram/guard": "0.11.0",
     "@astram/core": "1.4.0",
-    "@astram/guard": "0.10.2",
     "@astram/engine": "0.5.2"
   },
   "peerDependencies": {