@bevel-software/platform-core-backend 0.22.0 → 0.24.0

package/src/modules/agent-instructions/shared-file-rules.ts

@@ -0,0 +1,314 @@
+/**
+ * The rules that apply to MORE THAN ONE file tool, written ONCE.
+ *
+ * They used to be appended, in full, to every tool description that they
+ * covered: the content rule rode on all twelve file tools, the agent-guide
+ * reminder on all of them plus the shell, the write-mode and escape-sequence
+ * paragraphs on two or three apiece. A description then ran to two or three
+ * thousand characters, most of it text the agent had already read on the tool
+ * above — and clients cut long descriptions from the END, which is where the
+ * text specific to the tool sits. Agents saw `file_stat`, `read_file`,
+ * `write_file` and `write_files` arrive ending in "[truncated]".
+ *
+ * So the shared rules are stated in TWO places and in neither description:
+ *
+ *  - the MCP `instructions` of the initialize handshake (see `compose.ts`),
+ *    which Claude Code, Claude Desktop and Cursor put in the system prompt;
+ *  - the platform-managed agent guide at the repository root (`AGENTS.md` by
+ *    default), rendered from `{{sharedFileRules}}` in the template — claude.ai
+ *    on the web, the Agent SDK and Cline drop `instructions`, and a guide the
+ *    agent is told to read before its first action is always available.
+ *
+ * Both places get the SAME string, from {@link sharedFileRulesSection} — not
+ * two hand-mirrored copies. A rule written twice is a rule that drifts, and a
+ * drifted rule is worse than a repeated one, because the agent cannot tell
+ * which copy is current. Each description ends instead with
+ * {@link sharedRulesPointer}, one sentence naming the section and the file.
+ *
+ * Pure text, a function of the layout only: the guide's file name is a
+ * deployment setting, so nothing here may snapshot `AGENTS.md`.
+ */
+
+import {
+  DEFAULT_KB_LAYOUT,
+  agentsFileOf,
+  LEGACY_AGENTS_FILE,
+  platformFilesByDepth,
+  type KbLayout,
+} from '@bevel-software/platform-shared';
+import { CHAIN_FAILURES_RULE, CHAIN_LARGE_RESULTS_RULE } from '@bevel-software/platform-mcp-core';
+
+/** The heading the rules live under, in both places and in the pointer sentence. */
+export const SHARED_RULES_SECTION = 'Working with files';
+
+/**
+ * The guide's name on a knowledge base seeded before it was renamed to
+ * {@link LEGACY_AGENTS_FILE}. Named in the conventions rule because the seeder
+ * never deletes a file it did not expect, so such a knowledge base still
+ * carries one.
+ */
+const PRE_RENAME_AGENTS_FILE = 'CLAUDE.md';
+
+/**
+ * The ceiling on the whole section. Pinned by a test: the section lands in
+ * every conversation through two channels, and a rule moved here to shorten a
+ * description has only moved the cost if the section itself grows without
+ * limit. Measured against {@link sharedFileRulesSection} under the default
+ * layout.
+ *
+ * 7,000 since two rules moved in from descriptions they took past their cap:
+ * the chain's own (what a failed chain and an oversized result answer), true
+ * of every call rather than of how to write one, and why large, escape-heavy
+ * and binary content goes by upload, which three write tools each said in
+ * full.
+ */
+export const SHARED_FILE_RULES_CAP = 7_000;
+
+/** One shared rule: how the guide heads it, and the rule itself. */
+export interface SharedFileRule {
+  /** Stable id, so a test can name the rule that went missing. */
+  id: string;
+  /** The heading this rule gets in the section. */
+  heading: string;
+  /** The rule, as both places state it. Markdown paragraphs, blank-line separated. */
+  body: string;
+}
+
+/**
+ * Every shared rule, in reading order: what to read first, what the content
+ * is, what a write may do, then the two protocols that guard a destructive
+ * call.
+ *
+ * The bodies are the sentences the descriptions used to carry, moved rather
+ * than rewritten wherever the wording still reads outside its old tool — the
+ * ones that said "this tool" or "this call" name the tools instead.
+ */
+export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
+  const agentsFile = agentsFileOf(layout);
+  return [
+    {
+      id: 'agent-guide',
+      heading: "This knowledge base's own conventions",
+      body: conventionsRule(agentsFile),
+    },
+    {
+      id: 'content-kinds',
+      heading: 'Text, documents, images and other binaries',
+      body:
+        'read_file returns text for text files and extracted text for documents ' +
+        '(.docx/.pptx/.xlsx/.odt/.odp/.ods/.pdf, .eml/.msg); write_file, write_files and edit_file accept TEXT only — ' +
+        'they refuse documents, images, archives and other binary files (legacy .doc/.ppt/.xls included) with kind ' +
+        "`binary_not_writable`, naming the file's kind and the tool to use instead; copy_file, move_file and delete_file " +
+        'act on bytes of any kind and unzip extracts the entries of a `.zip`; new binary content arrives by upload ' +
+        '(see below). file_stat reports `contentMode` ' +
+        '(`text` | `document` | `binary`) so you can decide before acting.\n\n' +
+        'Office and OpenDocument files (.docx/.pptx/.xlsx, .odt/.odp/.ods) and PDFs read as EXTRACTED text under an ' +
+        'honest `[extracted text of …]` header, with `[slide N]`/`[sheet: Name]`/`[page N]` markers — the extraction ' +
+        'is READ-ONLY (layout/images omitted; such files cannot be edited as text, only replaced by uploading a new ' +
+        'version). Email files (.eml/.msg) read the same way: a `[from]`/`[to]`/`[subject]`/`[date]` header block, the ' +
+        'body (plain-text part preferred; an HTML-only body is stripped to text), and an `[attachments]` name list — ' +
+        'attachments are listed, never extracted. grep searches inside all of those, through the same extractions.\n\n' +
+        'Images (.png/.jpg/.jpeg/.gif/.webp) read as the IMAGE ITSELF, as native MCP image content with a one-line ' +
+        'text note naming the file, so you can look at the picture — up to 3.5 MB of raw image data; a larger image ' +
+        'gets an honest refusal asking for a locally downscaled copy or a smaller export (`.svg` is text and reads as ' +
+        'text). Images come back only on a DIRECT read_file: inside `call_tool_chain` an image read yields an ' +
+        '`{ image_omitted, note }` stub instead, so read an image outside a chain when you mean to look at it. Any other ' +
+        'binary file reads as a one-line description rather than raw bytes.',
+    },
+    {
+      id: 'write-mode',
+      heading: 'What a write may do at a path',
+      body:
+        'On write_file and write_files, `mode` decides what may happen at a path and DEFAULTS TO `create`: `create` ' +
+        'writes a new file and refuses a path that already exists (`exists`, with the path — pass `mode: overwrite` to ' +
+        'replace it), `overwrite` replaces what is there (creating it if there is nothing), `update` replaces an ' +
+        'existing file and refuses a path that does not exist (`missing`). A refused path is left exactly as it was.',
+    },
+    {
+      id: 'images-in-pages',
+      heading: 'Where the images a page uses go',
+      body:
+        'Keep them in an `assets/` folder next to the page that uses them and link them with a relative path, e.g. ' +
+        '`![Approval screen](./assets/approval-screen.png)`; the page renders them inline.',
+    },
+    {
+      id: 'escape-sequences',
+      heading: 'Escape sequences in content you send',
+      body:
+        'On write_file, write_files and edit_file, which take content as a JSON string: some clients decode escape ' +
+        'sequences in arguments before sending, so content meant to CONTAIN an escape rather than what it stands for ' +
+        '(the six characters backslash, `u`, `0`, `0`, `4`, `1`, say, rather than the letter `A`) can reach the tool ' +
+        'already decoded — what arrives is stored byte for byte, so when that distinction matters, verify what landed ' +
+        '(`read_file`, or a hash) and send such content by upload (see below), which lands it unchanged.',
+    },
+    {
+      // The reason the upload route exists, said once. Each of the three tools
+      // that take content as a JSON string names the route in one sentence of
+      // its own; WHY a file should go that way, and how, is here.
+      id: 'upload-route',
+      heading: 'Large, escape-heavy and binary content goes by upload',
+      body:
+        'write_file, write_files and edit_file take content as a JSON string you have to type out in full, so a long ' +
+        'file is cut off mid-answer, a file full of backslashes or `\\u` escapes fails to parse as a parameter, and ' +
+        'an image, a PDF or a zip cannot be sent at all. For any of those: call `request_file_upload`, POST the file — ' +
+        'or one zip holding many files — to the address it answers with any HTTP client ' +
+        '(`curl -X POST --data-binary @<file> "<uploadUrl>?filename=<name>"`), then `apply_file_upload` to land it on ' +
+        'a branch in one commit. The bytes never pass through the conversation, so nothing is cut or mangled on the ' +
+        'way. A person can also use Upload in the app.',
+    },
+    {
+      id: 'dry-run-confirm',
+      heading: 'Dry-run before a move, a copy or a folder delete',
+      body:
+        'move_file, copy_file and delete_folder take `dryRun: true`: it changes nothing and answers the impact — ' +
+        'what the call would touch, `allowed`, and `reason` when it may not run. A non-empty folder is deleted, and a ' +
+        'move that changes your access runs, only with `confirm: true`; without it the call changes nothing and ' +
+        'returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — ' +
+        'dry-run, check the impact, then confirm. delete_file takes neither: it removes the one file you named, so ' +
+        'check it first with file_stat (`deletable`) if you are unsure.',
+    },
+    {
+      id: 'managed-items',
+      heading: 'What these tools never move or delete',
+      body:
+        `A platform file (${platformFileList(layout)}) is refused with ` +
+        '"<name> is a platform file and stays in its folder." — a folder that moves ' +
+        'takes its own platform files along, still in their folder, and a folder that is deleted takes them with it in ' +
+        'the same one change, so its files are never left ungoverned part-way. A platform folder (the repository root ' +
+        `or a reserved root folder such as \`${layout.knowledgeBaseDir}/\`) and git metadata are refused, and so is creating a ` +
+        'platform file or folder at a destination (renaming a note to `access.md` is refused). A path that is, or goes ' +
+        'through, a symbolic link is refused: links are never followed or removed. On a protected branch you must be ' +
+        'able to write everything the call touches — for a folder, every file under it, at its old and its new path. ' +
+        'file_stat reports `managed`, `movable` and `deletable` so you can tell before the call.',
+    },
+    {
+      id: 'refused-for-permissions',
+      heading: 'When a write is refused for permissions',
+      body:
+        'A refusal is not necessarily the end of the road: the `write-denied` error says whether you may propose the ' +
+        'change instead (create a branch from this one, repeat the call on it, then `open_change_request` into this ' +
+        'branch) and lists those steps.',
+    },
+    {
+      // What a chain DOES, as opposed to how to write one — which stays in
+      // `call_tool_chain`'s own description. The sentences are `mcp-core`'s,
+      // the same ones a surface with no shared rules puts in the description
+      // itself, so the rule reads the same wherever an agent finds it. What a
+      // chained read does to an image is in the content rule above.
+      id: 'tool-chain',
+      heading: 'When several calls run as one chain',
+      body: `On call_tool_chain: ${CHAIN_FAILURES_RULE}\n\n${CHAIN_LARGE_RESULTS_RULE}`,
+    },
+  ];
+}
+
+/**
+ * The platform files as the rules list them — from the one function that knows
+ * which they are, so the list cannot drift from what actually refuses a move,
+ * and the guide appears under this deployment's name for it.
+ *
+ * WITH THE DEPTH each name counts at, because the name alone is half the rule:
+ * `access.md` governs the folder it sits in and `.bevelignore` layers, so both
+ * are platform files wherever they are; `roles.yaml` and the guide are read
+ * from the repository root only, so a nested copy of either is ordinary
+ * content that moves and deletes like any page. An agent told only the names
+ * refuses a rename it may make, and trusts a nested `access.md` it may not.
+ */
+function platformFileList(layout: KbLayout): string {
+  const { anyDepth, rootOnly } = platformFilesByDepth(layout);
+  const quoted = (names: readonly string[]): string => names.map((name) => `\`${name}\``).join(' or ');
+  return `${quoted(anyDepth)} in any folder, ${quoted(rootOnly)} at the repository root`;
+}
+
+/**
+ * The conventions reminder — which file holds the author's own rules for this
+ * knowledge base, and to read it first.
+ *
+ * `CLAUDE.md` is named as a fallback because knowledge bases seeded before the
+ * rename still carry one. WHEN THE GUIDE HAS BEEN RENAMED the sentence names
+ * two files, ours first: the second is the organisation's OWN `AGENTS.md`,
+ * which on such a deployment is ordinary content the platform never touches —
+ * and which no harness reads for a remote agent, because a remote agent has no
+ * checkout. Under the default name the wording collapses to the one file it
+ * has always named.
+ */
+function conventionsRule(agentsFile: string): string {
+  if (agentsFile === LEGACY_AGENTS_FILE) {
+    return (
+      `Before your first read or change in a workspace, read \`${LEGACY_AGENTS_FILE}\` at the KB root — or ` +
+      `\`${PRE_RENAME_AGENTS_FILE}\` on a knowledge base seeded before it was renamed — if either exists: it holds ` +
+      "the author's conventions for this knowledge base, and you should follow them."
+    );
+  }
+  return (
+    `Before your first read or change in a workspace, read \`${agentsFile}\` at the KB root, then ` +
+    `\`${LEGACY_AGENTS_FILE}\` if it also exists (the organisation's own conventions) — or ` +
+    `\`${PRE_RENAME_AGENTS_FILE}\` on a knowledge base seeded before it was renamed: together they hold the ` +
+    'conventions for this knowledge base, and you should follow them.'
+  );
+}
+
+/**
+ * The shared rules as ONE markdown section — the string both channels carry,
+ * byte for byte. A `##` section so it drops into the managed guide at that
+ * level and still reads as a block in the instructions blob.
+ */
+export function sharedFileRulesSection(layout: KbLayout): string {
+  const body = sharedFileRules(layout)
+    .map((rule) => `### ${rule.heading}\n\n${rule.body}`)
+    .join('\n\n');
+  return `## ${SHARED_RULES_SECTION}\n\n${body}`;
+}
+
+/**
+ * The longest guide file name the pointer sentence spells out. Beyond this it
+ * names the guide by its ROLE instead (see {@link sharedRulesPointer}).
+ *
+ * There has to be a bound somewhere, because the pointer rides on every file
+ * tool and a file name is not a fixed cost: `validateFilename` allows a name
+ * of up to 255 bytes, so an unbounded pointer could reach 318 characters and
+ * push `file_stat` to 1,428 — over the description cap, recreating on a
+ * renamed deployment exactly the truncation this module exists to prevent, and
+ * invisibly, because every measurement is taken under the default layout.
+ *
+ * 40 is well past any name a deployment plausibly picks
+ * (`ENGINEERING-AGENT-CONVENTIONS.md` is 32) and the fallback below is only
+ * reachable past it.
+ */
+export const POINTER_GUIDE_NAME_BUDGET = 40;
+
+/**
+ * The one sentence a tool description ends with, in place of the paragraphs it
+ * used to carry. Short on purpose: it costs every description the same ~100
+ * characters at worst, and its whole job is to name the section and the file
+ * to read.
+ *
+ * BOUNDED BY CONSTRUCTION, which is what lets the description cap mean
+ * something on a deployment that renamed its guide: a name within
+ * {@link POINTER_GUIDE_NAME_BUDGET} is spelled out, and a longer one gets the
+ * generic wording. Naming the file is the better sentence and wins whenever it
+ * fits; a name past the budget is pathological, and there the choice is between
+ * a sentence that says where to look and a catalog entry the client cuts. The
+ * guide's own name is still in the section's first rule either way.
+ *
+ * An absent layout means the default one, as it does in
+ * `composeAgentInstructions`: a caller reading the layout from configuration
+ * gets `undefined` when none is set, and the pointer must still name a file.
+ */
+export function sharedRulesPointer(layout: KbLayout = DEFAULT_KB_LAYOUT): string {
+  const agentsFile = agentsFileOf(layout);
+  const where =
+    agentsFile.length <= POINTER_GUIDE_NAME_BUDGET ? agentsFile : 'the agent guide at the KB root';
+  return ` Shared rules for all file tools: see "${SHARED_RULES_SECTION}" in ${where}.`;
+}
+
+/**
+ * The most the pointer can ever cost a description, over every layout. What the
+ * description cap is measured against, the way the tool prefix is measured at
+ * ITS cap rather than at whatever the current admin wrote: a description that
+ * only fits beside the short default guide name does not really fit.
+ */
+export const SHARED_RULES_POINTER_MAX = Math.max(
+  sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: `${'x'.repeat(POINTER_GUIDE_NAME_BUDGET - 3)}.md` }).length,
+  sharedRulesPointer({ ...DEFAULT_KB_LAYOUT, agentsFile: `${'x'.repeat(POINTER_GUIDE_NAME_BUDGET + 10)}.md` }).length,
+);

