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

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

@@ -1,11 +1,14 @@
 import jwt from 'jsonwebtoken';
-import { eq } from 'drizzle-orm';
+import { and, eq, isNotNull, isNull } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { users } from '../database/schema.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { canonicalEmail, hashEmail } from '../../shared/email-identity.js';
 import {
   AccountAdmissionRefusedError,
+  AccountChangeRefusedError,
+  AccountDeactivatedError,
+  AuthBackendError,
   admitEveryone,
   type AccountProvisionReason,
   type IAccountAdmission,
@@ -16,9 +19,22 @@ import {
   timingSafeStringEqual,
   MIN_PASSWORD_LENGTH,
 } from './password-hash.js';
+import { RECOVERY_BOT_EMAIL } from '../workflow/recovery-bot.js';
+import { DIRECTORY_SYNC_BOT_EMAIL } from '../access/directory-sync-bot.js';
 
 const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
+/**
+ * How long {@link AuthService.isActive} trusts what it last read. Every
+ * request carrying a credential asks, so the answer is kept briefly rather
+ * than read each time; switching an account off or on in THIS process
+ * forgets it at once, and another replica sees the change within this long.
+ */
+const ACTIVE_CACHE_MS = 30_000;
+
+/** The accounts core runs its own work as. Nobody signs in with them, and nobody switches them off. */
+const SYSTEM_ACCOUNT_EMAILS: readonly string[] = [RECOVERY_BOT_EMAIL, DIRECTORY_SYNC_BOT_EMAIL];
+
 /**
  * What every caller is told when it tries to give the deployment admin a
  * stored password — the Account page's own change and an admin's "Set
@@ -129,7 +145,19 @@ export class AuthService {
       .limit(1);
     if (existing) return;
     const verdict = await this.admission.canProvision(normalizedEmail, reason);
-    if (!verdict.ok) throw new AccountAdmissionRefusedError(verdict.message);
+    if (verdict.ok) return;
+    // A first sign-in the port would rather keep than turn away: the person
+    // is put on file, switched off, for an admin to switch on — and is still
+    // refused now, with the port's words. Only for single sign-on, the one
+    // provisioning nobody asked for (see `AccountAdmissionVerdict`).
+    if (verdict.waitForAdmin && reason === 'sso') {
+      await this.db
+        .insert(users)
+        .values({ email: normalizedEmail, name: normalizedEmail.split('@')[0] || normalizedEmail, deactivatedAt: new Date() })
+        .onConflictDoNothing({ target: users.email });
+      throw new AccountAdmissionRefusedError(verdict.message, { waitingForAdmin: true });
+    }
+    throw new AccountAdmissionRefusedError(verdict.message);
   }
 
   /**
@@ -200,6 +228,9 @@ export class AuthService {
         await verifyPassword(provided, await decoyHash());
         throw new Error('Invalid credentials');
       }
+      // Never refused for being switched off: the environment password is
+      // the deployment's way back in, and {@link deactivate} refuses this
+      // account for that reason.
       const defaultName = normalizedEmail.split('@')[0] || normalizedEmail;
       await this.assertAdmitted(normalizedEmail, 'bootstrap');
       const admin = await this.upsertUserByEmail(normalizedEmail, defaultName);
@@ -215,6 +246,9 @@ export class AuthService {
     if (!user?.passwordHash || !matches) {
       throw new Error('Invalid credentials');
     }
+    // Only now, with the password proven: telling a stranger that an address
+    // is switched off would tell them it has an account.
+    if (user.deactivatedAt) throw new AccountDeactivatedError();
     return { token: this.signToken(user.id, user.email), user: this.toClientUser(user) };
   }
 
@@ -246,6 +280,7 @@ export class AuthService {
     await this.assertAdmitted(normalizedEmail, 'sso');
     const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
     const user = await this.upsertUserByEmail(normalizedEmail, displayName);
+    if (user.deactivatedAt) throw new AccountDeactivatedError();
     return { token: this.signToken(user.id, user.email), user: this.toClientUser(user) };
   }
 
@@ -255,7 +290,13 @@ export class AuthService {
    * account (e.g. one that first arrived via SSO, or a reset for a locked-out
    * user) is deliberate admin behavior, not an error.
    *
-   * The deployment admin is the one target this refuses, for the reason
+   * WITHOUT a password the account is made for single sign-on: the person
+   * signs in through the deployment's provider and finds their account
+   * waiting, already holding its place (a seat, on a host that sells them).
+   * Password sign-in refuses it until a password is set. For an address that
+   * already has an account it changes nothing but an explicitly given name.
+   *
+   * WITH a password, the deployment admin is the one target this refuses, for the reason
    * {@link changePassword} refuses it: that account's password is the
    * environment's, so a stored hash would not replace it but ADD a second
    * credential — one that keeps signing in after `ADMIN_PASSWORD` is rotated,
@@ -266,12 +307,26 @@ export class AuthService {
   async createAccount(
     email: string,
     name: string | undefined,
-    password: string,
+    password?: string,
   ): Promise<AuthUser> {
     const normalizedEmail = canonicalEmail(email ?? '');
     if (!EMAIL_REGEX.test(normalizedEmail)) {
       throw new Error('Invalid email');
     }
+    const suppliedName = (name ?? '').trim();
+    const displayName = suppliedName || normalizedEmail.split('@')[0] || normalizedEmail;
+    if (!password) {
+      await this.assertAdmitted(normalizedEmail, 'admin-create');
+      const [created] = await this.db
+        .insert(users)
+        .values({ email: normalizedEmail, name: displayName })
+        .onConflictDoUpdate({
+          target: users.email,
+          set: suppliedName ? { name: suppliedName, updatedAt: new Date() } : { updatedAt: new Date() },
+        })
+        .returning();
+      return this.toClientUser(created);
+    }
     // Before the policy check, so the refusal names the real reason rather
     // than sending the admin off to pick a longer password first.
     if (this.isEnvAdminEmail(normalizedEmail)) {
@@ -279,8 +334,6 @@ export class AuthService {
     }
     this.assertPasswordPolicy(password);
     await this.assertAdmitted(normalizedEmail, 'admin-create');
-    const suppliedName = (name ?? '').trim();
-    const displayName = suppliedName || normalizedEmail.split('@')[0] || normalizedEmail;
     const passwordHash = await hashPassword(password);
     // One atomic upsert. On conflict (re-provisioning an existing account) an
     // EXPLICITLY supplied name is persisted too; a blank name keeps the
@@ -402,6 +455,10 @@ export class AuthService {
       name: string;
       hasPassword: boolean;
       isEnvAdmin: boolean;
+      /** When an admin switched the account off; null while it is on. */
+      deactivatedAt: Date | null;
+      /** One of the accounts the platform runs its own work as: never switched off, nobody signs in with it. */
+      isSystem: boolean;
       createdAt: Date;
     }>
   > {
@@ -412,6 +469,8 @@ export class AuthService {
       name: row.name,
       hasPassword: row.passwordHash != null,
       isEnvAdmin: this.reportsAsEnvAdmin(row.email),
+      deactivatedAt: row.deactivatedAt,
+      isSystem: SYSTEM_ACCOUNT_EMAILS.includes(row.email),
       createdAt: row.createdAt,
     }));
   }
