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

package/src/modules/database/migrate.ts

@@ -1,9 +1,11 @@
 import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { sql } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('database');
-import { DEFAULT_DB_SCHEMA, dbSchemaOf, type Database } from './connection.js';
+import { DEFAULT_DB_SCHEMA, dbSchemaOf, piiKeysOf, type Database } from './connection.js';
 import { AdvisoryLock, withAdvisoryLock } from './advisory-lock.js';
+import { PII_SEALED_SHAPE_SQL_REGEX, isEncryptedBlob, type PiiKeys } from '../../shared/column-crypto.js';
 
 /*
  * ── Per-tier migration folders ──────────────────────────────────────────────
@@ -69,6 +71,9 @@ export async function runCoreMigrations(db: Database, folder: string): Promise<v
       log.info('Running core database migrations...');
       await migrate(db, { migrationsFolder: folder, migrationsTable: '__drizzle_migrations_core', migrationsSchema });
       log.info('Core migrations complete.');
+      // Under the same lock, before anything reads or writes a PII column:
+      // the data half of migration 0016, which SQL cannot do (see below).
+      await runPiiEncryptionBackfill(db);
     },
     { tenantKey },
   );
@@ -96,3 +101,350 @@ export async function runEnterpriseMigrations(db: Database, folder: string): Pro
     { tenantKey },
   );
 }
+
+/*
+ * ── PII column encryption backfill ──────────────────────────────────────────
+ *
+ * Migration 0016 adds the `*_bidx` columns; the DATA change — rewriting
+ * pre-existing plaintext PII to AES-256-GCM ciphertext and filling the blind
+ * indexes — happens here, programmatically, because it needs the key the
+ * handle holds (SQL migrations cannot encrypt). Runs on every start right after
+ * the core history, under the migrations lock, and is idempotent: sealed rows
+ * carry the `PII_CIPHERTEXT_PREFIX` marker and are excluded by the SELECT's
+ * own WHERE clause, so a completed backfill degenerates to one cheap,
+ * empty-result query per table.
+ *
+ * Concurrency: the migrations lock (keyed per tenant, like the history it
+ * guards) serialises two processes booting at once. Each UPDATE is also
+ * compare-and-swap — the WHERE clause pins every value the row was read with
+ * — so a writer that slips in between the scan and the write (an old-version
+ * instance in a mixed-version window) loses nothing: the CAS update matches
+ * zero rows and the next start's pass seals whatever that writer left
+ * behind. Deployments should still stop the old app before starting the new
+ * one (see UPGRADING.md); the lock and CAS make the failure mode of not doing
+ * so "unsealed until next start", never "silently overwritten".
+ *
+ * Once every row is sealed, the same transaction applies the constraints that
+ * could not ship in the SQL migration: SET NOT NULL on the bidx columns and
+ * the unique-index swaps (`users_email_unique` on the now-randomized
+ * ciphertext is meaningless, `users_email_bidx_unq` takes over; the same for
+ * the approvals and the join requests). The new unique index goes up BEFORE
+ * the old one is dropped so duplicate protection never has a gap. Legacy rows
+ * that collide under the normalized blind index are handled first: duplicate
+ * approval and join-request rows (the same logical row, a case-variant email)
+ * are collapsed; duplicate USERS are a genuine account conflict and abort the
+ * start with the row ids so an operator can merge them deliberately. All
+ * statements are IF-EXISTS-guarded — re-running is a no-op.
+ *
+ * Runs against whatever schema the handle searches first: a tenant's own, or
+ * `public`, under that handle's key. Every table name is unqualified for that
+ * reason.
+ *
+ * This is the one place that works on the STORED form. The handle's
+ * connection opens every sealed value of a result, which here would hide
+ * exactly what has to be told apart — so the columns are read as bytes
+ * ({@link asStored}), which it leaves alone, and written as ready-made
+ * ciphertext, which it passes through.
+ */
+
+interface PiiBackfillTable {
+  table: string;
+  /** Columns that uniquely identify a row for the write-back UPDATE. */
+  key: string[];
+  /** Columns whose plaintext values get rewritten as ciphertext. */
+  encrypted: string[];
+  /** Blind-index column to fill from the plaintext of `source`. */
+  bidx?: { source: string; column: string };
+}
+
+const PII_BACKFILL_TABLES: PiiBackfillTable[] = [
+  { table: 'users', key: ['id'], encrypted: ['email', 'name', 'avatar_url'], bidx: { source: 'email', column: 'email_bidx' } },
+  { table: 'pr_file_approvals', key: ['id'], encrypted: ['approver_email', 'approver_name'], bidx: { source: 'approver_email', column: 'approver_email_bidx' } },
+  { table: 'pr_merge_log', key: ['id'], encrypted: ['triggered_by_email', 'triggered_by_name', 'error'], bidx: { source: 'triggered_by_email', column: 'triggered_by_email_bidx' } },
+  { table: 'pr_comments', key: ['id'], encrypted: ['author_email', 'author_name', 'body'], bidx: { source: 'author_email', column: 'author_email_bidx' } },
+  { table: 'change_requests', key: ['id'], encrypted: ['author_email', 'author_name', 'title', 'body', 'apply_failure_reason', 'apply_failed_by_name'], bidx: { source: 'author_email', column: 'author_email_bidx' } },
+  { table: 'pending_commits', key: ['id'], encrypted: ['author_email', 'author_name', 'last_error'], bidx: { source: 'author_email', column: 'author_email_bidx' } },
+  { table: 'file_locks', key: ['workspace_id', 'branch', 'path'], encrypted: ['holder_name'] },
+  { table: 'plugin_join_requests', key: ['id'], encrypted: ['requester_email', 'requester_name', 'failure_reason'], bidx: { source: 'requester_email', column: 'requester_email_bidx' } },
+];
+
+const ident = (name: string) => sql.raw(`"${name}"`);
+
+/** What the backfill needs from a drizzle client — the db or a transaction. */
+type Executor = Pick<Database, 'execute'>;
+
+/** A text column as it is stored: bytes, so the handle's connection does not open it. */
+const asStored = (col: string) => sql`convert_to(${ident(col)}, 'UTF8') AS ${ident(col)}`;
+
+/** What {@link asStored} selected, back as text; anything else as it came. */
+const storedText = (value: unknown): unknown => (Buffer.isBuffer(value) ? value.toString('utf8') : value);
+
+/**
+ * A column "needs sealing" when it holds non-empty text that isn't a blob.
+ * The shape regex is deliberately used as a NEGATIVE filter: anything failing
+ * it — including plaintext that merely BEGINS with the prefix — is selected
+ * and sealed, and `isEncryptedBlob` is the same pattern, so the two can never
+ * disagree about a value. Sealed rows all match, keeping the steady-state scan
+ * an empty-result query.
+ *
+ * `trustShape` is false on the FIRST backfill of a database (see
+ * {@link isFirstBackfill}): nothing has been sealed yet, so a value in this
+ * shape is plaintext somebody typed, and every non-empty value is selected.
+ */
+function needsSealing(col: string, trustShape: boolean) {
+  if (!trustShape) return sql`(${ident(col)} IS NOT NULL AND ${ident(col)} <> '')`;
+  return sql`(${ident(col)} IS NOT NULL AND ${ident(col)} <> '' AND ${ident(col)} !~ ${PII_SEALED_SHAPE_SQL_REGEX})`;
+}
+
+/**
+ * Whether this database has never been through the backfill: the blind-index
+ * column of `users` is still nullable. The backfill, the duplicate collapse
+ * and the constraints run in ONE transaction, so a nullable column means no
+ * backfill has ever committed here — and therefore that nothing in it is
+ * sealed, whatever it looks like.
+ *
+ * That is what lets a first backfill trust no shape at all. A blob is
+ * recognised by its shape, and a title or a display name is text a person
+ * chose: one typed in that shape before the upgrade would be read as sealed,
+ * skipped, and left in clear for good — and, sampled by
+ * {@link assertKeyOpensSealedRows}, would refuse the start for a key that is
+ * perfectly right. Once the first backfill has committed, every write goes
+ * through a handle that seals it, so no such value can arrive again.
+ */
+async function isFirstBackfill(tx: Executor): Promise<boolean> {
+  const result = await tx.execute(sql`
+    SELECT is_nullable FROM information_schema.columns
+    WHERE table_schema = current_schema() AND table_name = 'users' AND column_name = 'email_bidx'
+  `);
+  return (result.rows[0] as { is_nullable?: string } | undefined)?.is_nullable === 'YES';
+}
+
+/** How many rows one backfill query reads: a table is walked in batches, never loaded whole. */
+const BACKFILL_BATCH_ROWS = 500;
+
+/**
+ * The configured key must open what earlier starts sealed. A rotated or
+ * mistyped `SECRETS_ENC_KEY` would otherwise go unnoticed here — sealed rows
+ * are exactly the ones the scan skips — and surface only as every login
+ * failing and every lookup by email missing, because the blind indexes would
+ * be computed under the new key. One sealed value per table is enough: all
+ * rows of a deployment are sealed under one key. Refusing the start is the
+ * loud failure; re-keying a database is a deliberate operation, not a boot.
+ */
+async function assertKeyOpensSealedRows(tx: Executor, keys: PiiKeys): Promise<void> {
+  for (const t of PII_BACKFILL_TABLES) {
+    const col = t.bidx?.source ?? t.encrypted[0]!;
+    const sample = await tx.execute(
+      sql`SELECT ${asStored(col)} FROM ${ident(t.table)} WHERE ${ident(col)} ~ ${PII_SEALED_SHAPE_SQL_REGEX} LIMIT 1`,
+    );
+    const value = storedText((sample.rows[0] as Record<string, unknown> | undefined)?.[col]);
+    if (typeof value === 'string' && !keys.open(value).ok) {
+      throw new Error(
+        `PII encryption: ${t.table}.${col} is sealed with a key the configured SECRETS_ENC_KEY ` +
+          '(for a tenant: the one derived from TENANT_MASTER_KEY) does not open — refusing to start. ' +
+          'Restore the key that sealed it; changing the key is a re-keying of the database, not a configuration change.',
+      );
+    }
+  }
+}
+
+async function backfillTable(
+  tx: Executor,
+  keys: PiiKeys,
+  t: PiiBackfillTable,
+  trustShape: boolean,
+): Promise<number> {
+  // The key columns are read as text beside themselves, so the next batch can
+  // be asked for by value whatever their type is (a uuid, a serial, a path).
+  const keyText = (k: string) => `${k}__key`;
+  const cols = [
+    ...t.key.map(ident),
+    ...t.key.map((k) => sql`${ident(k)}::text AS ${ident(keyText(k))}`),
+    ...t.encrypted.map(asStored),
+    ...(t.bidx ? [ident(t.bidx.column)] : []),
+  ];
+  // Only rows with work left: the ciphertext prefix makes "unsealed" a plain
+  // SQL predicate, so a fully-sealed table costs one empty-result query.
+  const pending = [
+    ...t.encrypted.map((col) => needsSealing(col, trustShape)),
+    ...(t.bidx ? [sql`${ident(t.bidx.column)} IS NULL`] : []),
+  ];
+  const keyTuple = sql`(${sql.join(t.key.map((k) => sql`${ident(k)}::text`), sql`, `)})`;
+  // A blob, as far as this pass may believe one. On a first backfill nothing
+  // is sealed yet, so nothing is believed (see `isFirstBackfill`).
+  const sealedAlready = (value: string): boolean => trustShape && isEncryptedBlob(value);
+  let rewritten = 0;
+  /** The key of the last row read, as text: the next batch starts after it. */
+  let after: string[] | null = null;
+  // IN BATCHES, in key order. A table is never loaded whole: a deployment with
+  // years of change requests holds every title and body it ever had, and
+  // reading them into one result held the first start after the upgrade — and
+  // the memory of the process making it — for as long as that took. Walking by
+  // key rather than re-asking for "what is left" also ends: a row this pass
+  // leaves as it found it (a write overtook it) is passed, not met again.
+  for (;;) {
+    const past = after ? sql` AND ${keyTuple} > (${sql.join(after.map((v) => sql`${v}`), sql`, `)})` : sql``;
+    const result = await tx.execute(
+      sql`SELECT ${sql.join(cols, sql`, `)} FROM ${ident(t.table)} WHERE (${sql.join(pending, sql` OR `)})${past} ORDER BY ${keyTuple} LIMIT ${BACKFILL_BATCH_ROWS}`,
+    );
+    const batch = result.rows as Array<Record<string, unknown>>;
+    for (const read of batch) {
+      const row = Object.fromEntries(Object.entries(read).map(([col, value]) => [col, storedText(value)]));
+      const sets = [];
+      // Compare-and-swap: pin every value this row was read with, so a write
+      // that lands between scan and update makes this UPDATE match zero rows
+      // instead of clobbering the newer value.
+      const where = t.key.map((k) => sql`${ident(k)} = ${row[k]}`);
+      for (const col of t.encrypted) {
+        const value = row[col];
+        if (typeof value === 'string' && value !== '' && !sealedAlready(value)) {
+          sets.push(sql`${ident(col)} = ${keys.seal(value)}`);
+          where.push(sql`${ident(col)} = ${value}`);
+        }
+      }
+      if (t.bidx) {
+        // The blind index is derived from its source, so it is (re)computed
+        // whenever the source is being sealed in this pass — a legacy writer
+        // that put a NEW plaintext email on an already-indexed row left a stale
+        // index behind, and sealing the email alone would freeze that mismatch
+        // — and whenever it was never filled. The source may already be
+        // ciphertext (an index that was never filled beside a sealed address);
+        // the index is always computed over the plaintext, never over a blob
+        // the key cannot open.
+        const source = row[t.bidx.source];
+        const stored = row[t.bidx.column];
+        const text = typeof source === 'string' ? source : '';
+        const sealingSource = text !== '' && !sealedAlready(text);
+        if (sealingSource || stored == null) {
+          const opened = sealedAlready(text) ? keys.open(text) : ({ ok: true, plain: text } as const);
+          if (!opened.ok) {
+            throw new Error(
+              `PII encryption backfill: ${t.table}.${t.bidx.source} cannot be decrypted with the ` +
+                'configured SECRETS_ENC_KEY — refusing to derive a blind index from ciphertext. ' +
+                'Restore the key that sealed it, then restart.',
+            );
+          }
+          sets.push(sql`${ident(t.bidx.column)} = ${keys.index(opened.plain)}`);
+          // Pin the index AND its source: if a concurrent writer replaces the
+          // email between scan and write, the CAS must not attach the OLD
+          // email's blind index to the NEW value.
+          where.push(sql`${ident(t.bidx.column)} IS NOT DISTINCT FROM ${stored ?? null}`);
+          where.push(sql`${ident(t.bidx.source)} IS NOT DISTINCT FROM ${source ?? null}`);
+        }
+      }
+      if (sets.length === 0) continue;
+      const updated = await tx.execute(
+        sql`UPDATE ${ident(t.table)} SET ${sql.join(sets, sql`, `)} WHERE ${sql.join(where, sql` AND `)}`,
+      );
+      rewritten += updated.rowCount ?? 0;
+    }
+    if (batch.length < BACKFILL_BATCH_ROWS) return rewritten;
+    const last = batch[batch.length - 1]!;
+    after = t.key.map((k) => String(last[keyText(k)]));
+  }
+}
+
+/**
+ * The name on a refused apply that was recorded BEFORE this release: the
+ * address of whoever it names was never kept, so no blind index stands beside
+ * it and an account erasure has nothing to find it by.
+ *
+ * Matching it by display name instead got both mistakes at once: a person
+ * who had since changed their name kept the old one on the request for good,
+ * and somebody else of the same name had theirs taken away. So the name goes,
+ * once, here. The refusal itself stays, with its reason and its time; it
+ * reads "could not apply" without saying who. A refusal recorded from this
+ * release on carries its index and is never touched by this.
+ */
+async function clearUnindexedRefusalNames(tx: Executor): Promise<number> {
+  const cleared = await tx.execute(sql.raw(`
+    UPDATE "change_requests" SET "apply_failed_by_name" = NULL
+    WHERE "apply_failed_by_name" IS NOT NULL AND "apply_failed_by_email_bidx" IS NULL
+  `));
+  return cleared.rowCount ?? 0;
+}
+
+/**
+ * Legacy uniqueness was on the RAW email, so rows differing only by case or
+ * whitespace could coexist; under the normalized blind index they collide and
+ * the unique-index creation below would abort the start. Approval rows and
+ * join-request rows are the same logical row — collapse them, keeping the
+ * earliest. Colliding USER rows are distinct accounts; refuse loudly with the
+ * ids so an operator resolves the conflict deliberately instead of the
+ * upgrade guessing.
+ */
+async function resolveBidxCollisions(tx: Executor): Promise<void> {
+  await tx.execute(sql.raw(`
+    DELETE FROM "pr_file_approvals" a USING "pr_file_approvals" b
+    WHERE a."pr_number" = b."pr_number" AND a."path" = b."path"
+      AND a."approver_email_bidx" = b."approver_email_bidx" AND a."head_sha" = b."head_sha"
+      AND (a."approved_at" > b."approved_at" OR (a."approved_at" = b."approved_at" AND a."id" > b."id"))
+  `));
+  await tx.execute(sql.raw(`
+    DELETE FROM "plugin_join_requests" a USING "plugin_join_requests" b
+    WHERE a."plugin_key" = b."plugin_key" AND a."requester_email_bidx" = b."requester_email_bidx"
+      AND (a."created_at" > b."created_at" OR (a."created_at" = b."created_at" AND a."id" > b."id"))
+  `));
+  const dupes = await tx.execute(sql.raw(`
+    SELECT array_agg("id") AS ids FROM "users" GROUP BY "email_bidx" HAVING count(*) > 1
+  `));
+  if (dupes.rows.length > 0) {
+    const groups = (dupes.rows as Array<{ ids: string[] }>).map((r) => r.ids.join(', '));
+    throw new Error(
+      'PII encryption backfill: multiple user rows share the same email after normalization ' +
+        '(case/whitespace variants of one address). Merge or delete the duplicates, then restart. ' +
+        `Conflicting user ids: [${groups.join('], [')}]`,
+    );
+  }
+}
+
+const PII_FINALIZE_STATEMENTS = [
+  'ALTER TABLE "users" ALTER COLUMN "email_bidx" SET NOT NULL',
+  'CREATE UNIQUE INDEX IF NOT EXISTS "users_email_bidx_unq" ON "users" ("email_bidx")',
+  'ALTER TABLE "users" DROP CONSTRAINT IF EXISTS "users_email_unique"',
+  'ALTER TABLE "pr_file_approvals" ALTER COLUMN "approver_email_bidx" SET NOT NULL',
+  'CREATE UNIQUE INDEX IF NOT EXISTS "pr_file_approvals_bidx_unq" ON "pr_file_approvals" ("pr_number","path","approver_email_bidx","head_sha")',
+  'DROP INDEX IF EXISTS "pr_file_approvals_unq"',
+  'ALTER TABLE "pr_merge_log" ALTER COLUMN "triggered_by_email_bidx" SET NOT NULL',
+  'ALTER TABLE "pr_comments" ALTER COLUMN "author_email_bidx" SET NOT NULL',
+  'ALTER TABLE "change_requests" ALTER COLUMN "author_email_bidx" SET NOT NULL',
+  'ALTER TABLE "pending_commits" ALTER COLUMN "author_email_bidx" SET NOT NULL',
+  'ALTER TABLE "plugin_join_requests" ALTER COLUMN "requester_email_bidx" SET NOT NULL',
+  'CREATE UNIQUE INDEX IF NOT EXISTS "plugin_join_requests_requester_bidx_plugin_unq" ON "plugin_join_requests" ("requester_email_bidx","plugin_key")',
+  'DROP INDEX IF EXISTS "plugin_join_requests_requester_plugin_unq"',
+];
+
+/**
+ * Encrypt pre-existing plaintext PII rows, fill the blind-index columns, and
+ * apply the constraints migration 0016 deferred. Idempotent; `runCoreMigrations`
+ * runs it under the migrations lock right after the history. The handle must
+ * hold the knowledge base's key (`createDb(url, { piiKey })`; the composition
+ * root's does): one that holds none is refused before anything is read.
+ */
+export async function runPiiEncryptionBackfill(db: Database): Promise<void> {
+  const keys = piiKeysOf(db);
+  await db.transaction(async (tx) => {
+    const first = await isFirstBackfill(tx);
+    // Nothing is sealed before the first backfill, so there is no sealed row
+    // for the key to be checked against — and a value that only LOOKS sealed
+    // must not be taken for one (see `isFirstBackfill`).
+    if (!first) await assertKeyOpensSealedRows(tx, keys);
+    let rewritten = 0;
+    for (const t of PII_BACKFILL_TABLES) {
+      rewritten += await backfillTable(tx, keys, t, !first);
+    }
+    if (rewritten > 0) log.info(`PII encryption backfill: rewrote ${rewritten} row(s).`);
+    const cleared = await clearUnindexedRefusalNames(tx);
+    if (cleared > 0) {
+      log.info(`PII encryption backfill: took the name off ${cleared} refused apply(ies) recorded before this release.`);
+    }
+    // Only where the unique indexes are not up yet. Once they are, they are
+    // what keeps two rows from sharing an index, so there is nothing to
+    // collapse — and the collapse is two self-joins and an aggregate over
+    // whole tables, which every later start paid for nothing.
+    if (first) await resolveBidxCollisions(tx);
+    for (const statement of PII_FINALIZE_STATEMENTS) {
+      await tx.execute(sql.raw(statement));
+    }
+  });
+}

