@bevel-software/platform-core-backend 0.26.0 → 0.28.0

package/src/modules/auth/__tests__/auth.service.created.pg.test.ts

@@ -0,0 +1,69 @@
+import { afterAll, describe, expect, it } from 'vitest';
+import { randomBytes } from 'node:crypto';
+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 { AuthService } from '../auth.service.js';
+
+/**
+ * Whether an account is NEW is answered by the upsert's own returned row,
+ * through Postgres's `xmax = 0` (see `CREATED` in auth.service.ts): zero on
+ * a row the statement inserted, set on one its `ON CONFLICT DO UPDATE`
+ * touched. No stub can stand in for that, so this crosses a real Postgres
+ * (see `pg-scratch.ts`): the invite's notification hangs on the answer, and
+ * a wrong one would either tell nobody or tell the same person twice.
+ */
+const KEY = randomBytes(32).toString('base64');
+const open: Database[] = [];
+
+async function migratedDatabase(): Promise<Database> {
+  const db = createDb(await scratchDatabaseUrl('hexis_created'), { piiKey: KEY });
+  open.push(db);
+  await runCoreMigrations(db, coreMigrationsDir());
+  return db;
+}
+
+describe.skipIf(!PG_ADMIN_URL)('whether an account is new, on a real Postgres', () => {
+  afterAll(async () => {
+    for (const db of open) await closeDb(db);
+    await dropScratchDatabases();
+  }, PG_TEST_TIMEOUT);
+
+  it(
+    'says created once per address: the insert, and never the conflict-update after it',
+    async () => {
+      const db = await migratedDatabase();
+      const auth = new AuthService(db, { jwtSecret: 'test-jwt-secret', adminEmail: '', adminPassword: '', allowedEmailDomains: [] });
+
+      // Without a password: the first write inserts, the second only updates.
+      const first = await auth.createAccountWithoutPassword('Lena@Acme.test', 'Lena');
+      expect(first.created).toBe(true);
+      expect(first.user).toMatchObject({ email: 'lena@acme.test', name: 'Lena' });
+      const again = await auth.createAccountWithoutPassword('lena@acme.test', 'Lena Park');
+      expect(again.created).toBe(false);
+      expect(again.user).toMatchObject({ id: first.user.id, name: 'Lena Park' });
+
+      // With a starting password: a new address is created with it...
+      const tom = await auth.createAccountWithStartingPassword('tom@acme.test', 'welcome-to-acme');
+      expect(tom).toMatchObject({ created: true, passwordSet: true, deactivated: false });
+      // ...an account that has a password keeps it, and is not new...
+      const tomAgain = await auth.createAccountWithStartingPassword('tom@acme.test', 'another-password');
+      expect(tomAgain).toMatchObject({ created: false, passwordSet: false, deactivated: false });
+      expect(tomAgain.user.id).toBe(tom.user.id);
+      // ...and an existing account with none gets it, through the conflict
+      // update: a password was set, and the account is still not new.
+      const lenaPassword = await auth.createAccountWithStartingPassword('lena@acme.test', 'welcome-to-acme');
+      expect(lenaPassword).toMatchObject({ created: false, passwordSet: true, deactivated: false });
+      expect(lenaPassword.user.id).toBe(first.user.id);
+
+      // What the rows say agrees: two accounts, both with a password now.
+      const accounts = await auth.listAccounts();
+      expect(accounts.map((a) => [a.email, a.hasPassword]).sort()).toEqual([
+        ['lena@acme.test', true],
+        ['tom@acme.test', true],
+      ]);
+    },
+    PG_TEST_TIMEOUT,
+  );
+});

package/src/modules/auth/__tests__/auth.service.test.ts

@@ -1,9 +1,13 @@
 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';
 import { AccountAdmissionRefusedError, type IAccountAdmission } from '../account-admission.js';
 import { hashPassword, verifyPassword } from '../password-hash.js';