@@ -443,6 +502,7 @@ export class AuthService {
     await this.assertAdmitted(normalizedEmail, 'embed');
     const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
     const user = await this.upsertUserByEmail(normalizedEmail, displayName);
+    if (user.deactivatedAt) throw new AccountDeactivatedError();
     return { id: user.id, email: user.email, name: user.name };
   }
 
@@ -455,6 +515,11 @@ export class AuthService {
     return user;
   }
 
+  /**
+   * The signature and expiry of a session token, and nothing else — whether
+   * its account is still on is {@link resolveSession}'s question. Every
+   * place a session is ACCEPTED goes through that one.
+   */
   verifyToken(token: string): { userId: string; email: string } {
     const decoded = jwt.verify(token, this.config.jwtSecret) as {
       userId: string;
@@ -463,6 +528,114 @@ export class AuthService {
     return { userId: decoded.userId, email: decoded.email };
   }
 
+  /**
+   * A session token that may still be used: signed by us, not expired, and
+   * its account still on. A token outlives a deactivation by up to seven
+   * days, so the signature alone no longer says the bearer may enter.
+   * Throws for an invalid token, {@link AccountDeactivatedError} for one
+   * whose account was switched off.
+   */
+  async resolveSession(token: string): Promise<{ userId: string; email: string }> {
+    const claim = this.verifyToken(token);
+    let active: boolean;
+    try {
+      active = await this.isActive(claim.userId);
+    } catch (err) {
+      // The token is fine; the database is not. Said apart from a refusal, so
+      // an outage is a 500 and not a sign-out (see `AuthBackendError`).
+      throw new AuthBackendError(err);
+    }
+    if (!active) throw new AccountDeactivatedError();
+    return claim;
+  }
+
+  private readonly activeCache = new Map<string, { active: boolean; at: number }>();
+
+  /**
+   * Whether the account behind a credential is on: it exists and no admin
+   * switched it off. Asked for every credential presented that does not
+   * already read the account (a session token, an internal token), so it is
+   * cached for {@link ACTIVE_CACHE_MS}; switching an account off or on in
+   * this process forgets its entry at once.
+   *
+   * A missing row is not on either — an erased account's tokens die with it.
+   *
+   * The deployment admin's account is always on, whatever its row says: its
+   * environment password signs it in regardless (see `loginWithPassword`),
+   * and a session that sign-in mints must then be usable too, or the way
+   * back into a deployment would lead nowhere. {@link deactivate} refuses
+   * the account, but a host may write the column itself.
+   */
+  async isActive(userId: string): Promise<boolean> {
+    const now = Date.now();
+    const hit = this.activeCache.get(userId);
+    if (hit && now - hit.at < ACTIVE_CACHE_MS) return hit.active;
+    const [row] = await this.db
+      .select({ email: users.email, deactivatedAt: users.deactivatedAt })
+      .from(users)
+      .where(eq(users.id, userId))
+      .limit(1);
+    const active = row !== undefined && (!row.deactivatedAt || this.isEnvAdminEmail(row.email ?? ''));
+    this.activeCache.set(userId, { active, at: now });
+    return active;
+  }
+
+  /**
+   * Switch an account off. Its row, history and place in roles and groups
+   * stay; every credential it holds stops being honoured (see
+   * {@link isActive}). Idempotent: an account already off keeps the moment
+   * it was first switched off.
+   *
+   * The deployment admin is refused: the environment password is the way
+   * back into a deployment whose every other admin is gone, and switching
+   * it off would close that door from inside. So are the machine accounts
+   * core runs its own work as. Refusing an admin's own account is the
+   * route's concern, since it knows who is asking.
+   *
+   * Returns false when there is no such account.
+   */
+  async deactivate(userId: string): Promise<boolean> {
+    const [row] = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
+    if (!row) return false;
+    if (this.isEnvAdminEmail(row.email)) {
+      throw new AccountChangeRefusedError('The deployment admin cannot be switched off: its password in the environment is the way back in.');
+    }
+    if (SYSTEM_ACCOUNT_EMAILS.includes(row.email)) {
+      throw new AccountChangeRefusedError('This account belongs to the platform itself and cannot be switched off.');
+    }
+    await this.db
+      .update(users)
+      .set({ deactivatedAt: new Date(), updatedAt: new Date() })
+      .where(and(eq(users.id, userId), isNull(users.deactivatedAt)));
+    this.activeCache.delete(userId);
+    return true;
+  }
+
+  /**
+   * Switch a deactivated account back on, if the deployment has room for it:
+   * the admission port is asked, as for a new account, because an account
+   * that is on takes the same place. A refusal throws
+   * {@link AccountAdmissionRefusedError} with the port's words. An account
+   * already on is not asked about.
+   *
+   * Returns false when there is no such account.
+   */
+  async reactivate(userId: string): Promise<boolean> {
+    const [row] = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
+    if (!row) return false;
+    if (!row.deactivatedAt) return true;
+    if (this.admission !== admitEveryone) {
+      const verdict = await this.admission.canProvision(row.email, 'reactivate');
+      if (!verdict.ok) throw new AccountAdmissionRefusedError(verdict.message);
+    }
+    await this.db
+      .update(users)
+      .set({ deactivatedAt: null, updatedAt: new Date() })
+      .where(and(eq(users.id, userId), isNotNull(users.deactivatedAt)));
+    this.activeCache.delete(userId);
+    return true;
+  }
+
   /**
    * Resolve a set of `authorId` hashes back to the app users that produced
    * them. Used by the PR list to display the human who triggered each PR

package/src/modules/auth/oidc-auth-provider.ts

@@ -7,7 +7,7 @@ import type { AuthProviderPlugin } from './auth.routes.js';
 import { AUTH_COOKIE_MAX_AGE_S } from './auth.routes.js';
 import { AUTH_COOKIE_NAME } from './auth.middleware.js';
 import type { AuthService } from './auth.service.js';
-import { AccountAdmissionRefusedError } from './account-admission.js';
+import { AccountAdmissionRefusedError, AccountDeactivatedError } from './account-admission.js';
 import { normalizeIssuerUrl } from '../settings/oidc-check.js';
 
 // Short-lived CSRF state + PKCE verifier for the OAuth round-trip: set before
@@ -325,7 +325,12 @@ export class OidcAuthProvider implements AuthProviderPlugin {
         // screen can say so instead of "try again".
         if (error instanceof AccountAdmissionRefusedError) {
           log.warn('OIDC sign-in refused by the account admission port:', { detail: error.message });
-          fail('admission');
+          fail(error.waitingForAdmin ? 'waiting' : 'admission');
+          return;
+        }
+        if (error instanceof AccountDeactivatedError) {
+          log.warn('OIDC sign-in refused: the account is switched off');
+          fail('deactivated');
           return;
         }
         log.error('OIDC callback error:', { err: error });

package/src/modules/database/core-schema.ts

@@ -1,8 +1,8 @@
 /**
  * CORE platform tables — the git-backed workspace/workflow, auth, access,
- * change requests, locks, the pending-commits queue, the ontology-session
- * touched-set, connection keys, MCP OAuth, and the Secrets Vault. A core-only
- * deployment migrates and runs on exactly these tables.
+ * change requests, locks, the pending-commits queue, connection keys, MCP
+ * OAuth, and the Secrets Vault. A core-only deployment migrates and runs on
+ * exactly these tables.
  *
  * Enterprise-only tables (chat, routines, watchlist, connectors, LLM config,
  * SharePoint/Atlassian links, feedback, upload, kb-revalidation) live in
@@ -37,6 +37,19 @@ export const users = pgTable('users', {
    * backfill would need, and being shown the setup once costs a click.
    */
   onboardingDone: boolean('onboarding_done').default(false).notNull(),
+  /**
+   * When an admin switched this account off; NULL while it is on. A
+   * deactivated account keeps its row, its history and its place in roles
+   * and groups, but nothing it holds is honoured: it cannot sign in, and its
+   * session, connection keys, agent tokens and internal tokens are refused
+   * the next time they are presented (see `AuthService.isActive`). Turning it
+   * back on restores all of them as they were.
+   *
+   * The off switch a host that sells seats needs — a seat is an account that
+   * is on — and the one an admin uses for someone who left without erasing
+   * what they did.
+   */
+  deactivatedAt: timestamp('deactivated_at'),
   createdAt: timestamp('created_at').defaultNow().notNull(),
   updatedAt: timestamp('updated_at').defaultNow().notNull(),
 });