package/src/modules/kb-fs/__tests__/branch-name.test.ts

@@ -67,6 +67,16 @@ describe('assertValidRelativePath', () => {
     ['nested parent', 'a/../b'],
     ['current segment', 'a/./b'],
     ['null byte', 'a\x00b'],
+    // A line break is not merely an unwritable name: git's `cat-file --batch`
+    // reads one `<ref>:<path>` object name per LINE, so a path carrying one
+    // is two specs and git answers about the first — under the gates that were
+    // asked about the whole string. Every other control character goes with
+    // them, matching what the shared `validateFilename` has always refused.
+    ['line feed', 'Docs/secret.md\nzzz'],
+    ['carriage return', 'Docs/secret.md\rzzz'],
+    ['tab', 'Docs/a\tb.md'],
+    ['escape', 'Docs/a\u001Bb.md'],
+    ['delete', 'Docs/a\u007Fb.md'],
     ['leading dash', '-afile'],
   ])('rejects %s (%s)', (_label, p) => {
     expect(() => assertValidRelativePath(p)).toThrow(WorkflowValidationError);

package/src/modules/kb-fs/__tests__/repo-path.test.ts

@@ -4,6 +4,7 @@ import {
   assertKbDirNameFree,
   assertRepoRootNameFree,
   assertRepoRootNameFreeArgs,
+  hasControlCharacter,
   isInsideRepo,
   normalizePathArgs,
   normalizeWorkspacePath,
@@ -47,6 +48,14 @@ describe('isInsideRepo', () => {
     expect(isInsideRepo('knowledge-base/KnowledgeBase/a\\b.md', KB)).toBe(false);
   });
 
+  it('refuses a control character anywhere: git reads a line break in a path as a separator', () => {
+    expect(isInsideRepo('knowledge-base/Docs/secret.md\nzzz', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base/Docs/secret.md\rzzz', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base/Docs/a\u0000b.md', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base/Docs/a\u001Bb.md', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base/Docs/a\u007Fb.md', KB)).toBe(false);
+  });
+
   it('tolerates a trailing slash on a directory path', () => {
     expect(isInsideRepo('knowledge-base/', KB)).toBe(true);
     expect(isInsideRepo('knowledge-base/KnowledgeBase/Projects/', KB)).toBe(true);
@@ -113,6 +122,120 @@ describe('assertInsideRepo', () => {
   });
 });
 
+describe('a line break in a path — one name to the gates, two object names to git', () => {
+  // `git cat-file --batch` reads one `<ref>:<path>` spec per LINE. A path
+  // carrying a `\n` therefore means TWO things at once: the read gate, the
+  // download gate and the not-a-directory check are answered about the whole
+  // string — a name that exists nowhere, so the real file's own frontmatter
+  // rules are never the ones consulted — while git answers about the part
+  // before the break and hands over its bytes. In the access resolver's batch
+  // read the extra answer also shifts every result after it, so one directory
+  // is judged by another's `access.md`.
+  //
+  // Which is why the refusal is HERE, at the normaliser every accepted path
+  // passes through, and not at the route that happened to surface it: the next
+  // caller to build a git spec out of a path will not remember this.
+  const INJECTED = 'knowledge-base/Docs/secret.md\nzzz';
+
+  it('is refused by the normaliser, with a message that says what is wrong', () => {
+    let err: unknown;
+    try {
+      normalizeWorkspacePath(INJECTED, KB);
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(WorkflowValidationError);
+    const e = err as WorkflowValidationError;
+    expect(e.status).toBe(400);
+    expect(e.message).toMatch(/control character/);
+    // Never "use this instead": there is no corrected spelling of a name with
+    // an invisible byte in it.
+    expect(e.message).not.toMatch(/Use "/);
+    // The path is named, ESCAPED — `sanitizedPath`, the same spelling every
+    // other refusal uses — so the character that made the path invalid cannot
+    // forge a second line of the refusal either.
+    expect(e.payload).toMatchObject({
+      kind: 'path-control-character',
+      path: 'knowledge-base/Docs/secret.md\\nzzz',
+    });
+    expect(e.message).toContain('"knowledge-base/Docs/secret.md\\nzzz"');
+    expect(e.message).not.toContain('\n');
+  });
+
+  it('is refused the same way unprefixed, which is the form a route receives', () => {
+    expect(() => normalizeWorkspacePath('Docs/secret.md\nzzz', KB)).toThrow(/control character/);
+  });
+
+  it('is refused by the check AFTER the normaliser too', () => {
+    expect(() => assertInsideRepo(INJECTED, KB)).toThrow(/control character/);
+  });
+
+  it('refuses every control character, not only the line breaks', () => {
+    for (const ch of ['\u0000', '\u0001', '\t', '\n', '\u000B', '\r', '\u001F', '\u007F']) {
+      expect(() => normalizeWorkspacePath(`knowledge-base/Docs/a${ch}b.md`, KB), ch).toThrow(
+        WorkflowValidationError,
+      );
+    }
+  });
+
+  it('refuses a CHECKOUT FOLDER NAME carrying one, which the normaliser would otherwise emit', () => {
+    // The name is prefixed onto the result rather than read from it, so a
+    // clean path joined to `kb\nname` would come out carrying the break: the
+    // normaliser would emit exactly what it refuses from a caller, from inputs
+    // that were each individually fine.
+    let err: unknown;
+    try {
+      normalizeWorkspacePath('Docs/report.md', 'kb\nname');
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(WorkflowValidationError);
+    const e = err as WorkflowValidationError;
+    // Named as the CONFIGURATION error it is: an operator told their own path
+    // was invalid would have nothing to fix.
+    expect(e.message).toMatch(/checkout folder name/);
+    expect(e.message).toMatch(/KB_DIR_NAME/);
+    expect(e.message).toContain('"kb\\nname"');
+    expect(e.payload).toMatchObject({ kind: 'kb-dir-name-control-character', kbDirName: 'kb\\nname' });
+    // The guarantee the fence is for: no return value of this function carries
+    // a control character, whatever it was given.
+    for (const dir of ['kb\nname', 'kb\rname', 'kb\u0000name']) {
+      for (const p of ['Docs/report.md', `${dir}/Docs/report.md`, 'x']) {
+        let out: string | null = null;
+        try {
+          out = normalizeWorkspacePath(p, dir);
+        } catch {
+          out = null;
+        }
+        if (out !== null) expect(hasControlCharacter(out), `${dir} + ${p}`).toBe(false);
+      }
+    }
+  });
+
+  it('exposes the rule as a predicate, so the places that SET a name share it', () => {
+    expect(hasControlCharacter('knowledge-base')).toBe(false);
+    expect(hasControlCharacter('kb\nname')).toBe(true);
+    expect(hasControlCharacter('kb\u007Fname')).toBe(true);
+    // U+2028 is not in the range: nothing to git, and a name carrying one is
+    // creatable today — refusing it would make an existing file unreadable.
+    expect(hasControlCharacter('kb\u2028name')).toBe(false);
+  });
+
+  it('leaves ordinary names alone — the rule costs no real path', () => {
+    expect(normalizeWorkspacePath('knowledge-base/Docs/[Approved] Handbook_Order archive.docx', KB)).toBe(
+      'knowledge-base/Docs/[Approved] Handbook_Order archive.docx',
+    );
+    expect(normalizeWorkspacePath('knowledge-base/Docs/Ünïcödé — naïve.md', KB)).toBe(
+      'knowledge-base/Docs/Ünïcödé — naïve.md',
+    );
+  });
+
+  it('refuses it through normalizePathArgs, which is where the MCP tools meet the rule', () => {
+    expect(() => normalizePathArgs({ path: INJECTED }, KB)).toThrow(/control character/);
+    expect(() => normalizePathArgs({ files: [{ path: INJECTED }] }, KB)).toThrow(/control character/);
+  });
+});
+
 describe('normalizeWorkspacePath — THE normaliser', () => {
   it('leaves a path that is already inside the repository alone', () => {
     expect(normalizeWorkspacePath('knowledge-base/KnowledgeBase/Foo.md', KB)).toBe('knowledge-base/KnowledgeBase/Foo.md');

package/src/modules/kb-fs/branch-name.ts

@@ -49,7 +49,20 @@ export function assertValidBranchName(name: string): void {
 export function assertValidRelativePath(relativePath: string): void {
   if (!relativePath) throw new WorkflowValidationError('path is required');
   if (relativePath.length > 1024) throw new WorkflowValidationError('path too long');
-  if (relativePath.includes('\0')) throw new WorkflowValidationError('path contains NUL');
+  // NUL, every other C0 control and DEL. A NUL is named on its own because it
+  // terminates a C string and git's `-z` output; the rest are refused with it
+  // because a LINE BREAK in a path is a separator in git's line-oriented stdin
+  // protocols — `cat-file --batch` reads one `<ref>:<path>` per line, so
+  // `Docs/secret.md\nzzz` is two object names while every gate upstream was
+  // asked about one string. See `CONTROL_CHARACTERS` in `repo-path.ts`, which
+  // refuses the same range at the normaliser; this is the same rule at the
+  // check every path handed to git as a pathspec passes through.
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x1F\x7F]/.test(relativePath)) {
+    throw new WorkflowValidationError(
+      relativePath.includes('\0') ? 'path contains NUL' : 'path contains a control character',
+    );
+  }
   if (relativePath.includes('\\')) {
     throw new WorkflowValidationError('path must use forward slashes only');
   }