@bevel-software/platform-core-backend 0.15.1 → 0.19.0

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

@@ -2,7 +2,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import express from 'express';
 import type { Server } from 'node:http';
 import { createAccountRoutes } from '../account.routes.js';
-import type { AuthService } from '../auth.service.js';
+import { AuthService } from '../auth.service.js';
+import { hashPassword } from '../password-hash.js';
+import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 
 const authService = {
@@ -15,7 +17,7 @@ const authService = {
 // Satisfies the route's narrow Pick<IAccountErasureService, 'eraseUser'>
 // contract directly — no concrete-service cast needed.
 const accountErasure = {
-  eraseUser: vi.fn(async (_userId: string) => true),
+  eraseUser: vi.fn<(userId: string, opts?: { erasureId?: string }) => Promise<boolean>>(async () => true),
 };
 
 function makeApp(opts: { admin: boolean; email?: string }) {
@@ -81,6 +83,48 @@ describe('account routes — admin gate', () => {
     expect(authService.createAccount).toHaveBeenCalledWith('b@example.com', 'B', 'long-enough-pw');
   });
 
+  it('list reports hasPassword + isEnvAdmin and never carries a hash or password', async () => {
+    const passwordHash = await hashPassword('stored-password-1');
+    const rows = [
+      { id: 'u1', email: 'root@example.com', name: 'Root', passwordHash: null, createdAt: new Date() },
+      { id: 'u2', email: 'b@example.com', name: 'B', passwordHash, createdAt: new Date() },
+    ];
+    // A real AuthService over a stub db — the route's body is what the
+    // service produces from full `users` rows, hash column included.
+    const db = {
+      select: () => ({ from: () => ({ orderBy: async () => rows }) }),
+    } as unknown as Database;
+    const realAuth = new AuthService(db, {
+      jwtSecret: 'test-jwt-secret',
+      adminEmail: 'root@example.com',
+      adminPassword: 'env-admin-secret',
+      allowedEmailDomains: [],
+    });
+    const app = express();
+    app.use((req, _res, next) => {
+      req.userId = 'caller';
+      req.userEmail = 'caller@example.com';
+      next();
+    });
+    app.use('/api', createAccountRoutes(realAuth, { isAdmin: async () => true }, accountErasure));
+    const base = await listen(app);
+
+    const res = await fetch(`${base}/api/admin/accounts`);
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    const body = JSON.parse(text) as {
+      accounts: Array<{ email: string; hasPassword: boolean; isEnvAdmin: boolean }>;
+    };
+    expect(body.accounts.map((a) => [a.email, a.hasPassword, a.isEnvAdmin])).toEqual([
+      ['root@example.com', false, true],
+      ['b@example.com', true, false],
+    ]);
+    expect(text).not.toContain('scrypt:');
+    expect(text).not.toContain('passwordHash');
+    expect(text).not.toContain('env-admin-secret');
+    expect(text).not.toContain('stored-password-1');
+  });
+
   it('erasure: refuses non-admins, refuses self, 404s unknown, 204s success', async () => {
     const nonAdmin = await listen(makeApp({ admin: false }));
     expect((await fetch(`${nonAdmin}/api/admin/accounts/u9`, { method: 'DELETE' })).status).toBe(403);
@@ -135,3 +179,135 @@ describe('account routes — admin gate', () => {
     expect(body.error).toContain('at least 8');
   });
 });
+
+describe('account routes — removing the erased address from access files', () => {
+  const lee = { id: 'u2', email: 'lee@example.com', name: 'Lee' };
+  const caller = { id: 'u1', email: 'caller@example.com', name: 'Caller' };
+
+  function makeRemovalApp() {
+    const auth = {
+      ...authService,
+      getUserById: vi.fn(async (id: string) => (id === 'u2' ? lee : id === 'u1' ? caller : null)),
+    } as unknown as AuthService;
+    const accessRemoval = {
+      report: vi.fn(async () => ({
+        roles: 1,
+        groups: 1,
+        accessRules: 2,
+        fileGrants: 1,
+        total: 5,
+        files: ['Sales/Plan.md', 'Sales/access.md', 'groups.yaml', 'roles.yaml'],
+        removable: true,
+        blockedReason: null,
+        unwritable: ['Sales/Plan.md'],
+      })),
+      assertRemovable: vi.fn(async () => {}),
+      remove: vi.fn(async () => ({ removedFrom: ['roles.yaml'], stillNamedIn: [] as string[] | null })),
+      filesNaming: vi.fn(async (): Promise<string[]> => ['Sales/access.md', 'roles.yaml']),
+    };
+    const app = express();
+    app.use((req, _res, next) => {
+      req.userId = 'u1';
+      req.userEmail = 'caller@example.com';
+      next();
+    });
+    app.use('/api', createAccountRoutes(auth, { isAdmin: async () => true }, accountErasure, accessRemoval));
+    return { app, accessRemoval };
+  }
+
+  it('reports the reference counts for the confirmation, without the address', async () => {
+    const { app, accessRemoval } = makeRemovalApp();
+    const base = await listen(app);
+    const res = await fetch(`${base}/api/admin/accounts/u2/references`);
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    expect(JSON.parse(text)).toMatchObject({ total: 5, roles: 1, groups: 1, accessRules: 2, fileGrants: 1 });
+    // The TARGET's address is counted; the ACTING admin's decides what they
+    // can write, so the dialog can warn before the delete.
+    expect(accessRemoval.report).toHaveBeenCalledWith('lee@example.com', 'caller@example.com');
+    expect(JSON.parse(text).unwritable).toEqual(['Sales/Plan.md']);
+    expect(text).not.toContain('lee@example.com');
+    expect((await fetch(`${base}/api/admin/accounts/ghost/references`)).status).toBe(404);
+  });
+
+  it('option off: erases as today (204) and never touches the access files', async () => {
+    const { app, accessRemoval } = makeRemovalApp();
+    const base = await listen(app);
+    const res = await fetch(`${base}/api/admin/accounts/u2`, { method: 'DELETE' });
+    expect(res.status).toBe(204);
+    expect(accountErasure.eraseUser).toHaveBeenLastCalledWith('u2');
+    expect(accessRemoval.assertRemovable).not.toHaveBeenCalled();
+    expect(accessRemoval.remove).not.toHaveBeenCalled();
+  });
+
+  it('option on: erases, then removes in one call named by the anonymised id', async () => {
+    const { app, accessRemoval } = makeRemovalApp();
+    const base = await listen(app);
+    const res = await fetch(`${base}/api/admin/accounts/u2?removeFromAccess=1`, { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { erased: boolean; accessRemoval: { ok: boolean; removedFrom: string[] } };
+    expect(body).toEqual({ erased: true, accessRemoval: { ok: true, removedFrom: ['roles.yaml'], stillNamedIn: [] } });
+
+    const [, opts] = vi.mocked(accountErasure.eraseUser).mock.calls.at(-1)! as unknown as [string, { erasureId: string }];
+    expect(opts.erasureId).toMatch(/^[0-9a-f-]{36}$/);
+    expect(accessRemoval.remove).toHaveBeenCalledTimes(1);
+    const [actor, email, accountId] = accessRemoval.remove.mock.calls[0] as unknown as [
+      { email: string },
+      string,
+      string,
+    ];
+    expect(actor.email).toBe('caller@example.com');
+    expect(email).toBe('lee@example.com');
+    expect(accountId).toBe(`deleted-${opts.erasureId}`);
+    // Erasure happened before the removal.
+    expect(vi.mocked(accountErasure.eraseUser).mock.invocationCallOrder.at(-1)!).toBeLessThan(
+      accessRemoval.remove.mock.invocationCallOrder[0],
+    );
+  });
+
+  it('commit failure: the account is still erased and the response lists the files still naming the user', async () => {
+    const { app, accessRemoval } = makeRemovalApp();
+    accessRemoval.remove.mockRejectedValueOnce(new Error('push rejected: /srv/kb internal detail'));
+    const base = await listen(app);
+    const res = await fetch(`${base}/api/admin/accounts/u2?removeFromAccess=1`, { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    const body = JSON.parse(text) as {
+      erased: boolean;
+      accessRemoval: { ok: boolean; error: string; stillNamedIn: string[] };
+    };
+    expect(accountErasure.eraseUser).toHaveBeenCalledTimes(1);
+    expect(body.erased).toBe(true);
+    expect(body.accessRemoval.ok).toBe(false);
+    expect(body.accessRemoval.stillNamedIn).toEqual(['Sales/access.md', 'roles.yaml']);
+    expect(text).not.toContain('/srv/kb');
+    expect(text).not.toContain('lee@example.com');
+  });
+
+  it('commit failure with an unreadable re-scan reports the files as unknown, not as none', async () => {
+    const { app, accessRemoval } = makeRemovalApp();
+    accessRemoval.remove.mockRejectedValueOnce(new Error('push rejected'));
+    accessRemoval.filesNaming.mockRejectedValueOnce(new Error('EACCES'));
+    const base = await listen(app);
+    const res = await fetch(`${base}/api/admin/accounts/u2?removeFromAccess=1`, { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { erased: boolean; accessRemoval: { ok: boolean; stillNamedIn: string[] | null } };
+    expect(body.erased).toBe(true);
+    expect(body.accessRemoval.ok).toBe(false);
+    expect(body.accessRemoval.stillNamedIn).toBeNull();
+  });
+
+  it('the guards refuse up front: nothing is erased', async () => {
+    const { app, accessRemoval } = makeRemovalApp();
+    const { WorkflowDomainError } = await import('../../../shared/domain-errors.js');
+    accessRemoval.assertRemovable.mockRejectedValueOnce(
+      new WorkflowDomainError('This is the last Admin; the Admin role must keep at least one direct email member.', 409),
+    );
+    const base = await listen(app);
+    const res = await fetch(`${base}/api/admin/accounts/u2?removeFromAccess=1`, { method: 'DELETE' });
+    expect(res.status).toBe(409);
+    expect(((await res.json()) as { error: string }).error).toMatch(/last Admin/);
+    expect(accountErasure.eraseUser).not.toHaveBeenCalled();
+    expect(accessRemoval.remove).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { Request, Response, NextFunction } from 'express';
+import { createAuthMiddleware, AUTH_COOKIE_NAME } from '../auth.middleware.js';
+import type { AuthService } from '../auth.service.js';
+
+/**
+ * The cookie fallback is the whole reason a markdown image can be a plain
+ * `<img>`: the tag sends no Authorization header, only the `bevel_token`
+ * cookie the login route set. Nothing else in the suite exercised that path
+ * (the route harnesses inject `userId` directly), so this pins it.
+ */
+
+const GOOD_TOKEN = 'good-token';
+const IDENTITY = { userId: 'user-1', email: 'alice@example.com' };
+
+function run(headers: Record<string, string>) {
+  const verifyToken = vi.fn((token: string) => {
+    if (token !== GOOD_TOKEN) throw new Error('bad token');
+    return IDENTITY;
+  });
+  const authService = { verifyToken } as unknown as AuthService;
+  const req = { headers } as unknown as Request;
+  const json = vi.fn();
+  const status = vi.fn(() => ({ json }));
+  const res = { status } as unknown as Response;
+  const next = vi.fn() as unknown as NextFunction;
+  createAuthMiddleware(authService)(req, res, next);
+  return { req, next, status, json, verifyToken };
+}
+
+describe('createAuthMiddleware', () => {
+  it('authenticates a request that carries only the auth cookie (an <img>, an EventSource)', () => {
+    const { req, next, status } = run({ cookie: `${AUTH_COOKIE_NAME}=${GOOD_TOKEN}` });
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(status).not.toHaveBeenCalled();
+    expect(req.userId).toBe(IDENTITY.userId);
+    expect(req.userEmail).toBe(IDENTITY.email);
+  });
+
+  it('finds the cookie among others, and decodes a percent-encoded value', () => {
+    const { next, verifyToken } = run({
+      cookie: `theme=dark; ${AUTH_COOKIE_NAME}=${encodeURIComponent(GOOD_TOKEN)}; seen=1`,
+    });
+    expect(verifyToken).toHaveBeenCalledWith(GOOD_TOKEN);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('prefers the Bearer header when both are present', () => {
+    const { next, verifyToken } = run({
+      authorization: `Bearer ${GOOD_TOKEN}`,
+      cookie: `${AUTH_COOKIE_NAME}=stale-cookie`,
+    });
+    expect(verifyToken).toHaveBeenCalledTimes(1);
+    expect(verifyToken).toHaveBeenCalledWith(GOOD_TOKEN);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('refuses a request with neither', () => {
+    const { next, status, json } = run({});
+    expect(next).not.toHaveBeenCalled();
+    expect(status).toHaveBeenCalledWith(401);
+    expect(json.mock.calls[0][0].error).toContain('auth cookie');
+  });
+
+  it('refuses an empty cookie value as missing, not as a token to verify', () => {
+    const { next, status, verifyToken } = run({ cookie: `${AUTH_COOKIE_NAME}=` });
+    expect(verifyToken).not.toHaveBeenCalled();
+    expect(next).not.toHaveBeenCalled();
+    expect(status).toHaveBeenCalledWith(401);
+  });
+
+  it('refuses a cookie the auth service rejects', () => {
+    const { next, status, json } = run({ cookie: `${AUTH_COOKIE_NAME}=forged` });
+    expect(next).not.toHaveBeenCalled();
+    expect(status).toHaveBeenCalledWith(401);
+    expect(json.mock.calls[0][0].error).toBe('Invalid or expired token');
+  });
+});

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

@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest';
 import type { Database } from '../../database/connection.js';
 import type { CoreConfig } from '../../../core-config.js';
 import { AuthService } from '../auth.service.js';
-import { hashPassword } from '../password-hash.js';
+import { hashPassword, verifyPassword } from '../password-hash.js';
 
 /**
  * Minimal drizzle chain stub (same idiom as the secrets-vault tests): each
@@ -69,21 +69,25 @@ const ROW = {
   email: 'alice@example.com',
   name: 'Alice',
   avatarUrl: null,
+  // NOT NULL with a default in the schema: a row read back from the database
+  // always has a boolean here, so the fixture carries one rather than letting
+  // every asserted payload read `undefined`.
+  onboardingDone: false,
 };
 
 describe('AuthService.loginWithPassword — env bootstrap admin', () => {
   const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' });
 
   it('signs in the env admin and upserts their user row', async () => {
-    const { db } = makeFakeDb([[{ ...ROW, email: 'root@example.com', name: 'root' }]]);
+    // Two queued results: the lookup every login now performs, then the upsert.
+    const { db } = makeFakeDb([[], [{ ...ROW, email: 'root@example.com', name: 'root' }]]);
     const svc = new AuthService(db, config);
     const result = await svc.loginWithPassword('Root@Example.com', 'sup3r-secret');
     expect(result.user.email).toBe('root@example.com');
     expect(result.token.length).toBeGreaterThan(20);
   });
 
-  it('rejects the admin email with a wrong password (and does not fall back oddly)', async () => {
-    // Wrong env password → falls through to the DB path; no row → refused.
+  it('rejects the admin email with a wrong password', async () => {
     const { db } = makeFakeDb([[]]);
     const svc = new AuthService(db, config);
     await expect(svc.loginWithPassword('root@example.com', 'wrong')).rejects.toThrow(
@@ -91,6 +95,96 @@ describe('AuthService.loginWithPassword — env bootstrap admin', () => {
     );
   });
 
+  // The generic "Invalid credentials" only hides the configured admin email if
+  // the WORK is generic too. The decoy hash equalises the scrypt half for
+  // every address; this pins the database half, which a branch that answered
+  // the admin's address without a lookup would otherwise leave one round trip
+  // shorter than every other address's — visible to repeated timing.
+  it('does the same lookup for a wrong password whichever address it is for', async () => {
+    const attempts = ['root@example.com', 'nobody@example.com', 'alice@example.com'];
+    const counts: number[] = [];
+    for (const email of attempts) {
+      const { db } = makeFakeDb([[]]);
+      await expect(
+        new AuthService(db, config).loginWithPassword(email, 'wrong'),
+      ).rejects.toThrow('Invalid credentials');
+      counts.push(vi.mocked(db.select).mock.calls.length);
+    }
+    expect(counts).toEqual([1, 1, 1]);
+  });
+
+  // The environment password is this account's only credential, so a hash on
+  // its row is not a second one. Such a hash can exist without anyone
+  // planting it today: it may pre-date the rule that refuses to write one, or
+  // belong to an ordinary account that only later became `ADMIN_EMAIL`. If it
+  // still signed in, rotating `ADMIN_PASSWORD` would leave the old credential
+  // working — precisely what refusing the write was meant to prevent.
+  it('refuses a stored hash on the deployment admin row', async () => {
+    const passwordHash = await hashPassword('planted-password');
+    const { db, captured } = makeFakeDb([[{ ...ROW, email: 'root@example.com', passwordHash }]]);
+    const svc = new AuthService(db, config);
+    await expect(svc.loginWithPassword('root@example.com', 'planted-password')).rejects.toThrow(
+      'Invalid credentials',
+    );
+    // The row IS read — every email takes the same lookup, so that this one
+    // cannot be picked out by how long a wrong password takes — but its hash
+    // is not what the answer is drawn from. Nothing is written either way.
+    expect(vi.mocked(db.select)).toHaveBeenCalledTimes(1);
+    expect(captured.set).toHaveLength(0);
+    expect(captured.values).toHaveLength(0);
+  });
+
+  // The refusal is a rule about this login, not a deletion of the row — which
+  // is why it is safe. Hand the identity back to the app by unsetting
+  // `ADMIN_PASSWORD` and its stored password works again, the same way
+  // `isEnvAdmin` stops being reported.
+  it('accepts that same stored hash once ADMIN_PASSWORD is unset', async () => {
+    const passwordHash = await hashPassword('planted-password');
+    const { db } = makeFakeDb([[{ ...ROW, email: 'root@example.com', passwordHash }]]);
+    const svc = new AuthService(
+      db,
+      makeConfig({ adminEmail: 'root@example.com', adminPassword: '' }),
+    );
+    const result = await svc.loginWithPassword('root@example.com', 'planted-password');
+    expect(result.user.email).toBe('root@example.com');
+    expect(result.user.isEnvAdmin).toBe(false);
+  });
+
+  /**
+   * With password sign-in switched off, `ADMIN_PASSWORD` is a credential
+   * nothing accepts: reporting the account as the environment's admin would
+   * send its owner to a login method the deployment does not offer.
+   */
+  it('is not reported as the env admin when password login is disabled', async () => {
+    const { db } = makeFakeDb([[{ ...ROW, email: 'root@example.com' }]]);
+    const svc = new AuthService(
+      db,
+      makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret', loginPasswordEnabled: false }),
+    );
+    const accounts = await svc.listAccounts();
+    expect(accounts.find((a) => a.email === 'root@example.com')?.isEnvAdmin).toBe(false);
+  });
+
+  // Not reported, but still that account: a hash stored for it while sign-in
+  // is off would be a credential the row is never meant to carry.
+  it('still refuses to store a password for the env admin while password login is disabled', async () => {
+    const cfg = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret', loginPasswordEnabled: false });
+    const { db: forCreate, captured } = makeFakeDb([[]]);
+    await expect(
+      new AuthService(forCreate, cfg).createAccount('root@example.com', 'Root', 'a-long-enough-password'),
+    ).rejects.toThrow('set in the deployment environment');
+    const { db: forChange, captured: capturedByChange } = makeFakeDb([
+      [{ ...ROW, email: 'root@example.com', passwordHash: null }],
+    ]);
+    await expect(
+      new AuthService(forChange, cfg).changePassword(ROW.id, undefined, 'a-long-enough-password'),
+    ).rejects.toThrow('set in the deployment environment');
+    for (const writes of [captured, capturedByChange]) {
+      expect(writes.set).toHaveLength(0);
+      expect(writes.values).toHaveLength(0);
+    }
+  });
+
   it('is disabled entirely when either env var is empty', async () => {
     for (const cfg of [
       makeConfig({ adminEmail: 'root@example.com', adminPassword: '' }),
@@ -198,6 +292,207 @@ describe('AuthService.createAccount / changePassword', () => {
   });
 });
 
+/**
+ * The three kinds of account that reach the Account page's password change,
+ * and what separates them.
+ *
+ * The reported bug was "an administrator cannot change their password", and
+ * the first two cases pin down that ROLE is not the dividing line: the Admin
+ * role lives in `roles.yaml` and is read by `IAdminAccessService` for the
+ * admin routes — it never reaches this service, so an Admin-role account is
+ * the same row as a business user's and takes byte-identical paths here. The
+ * real divide is the DEPLOYMENT admin, whose password is in the environment.
+ */
+describe('AuthService.changePassword — the three account kinds', () => {
+  const ENV_ADMIN = { adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' };
+
+  // (a) an Admin-role account and (b) a business user: same table, same code.
+  // Parameterised deliberately — one body proves the two are not distinguished
+  // rather than two bodies that could drift apart.
+  for (const kind of [
+    { label: 'an Admin-role account', email: 'admin-role@example.com', id: 'user-admin' },
+    { label: 'a business user', email: 'bob@example.com', id: 'user-bob' },
+  ]) {
+    describe(kind.label, () => {
+      const row = async () => ({
+        ...ROW,
+        id: kind.id,
+        email: kind.email,
+        passwordHash: await hashPassword('old-password'),
+      });
+
+      it('refuses a wrong current password', async () => {
+        const { db } = makeFakeDb([[await row()]]);
+        await expect(
+          new AuthService(db, makeConfig(ENV_ADMIN)).changePassword(
+            kind.id,
+            'not-it',
+            'new-password-1',
+          ),
+        ).rejects.toThrow('Current password is incorrect');
+      });
+
+      it('refuses an omitted current password once one is set', async () => {
+        const { db } = makeFakeDb([[await row()]]);
+        await expect(
+          new AuthService(db, makeConfig(ENV_ADMIN)).changePassword(
+            kind.id,
+            undefined,
+            'new-password-1',
+          ),
+        ).rejects.toThrow('Current password is incorrect');
+      });
+
+      it('applies the same password policy', async () => {
+        const { db } = makeFakeDb([[await row()]]);
+        await expect(
+          new AuthService(db, makeConfig(ENV_ADMIN)).changePassword(kind.id, 'old-password', 'short'),
+        ).rejects.toThrow(/at least/);
+      });
+
+      it('stores a new hash for the right current password', async () => {
+        const { db, captured } = makeFakeDb([[await row()], undefined]);
+        await new AuthService(db, makeConfig(ENV_ADMIN)).changePassword(
+          kind.id,
+          'old-password',
+          'new-password-1',
+        );
+        const set = captured.set[0] as { passwordHash: string };
+        expect(set.passwordHash.startsWith('scrypt:')).toBe(true);
+        // The stored hash is the NEW password and no longer the old one, so
+        // the next sign-in behaves the way the tester expected.
+        expect(await verifyPassword('new-password-1', set.passwordHash)).toBe(true);
+        expect(await verifyPassword('old-password', set.passwordHash)).toBe(false);
+      });
+
+      it('is not flagged as the deployment admin', async () => {
+        const { db } = makeFakeDb([[await row()]]);
+        const user = await new AuthService(db, makeConfig(ENV_ADMIN)).getUserById(kind.id);
+        expect(user?.isEnvAdmin).toBe(false);
+      });
+    });
+  }
+
+  // (c) the deployment admin. Its password is the environment's, so a stored
+  // hash would not replace it — it would ADD a credential that also signs in,
+  // outlives rotating ADMIN_PASSWORD, and then makes every later attempt that
+  // types the environment password as the current one fail against the stray
+  // hash. Refused in the service, not only hidden on the page.
+  describe('the deployment admin', () => {
+    const rootRow = { ...ROW, id: 'user-root', email: 'root@example.com', passwordHash: null };
+
+    it('is refused, and nothing is written', async () => {
+      const { db, captured } = makeFakeDb([[rootRow], undefined]);
+      await expect(
+        new AuthService(db, makeConfig(ENV_ADMIN)).changePassword(
+          'user-root',
+          'sup3r-secret',
+          'new-password-1',
+        ),
+      ).rejects.toThrow(/set in the deployment environment/);
+      expect(captured.set).toHaveLength(0);
+    });
+
+    it('is refused without a current password too — the no-hash path no longer lets a session holder plant one', async () => {
+      const { db, captured } = makeFakeDb([[rootRow], undefined]);
+      await expect(
+        new AuthService(db, makeConfig(ENV_ADMIN)).changePassword(
+          'user-root',
+          undefined,
+          'new-password-1',
+        ),
+      ).rejects.toThrow(/cannot be changed here/);
+      expect(captured.set).toHaveLength(0);
+    });
+
+    it('is refused even once a hash exists, and the refusal names the real reason', async () => {
+      const passwordHash = await hashPassword('planted-password');
+      const { db } = makeFakeDb([[{ ...rootRow, passwordHash }], undefined]);
+      await expect(
+        new AuthService(db, makeConfig(ENV_ADMIN)).changePassword(
+          'user-root',
+          'planted-password',
+          'short',
+        ),
+        // Refused BEFORE the policy check: being sent to pick a longer password
+        // would be a lie about why the change cannot happen.
+      ).rejects.toThrow(/deployment environment/);
+    });
+
+    it('carries the flag to the client without any part of the credential', async () => {
+      const { db } = makeFakeDb([[rootRow]]);
+      const user = await new AuthService(db, makeConfig(ENV_ADMIN)).getUserById('user-root');
+      expect(user?.isEnvAdmin).toBe(true);
+      // The whole shape, pinned the way listAccounts pins its own: these keys
+      // and no others, so a column added to `users` cannot reach the browser
+      // by being spread in, and one that is dropped is noticed here.
+      expect(Object.keys(user ?? {}).sort()).toEqual([
+        'avatarUrl',
+        'email',
+        'id',
+        'isEnvAdmin',
+        'name',
+        'onboardingDone',
+      ]);
+      expect(user?.onboardingDone).toBe(false);
+      expect(JSON.stringify(user)).not.toContain('sup3r-secret');
+    });
+
+    // The Account page is not the only way to a stored hash: any admin can aim
+    // "Set password" (POST /api/admin/accounts → createAccount) at this email.
+    // A hash planted there would be exactly the second credential the
+    // self-service refusal exists to prevent, so it is refused at the service.
+    it("is refused an admin's Set password too, and nothing is written", async () => {
+      const { db, captured } = makeFakeDb([[rootRow]]);
+      await expect(
+        new AuthService(db, makeConfig(ENV_ADMIN)).createAccount(
+          // Canonicalised first: a differently-cased ADMIN_EMAIL is the same
+          // identity and must not slip past the check.
+          'Root@Example.com',
+          'Root',
+          'planted-password',
+        ),
+      ).rejects.toThrow(/set in the deployment environment/);
+      expect(captured.values).toHaveLength(0);
+      expect(captured.conflict).toHaveLength(0);
+    });
+
+    it("is refused before the policy check, so the admin is told the real reason", async () => {
+      const { db } = makeFakeDb([[rootRow]]);
+      await expect(
+        new AuthService(db, makeConfig(ENV_ADMIN)).createAccount('root@example.com', 'Root', 'short'),
+      ).rejects.toThrow(/deployment environment/);
+    });
+
+    it('takes an admin-set password again once ADMIN_PASSWORD is unset', async () => {
+      const { db, captured } = makeFakeDb([[rootRow]]);
+      await new AuthService(
+        db,
+        makeConfig({ adminEmail: 'root@example.com', adminPassword: '' }),
+      ).createAccount('root@example.com', 'Root', 'ordinary-password');
+      expect((captured.values[0] as { passwordHash: string }).passwordHash.startsWith('scrypt:')).toBe(
+        true,
+      );
+    });
+
+    it('is an ordinary account — form and all — while ADMIN_PASSWORD is unset', async () => {
+      const passwordHash = await hashPassword('old-password');
+      const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: '' });
+      const flagged = await new AuthService(
+        makeFakeDb([[{ ...rootRow, passwordHash }]]).db,
+        config,
+      ).getUserById('user-root');
+      expect(flagged?.isEnvAdmin).toBe(false);
+
+      const { db, captured } = makeFakeDb([[{ ...rootRow, passwordHash }], undefined]);
+      await new AuthService(db, config).changePassword('user-root', 'old-password', 'new-password-1');
+      expect((captured.set[0] as { passwordHash: string }).passwordHash.startsWith('scrypt:')).toBe(
+        true,
+      );
+    });
+  });
+});
+
 describe('AuthService.listAccounts', () => {
   it('reports hasPassword without ever exposing the hash', async () => {
     const passwordHash = await hashPassword('pw-longer-than-8');
@@ -214,6 +509,44 @@ describe('AuthService.listAccounts', () => {
     ]);
     expect(JSON.stringify(accounts)).not.toContain('scrypt:');
   });
+
+  it('marks the env admin with and without a stored hash, independently of hasPassword', async () => {
+    const passwordHash = await hashPassword('pw-longer-than-8');
+    const rows = [
+      { ...ROW, id: 'root-hashed', email: 'root@example.com', passwordHash, createdAt: new Date() },
+      { ...ROW, id: 'user-2', email: 'bob@example.com', passwordHash, createdAt: new Date() },
+      { ...ROW, id: 'user-3', email: 'sso@example.com', passwordHash: null, createdAt: new Date() },
+    ];
+    const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' });
+
+    const withHash = await new AuthService(makeFakeDb([rows]).db, config).listAccounts();
+    expect(withHash.map((a) => [a.email, a.hasPassword, a.isEnvAdmin])).toEqual([
+      ['root@example.com', true, true],
+      ['bob@example.com', true, false],
+      ['sso@example.com', false, false],
+    ]);
+
+    const noHashRows = [{ ...rows[0], passwordHash: null }];
+    const withoutHash = await new AuthService(makeFakeDb([noHashRows]).db, config).listAccounts();
+    expect(withoutHash.map((a) => [a.hasPassword, a.isEnvAdmin])).toEqual([[false, true]]);
+
+    // Neither the hash nor the environment password ever leaves the service.
+    const json = JSON.stringify([...withHash, ...withoutHash]);
+    expect(json).not.toContain('scrypt:');
+    expect(json).not.toContain('sup3r-secret');
+    for (const account of [...withHash, ...withoutHash]) {
+      expect(Object.keys(account).sort()).toEqual(
+        ['createdAt', 'email', 'hasPassword', 'id', 'isEnvAdmin', 'name'],
+      );
+    }
+  });
+
+  it('is not the env admin while ADMIN_PASSWORD is unset (SSO-only deployment)', async () => {
+    const rows = [{ ...ROW, email: 'root@example.com', passwordHash: null, createdAt: new Date() }];
+    const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: '' });
+    const accounts = await new AuthService(makeFakeDb([rows]).db, config).listAccounts();
+    expect(accounts[0].isEnvAdmin).toBe(false);
+  });
 });
 
 /**
@@ -264,7 +597,7 @@ describe('AuthService — the SSO domain allow-list', () => {
       adminEmail: 'root@gmail.com',
       adminPassword: 'sup3r-secret',
     });
-    const { db } = makeFakeDb([[{ ...ROW, email: 'root@gmail.com', name: 'root' }]]);
+    const { db } = makeFakeDb([[], [{ ...ROW, email: 'root@gmail.com', name: 'root' }]]);
     const out = await new AuthService(db, outsideConfig).loginWithPassword(
       'root@gmail.com',
       'sup3r-secret',