@@ -160,6 +173,18 @@ export const changeRequests = pgTable('change_requests', {
   createdAt: timestamp('created_at').defaultNow().notNull(),
   updatedAt: timestamp('updated_at'),
   closedAt: timestamp('closed_at'),
+  /**
+   * Why a closed request was closed, when something other than a person
+   * closed it. Today the one value is 'repository-replaced': the admin
+   * pointed the deployment at a different knowledge-base repository and chose
+   * to close the requests rather than keep them. Null for every request
+   * closed the ordinary way — by its author, or by the deleted-branch sweep —
+   * so the column reads as "nobody recorded a reason", not as a default.
+   *
+   * The row is never deleted: a replaced repository loses the branches, not
+   * the record of what people asked for.
+   */
+  closedReason: text('closed_reason'),
 }, (t) => ({
   numberUnq: uniqueIndex('change_requests_number_unq').on(t.number),
   // Enforce the "A→B blocks A→B while open" uniqueness rule at the DB level —
@@ -382,30 +407,6 @@ export const secrets = pgTable('secrets', {
   sharedKeyUnq: uniqueIndex('secrets_shared_key_unq').on(t.key).where(sql`${t.userId} is null`),
 }));
 
-/**
- * Ontology-session boundary — the per-session log of which named ontologies a
- * run has TOUCHED (one row per `(session_id, ontology)`). Each agent operation
- * that resolves to a named ontology records a row here (idempotent on the PK).
- *
- * The rule the gate enforces from this set:
- *   - READS are always allowed; they just record the ontology they touched.
- *   - WRITES are allowed only while the session's touched set is a SINGLE named
- *     ontology equal to the write target. Once a session has touched two or
- *     more ontologies (e.g. by reading across them), every write is blocked —
- *     "read across ontologies → you can't write anymore at all."
- *
- * Postgres is the durable source of truth so the boundary holds across a
- * backend restart (an in-memory set would reset and silently un-poison a run).
- * A write-through in-process cache fronts this table for the chatty read path;
- * a cache miss falls back here.
- *
- *   - PK is `(session_id, ontology)` — a set, idempotent on repeat touches.
- *   - `ontology` is the resolved ontology id (e.g. `KnowledgeBase/Product`).
- *     Neutral touches don't record, so they never write a row.
- *   - `touched_at` drives the abandoned-run `sweepOlderThan` backstop; the
- *     primary reclamation is an explicit delete of all of a session's rows at
- *     run end.
- */
 /**
  * OAuth clients dynamically registered by MCP clients (RFC 7591 DCR). When an
  * MCP client (claude.ai, Claude Code) connects to `/api/mcp` without a
@@ -575,6 +576,13 @@ export const agentEvents = pgTable('agent_events', {
   ),
 }));
 
+/**
+ * UNUSED IN THIS RELEASE. It backed the per-session boundary that a deployment
+ * now owns for itself, behind the agent read/write hooks; nothing in this
+ * package reads or writes it any more. The definition stays for ONE release so
+ * that no deployment runs a version in which neither side has the table, and
+ * the NEXT release drops it (see `TODOS.md`). Do not build on it.
+ */
 export const sessionOntologyTouches = pgTable('session_ontology_touches', {
   sessionId: text('session_id').notNull(),
   ontology: text('ontology').notNull(),

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');
   }