@astram/identity 0.8.0 → 0.9.0

package/dist/features/shared/identity-error.interceptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-error.interceptor.d.ts","sourceRoot":"","sources":["../../../src/features/shared/identity-error.interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAQL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AAqB/D;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAwBzD;AAED,qBACa,wBAAyB,YAAW,eAAe;IAC9D,SAAS,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CAK9E"}
+{"version":3,"file":"identity-error.interceptor.d.ts","sourceRoot":"","sources":["../../../src/features/shared/identity-error.interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAQL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AAsB/D;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAyBzD;AAED,qBACa,wBAAyB,YAAW,eAAe;IAC9D,SAAS,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CAK9E"}

package/dist/features/shared/identity-error.interceptor.js

@@ -55,6 +55,8 @@ function toIdentityHttpError(err) {
         return new common_1.ConflictException(err.message);
     if (err instanceof identity_errors_js_1.IdentityBadRequestError)
         return new common_1.BadRequestException(err.message);
+    if (err instanceof identity_errors_js_1.IdentityUnavailableError)
+        return new common_1.ServiceUnavailableException(err.message);
     if (err instanceof guard_1.ScopeCycleError) {
         return new common_1.ConflictException('That move would put an organisation inside its own sub-tree.');
     }

package/dist/features/shared/identity-errors.d.ts

@@ -16,6 +16,14 @@ export declare class IdentityNotFoundError extends Error {
 export declare class IdentityConflictError extends Error {
     constructor(message: string);
 }
+/**
+ * A store the action needs could not answer (a deadlock, a lock timeout, an outage) and nothing
+ * was changed (→ 503, retryable). The message is fixed: never the driver's text, which can name
+ * the values written.
+ */
+export declare class IdentityUnavailableError extends Error {
+    constructor(message: string);
+}
 /** The request is malformed (→ 400). */
 export declare class IdentityBadRequestError extends Error {
     constructor(message: string);

package/dist/features/shared/identity-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-errors.d.ts","sourceRoot":"","sources":["../../../src/features/shared/identity-errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qEAAqE;AACrE,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,6FAA6F;AAC7F,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,uFAAuF;AACvF,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,wCAAwC;AACxC,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B"}
+{"version":3,"file":"identity-errors.d.ts","sourceRoot":"","sources":["../../../src/features/shared/identity-errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qEAAqE;AACrE,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,6FAA6F;AAC7F,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,uFAAuF;AACvF,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,wCAAwC;AACxC,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/features/shared/identity-errors.js

@@ -6,7 +6,7 @@
  * Messages are user-facing: they name no raw ids (ADR-0012) and carry no store detail.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IdentityBadRequestError = exports.IdentityConflictError = exports.IdentityNotFoundError = exports.IdentityForbiddenError = void 0;
+exports.IdentityBadRequestError = exports.IdentityUnavailableError = exports.IdentityConflictError = exports.IdentityNotFoundError = exports.IdentityForbiddenError = void 0;
 /** The caller may not perform this action on this target (→ 403). */
 class IdentityForbiddenError extends Error {
     constructor(message) {
@@ -31,6 +31,18 @@ class IdentityConflictError extends Error {
     }
 }
 exports.IdentityConflictError = IdentityConflictError;
+/**
+ * A store the action needs could not answer (a deadlock, a lock timeout, an outage) and nothing
+ * was changed (→ 503, retryable). The message is fixed: never the driver's text, which can name
+ * the values written.
+ */
+class IdentityUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IdentityUnavailableError';
+    }
+}
+exports.IdentityUnavailableError = IdentityUnavailableError;
 /** The request is malformed (→ 400). */
 class IdentityBadRequestError extends Error {
     constructor(message) {

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

@@ -45,6 +45,8 @@ export declare class UserService {
      * 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
      * by the engine's create wall (a company outside the caller's subtree ⇒ 403, nothing persists).
+     * A username already taken (KI #87: also a concurrent create of the same one; the unique index
+     * decides) ⇒ {@link IdentityConflictError} (409), nothing persists.
      */
     createUser(actor: Principal, input: {
         username: string;
@@ -64,6 +66,8 @@ export declare class UserService {
      * (engine shape, fail closed). Reset links are burned BEFORE (a failure aborts the change).
      */
     private changeEmail;
+    /** The helper call with the audit row on its transaction (see {@link changeEmail}). */
+    private applyEmailChange;
     /**
      * 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,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"}
+{"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,EAExB,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;AAqCzD,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;;;;;;OAMG;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;IAkBpB,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;IAyBzB,uFAAuF;IACvF,OAAO,CAAC,gBAAgB;IA8BxB;;;;;;;;;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

@@ -22,6 +22,31 @@ 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");
+/**
+ * KI #87: `users` has two unique keys besides the PK, `IDX_users_username` (migration 001) and
+ * `uq_users_email` (021, `utf8mb4_unicode_ci`: folds case, accents, width, trailing spaces). The
+ * engine passes the driver's duplicate-key error through unchanged; this service, which knows
+ * those are the only keys a user write can collide on, answers it as a 409 with a fixed text.
+ * Recognised by errno/code only: the driver's message names the value and is never echoed.
+ */
+function isDuplicateKey(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const e = err;
+    return e.errno === 1062 || e.code === 'ER_DUP_ENTRY';
+}
+const USERNAME_OR_EMAIL_TAKEN = 'That username or email is already in use.';
+/** Run a user write; a duplicate key becomes {@link IdentityConflictError}, all else rethrows. */
+async function mappingDuplicates(write) {
+    try {
+        return await write();
+    }
+    catch (err) {
+        if (isDuplicateKey(err))
+            throw new identity_errors_js_1.IdentityConflictError(USERNAME_OR_EMAIL_TAKEN);
+        throw err;
+    }
+}
 const USER_SEARCH_FIELDS = ['username', 'email'];
 const USER_SORT_FIELDS = ['username', 'email', 'status', 'createdAt'];
 /**
@@ -67,19 +92,21 @@ let UserService = UserService_1 = class UserService {
      * 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
      * by the engine's create wall (a company outside the caller's subtree ⇒ 403, nothing persists).
+     * A username already taken (KI #87: also a concurrent create of the same one; the unique index
+     * decides) ⇒ {@link IdentityConflictError} (409), nothing persists.
      */
     async createUser(actor, input) {
         if (!input.companyUuid) {
-            return this.records.create('user', { fields: { username: input.username } });
+            return mappingDuplicates(() => this.records.create('user', { fields: { username: input.username } }));
         }
         const companyUuid = input.companyUuid;
-        return this.records.transaction(async (tx) => {
+        return mappingDuplicates(() => this.records.transaction(async (tx) => {
             const id = await tx.create('user', { fields: { username: input.username } });
             await tx.create('company_membership', {
                 fields: { userUuid: id, companyUuid, isActive: true, status: 'active' },
             });
             return id;
-        });
+        }));
     }
     /** List users (tenant-scoped by the pipe), with paging/search/sort. */
     listUsers(params) {
@@ -121,7 +148,7 @@ let UserService = UserService_1 = class UserService {
         if (emailChanged)
             await this.changeEmail(actor, uuid, newEmail);
         if (Object.keys(fields).length > 0) {
-            await this.records.update('user', uuid, { fields });
+            await mappingDuplicates(() => this.records.update('user', uuid, { fields }));
         }
         if (statusChanged || wantsInactive)
             await this.applyStatusChange(uuid, String(patch.status));
@@ -143,7 +170,26 @@ let UserService = UserService_1 = class UserService {
         }
         if (this.resetTokens)
             await this.resetTokens.invalidateAllForPrincipal(uuid);
-        const outcome = await changer.change({
+        let outcome;
+        try {
+            outcome = await this.applyEmailChange(changer, actor, uuid, newEmail);
+        }
+        catch {
+            // The helper's contract: a throw is a store error (a 1213 deadlock, the named-lock timeout,
+            // the audit write), rolled back. Retryable → 503; the driver text (it can name the address)
+            // is neither returned nor logged.
+            this.logger.warn('admin email change could not be applied (store error); nothing changed');
+            throw new identity_errors_js_1.IdentityUnavailableError('The email address could not be changed right now. Try again.');
+        }
+        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.');
+    }
+    /** The helper call with the audit row on its transaction (see {@link changeEmail}). */
+    applyEmailChange(changer, actor, uuid, newEmail) {
+        return changer.change({
             principalId: uuid,
             newEmail,
             withinTransaction: async (query, result) => {
@@ -165,11 +211,6 @@ let UserService = UserService_1 = class UserService {
                 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

package/migrations/1710000000021-AddUsersEmailUniqueIndex.cjs

@@ -0,0 +1,145 @@
+/**
+ * Framework identity migration — `UNIQUE INDEX uq_users_email (u_email)` on `shield_app.users`
+ * (KI #87, follow-up to security hardening Phase 12 / KI #14).
+ *
+ * WHY: `u_email` (VARCHAR(255) NULL, created by `...001`) had no index and no uniqueness, so two
+ * users could hold the same address (a concurrent create, a direct SQL write) and every collision
+ * read scanned the table. The email is a credential attribute (forgot-password mails it), so
+ * uniqueness is now a database guarantee: a duplicate write fails with ER_DUP_ENTRY (1062).
+ *
+ * WHAT COUNTS AS EQUAL is the column collation, `utf8mb4_unicode_ci` (PAD SPACE), probed live on
+ * MariaDB 11.4: case (`A` = `a`), trailing spaces (`a@x.com ` = `a@x.com`), full-width forms
+ * (`ａ` = `a`), accents (`é` = `e`), `ß` = `ss`, ligatures and ignorable characters (a zero-width
+ * space, a trailing no-break space) all fold. NOT folded: LEADING spaces and other trailing
+ * whitespace (tab, newline). The app writes `canonicalEmail` (trim → NFKC → lower-case), so those
+ * never reach the column through the framework.
+ *
+ * Steps (inside the runner's ONE transaction for this migration, `@astram/migrate`):
+ *   0. Skip entirely when `uq_users_email` already exists as a UNIQUE index (idempotent re-run).
+ *   1. Normalise empty / whitespace-only `u_email` to NULL (`''` and `'   '` are collation-equal
+ *      and would collide; NULLs may repeat in a UNIQUE index).
+ *   2. PRE-CHECK: `GROUP BY u_email HAVING COUNT(*) > 1` (grouped by the same collation the index
+ *      uses). Any group ⇒ the migration THROWS, listing each group as a MASKED address
+ *      (`a***@example.com`) and a count — never a user id, never a full address. The throw rolls
+ *      the transaction back, so step 1 is undone too and NO row is changed. Duplicates are never
+ *      auto-resolved: the operator gives each user a distinct address (e.g. the admin user edit)
+ *      and re-runs.
+ *   3. `ADD UNIQUE INDEX IF NOT EXISTS` (DDL: implicit commit of step 1). A duplicate written
+ *      between step 2 and the build fails the build with 1062; it is reported the same masked way
+ *      (the driver's own message would echo the full address). On THAT late path step 1 is already
+ *      committed (blanks stay NULL); the report says so, and a re-run is safe.
+ *
+ * `down` drops the index only (`DROP INDEX IF EXISTS`). The NULL normalisation is NOT reverted:
+ * an empty address and NULL mean the same thing (no email), and the original values are gone.
+ *
+ * Literal schema/table/column names, parameterized values, no ids. Run by the DDL account
+ * (`shield_migrate`: DDL + DML on `shield_app`). `shield_core` / `shield_app_crud` need no new
+ * grant. Sorts after `...001` (creates `users`) and `...020` (the latest), before the dev seeds
+ * (`...099`/`...100`, distinct addresses).
+ */
+
+const SCHEMA = 'shield_app';
+const TABLE = 'users';
+const COLUMN = 'u_email';
+const INDEX = 'uq_users_email';
+const MIGRATION = '1710000000021-AddUsersEmailUniqueIndex';
+/** Groups listed in the failure message; the rest are counted. */
+const MAX_LISTED_GROUPS = 50;
+const ER_DUP_ENTRY = 1062;
+
+/** Same rule as `@astram/guard` `maskEmail` (kept local: a migration loads no runtime package). */
+function maskEmail(value) {
+  const at = value.lastIndexOf('@');
+  if (at <= 0 || at === value.length - 1) return '***';
+  return `${value.slice(0, 1)}***@${value.slice(at + 1)}`;
+}
+
+/** `null` = no index of that name; otherwise whether it is UNIQUE. */
+async function indexState(query) {
+  const rows = await query(
+    `SELECT NON_UNIQUE AS non_unique
+       FROM information_schema.STATISTICS
+      WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND INDEX_NAME = ?
+      LIMIT 1`,
+    [SCHEMA, TABLE, INDEX],
+  );
+  if (!Array.isArray(rows) || rows.length === 0) return null;
+  return { unique: Number(rows[0].non_unique) === 0 };
+}
+
+/** Duplicate groups by the column collation: `[{ masked, count }]`, largest first. */
+async function duplicateGroups(query) {
+  const rows = await query(
+    `SELECT ${COLUMN} AS sample, COUNT(*) AS n
+       FROM \`${SCHEMA}\`.\`${TABLE}\`
+      WHERE ${COLUMN} IS NOT NULL
+      GROUP BY ${COLUMN}
+     HAVING COUNT(*) > 1
+      ORDER BY n DESC`,
+  );
+  // The group's representative is any member; trim it so a padded one masks the same way.
+  return (Array.isArray(rows) ? rows : []).map((r) => ({
+    masked: maskEmail(String(r.sample).trim()),
+    count: Number(r.n),
+  }));
+}
+
+function duplicateError(groups, emptiesNormalised) {
+  const listed = groups.slice(0, MAX_LISTED_GROUPS).map((g) => `  - ${g.masked}: ${g.count} users`);
+  if (groups.length > MAX_LISTED_GROUPS) {
+    listed.push(`  - ... and ${groups.length - MAX_LISTED_GROUPS} more group(s)`);
+  }
+  const changed = emptiesNormalised
+    ? 'No index was created and no duplicate was modified (empty or whitespace-only addresses were set to NULL).'
+    : 'No index was created and no row was changed.';
+  return new Error(
+    `${MIGRATION}: cannot add UNIQUE index ${INDEX} on ${SCHEMA}.${TABLE}.${COLUMN}: ` +
+      `${groups.length} email address(es) are held by more than one user ` +
+      '(compared as the column collation utf8mb4_unicode_ci does: case-, accent-, width- and ' +
+      'trailing-space-insensitive; addresses masked):\n' +
+      `${listed.join('\n')}\n` +
+      `${changed} Give each of these users a distinct address or clear it (for example with the ` +
+      'administrator user edit, PUT /identity/users/:uuid), then re-run astram-migrate. ' +
+      'See "Upgrading from 0.9.x" in the create-astram-app README.',
+  );
+}
+
+async function up({ query }) {
+  const state = await indexState(query);
+  if (state !== null) {
+    if (state.unique) return; // already applied (idempotent re-run)
+    throw new Error(
+      `${MIGRATION}: ${SCHEMA}.${TABLE} has a NON-unique index named ${INDEX}; ` +
+        'drop or rename it, then re-run astram-migrate.',
+    );
+  }
+
+  await query(
+    `UPDATE \`${SCHEMA}\`.\`${TABLE}\`
+        SET ${COLUMN} = NULL
+      WHERE ${COLUMN} IS NOT NULL AND ${COLUMN} REGEXP '^[[:space:]]*$'`,
+  );
+
+  const groups = await duplicateGroups(query);
+  if (groups.length > 0) throw duplicateError(groups, false);
+
+  try {
+    await query(
+      `ALTER TABLE \`${SCHEMA}\`.\`${TABLE}\` ADD UNIQUE INDEX IF NOT EXISTS \`${INDEX}\` (${COLUMN})`,
+    );
+  } catch (err) {
+    if (err === null || typeof err !== 'object' || err.errno !== ER_DUP_ENTRY) throw err;
+    // A duplicate was written after the pre-check. Never surface the driver message (full address).
+    const late = await duplicateGroups(query);
+    if (late.length > 0) throw duplicateError(late, true);
+    throw new Error(
+      `${MIGRATION}: a duplicate ${COLUMN} was written while the index was built; re-run astram-migrate.`,
+    );
+  }
+}
+
+async function down({ query }) {
+  await query(`ALTER TABLE \`${SCHEMA}\`.\`${TABLE}\` DROP INDEX IF EXISTS \`${INDEX}\``);
+}
+
+module.exports = { up, down };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/identity",
-  "version": "0.8.0",
+  "version": "0.9.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,9 +36,9 @@
   },
   "dependencies": {
     "mariadb": "^3.5.4",
-    "@astram/guard": "0.11.0",
     "@astram/core": "1.4.0",
-    "@astram/engine": "0.5.2"
+    "@astram/engine": "0.5.2",
+    "@astram/guard": "0.11.2"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",