package/src/modules/audit/agent-audit.service.ts

@@ -1,4 +1,4 @@
-import { and, asc, count, desc, eq, isNull, lt, or, type SQL } from 'drizzle-orm';
+import { and, count, desc, eq, isNull, lt, or, type SQL } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 import type { Database } from '../database/connection.js';
 import { agentConnections, agentEvents, oauthTokens, users } from '../database/schema.js';
@@ -101,7 +101,9 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
         .from(agentConnections)
         .innerJoin(users, eq(agentConnections.userId, users.id))
         .where(mine === null ? undefined : eq(agentConnections.userId, mine))
-        .orderBy(asc(users.email), desc(agentConnections.connectedAt)),
+        // Not by email: that column is randomized ciphertext, and ORDER BY
+        // on it is noise. The sort below orders by email in-process.
+        .orderBy(desc(agentConnections.connectedAt)),
       this.db
         .select({ keyId: agentEvents.keyId, connectionId: agentEvents.connectionId, n: count() })
         .from(agentEvents)

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

@@ -0,0 +1,253 @@
+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 {
+  AccountAdmissionRefusedError,
+  AccountChangeRefusedError,
+  AccountDeactivatedError,
+  AuthBackendError,
+  type AccountProvisionReason,
+  type IAccountAdmission,
+} from '../account-admission.js';
+import { hashPassword } from '../password-hash.js';
+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.
+ */
+function makeFakeDb(queue: unknown[]) {
+  const captured: { values: Record<string, unknown>[]; set: Record<string, unknown>[] } = { values: [], set: [] };
+  function nextChain(): unknown {
+    const result = queue.shift();
+    const chain: Record<string, unknown> = {};
+    const passthrough = (recorder?: (arg: Record<string, unknown>) => void) =>
+      vi.fn((arg?: unknown) => {
+        recorder?.(arg as Record<string, unknown>);
+        return chain;
+      });
+    Object.assign(chain, {
+      values: passthrough((a) => captured.values.push(a)),
+      set: passthrough((a) => captured.set.push(a)),
+      where: passthrough(),
+      limit: passthrough(),
+      from: passthrough(),
+      orderBy: passthrough(),
+      returning: passthrough(),
+      onConflictDoUpdate: passthrough(),
+      onConflictDoNothing: passthrough(),
+      then: (ok: (v: unknown) => unknown, ko: (e: unknown) => unknown) => Promise.resolve(result).then(ok, ko),
+    });
+    return chain;
+  }
+  const db = {
+    insert: vi.fn(() => nextChain()),
+    select: vi.fn(() => nextChain()),
+    update: vi.fn(() => nextChain()),
+  } as unknown as Database;
+  return { db, captured };
+}
+
+function makeConfig(over: Partial<CoreConfig> = {}): CoreConfig {
+  return { jwtSecret: 'test-jwt-secret', adminEmail: '', adminPassword: '', allowedEmailDomains: [], ...over } as CoreConfig;
+}
+
+const ROW = { id: 'user-1', email: 'alice@example.com', name: 'Alice', avatarUrl: null, onboardingDone: false, deactivatedAt: null };
+const OFF = { ...ROW, deactivatedAt: new Date('2026-09-01') };
+
+function recordingPort(verdict: Awaited<ReturnType<IAccountAdmission['canProvision']>>) {
+  const asked: Array<[string, AccountProvisionReason]> = [];
+  const port: IAccountAdmission = {
+    canProvision: async (email, reason) => {
+      asked.push([email, reason]);
+      return verdict;
+    },
+  };
+  return { port, asked };
+}
+
+describe('signing in with a switched-off account', () => {
+  it('refuses a password sign-in once the password is proven, and says why', async () => {
+    const passwordHash = await hashPassword('a-long-enough-password');
+    const { db } = makeFakeDb([[{ ...OFF, passwordHash }]]);
+    const svc = new AuthService(db, makeConfig());
+    await expect(svc.loginWithPassword('alice@example.com', 'a-long-enough-password')).rejects.toBeInstanceOf(
+      AccountDeactivatedError,
+    );
+  });
+
+  it('gives a wrong password the same answer as for any account, so it reveals nothing', async () => {
+    const passwordHash = await hashPassword('a-long-enough-password');
+    const { db } = makeFakeDb([[{ ...OFF, passwordHash }]]);
+    const svc = new AuthService(db, makeConfig());
+    await expect(svc.loginWithPassword('alice@example.com', 'the-wrong-password')).rejects.toThrow('Invalid credentials');
+  });
+
+  it('refuses a single sign-on sign-in, without issuing a session', async () => {
+    const { db } = makeFakeDb([[OFF]]);
+    const svc = new AuthService(db, makeConfig());
+    await expect(svc.loginWithSso('alice@example.com', 'Alice')).rejects.toBeInstanceOf(AccountDeactivatedError);
+  });
+
+  it('refuses an embed identity', async () => {
+    const { db } = makeFakeDb([[OFF]]);
+    const svc = new AuthService(db, makeConfig());
+    await expect(svc.getOrCreateByEmail('alice@example.com')).rejects.toBeInstanceOf(AccountDeactivatedError);
+  });
+});
+
+describe('a session that outlives a deactivation', () => {
+  it('stops being accepted once the account is switched off', async () => {
+    const { db } = makeFakeDb([[ROW], [{ deactivatedAt: new Date() }]]);
+    const svc = new AuthService(db, makeConfig());
+    const { token } = await svc.loginWithSso('alice@example.com', 'Alice');
+    // The signature alone is still good…
+    expect(svc.verifyToken(token).userId).toBe(ROW.id);
+    // …but the session is not.
+    await expect(svc.resolveSession(token)).rejects.toBeInstanceOf(AccountDeactivatedError);
+  });
+
+  it('is told apart from a refusal when the account cannot be looked up', async () => {
+    const { db } = makeFakeDb([[ROW]]);
+    const svc = new AuthService(db, makeConfig());
+    const { token } = await svc.loginWithSso('alice@example.com', 'Alice');
+    vi.mocked(db.select).mockImplementationOnce(() => {
+      throw new Error('db down');
+    });
+    await expect(svc.resolveSession(token)).rejects.toBeInstanceOf(AuthBackendError);
+  });
+
+  it('is accepted while the account is on', async () => {
+    const { db } = makeFakeDb([[ROW], [{ deactivatedAt: null }]]);
+    const svc = new AuthService(db, makeConfig());
+    const { token } = await svc.loginWithSso('alice@example.com', 'Alice');
+    await expect(svc.resolveSession(token)).resolves.toEqual({ userId: ROW.id, email: ROW.email });
+  });
+});
+
+describe('AuthService.isActive', () => {
+  it('reads once and keeps the answer briefly', async () => {
+    const { db } = makeFakeDb([[{ deactivatedAt: null }]]);
+    const svc = new AuthService(db, makeConfig());
+    expect(await svc.isActive('user-1')).toBe(true);
+    expect(await svc.isActive('user-1')).toBe(true);
+    expect(vi.mocked(db.select)).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats the deployment admin as on whatever its row says, so its rescue session works', async () => {
+    const config = makeConfig({ adminEmail: 'root@example.com', adminPassword: 'sup3r-secret' });
+    const { db } = makeFakeDb([[{ email: 'root@example.com', deactivatedAt: new Date() }]]);
+    expect(await new AuthService(db, config).isActive('root-id')).toBe(true);
+  });
+
+  it('treats an account that no longer exists as off', async () => {
+    const { db } = makeFakeDb([[]]);
+    expect(await new AuthService(db, makeConfig()).isActive('gone')).toBe(false);
+  });
+
+  it('forgets the cached answer when this process switches the account off', async () => {
+    const { db } = makeFakeDb([[{ deactivatedAt: null }], [ROW], [], [{ deactivatedAt: new Date() }]]);
+    const svc = new AuthService(db, makeConfig());
+    expect(await svc.isActive(ROW.id)).toBe(true);
+    expect(await svc.deactivate(ROW.id)).toBe(true);
+    expect(await svc.isActive(ROW.id)).toBe(false);
+  });
+});
+
+describe('AuthService.deactivate', () => {
+  it('records when the account was switched off', async () => {
+    const { db, captured } = makeFakeDb([[ROW], []]);
+    expect(await new AuthService(db, makeConfig()).deactivate(ROW.id)).toBe(true);
+    expect(captured.set[0].deactivatedAt).toBeInstanceOf(Date);
+  });
+
+  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();
+  });
+
+  it('refuses the accounts the platform runs its own work as', async () => {
+    const { db } = 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();
+  });
+});
+
+describe('AuthService.reactivate', () => {
+  it('asks the admission port, as for a new account, and switches it on when admitted', async () => {
+    const { port, asked } = recordingPort({ ok: true });
+    const { db, captured } = makeFakeDb([[OFF], []]);
+    expect(await new AuthService(db, makeConfig(), port).reactivate(ROW.id)).toBe(true);
+    expect(asked).toEqual([['alice@example.com', 'reactivate']]);
+    expect(captured.set[0].deactivatedAt).toBeNull();
+  });
+
+  it("refuses with the port's words when there is no room, and changes nothing", async () => {
+    const { port } = recordingPort({ ok: false, message: 'All 3 seats are taken' });
+    const { db } = makeFakeDb([[OFF]]);
+    const svc = new AuthService(db, makeConfig(), port);
+    await expect(svc.reactivate(ROW.id)).rejects.toThrow('All 3 seats are taken');
+    expect(vi.mocked(db.update)).not.toHaveBeenCalled();
+  });
+
+  it('does not ask about an account that is already on', async () => {
+    const { port, asked } = recordingPort({ ok: false, message: 'full' });
+    const { db } = makeFakeDb([[ROW]]);
+    expect(await new AuthService(db, makeConfig(), port).reactivate(ROW.id)).toBe(true);
+    expect(asked).toEqual([]);
+  });
+});
+
+describe('a first sign-in the port would rather keep waiting', () => {
+  const waiting = { ok: false as const, message: 'No seat left; the admin can let you in', waitForAdmin: true };
+
+  it('puts the person on file switched off, and still refuses the sign-in', async () => {
+    const { port } = recordingPort(waiting);
+    const { db, captured } = makeFakeDb([[], []]);
+    const svc = new AuthService(db, makeConfig(), port);
+    const err = await svc.loginWithSso('new@example.com', 'New').catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(AccountAdmissionRefusedError);
+    expect((err as AccountAdmissionRefusedError).waitingForAdmin).toBe(true);
+    expect((err as Error).message).toBe(waiting.message);
+    expect(captured.values).toHaveLength(1);
+    expect(captured.values[0]).toMatchObject({ email: 'new@example.com' });
+    expect(captured.values[0].deactivatedAt).toBeInstanceOf(Date);
+  });
+
+  it('is a plain refusal when an admin creates the account', async () => {
+    const { port } = recordingPort(waiting);
+    const { db } = 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();
+  });
+});
+
+describe('AuthService.createAccount without a password', () => {
+  it('makes an account for single sign-on, with no hash stored', async () => {
+    const { db, captured } = makeFakeDb([[{ ...ROW, passwordHash: null }]]);
+    const user = await new AuthService(db, makeConfig()).createAccount('Alice@Example.com', '');
+    expect(user.email).toBe('alice@example.com');
+    // The index column is written with the address; the handle indexes it.
+    expect(captured.values[0]).toEqual({ email: 'alice@example.com', emailBidx: 'alice@example.com', name: 'alice' });
+  });
+
+  it('asks the admission port, as any new account does', async () => {
+    const { port, asked } = recordingPort({ ok: true });
+    const { db } = makeFakeDb([[], [{ ...ROW, passwordHash: null }]]);
+    await new AuthService(db, makeConfig(), port).createAccount('alice@example.com', 'Alice');
+    expect(asked).toEqual([['alice@example.com', 'admin-create']]);
+  });
+});