+import { RECOVERY_BOT_EMAIL } from '../../workflow/recovery-bot.js';
+import { DIRECTORY_SYNC_BOT_EMAIL } from '../../access/directory-sync-bot.js';
 
 /**
  * Minimal drizzle chain stub (same idiom as the secrets-vault tests): each
@@ -291,6 +295,102 @@ describe('AuthService.createAccount / changePassword', () => {
     const set = captured.set[0] as { passwordHash: string };
     expect(set.passwordHash.startsWith('scrypt:')).toBe(true);
   });
+
+  // The system-account guard sits on EVERY password write, not only the
+  // invite's starting password: a bot holding a hash could sign in.
+  it.each([RECOVERY_BOT_EMAIL, DIRECTORY_SYNC_BOT_EMAIL])(
+    'createAccount refuses a password for the platform account %s, writing nothing',
+    async (email) => {
+      const { db } = makeFakeDb([]);
+      await expect(
+        new AuthService(db, makeConfig()).createAccount(email, undefined, 'brand-new-pass'),
+      ).rejects.toThrow('System accounts cannot be given a password');
+      expect(db.insert).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each([RECOVERY_BOT_EMAIL, DIRECTORY_SYNC_BOT_EMAIL])(
+    'changePassword refuses the platform account %s, writing nothing',
+    async (email) => {
+      const { db } = makeFakeDb([[{ ...ROW, email, passwordHash: null }]]);
+      await expect(
+        new AuthService(db, makeConfig()).changePassword('user-1', undefined, 'first-password'),
+      ).rejects.toThrow('System accounts cannot be given a password');
+      expect(db.update).not.toHaveBeenCalled();
+    },
+  );
+});
+
+describe('AuthService.createAccountWithStartingPassword — an invite never replaces a password', () => {
+  it('sets it in ONE upsert that writes only over an account with no password that is switched on', async () => {
+    const { db, captured } = makeFakeDb([[{ ...ROW, passwordHash: 'scrypt:x' }]]);
+    const result = await new AuthService(db, makeConfig()).createAccountWithStartingPassword(
+      'Alice@Example.com',
+      'starting-pass-1',
+    );
+    expect(result.passwordSet).toBe(true);
+    expect(result.user.email).toBe('alice@example.com');
+    const conflict = captured.conflict[0] as { set: { passwordHash: string; name?: string }; setWhere: unknown };
+    expect(conflict.set.passwordHash.startsWith('scrypt:')).toBe(true);
+    // The test and the write are one statement: the guard rides on the upsert,
+    // and writes only where there is no password AND the account is on.
+    const guard = new PgDialect().sqlToQuery(conflict.setWhere as SQL);
+    expect(guard.sql).toBe('("users"."password_hash" is null and "users"."deactivated_at" is null)');
+    expect(guard.params).toEqual([]);
+    expect(conflict.set.name).toBeUndefined();
+    expect(db.select).not.toHaveBeenCalled();
+  });
+
+  it('leaves an account the guard refused as it was, and says so', async () => {
+    // The upsert's guard refused the row (it has a password now): nothing returned, the row is read back.
+    const { db, captured } = makeFakeDb([[], [{ ...ROW, passwordHash: 'scrypt:own', deactivatedAt: null }]]);
+    const result = await new AuthService(db, makeConfig()).createAccountWithStartingPassword(
+      'alice@example.com',
+      'starting-pass-1',
+    );
+    expect(result.passwordSet).toBe(false);
+    expect(result.deactivated).toBe(false);
+    expect(result.user.email).toBe('alice@example.com');
+    expect(captured.set).toEqual([]);
+  });
+
+  it('tells a switched-off account apart from one with its own password', async () => {
+    const { db } = makeFakeDb([[], [{ ...ROW, passwordHash: null, deactivatedAt: new Date('2026-09-01T00:00:00Z') }]]);
+    const result = await new AuthService(db, makeConfig()).createAccountWithStartingPassword(
+      'alice@example.com',
+      'starting-pass-1',
+    );
+    expect(result).toMatchObject({ passwordSet: false, deactivated: true });
+  });
+
+  it.each([RECOVERY_BOT_EMAIL, DIRECTORY_SYNC_BOT_EMAIL])(
+    'refuses the platform account %s, writing nothing',
+    async (email) => {
+      const { db } = makeFakeDb([]);
+      await expect(
+        new AuthService(db, makeConfig()).createAccountWithStartingPassword(email, 'starting-pass-1'),
+      ).rejects.toThrow('System accounts cannot be given a password');
+      expect(db.insert).not.toHaveBeenCalled();
+      expect(db.select).not.toHaveBeenCalled();
+    },
+  );
+
+  it('leaves the deployment admin to the environment password, writing nothing', async () => {
+    const { db } = makeFakeDb([[{ ...ROW, email: 'root@example.com' }]]);
+    const result = await new AuthService(
+      db,
+      makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' }),
+    ).createAccountWithStartingPassword('root@example.com', 'starting-pass-1');
+    expect(result.passwordSet).toBe(false);
+    expect(db.insert).not.toHaveBeenCalled();
+  });
+
+  it('enforces the password policy', async () => {
+    const { db } = makeFakeDb([]);
+    await expect(
+      new AuthService(db, makeConfig()).createAccountWithStartingPassword('alice@example.com', 'short'),
+    ).rejects.toThrow(/at least/);
+  });
 });
 
 /**
@@ -539,7 +639,7 @@ describe('AuthService.listAccounts', () => {
     expect(json).not.toContain('sup3r-secret');
     for (const account of [...withHash, ...withoutHash]) {
       expect(Object.keys(account).sort()).toEqual(
-        ['createdAt', 'deactivatedAt', 'email', 'hasPassword', 'id', 'isEnvAdmin', 'isSystem', 'name'],
+        ['createdAt', 'deactivatedAt', 'email', 'hasPassword', 'id', 'isEnvAdmin', 'isOwner', 'isSystem', 'name', 'ownerCanBeDeleted'],
       );
     }
   });
@@ -552,6 +652,64 @@ describe('AuthService.listAccounts', () => {
   });
 });
 
+describe('AuthService — the owner', () => {
+  // A deployment with a server-held owner password (self-hosted) and one
+  // without (the cloud's configuration: `adminPassword: ''`).
+  const WITH_PASSWORD = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' });
+  const WITHOUT_PASSWORD = makeConfig({ adminEmail: 'root@example.com', adminPassword: '' });
+
+  it('recognises the owner by address alone, with or without ADMIN_PASSWORD, compared canonically', () => {
+    for (const config of [WITH_PASSWORD, WITHOUT_PASSWORD]) {
+      const svc = new AuthService(makeFakeDb([]).db, config);
+      expect(svc.isOwnerEmail('root@example.com')).toBe(true);
+      expect(svc.isOwnerEmail('  Root@Example.COM ')).toBe(true);
+      expect(svc.isOwnerEmail('alice@example.com')).toBe(false);
+      expect(svc.isOwnerEmail('')).toBe(false);
+      expect(svc.isOwnerEmail({ evil: true } as unknown as string)).toBe(false);
+      expect(svc.isOwnerEmail(undefined as unknown as string)).toBe(false);
+    }
+  });
+
+  it('has no owner when ADMIN_EMAIL is unset, so a blank address is never one', () => {
+    const svc = new AuthService(makeFakeDb([]).db, makeConfig({ adminEmail: '', adminPassword: '' }));
+    expect(svc.isOwnerEmail('')).toBe(false);
+    expect(svc.isOwnerEmail('root@example.com')).toBe(false);
+  });
+
+  it("refuses to delete the owner's account unless they can sign back in with the server's password", () => {
+    const refusal = "The owner's account can't be deleted: they would have no way to sign in.";
+    // The cloud: no server-held password.
+    expect(() => new AuthService(makeFakeDb([]).db, WITHOUT_PASSWORD).assertDeletable('root@example.com')).toThrow(refusal);
+    // A password the server holds, but password sign-in is switched off.
+    const passwordOff = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret', loginPasswordEnabled: false });
+    expect(() => new AuthService(makeFakeDb([]).db, passwordOff).assertDeletable('Root@example.com')).toThrow(refusal);
+    // Self-hosted with ADMIN_PASSWORD and password sign-in on: allowed, as today.
+    expect(() => new AuthService(makeFakeDb([]).db, WITH_PASSWORD).assertDeletable('root@example.com')).not.toThrow();
+    // Anyone else, on either deployment.
+    for (const config of [WITH_PASSWORD, WITHOUT_PASSWORD]) {
+      expect(() => new AuthService(makeFakeDb([]).db, config).assertDeletable('alice@example.com')).not.toThrow();
+    }
+  });
+
+  it('the accounts list says who the owner is and whether their account may be deleted', async () => {
+    const rows = [
+      { ...ROW, email: 'root@example.com', passwordHash: null, createdAt: new Date() },
+      { ...ROW, id: 'user-2', email: 'alice@example.com', passwordHash: null, createdAt: new Date() },
+    ];
+    const pick = (a: { email: string; isOwner: boolean; ownerCanBeDeleted: boolean }) => [a.email, a.isOwner, a.ownerCanBeDeleted];
+    const withPassword = await new AuthService(makeFakeDb([rows]).db, WITH_PASSWORD).listAccounts();
+    expect(withPassword.map(pick)).toEqual([
+      ['alice@example.com', false, false],
+      ['root@example.com', true, true],
+    ]);
+    const withoutPassword = await new AuthService(makeFakeDb([rows]).db, WITHOUT_PASSWORD).listAccounts();
+    expect(withoutPassword.map(pick)).toEqual([
+      ['alice@example.com', false, false],
+      ['root@example.com', true, false],
+    ]);
+  });
+});
+
 /**
  * `ALLOWED_EMAIL_DOMAINS` is the SSO allow-list, and only that.
  *

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

@@ -0,0 +1,69 @@
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('accounts');
+
+/**
+ * An admin invited somebody: a NEW account was made for the address. Never
+ * raised for an account that was already there (an invite that only set a
+ * starting password, a password reset, a rename), and never for a first
+ * single sign-on, which provisions by itself: the person is already in.
+ */
+export interface AccountInvitedEvent {
+  /** The new account, as the admin's answer carries it. */
+  account: Pick<AuthUser, 'id' | 'email' | 'name'>;
+  /** The admin who invited them. */
+  invitedBy: Pick<AuthUser, 'id' | 'email' | 'name'>;
+  /**
+   * Whether the account was created with a starting password the admin
+   * typed. The password itself never travels: a listener that writes to the
+   * person says it comes from the admin separately.
+   */
+  passwordSet: boolean;
+}
+
+/**
+ * A listener answers how it reached the person — a non-empty channel name,
+ * `'email'` say — or null when it did not (nothing configured, the send
+ * failed). It is awaited: the admin's answer says who was notified,
+ * truthfully, so a listener bounds its own wait. A throw is logged and
+ * counts as null; it never fails the invite. An empty name is no channel and
+ * counts as null too.
+ */
+export type AccountInvitedHook = (event: AccountInvitedEvent) => Promise<string | null>;
+
+/**
+ * Core's seam for "an account was invited": a deployment (the cloud with its
+ * mail, an enterprise overlay) registers how to tell the person, and core
+ * says in its answer whether somebody did. Core registers nothing, so a
+ * core-only deployment notifies nobody and the admin is handed the link and
+ * the message to send, as before.
+ */
+export interface IAccountHooks {
+  onAccountInvited(hook: AccountInvitedHook): void;
+  /** Run every listener in registration order; the channels that reached the person, in that order. */
+  runAccountInvited(event: AccountInvitedEvent): Promise<string[]>;
+}
+
+export class AccountHooks implements IAccountHooks {
+  private readonly invited: AccountInvitedHook[] = [];
+
+  onAccountInvited(hook: AccountInvitedHook): void {
+    this.invited.push(hook);
+  }
+
+  async runAccountInvited(event: AccountInvitedEvent): Promise<string[]> {
+    const notified: string[] = [];
+    for (const hook of this.invited) {
+      try {
+        const channel = await hook(event);
+        if (channel !== null && channel !== '') notified.push(channel);
+      } catch (err) {
+        // The account exists whether or not the person was told: the admin's
+        // answer says they were not, and the admin sends the link themselves.
+        log.error('an account-invited listener failed; the person was not notified by it:', { err });
+      }
+    }
+    return notified;
+  }
+}

