@bevel-software/platform-core-backend 0.27.0 → 0.28.1

package/src/modules/access/access.routes.ts

@@ -21,6 +21,7 @@ import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { AuthService } from '../auth/auth.service.js';
+import type { IAccountSwitchGuard } from '../auth/account-switch-guard.js';
 import type { WorkflowService } from '../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
@@ -51,6 +52,7 @@ import { RolesAdminService } from './roles-admin.service.js';
 import type { Principal } from '../access-model/access-splice.js';
 import type { Database } from '../database/connection.js';
 import { users } from '../database/schema.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
 import '../auth/auth.middleware.js';
 
 /** Verbs the share UI may grant. Verbs are independent — `download` is grantable on its own. */
@@ -85,6 +87,8 @@ export function createAccessRoutes(
   accessControl: IAccessControl,
   workspaceService: WorkspaceService,
   authService: AuthService,
+  /** Auth's switch-off coordination, for the invite's promotion (`ifActive`). */
+  switchGuard: IAccountSwitchGuard,
   workflowService: WorkflowService,
   eventBus: WorkflowEventBus,
   db: Database,
@@ -431,12 +435,15 @@ export function createAccessRoutes(
 
   /**
    * POST /api/workspace/:id/access/batch
-   * Body: `{ paths: string[], verb?: 'write' | 'owner' }`. Returns
+   * Body: `{ paths: string[], verb?: 'write' | 'owner' | 'read' }`. Returns
    * `{ results: { [path]: boolean } }`.
    *
    * `verb` defaults to `write`, the question every existing caller asks.
    * `owner` answers from the `owner:` lists alone — no admin rescue, and a
-   * writer is not an owner — which is what an Owner pill has to mean.
+   * writer is not an owner — which is what an Owner pill has to mean. `read`
+   * is the verdict the single lookup's `canRead` gives, for many paths at
+   * once: what New page asks on a draft branch, where a page may go wherever
+   * its author may read, of every Knowledge folder in one request.
    */
   router.post('/workspace/:id/access/batch', async (req, res) => {
     const user = await requireUser(req, res);
@@ -451,13 +458,18 @@ export function createAccessRoutes(
       res.status(400).json({ error: 'paths cannot exceed 500 entries per request' });
       return;
     }
-    if (verb !== 'write' && verb !== 'owner') {
-      res.status(400).json({ error: 'verb must be "write" or "owner"' });
+    if (verb !== 'write' && verb !== 'owner' && verb !== 'read') {
+      res.status(400).json({ error: 'verb must be "write", "owner" or "read"' });
       return;
     }
 
     try {
-      const batch = verb === 'owner' ? accessControl.canOwnerBatch : accessControl.canWriteBatch;
+      const batch =
+        verb === 'owner'
+          ? accessControl.canOwnerBatch
+          : verb === 'read'
+            ? accessControl.canReadBatch
+            : accessControl.canWriteBatch;
       const result = await batch.call(
         accessControl,
         req.params.id,
@@ -1228,6 +1240,39 @@ export function createAccessRoutes(
     }
   });
 
+  // Who the admins are, for anyone signed in: the top bar tells someone who
+  // is not an admin to ask one, and names them. Names and emails ONLY — the
+  // roster above (every role, its members, groups and references) stays
+  // admin-only. Names come from the accounts table; an admin with no account
+  // yet (a deployment admin before first sign-in, say) is named by address.
+  // A role member whose account is switched off cannot sign in to invite
+  // anyone, so is left out; a deployment admin is not (it signs in with the
+  // environment's password regardless).
+  router.get('/access/admins', async (req, res) => {
+    const user = await requireUser(req, res);
+    if (!user) return;
+    try {
+      const emails = await rolesAdmin.getAdminEmails();
+      const rows =
+        emails.length === 0
+          ? []
+          : await db
+              .select({ email: users.email, name: users.name, deactivatedAt: users.deactivatedAt })
+              .from(users)
+              .where(inArray(users.emailBidx, emails));
+      const names = new Map(rows.map((r) => [canonicalEmail(r.email), r.name?.trim() ?? '']));
+      const off = new Set(rows.filter((r) => r.deactivatedAt).map((r) => canonicalEmail(r.email)));
+      const admins = emails
+        .filter((email) => !off.has(email) || rolesAdmin.isFixedAdmin(email))
+        .map((email) => ({ name: names.get(email) || email, email }))
+        .sort((a, b) => a.name.localeCompare(b.name) || a.email.localeCompare(b.email));
+      res.json({ admins });
+    } catch (err) {
+      const { status, body } = toHttpError(err);
+      res.status(status).json(body);
+    }
+  });
+
   // NOTE: POST /access/roles (create), PATCH /access/roles/:canonical
   // (rename), and DELETE /access/roles/:canonical are GONE — roles are
   // app-defined capabilities, not user-editable objects.
@@ -1239,7 +1284,23 @@ export function createAccessRoutes(
       await assertRolesAdmin(user.email);
       const canonical = canonicalRoleName(req.params.canonical);
       const email = requireNonEmptyString((req.body ?? {}).email, 'email');
-      res.json({ roles: await rolesAdmin.addMember(user, canonical, email) });
+      // `ifActive`: the invite's promotion, which leaves a switched-off
+      // account unchanged. Inside the roles file's lock, auth reads the
+      // account under the address's switch lock and keeps that transaction
+      // open until roles.yaml is written and committed
+      // (`IAccountSwitchGuard.whileSwitchedOn`). So a switch-off either committed
+      // before the read (the promotion is refused) or waits until the
+      // promotion is written (it lands after, as for any Admin switched off
+      // later: the place in roles stays, the credentials stop being honoured).
+      const ifActive = (req.body ?? {}).ifActive;
+      if (ifActive !== undefined && typeof ifActive !== 'boolean') {
+        res.status(400).json({ error: 'ifActive must be a boolean' });
+        return;
+      }
+      const whileSwitchedOn = (write: () => Promise<void>): Promise<void> => switchGuard.whileSwitchedOn(email, write);
+      res.json({
+        roles: await rolesAdmin.addMember(user, canonical, email, ifActive ? { aroundWrite: whileSwitchedOn } : undefined),
+      });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);

package/src/modules/access/roles-admin.service.ts

@@ -103,6 +103,13 @@ export interface RoleRosterEntry {
    * email once, as fixed.
    */
   fixedMembers: string[];
+  /**
+   * The note the page prints beside {@link fixedMembers}, and the sentence
+   * both Admin-membership refusals lead with. Sent with the roster so the
+   * page keeps no copy of the wording. Null when the role has no fixed
+   * members.
+   */
+  fixedMembersNote: string | null;
   /** Canonical names of groups this role is assigned to (`group:` members). */
   groups: string[];
   isAdmin: boolean;
@@ -165,11 +172,12 @@ export class RolesAdminService {
   private readonly fixedAdminEmails: readonly string[];
   /**
    * The one explanation both Admin-role refusals carry, verbatim: the note the
-   * page prints beside a fixed member. Kept as a named constant so the refusal
-   * an API caller reads and the note a UI reader sees cannot drift apart.
+   * page prints beside a fixed member, which it reads from the roster's
+   * `fixedMembersNote`. One constant, so the refusal an API caller reads and
+   * the note a UI reader sees cannot drift apart.
    */
   private static readonly FIXED_ADMIN_NOTE =
-    'Deployment admin, set in the server configuration; cannot be removed here';
+    'Owner; cannot be removed here';
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
@@ -227,9 +235,10 @@ export class RolesAdminService {
   /**
    * Is `email` a deployment admin — an address the server configuration makes
    * an Admin, ahead of `roles.yaml`? Drives both the fixed member rows and
-   * the add/remove refusals on the Admin role.
+   * the add/remove refusals on the Admin role, and keeps a switched-off
+   * deployment admin among the admins people are told to ask.
    */
-  private isFixedAdmin(email: string): boolean {
+  isFixedAdmin(email: string): boolean {
     return this.fixedAdminEmails.includes(canonicalEmail(email));
   }
 
@@ -326,6 +335,8 @@ export class RolesAdminService {
         // Only Admin has fixed members: `deploymentOwners` is an Admin rescue
         // in the resolver, never a general grant, so no other role gains one.
         fixedMembers: isAdmin ? [...this.fixedAdminEmails] : [],
+        fixedMembersNote:
+          isAdmin && this.fixedAdminEmails.length > 0 ? RolesAdminService.FIXED_ADMIN_NOTE : null,
         groups: role.members
           .filter(isGroupRefMember)
           .map((m) => canonicalRoleName(m.slice(GROUP_REF_PREFIX.length))),
@@ -342,6 +353,18 @@ export class RolesAdminService {
     return out;
   }
 
+  /**
+   * The addresses the app treats as an Admin, each once — the resolver's own
+   * membership answer ({@link IAccessControl.adminEmails}), so who this names
+   * and who the admin gates admit cannot drift apart. Nothing else about
+   * roles: this backs a read any signed-in person may make (who to ask for an
+   * invite), unlike the roster.
+   */
+  async getAdminEmails(): Promise<string[]> {
+    const workspaceId = await this.ensureWorkspace();
+    return this.accessControl.adminEmails(workspaceId);
+  }
+
   /**
    * Whether the default-branch roles.yaml parses. Drives the "roles file
    * corrupted" banner. Auth-only (never admin-gated): a corrupted file resolves
@@ -446,10 +469,24 @@ export class RolesAdminService {
    * admits it ahead of `roles.yaml` — so the write would add a row that means
    * nothing, next to the fixed row the page already shows. Other roles are
    * unaffected: a deployment admin is an ordinary member of "Sales".
+   *
+   * `aroundWrite`, when given, runs once the roles file's lock is held and
+   * is handed the edit itself (read, check, write, commit) to run. What it
+   * does around that call brackets the whole write: the invite holds the
+   * address's account-switch lock (a transaction-scoped advisory lock keyed
+   * on the canonical email, see `AuthService.whileSwitchedOn`) across it, so
+   * a switch-off cannot commit in between, whether or not the account exists
+   * yet (see the members route). It may throw instead of calling `write`;
+   * nothing is written then.
    */
-  async addMember(actor: AuthUser, canonical: string, email: string): Promise<RoleRosterEntry[]> {
+  async addMember(
+    actor: AuthUser,
+    canonical: string,
+    email: string,
+    opts?: { aroundWrite?: (write: () => Promise<void>) => Promise<void> },
+  ): Promise<RoleRosterEntry[]> {
     this.assertNotFixedAdmin(canonical, email);
-    await this.runEdit(actor, (text) => editAddMember(text, canonical, email));
+    await this.runEdit(actor, (text) => editAddMember(text, canonical, email), opts?.aroundWrite);
     return this.getRoster();
   }
 
@@ -682,17 +719,20 @@ export class RolesAdminService {
    * `pre` produces the candidate (and may throw RolesAdminError for invariant
    * violations before any write). Skips on a no-op. Every candidate passes
    * the resolver's own parser (assertLoadable) plus the pre-disk validator
-   * before a byte lands.
+   * before a byte lands. `aroundWrite` wraps the locked edit (see
+   * {@link addMember}).
    */
   private async runEdit(
     actor: AuthUser,
     pre: (currentText: string) => EditResult,
+    aroundWrite?: (write: () => Promise<void>) => Promise<void>,
   ): Promise<void> {
     const workspaceId = await this.ensureWorkspace();
     await this.assertRolesUnlocked(workspaceId, actor);
-    return this.locked.withFileLocks(workspaceId, actor, [ROLES_YAML], () =>
-      this.runEditLocked(workspaceId, actor, pre),
-    );
+    return this.locked.withFileLocks(workspaceId, actor, [ROLES_YAML], () => {
+      const write = () => this.runEditLocked(workspaceId, actor, pre);
+      return aroundWrite ? aroundWrite(write) : write();
+    });
   }
 
   private async runEditLocked(

package/src/modules/access/user-access-removal.service.ts

@@ -492,7 +492,7 @@ export class UserAccessRemovalService {
   /** Why `email` may not be removed from access files, or null when it may. */
   private blockedReason(rolesText: string | undefined, email: string): string | null {
     if (this.deploymentOwners.some((o) => canonicalEmail(o) === email)) {
-      return 'This is the deployment owner (ADMIN_EMAIL); their access cannot be removed here.';
+      return 'The owner stays in roles and access rules.';
     }
     const admin = rolesText
       ? (() => {

package/src/modules/auth/__tests__/account-deactivation.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
+import { PgDialect } from 'drizzle-orm/pg-core';
+import type { SQL } from 'drizzle-orm';
 import type { Database } from '../../database/connection.js';
 import type { CoreConfig } from '../../../core-config.js';
 import { AuthService } from '../auth.service.js';
@@ -16,10 +18,19 @@ import { RECOVERY_BOT_EMAIL } from '../../workflow/recovery-bot.js';
 /**
  * Drizzle chain stub, as in `auth.service.test.ts`: each db.select() /
  * insert() / update() consumes the next queued result; awaiting any point of
- * the chain resolves it. Records what was inserted and set.
+ * the chain resolves it. Records what was inserted and set, and, in order,
+ * every write and lock (`execute`) with the handle it went through: `db`
+ * itself, or the `tx` a transaction hands its callback (a different object,
+ * between `begin` and `commit`), so a lock taken outside the transaction
+ * shows up as `db:`.
  */
 function makeFakeDb(queue: unknown[]) {
-  const captured: { values: Record<string, unknown>[]; set: Record<string, unknown>[] } = { values: [], set: [] };
+  const captured: { values: Record<string, unknown>[]; set: Record<string, unknown>[]; order: string[] } = {
+    values: [],
+    set: [],
+    order: [],
+  };
+  const dialect = new PgDialect();
   function nextChain(): unknown {
     const result = queue.shift();
     const chain: Record<string, unknown> = {};
@@ -42,12 +53,27 @@ function makeFakeDb(queue: unknown[]) {
     });
     return chain;
   }
-  const db = {
-    insert: vi.fn(() => nextChain()),
+  const handle = (tag: 'db' | 'tx') => ({
+    insert: vi.fn(() => (captured.order.push(`${tag}:insert`), nextChain())),
     select: vi.fn(() => nextChain()),
-    update: vi.fn(() => nextChain()),
-  } as unknown as Database;
-  return { db, captured };
+    update: vi.fn(() => (captured.order.push(`${tag}:update`), nextChain())),
+    execute: vi.fn(async (query: SQL) => {
+      const { sql, params } = dialect.sqlToQuery(query);
+      captured.order.push(`${tag}:${sql} ${JSON.stringify(params)}`);
+      return [];
+    }),
+  });
+  const tx = handle('tx');
+  const db = {
+    ...handle('db'),
+    transaction: async <T,>(cb: (t: typeof tx) => Promise<T>) => {
+      captured.order.push('begin');
+      const out = await cb(tx);
+      captured.order.push('commit');
+      return out;
+    },
+  };
+  return { db: db as unknown as Database, captured };
 }
 
 function makeConfig(over: Partial<CoreConfig> = {}): CoreConfig {
@@ -156,6 +182,64 @@ describe('AuthService.isActive', () => {
   });
 });
 
+// An earlier version could switch off an owner without a server-held
+// password; nothing in the product can switch them back on for a workspace
+// whose only admin they are. Their way in clears it.
+describe('an owner switched off by an earlier version', () => {
+  const OWNER_OFF = { ...OFF, id: 'owner-1', email: 'root@example.com' };
+
+  for (const [label, adminPassword] of [
+    ['with ADMIN_PASSWORD', 'sup3r-secret'],
+    ['without ADMIN_PASSWORD (the cloud)', ''],
+  ] as const) {
+    const config = makeConfig({ adminEmail: 'root@example.com', adminPassword });
+
+    it(`signs in with single sign-on, and the switch-off is cleared on the row, ${label}`, async () => {
+      const { db, captured } = makeFakeDb([[OWNER_OFF], []]);
+      const { user } = await new AuthService(db, config).loginWithSso('root@example.com', 'Root');
+      expect(user.id).toBe('owner-1');
+      expect(captured.set).toEqual([expect.objectContaining({ deactivatedAt: null })]);
+    });
+
+    it(`is let in as an embed identity, ${label}`, async () => {
+      const { db, captured } = makeFakeDb([[OWNER_OFF], []]);
+      await expect(new AuthService(db, config).getOrCreateByEmail('root@example.com')).resolves.toMatchObject({ id: 'owner-1' });
+      expect(captured.set).toEqual([expect.objectContaining({ deactivatedAt: null })]);
+    });
+
+    it(`keeps a session they already hold, ${label}`, async () => {
+      const { db, captured } = makeFakeDb([[{ id: 'owner-1', email: 'root@example.com', deactivatedAt: new Date() }], []]);
+      expect(await new AuthService(db, config).isActive('owner-1')).toBe(true);
+      expect(captured.set).toEqual([expect.objectContaining({ deactivatedAt: null })]);
+    });
+  }
+
+  it('signs in with a password they hold on the row, without ADMIN_PASSWORD', async () => {
+    const passwordHash = await hashPassword('a-long-enough-password');
+    const { db, captured } = makeFakeDb([[{ ...OWNER_OFF, passwordHash }], []]);
+    const svc = new AuthService(db, makeConfig({ adminEmail: 'root@example.com' }));
+    const { user } = await svc.loginWithPassword('root@example.com', 'a-long-enough-password');
+    expect(user.id).toBe('owner-1');
+    expect(captured.set).toEqual([expect.objectContaining({ deactivatedAt: null })]);
+  });
+
+  it('signs in with ADMIN_PASSWORD, and the switch-off is cleared on the row', async () => {
+    // The lookup, the upsert, then the clearing update.
+    const { db, captured } = makeFakeDb([[OWNER_OFF], [OWNER_OFF], []]);
+    const svc = new AuthService(db, makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' }));
+    const { user } = await svc.loginWithPassword('root@example.com', 'sup3r-secret');
+    expect(user.id).toBe('owner-1');
+    expect(captured.set).toEqual([expect.objectContaining({ deactivatedAt: null })]);
+  });
+
+  it('leaves a switched-off account that is not an owner switched off', async () => {
+    const { db, captured } = makeFakeDb([[OFF]]);
+    const svc = new AuthService(db, makeConfig({ adminEmail: 'root@example.com' }));
+    await expect(svc.loginWithSso('alice@example.com', 'Alice')).rejects.toBeInstanceOf(AccountDeactivatedError);
+    expect(captured.set).toEqual([]);
+  });
+});
+
 describe('AuthService.deactivate', () => {
   it('records when the account was switched off', async () => {
     const { db, captured } = makeFakeDb([[ROW], []]);
@@ -163,22 +247,59 @@ describe('AuthService.deactivate', () => {
     expect(captured.set[0].deactivatedAt).toBeInstanceOf(Date);
   });
 
+  it('switches off under the address switch lock, taken before the update', async () => {
+    const { db, captured } = makeFakeDb([[{ ...ROW, email: 'Alice@Example.com' }], []]);
+    await new AuthService(db, makeConfig()).deactivate(ROW.id);
+    expect(captured.order).toEqual([
+      'begin',
+      // The wait for the lock is bounded, inside the transaction.
+      `tx:select set_config('lock_timeout', $1, true) ["15000"]`,
+      'tx:select pg_advisory_xact_lock(hashtext($1)) ["account-switch:alice@example.com"]',
+      'tx:update',
+      'commit',
+    ]);
+  });
+
   it('answers false for an account that does not exist', async () => {
     const { db } = makeFakeDb([[]]);
     expect(await new AuthService(db, makeConfig()).deactivate('nobody')).toBe(false);
   });
 
-  it('refuses the deployment admin, whose environment password is the way back in', async () => {
-    const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' });
-    const { db } = makeFakeDb([[{ ...ROW, email: 'root@example.com' }]]);
-    await expect(new AuthService(db, config).deactivate(ROW.id)).rejects.toBeInstanceOf(AccountChangeRefusedError);
-    expect(vi.mocked(db.update)).not.toHaveBeenCalled();
+  // With a server-held owner password (self-hosted) and without one (the
+  // cloud's configuration): the owner is never switched off, and the refusal
+  // comes before any lock or write (`captured.order` stays empty).
+  for (const [label, adminPassword] of [
+    ['with ADMIN_PASSWORD', 'sup3r-secret'],
+    ['without ADMIN_PASSWORD (the cloud)', ''],
+  ] as const) {
+    it(`refuses the owner, ${label}, and says why`, async () => {
+      const config = makeConfig({ adminEmail: 'root@example.com', adminPassword });
+      const { db, captured } = makeFakeDb([[{ ...ROW, email: 'root@example.com' }]]);
+      const refusal = new AuthService(db, config).deactivate(ROW.id);
+      await expect(refusal).rejects.toBeInstanceOf(AccountChangeRefusedError);
+      await expect(refusal).rejects.toThrow("The owner can't be switched off.");
+      expect(captured.order).toEqual([]);
+    });
+
+    it(`still switches off an account that is not the owner, ${label}`, async () => {
+      const config = makeConfig({ adminEmail: 'root@example.com', adminPassword });
+      const { db, captured } = makeFakeDb([[ROW], []]);
+      expect(await new AuthService(db, config).deactivate(ROW.id)).toBe(true);
+      expect(captured.set[0].deactivatedAt).toBeInstanceOf(Date);
+    });
+  }
+
+  it('refuses the owner even with password sign-in switched off', async () => {
+    const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret', loginPasswordEnabled: false });
+    const { db, captured } = makeFakeDb([[{ ...ROW, email: 'root@example.com' }]]);
+    await expect(new AuthService(db, config).deactivate(ROW.id)).rejects.toThrow("The owner can't be switched off.");
+    expect(captured.order).toEqual([]);
   });
 
   it('refuses the accounts the platform runs its own work as', async () => {
-    const { db } = makeFakeDb([[{ ...ROW, email: RECOVERY_BOT_EMAIL }]]);
+    const { db, captured } = makeFakeDb([[{ ...ROW, email: RECOVERY_BOT_EMAIL }]]);
     await expect(new AuthService(db, makeConfig()).deactivate(ROW.id)).rejects.toThrow('platform itself');
-    expect(vi.mocked(db.update)).not.toHaveBeenCalled();
+    expect(captured.order).toEqual([]);
   });
 });
 
@@ -221,17 +342,25 @@ describe('a first sign-in the port would rather keep waiting', () => {
     expect(captured.values).toHaveLength(1);
     expect(captured.values[0]).toMatchObject({ email: 'new@example.com' });
     expect(captured.values[0].deactivatedAt).toBeInstanceOf(Date);
+    // Created switched off, so under the address's switch lock.
+    expect(captured.order).toEqual([
+      'begin',
+      `tx:select set_config('lock_timeout', $1, true) ["15000"]`,
+      'tx:select pg_advisory_xact_lock(hashtext($1)) ["account-switch:new@example.com"]',
+      'tx:insert',
+      'commit',
+    ]);
   });
 
   it('is a plain refusal when an admin creates the account', async () => {
     const { port } = recordingPort(waiting);
-    const { db } = makeFakeDb([[]]);
+    const { db, captured } = makeFakeDb([[]]);
     const err = await new AuthService(db, makeConfig(), port)
       .createAccount('new@example.com', 'New')
       .catch((e: unknown) => e);
     expect(err).toBeInstanceOf(AccountAdmissionRefusedError);
     expect((err as AccountAdmissionRefusedError).waitingForAdmin).toBe(false);
-    expect(vi.mocked(db.insert)).not.toHaveBeenCalled();
+    expect(captured.order).toEqual([]);
   });
 });
 

package/src/modules/auth/__tests__/account-hooks.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from 'vitest';
+import { AccountHooks, type AccountInvitedEvent } from '../account-hooks.js';
+
+const EVENT: AccountInvitedEvent = {
+  account: { id: 'u-lena', email: 'lena@acme.test', name: 'lena' },
+  invitedBy: { id: 'u-dana', email: 'dana@acme.test', name: 'Dana Admin' },
+  passwordSet: true,
+};
+
+describe('AccountHooks: an account was invited', () => {
+  it('notifies nobody when nothing is registered, and says so', async () => {
+    expect(await new AccountHooks().runAccountInvited(EVENT)).toEqual([]);
+  });
+
+  it('runs every listener in registration order, with the event, and collects the channels that reached the person', async () => {
+    const hooks = new AccountHooks();
+    const seen: string[] = [];
+    hooks.onAccountInvited(async (event) => {
+      seen.push(`mail:${event.account.email}:${event.passwordSet}`);
+      return 'email';
+    });
+    hooks.onAccountInvited(async () => {
+      seen.push('chat');
+      return null;
+    });
+    hooks.onAccountInvited(async () => {
+      seen.push('sms');
+      return 'sms';
+    });
+    expect(await hooks.runAccountInvited(EVENT)).toEqual(['email', 'sms']);
+    expect(seen).toEqual(['mail:lena@acme.test:true', 'chat', 'sms']);
+  });
+
+  it('a listener that throws counts as not having notified, and stops nothing', async () => {
+    const hooks = new AccountHooks();
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      hooks.onAccountInvited(async () => {
+        throw new Error('smtp down');
+      });
+      hooks.onAccountInvited(async () => 'email');
+      expect(await hooks.runAccountInvited(EVENT)).toEqual(['email']);
+      // Logged, so a failing mailer is diagnosable from the server's log.
+      expect(error).toHaveBeenCalledTimes(1);
+      expect(String(error.mock.calls[0]![0])).toContain('an account-invited listener failed');
+    } finally {
+      error.mockRestore();
+    }
+  });
+
+  it('an empty channel name is no channel: it counts as not having notified', async () => {
+    const hooks = new AccountHooks();
+    hooks.onAccountInvited(async () => '');
+    hooks.onAccountInvited(async () => 'email');
+    expect(await hooks.runAccountInvited(EVENT)).toEqual(['email']);
+  });
+});

package/src/modules/auth/__tests__/account-switch-lock.pg.test.ts

@@ -0,0 +1,78 @@
+import { afterAll, describe, expect, it } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import pg from 'pg';
+import { closeDb, createDb, type Database } from '../../database/connection.js';
+import { runCoreMigrations } from '../../database/migrate.js';
+import { coreMigrationsDir } from '../../../assets.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, dropScratchDatabases, scratchDatabaseUrl } from '../../../__tests__/pg-scratch.js';
+import { WorkflowDomainError } from '../../../shared/domain-errors.js';
+import { AuthService } from '../auth.service.js';
+import { ACCOUNT_BUSY_MESSAGE, takeAccountSwitchLock } from '../account-switch-lock.js';
+
+/**
+ * The account switch lock's promise, against a real Postgres (see
+ * `pg-scratch.ts`): a wait that runs out is a 409 `account-busy`, never the
+ * driver's error. Drizzle wraps that error (the SQLSTATE `55P03` is on its
+ * cause), which no stub of the driver shows, so the contention is real here:
+ * another connection holds the address's lock while the lock is asked for.
+ */
+const KEY = randomBytes(32).toString('base64');
+const open: Database[] = [];
+const holders: pg.Client[] = [];
+
+async function migratedDatabase(): Promise<{ db: Database; url: string }> {
+  const url = await scratchDatabaseUrl('hexis_switch');
+  const db = createDb(url, { piiKey: KEY });
+  open.push(db);
+  await runCoreMigrations(db, coreMigrationsDir());
+  return { db, url };
+}
+
+/** Another connection holding `email`'s switch lock in an open transaction, as a promotion mid-write does. */
+async function holdLock(url: string, email: string): Promise<pg.Client> {
+  const holder = new pg.Client({ connectionString: url });
+  await holder.connect();
+  holders.push(holder);
+  await holder.query('begin');
+  await holder.query('select pg_advisory_xact_lock(hashtext($1))', [`account-switch:${email}`]);
+  return holder;
+}
+
+describe.skipIf(!PG_ADMIN_URL)('the account switch lock under contention, on a real Postgres', () => {
+  afterAll(async () => {
+    for (const holder of holders) await holder.end().catch(() => undefined);
+    for (const db of open) await closeDb(db);
+    await dropScratchDatabases();
+  }, PG_TEST_TIMEOUT);
+
+  it(
+    "answers a wait that runs out as the 409 account-busy, through Drizzle's wrapping",
+    async () => {
+      const { db, url } = await migratedDatabase();
+      const holder = await holdLock(url, 'alice@acme.test');
+      const refusal = db.transaction((tx) => takeAccountSwitchLock(tx, 'Alice@Acme.test', 200));
+      await expect(refusal).rejects.toBeInstanceOf(WorkflowDomainError);
+      await expect(refusal).rejects.toMatchObject({ status: 409, message: ACCOUNT_BUSY_MESSAGE, payload: { kind: 'account-busy' } });
+      // Released, the lock is taken at once.
+      await holder.query('commit');
+      await expect(db.transaction((tx) => takeAccountSwitchLock(tx, 'alice@acme.test', 200))).resolves.toBeUndefined();
+    },
+    PG_TEST_TIMEOUT,
+  );
+
+  it(
+    'switching an account off while a promotion holds its lock is refused as account-busy, and changes nothing',
+    async () => {
+      const { db, url } = await migratedDatabase();
+      const auth = new AuthService(db, { jwtSecret: 'test-jwt-secret', adminEmail: '', adminPassword: '', allowedEmailDomains: [] });
+      const { user } = await auth.createAccountWithoutPassword('lee@acme.test', 'Lee');
+      const holder = await holdLock(url, 'lee@acme.test');
+      // The real wait (15 s): what an admin's switch-off meets.
+      await expect(auth.deactivate(user.id)).rejects.toMatchObject({ status: 409, payload: { kind: 'account-busy' } });
+      await holder.query('commit');
+      const [lee] = (await auth.listAccounts()).filter((a) => a.email === 'lee@acme.test');
+      expect(lee?.deactivatedAt).toBeNull();
+    },
+    PG_TEST_TIMEOUT,
+  );
+});

package/src/modules/auth/__tests__/account-switch-lock.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from 'vitest';
+import { PgDialect } from 'drizzle-orm/pg-core';
+import type { SQL } from 'drizzle-orm';
+import { WorkflowDomainError } from '../../../shared/domain-errors.js';
+import { ACCOUNT_BUSY_MESSAGE, ACCOUNT_SWITCH_LOCK_WAIT_MS, takeAccountSwitchLock } from '../account-switch-lock.js';
+
+/** A transaction handle that records what it ran, and fails the lock statement when told to. */
+function fakeTx(failLockWith?: { code: string; message: string }) {
+  const dialect = new PgDialect();
+  const ran: string[] = [];
+  const execute = vi.fn(async (query: SQL) => {
+    const { sql, params } = dialect.sqlToQuery(query);
+    ran.push(`${sql} ${JSON.stringify(params)}`);
+    if (failLockWith && sql.includes('pg_advisory_xact_lock')) {
+      throw Object.assign(new Error(failLockWith.message), { code: failLockWith.code });
+    }
+    return [];
+  });
+  return { tx: { execute }, ran };
+}
+
+describe('takeAccountSwitchLock', () => {
+  it('bounds the wait with a transaction-local lock_timeout, set before the lock is asked for', async () => {
+    const { tx, ran } = fakeTx();
+    await takeAccountSwitchLock(tx, 'Alice@Example.com');
+    expect(ran).toEqual([
+      `select set_config('lock_timeout', $1, true) ["${ACCOUNT_SWITCH_LOCK_WAIT_MS}"]`,
+      'select pg_advisory_xact_lock(hashtext($1)) ["account-switch:alice@example.com"]',
+    ]);
+  });
+
+  it('answers a wait that ran out as a 409 account-busy, in the words the admin is told', async () => {
+    const { tx } = fakeTx({ code: '55P03', message: 'canceling statement due to lock timeout' });
+    const refusal = takeAccountSwitchLock(tx, 'alice@example.com');
+    await expect(refusal).rejects.toBeInstanceOf(WorkflowDomainError);
+    await expect(refusal).rejects.toMatchObject({ status: 409, message: ACCOUNT_BUSY_MESSAGE, payload: { kind: 'account-busy' } });
+  });
+
+  it('lets any other failure of the lock through unchanged', async () => {
+    const { tx } = fakeTx({ code: '57P01', message: 'terminating connection due to administrator command' });
+    await expect(takeAccountSwitchLock(tx, 'alice@example.com')).rejects.toThrow('terminating connection');
+  });
+});