package/src/modules/auth/__tests__/account-erasure.approval-gate.test.ts

@@ -70,6 +70,9 @@ function harness(opts: { participants?: IErasureParticipant[] } = {}) {
       locked.push((statement.queryChunks ?? []).filter((c) => typeof c === 'number'));
       return { rows: [] };
     },
+    // The one read the transaction makes: the refusals recorded before the
+    // encryption release, which it matches by name. None here.
+    select: () => ({ from: () => ({ where: async () => [] }) }),
     delete: (table: unknown) => ({
       where: () => {
         order.push(`delete:${tableOf(table)}`);
@@ -176,8 +179,9 @@ describe('AccountErasureService: approvals are rewritten under the approval lock
     const committed = h.order.indexOf('delete:users');
     const sweep = h.order.indexOf('after-commit:pr_file_approvals');
     expect(sweep).toBeGreaterThan(committed);
-    // The change requests get the same treatment, and did before this.
-    expect(h.order).toContain('after-commit:change_requests');
+    // The change requests get the same treatment, twice: once for the
+    // authorship, once for the refusal note of an apply that was in flight.
+    expect(h.order.filter((step) => step === 'after-commit:change_requests')).toHaveLength(2);
     // Both guarded on `users`: the marker is only recorded for a clause that
     // names it, so a sweep that dropped the `notExists` lands here instead.
     expect(h.order.filter((step) => step.startsWith('unguarded:'))).toEqual([]);