package/src/modules/auth/account-switch-guard.ts

@@ -0,0 +1,14 @@
+/**
+ * Auth's contract for a write that must not land on a switched-off account:
+ * `whileSwitchedOn` runs `write` only while `email` is not switched off, and
+ * keeps it so until `write` has finished. A switch-off either committed
+ * before the check (`write` is refused with a 409 `deactivated` and never
+ * runs) or waits until `write` is done. An address with no account yet counts
+ * as switched on.
+ *
+ * Implemented by `AuthService`; other modules take this contract, not the
+ * service, so how auth coordinates switch-offs stays its own.
+ */
+export interface IAccountSwitchGuard {
+  whileSwitchedOn(email: string, write: () => Promise<void>): Promise<void>;
+}

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

@@ -0,0 +1,58 @@
+import { sql } from 'drizzle-orm';
+import type { Database } from '../database/connection.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { pgErrorCode } from '../database/pg-error.js';
+
+/** The handle `db.transaction` hands its callback. */
+type Tx = Parameters<Parameters<Database['transaction']>[0]>[0];
+
+/**
+ * How long a switch-off or a promotion waits for the address's lock. The
+ * holder may be a promotion committing `roles.yaml` (a git commit and push,
+ * seconds), so the wait is generous; it is bounded all the same, for the
+ * reason `database/advisory-lock.ts` gives: a waiter blocked for good sits
+ * on a pooled connection, and a wedged holder would take the pool with it.
+ */
+export const ACCOUNT_SWITCH_LOCK_WAIT_MS = 15_000;
+
+/** Postgres raises this when `lock_timeout` expires while waiting for a lock. */
+const LOCK_NOT_AVAILABLE = '55P03';
+
+/** What a caller is told when the wait ran out: a 409, to try again shortly. */
+export const ACCOUNT_BUSY_MESSAGE = 'Another change to this account is still being saved; try again in a moment.';
+
+/**
+ * Hold, for the rest of `tx`, the one lock that orders an address's switch-off
+ * against a write that must not land on a switched-off account (the invite's
+ * Admin promotion).
+ *
+ * A row lock cannot do it: an address with no account yet has no row, and an
+ * account can be created switched off (single sign-on waiting for an admin)
+ * or created and switched off while the promotion is being written. So the
+ * lock is a transaction-scoped advisory lock on the canonical address, taken
+ * by every write that switches an account off and by the promotion, before
+ * either reads the row. Whichever comes second waits for the first to commit,
+ * then reads what it committed (READ COMMITTED takes a fresh snapshot per
+ * statement). A different address that hashes to the same key only waits.
+ *
+ * The wait is bounded by a transaction-local `lock_timeout`
+ * ({@link ACCOUNT_SWITCH_LOCK_WAIT_MS}), which the transaction's end reverts
+ * with everything else; running out of it is answered as a 409 `account-busy`.
+ */
+export async function takeAccountSwitchLock(
+  tx: Pick<Tx, 'execute'>,
+  email: string,
+  waitMs: number = ACCOUNT_SWITCH_LOCK_WAIT_MS,
+): Promise<void> {
+  await tx.execute(sql`select set_config('lock_timeout', ${String(waitMs)}, true)`);
+  try {
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtext(${`account-switch:${canonicalEmail(email)}`}))`);
+  } catch (err) {
+    // Drizzle wraps the driver's error, so the SQLSTATE is on its cause.
+    if (pgErrorCode(err) === LOCK_NOT_AVAILABLE) {
+      throw new WorkflowDomainError(ACCOUNT_BUSY_MESSAGE, 409, { kind: 'account-busy' });
+    }
+    throw err;
+  }
+}

package/src/modules/auth/account.routes.ts

@@ -6,12 +6,14 @@ import { printable } from '../../shared/printable.js';
 const log = logger('accounts');
 import type { AuthUser } from '@bevel-software/platform-shared';
 import type { AuthService } from './auth.service.js';
+import type { IAccountHooks } from './account-hooks.js';
 import { AccountAdmissionRefusedError, AccountChangeRefusedError } from './account-admission.js';
 import { erasedAccountId, type IAccountErasureService } from './account-erasure.service.js';
 import type { IAdminAccessService } from '../admin/admin.interface.js';
 import type { UserAccessRemovalService } from '../access/user-access-removal.service.js';
 import { sendError } from '../access/admin-route-helpers.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
 import './auth.middleware.js'; // Express Request augmentation
 
 /**
@@ -26,9 +28,22 @@ import './auth.middleware.js'; // Express Request augmentation
  * bootstrap admin (always-admin, see AdminAccessService).
  */
 export function createAccountRoutes(
-  authService: Pick<AuthService, 'listAccounts' | 'createAccount' | 'getUserById' | 'deactivate' | 'reactivate'>,
+  authService: Pick<
+    AuthService,
+    | 'listAccounts'
+    | 'createAccount'
+    | 'createAccountWithoutPassword'
+    | 'createAccountWithStartingPassword'
+    | 'getUserById'
+    | 'deactivate'
+    | 'reactivate'
+    | 'isOwnerEmail'
+    | 'assertDeletable'
+  >,
   adminAccess: IAdminAccessService,
   accountErasure: Pick<IAccountErasureService, 'eraseUser'>,
+  /** Who tells an invited person (see {@link IAccountHooks}); core registers nobody. */
+  accountHooks: Pick<IAccountHooks, 'runAccountInvited'>,
   accessRemoval?: Pick<UserAccessRemovalService, 'report' | 'assertRemovable' | 'remove' | 'filesNaming'>,
 ): express.Router {
   const router = express.Router();
@@ -42,7 +57,8 @@ export function createAccountRoutes(
   };
 
   // GET /api/admin/accounts — id, email, name, whether a password hash is
-  // stored, and whether the account is the env bootstrap admin.
+  // stored, whether the account is the env bootstrap admin, and whether it is
+  // an owner (and, if so, whether it may be deleted).
   router.get('/admin/accounts', requireAdmin, async (_req, res) => {
     res.json({ accounts: await authService.listAccounts() });
   });
@@ -51,11 +67,16 @@ export function createAccountRoutes(
   // (or reset the password of an existing one; upsert-by-email is deliberate,
   // see AuthService.createAccount). Without a password the account is for
   // single sign-on: the person finds it waiting when they first sign in.
+  // With `keepExistingPassword: true` (an invite's starting password) the
+  // password goes only to a new account or a switched-on one with none; the
+  // reply's `passwordSet` says whether it did, and `deactivated` whether a
+  // refusal was because the account is switched off.
   router.post('/admin/accounts', requireAdmin, async (req, res) => {
-    const { email, name, password } = req.body as {
+    const { email, name, password, keepExistingPassword } = req.body as {
       email?: string;
       name?: string;
       password?: unknown;
+      keepExistingPassword?: unknown;
     };
     if (!email) {
       res.status(400).json({ error: 'email is required' });
@@ -66,14 +87,80 @@ export function createAccountRoutes(
       res.status(400).json({ error: 'password must be a string' });
       return;
     }
+    // Fail closed: anything but a boolean is a mistake, never "overwrite".
+    if (keepExistingPassword !== undefined && typeof keepExistingPassword !== 'boolean') {
+      res.status(400).json({ error: 'keepExistingPassword must be a boolean' });
+      return;
+    }
+    if (keepExistingPassword === true && typeof password !== 'string') {
+      res.status(400).json({ error: 'keepExistingPassword needs a password' });
+      return;
+    }
+    // Another admin setting an owner's password could then sign in as the
+    // owner. The owner sets their own on the Account page; an owner account
+    // without a password (restoring one, say; an empty one counts as none,
+    // as in createAccount) is still created here. An invite's starting
+    // password is a password too: the owner is invited by nobody.
+    if (
+      password &&
+      authService.isOwnerEmail(email) &&
+      canonicalEmail(email) !== canonicalEmail(req.userEmail ?? '')
+    ) {
+      res.status(400).json({ error: "The owner's password can't be set by another admin; the owner sets it on their Account page." });
+      return;
+    }
     try {
+      // A NEW account is an invitation, and the deployment's listeners say
+      // how the person was told (`notified`): the answer the admin reads is
+      // true to what happened, so the dialog can say "emailed" or hand over
+      // the link. An account that was already there is not invited again.
+      const invited = async (account: AuthUser, created: boolean, passwordSet: boolean): Promise<string[]> => {
+        if (!created) return [];
+        // The inviting admin, by name when their account can be read. The
+        // account is already made: a failed read falls back to the identity
+        // the request carries rather than answering an error a retry could
+        // not make good (the account is not new the second time).
+        const requester = { id: req.userId ?? '', email: req.userEmail ?? '', name: '' };
+        const by = req.userId
+          ? await authService.getUserById(req.userId).catch((err: unknown) => {
+              log.warn('the inviting admin could not be read; the invite names them by address:', { err });
+              return null;
+            })
+          : null;
+        return accountHooks.runAccountInvited({
+          account: { id: account.id, email: account.email, name: account.name },
+          invitedBy: by ?? requester,
+          passwordSet,
+        });
+      };
+      if (keepExistingPassword === true && typeof password === 'string') {
+        const { user, created, passwordSet, deactivated } = await authService.createAccountWithStartingPassword(email, password);
+        const notified = await invited(user, created, passwordSet);
+        res.status(201).json({ ...user, passwordSet, deactivated, notified });
+        return;
+      }
+      if (!password) {
+        const { user, created } = await authService.createAccountWithoutPassword(email, name);
+        const notified = await invited(user, created, false);
+        res.status(201).json({ ...user, notified });
+        return;
+      }
+      // Set or reset password: an account that is here already, or one an
+      // admin makes with a password from the API. Not an invitation the
+      // listeners are told of: the dialog that invites never sends this form.
       const user = await authService.createAccount(email, name, password);
       res.status(201).json(user);
     } catch (error) {
       const msg = error instanceof Error ? error.message : 'Unknown error';
       // The deployment has no place for the account (a seat limit, say): the
       // port's own words, as a refusal rather than a malformed request.
-      res.status(error instanceof AccountAdmissionRefusedError ? 403 : 400).json({ error: msg });
+      // `kind` tells it apart from `requireAdmin`'s 403, which a caller must
+      // not read as "no seat left".
+      if (error instanceof AccountAdmissionRefusedError) {
+        res.status(403).json({ error: msg, kind: 'admission' });
+        return;
+      }
+      res.status(400).json({ error: msg });
     }
   });
 
@@ -100,6 +187,14 @@ export function createAccountRoutes(
         res.status(400).json({ error: error.message });
         return;
       }
+      // The address's switch lock is held by a change still being saved (an
+      // invite's promotion committing roles.yaml, say): the 409 the lock
+      // promises, with its words, so the admin tries again rather than
+      // reading an outage.
+      if (error instanceof WorkflowDomainError) {
+        res.status(error.status).json({ error: error.message, ...(error.payload ?? {}) });
+        return;
+      }
       log.error('switching an account off failed:', { err: error });
       res.status(500).json({ error: 'Could not switch this account off' });
     }
@@ -107,7 +202,8 @@ export function createAccountRoutes(
 
   // POST /api/admin/accounts/:userId/reactivate — switch it back on, if the
   // deployment has room: the admission port is asked, as for a new account
-  // (a host that sells seats answers from its plan; 403 with its words).
+  // (a host that sells seats answers from its plan; 403 with its words and
+  // `kind: 'admission'`).
   router.post('/admin/accounts/:userId/reactivate', requireAdmin, async (req, res) => {
     const userId = String(req.params.userId);
     try {
@@ -119,7 +215,7 @@ export function createAccountRoutes(
       res.status(204).end();
     } catch (error) {
       if (error instanceof AccountAdmissionRefusedError) {
-        res.status(403).json({ error: error.message });
+        res.status(403).json({ error: error.message, kind: 'admission' });
         return;
       }
       log.error('switching an account on failed:', { err: error });
@@ -174,14 +270,27 @@ export function createAccountRoutes(
     // for the removal below — never logged, never returned.
     let email: string | null = null;
     let actor: AuthUser | null = null;
-    if (removeFromAccess) {
+    try {
+      const user = await authService.getUserById(userId);
+      if (!user) {
+        res.status(404).json({ error: 'No such user' });
+        return;
+      }
+      // An owner who could not sign back in afterwards is refused for every
+      // caller, whether or not the access option is ticked.
+      authService.assertDeletable(user.email);
+      if (removeFromAccess) email = user.email;
+    } catch (err) {
+      if (err instanceof AccountChangeRefusedError) {
+        res.status(400).json({ error: err.message });
+        return;
+      }
+      log.error('looking up the account to erase failed:', { err });
+      res.status(500).json({ error: 'Failed to erase user' });
+      return;
+    }
+    if (removeFromAccess && email !== null) {
       try {
-        const user = await authService.getUserById(userId);
-        if (!user) {
-          res.status(404).json({ error: 'No such user' });
-          return;
-        }
-        email = user.email;
         // The existing guards: the deployment owner and the last Admin are
         // refused up front, before anything is erased.
         await accessRemoval!.assertRemovable(email);

package/src/modules/auth/auth.middleware.ts

@@ -30,7 +30,7 @@ export const AUTH_COOKIE_NAME = 'bevel_token';
  * beats the dep surface of a middleware. Returns `null` if the cookie
  * is absent or empty.
  */
-function readAuthCookie(req: Request): string | null {
+export function readAuthCookie(req: Request): string | null {
   const header = req.headers.cookie;
   if (!header) return null;
   for (const segment of header.split(';')) {