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

package/src/modules/github-app/github-app.routes.ts

@@ -0,0 +1,359 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import express from 'express';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import { logger } from '../../shared/logging.js';
+import type { DeploymentSettingsService } from '../settings/deployment-settings.service.js';
+import { GitHubAppClient, GitHubAppError } from './github-app.client.js';
+import { repositoriesAsSetting, type GitHubAppConnection } from './github-app.connection.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+
+const log = logger('github-app');
+
+const STATE_COOKIE = 'hexis_github_state';
+const STATE_MAX_AGE_S = 15 * 60;
+/** A GitHub organisation's name, as it appears in an address. */
+const ORGANIZATION_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
+/** GitHub refuses an app name longer than this. */
+const MAX_APP_NAME = 34;
+
+export interface GitHubAppRoutesDeps {
+  settings: Pick<DeploymentSettingsService, 'resolve' | 'record'>;
+  connection: GitHubAppConnection;
+  adminAccess: IAdminAccessService;
+  /** Where GitHub sends the browser back to: this deployment's own address. */
+  publicBackendUrl: string;
+  publicFrontendUrl: string;
+  /** Whether the deployment is set up: decides which page a round trip ends on. */
+  isComplete(): boolean;
+  client?: GitHubAppClient;
+}
+
+/** The address GitHub is told to send the browser back to once the app is installed. */
+export function githubAppCallbackUrl(publicBackendUrl: string): string {
+  return `${publicBackendUrl}/api/setup/github-app/callback`;
+}
+
+/**
+ * The manifest a deployment's own GitHub App is created from. It asks for
+ * what the deployment does and nothing else: read and write the contents of
+ * the repositories it is installed on. No webhook, no events, not public:
+ * the app is this deployment's, installed by its owner on the one
+ * repository the knowledge base lives in.
+ */
+export function githubAppManifest(publicBackendUrl: string, publicFrontendUrl: string): Record<string, unknown> {
+  const host = new URL(publicFrontendUrl).host;
+  return {
+    name: `Hexis ${host}`.slice(0, MAX_APP_NAME),
+    url: publicFrontendUrl,
+    description: `Lets the Hexis deployment at ${host} read and write the repository its knowledge base lives in.`,
+    redirect_url: `${publicBackendUrl}/api/setup/github-app/registered`,
+    callback_urls: [githubAppCallbackUrl(publicBackendUrl)],
+    // GitHub then sends the person back signed in, which is what lets the
+    // deployment check that the installation they name is one they hold.
+    request_oauth_on_install: true,
+    public: false,
+    default_permissions: { contents: 'write', metadata: 'read' },
+    default_events: [],
+  };
+}
+
+function readCookie(req: express.Request, name: string): string | null {
+  for (const segment of (req.headers.cookie ?? '').split(';')) {
+    const trimmed = segment.trim();
+    if (!trimmed.startsWith(`${name}=`)) continue;
+    try {
+      return decodeURIComponent(trimmed.slice(name.length + 1)) || null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function same(a: string, b: string): boolean {
+  const left = Buffer.from(a, 'utf8');
+  const right = Buffer.from(b, 'utf8');
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+/**
+ * Connecting a repository on GitHub through a GitHub App, from the setup
+ * screen. Mounted behind the deployment's sign-in; every route is an
+ * admin's.
+ *
+ *   GET  /setup/github-app               where the connection stands
+ *   POST /setup/github-app/manifest      start registering this deployment's own app
+ *   GET  /setup/github-app/registered    GitHub sends the browser back: the app exists
+ *   POST /setup/github-app/install       where on GitHub the app is installed
+ *   POST /setup/github-app/refresh       where to sign in, to read again what may be connected
+ *   GET  /setup/github-app/callback      GitHub sends the browser back: the app is installed
+ *   GET  /setup/github-app/repositories  what the deployment may be pointed at
+ *
+ * A ROUND TRIP IS STARTED BY A POST AND ENDED BY A GET. The two routes
+ * GitHub sends the browser to are ordinary navigations, authenticated by
+ * the session cookie; each checks a state this browser was given when the
+ * round trip started, and spends it. Nothing that starts one is a link, so
+ * a link somebody was sent starts nothing.
+ *
+ * WHAT THE DEPLOYMENT MAY REACH is never taken from the address the browser
+ * came back on. GitHub puts an installation's number there and anyone can
+ * write another: with one app serving many deployments, that number is the
+ * only thing between a deployment and another organisation's repositories.
+ * GitHub sends the person back signed in, and the deployment asks GitHub
+ * two things about THAT PERSON: which installations they reach, and which
+ * repositories of the one they named they can push to with their own
+ * account. The first alone is not enough, since read access to one
+ * repository puts an installation on that list. Only the second is what
+ * the deployment may be pointed at.
+ */
+export function createGitHubAppRoutes(deps: GitHubAppRoutesDeps): express.Router {
+  const router = express.Router();
+  const client = deps.client ?? new GitHubAppClient();
+  const { settings, connection } = deps;
+  const secure = deps.publicBackendUrl.startsWith('https');
+
+  const requireAdmin: express.RequestHandler = async (req, res, next) => {
+    if (!(await deps.adminAccess.isAdmin(req.userEmail))) {
+      res.status(403).json({ error: 'Admins only' });
+      return;
+    }
+    next();
+  };
+
+  /** A state for one round trip, kept in this browser until it comes back. */
+  const beginRoundTrip = (res: express.Response): string => {
+    const tag = settings.resolve('githubAppStateTag');
+    const state = `${tag ? `${tag}.` : ''}${randomBytes(24).toString('base64url')}`;
+    res.cookie(STATE_COOKIE, state, { httpOnly: true, sameSite: 'lax', secure, maxAge: STATE_MAX_AGE_S * 1000, path: '/' });
+    return state;
+  };
+  /** Whether the browser that came back is the one that was sent. */
+  const cameBack = (req: express.Request): boolean => {
+    const kept = readCookie(req, STATE_COOKIE);
+    const given = typeof req.query.state === 'string' ? req.query.state : '';
+    return Boolean(kept && given && same(kept, given));
+  };
+  /** Back to the setup screen, saying how the round trip ended. */
+  const finish = (res: express.Response, outcome: string): void => {
+    const page = deps.isComplete() ? '/deployment' : '/';
+    res.redirect(`${deps.publicFrontendUrl}${page}?github=${encodeURIComponent(outcome)}`);
+  };
+  const installUrl = (slug: string, state: string): string =>
+    `https://github.com/apps/${encodeURIComponent(slug)}/installations/new?state=${encodeURIComponent(state)}`;
+  const outcomeOf = (err: unknown): string =>
+    err instanceof GitHubAppError && err.kind === 'unreachable' ? 'unreachable' : 'refused';
+
+  router.get('/setup/github-app', requireAdmin, (_req, res) => {
+    const credentials = connection.credentials();
+    res.json({
+      // Who supplied the app. Null: this deployment has none yet, and can register its own.
+      registeredBy: connection.registeredBy(),
+      app: credentials ? { slug: credentials.slug, url: `https://github.com/apps/${credentials.slug}` } : null,
+      installation: connection.installationId()
+        ? { id: connection.installationId(), account: settings.resolve('githubInstallationAccount') }
+        : null,
+      repository: settings.resolve('githubRepository') || null,
+    });
+  });
+
+  router.post('/setup/github-app/manifest', requireAdmin, (req, res) => {
+    if (connection.credentials()) {
+      res.status(409).json({ error: 'This deployment already has a GitHub App.' });
+      return;
+    }
+    const organization = (req.body as { organization?: unknown } | undefined)?.organization;
+    const org = typeof organization === 'string' ? organization.trim() : '';
+    if (org && !ORGANIZATION_PATTERN.test(org)) {
+      res.status(400).json({ error: 'Enter the organisation’s name as it appears in its GitHub address.' });
+      return;
+    }
+    const state = beginRoundTrip(res);
+    const base = org ? `https://github.com/organizations/${org}/settings/apps/new` : 'https://github.com/settings/apps/new';
+    // The browser posts the manifest to GitHub itself: a form, not a request of ours.
+    res.json({
+      action: `${base}?state=${encodeURIComponent(state)}`,
+      manifest: githubAppManifest(deps.publicBackendUrl, deps.publicFrontendUrl),
+    });
+  });
+
+  router.get('/setup/github-app/registered', requireAdmin, async (req, res) => {
+    // Spent on return, however the return ends.
+    const returned = cameBack(req);
+    res.clearCookie(STATE_COOKIE, { path: '/' });
+    if (!returned) {
+      finish(res, 'state');
+      return;
+    }
+    const code = typeof req.query.code === 'string' ? req.query.code : '';
+    if (!code || connection.credentials()) {
+      finish(res, code ? 'already-registered' : 'refused');
+      return;
+    }
+    try {
+      const app = await client.convertManifest(code);
+      await settings.record(
+        {
+          githubAppId: app.appId,
+          githubAppSlug: app.slug,
+          githubAppPrivateKey: app.privateKey,
+          githubAppClientId: app.clientId,
+          githubAppClientSecret: app.clientSecret,
+        },
+        req.userId ?? null,
+      );
+      log.info(`GitHub App "${app.slug}" registered for this deployment`, { slug: app.slug, owner: app.owner });
+      // Straight on to installing it: the same round trip, the same state.
+      res.redirect(installUrl(app.slug, beginRoundTrip(res)));
+    } catch (err) {
+      log.error('the GitHub App could not be registered:', { detail: err instanceof Error ? err.message : String(err) });
+      finish(res, outcomeOf(err));
+    }
+  });
+
+  /**
+   * A POST that answers with the address, and the page sends the browser
+   * there. As a link it was a round trip anyone could start in an admin's
+   * browser by getting them to follow it: the state would be set, and
+   * whatever they then installed would come back with a state that matched.
+   */
+  router.post('/setup/github-app/install', requireAdmin, (_req, res) => {
+    const credentials = connection.credentials();
+    if (!credentials) {
+      res.status(409).json({ error: 'This deployment has no GitHub App yet. Create it first.' });
+      return;
+    }
+    res.json({ url: installUrl(credentials.slug, beginRoundTrip(res)) });
+  });
+
+  /**
+   * Ask GitHub again what the person may connect, WITHOUT installing
+   * anything: a sign-in with the app and nothing more, which comes back on
+   * the same callback with a code and no installation named.
+   *
+   * It exists because installing comes back only the first time. Once the
+   * app is installed, the address that installs it opens the installation's
+   * settings on GitHub, and GitHub sends nobody back from there: a
+   * repository added on that page was reached by the app and never offered
+   * here, since what is offered is what was recorded when the person
+   * connected. The same goes for an installation an organisation's owner
+   * approved later, in a browser of their own.
+   */
+  router.post('/setup/github-app/refresh', requireAdmin, (_req, res) => {
+    const credentials = connection.credentials();
+    if (!credentials) {
+      res.status(409).json({ error: 'This deployment has no GitHub App yet. Create it first.' });
+      return;
+    }
+    const state = beginRoundTrip(res);
+    res.json({
+      url: `https://github.com/login/oauth/authorize?client_id=${encodeURIComponent(credentials.clientId)}&state=${encodeURIComponent(state)}`,
+    });
+  });
+
+  router.get('/setup/github-app/callback', requireAdmin, async (req, res) => {
+    const returned = cameBack(req);
+    res.clearCookie(STATE_COOKIE, { path: '/' });
+    if (!returned) {
+      finish(res, 'state');
+      return;
+    }
+    const credentials = connection.credentials();
+    if (!credentials) {
+      finish(res, 'not-registered');
+      return;
+    }
+    // Someone without the right to install asked their organisation's owner
+    // to: nothing is installed yet, and there is nothing to record.
+    if (req.query.setup_action === 'request') {
+      finish(res, 'requested');
+      return;
+    }
+    const code = typeof req.query.code === 'string' ? req.query.code : '';
+    const given = typeof req.query.installation_id === 'string' ? req.query.installation_id : '';
+    if (!code || (given !== '' && !/^\d+$/.test(given))) {
+      finish(res, 'refused');
+      return;
+    }
+    // Back from installing, GitHub names the installation. Back from a
+    // sign-in alone (see `refresh`) it names none, and the one in question
+    // is the one this deployment has. Either way it is only a name: what
+    // decides is what GitHub says the person reaches, below.
+    const refreshing = given === '';
+    const named = given || connection.installationId();
+    try {
+      const userToken = await client.exchangeUserCode(credentials, code);
+      const reached = await client.installationsOf(userToken);
+      let held = named ? reached.find((installation) => installation.id === named) : undefined;
+      if (!named) {
+        // No installation on record and none named: the app was installed
+        // where this browser never came back from (an owner approved it
+        // later). One the person reaches is the one; several are a choice
+        // only installing from here can make.
+        if (reached.length === 0) {
+          finish(res, 'not-installed');
+          return;
+        }
+        if (reached.length > 1) {
+          finish(res, 'several');
+          return;
+        }
+        held = reached[0];
+      }
+      if (!held) {
+        log.warn('an installation was named that the person who came back cannot reach', { installation: named });
+        finish(res, 'not-yours');
+        return;
+      }
+      // Reaching the installation is not holding it: read access to one
+      // repository it covers is enough for GitHub to list it. What the
+      // deployment may be pointed at is what THIS PERSON can push to.
+      const theirs = await client.repositoriesOf(userToken, held.id);
+      const writable = theirs.repositories.filter((repository) => repository.writable).map((r) => r.fullName);
+      if (writable.length === 0) {
+        log.warn('the person who came back can push to nothing the installation covers', { installation: held.id });
+        finish(res, 'nothing-to-write');
+        return;
+      }
+      await settings.record(
+        {
+          githubInstallationId: held.id,
+          githubRepositoriesPermitted: repositoriesAsSetting(writable),
+          ...(held.account ? { githubInstallationAccount: held.account } : {}),
+        },
+        req.userId ?? null,
+      );
+      // A token in hand was another installation's.
+      connection.forget();
+      log.info(
+        refreshing
+          ? `what may be connected through the GitHub App on "${held.account}" was read again`
+          : `GitHub App installed on "${held.account}"`,
+        { installation: held.id, account: held.account, repositories: writable.length },
+      );
+      finish(res, refreshing ? 'refreshed' : 'connected');
+    } catch (err) {
+      log.error('the installation could not be confirmed:', { detail: err instanceof Error ? err.message : String(err) });
+      finish(res, outcomeOf(err));
+    }
+  });
+
+  router.get('/setup/github-app/repositories', requireAdmin, async (_req, res) => {
+    if (!connection.credentials() || !connection.installationId()) {
+      res.status(409).json({ error: 'Connect GitHub first.' });
+      return;
+    }
+    try {
+      res.json(await connection.repositories());
+    } catch (err) {
+      log.error('the repositories could not be listed:', { detail: err instanceof Error ? err.message : String(err) });
+      const unreachable = err instanceof GitHubAppError && err.kind === 'unreachable';
+      res.status(502).json({
+        error: unreachable
+          ? 'GitHub could not be reached. Try again shortly.'
+          : 'GitHub would not list the repositories. The app may have been uninstalled: connect it again.',
+      });
+    }
+  });
+
+  return router;
+}

package/src/modules/github-app/index.ts

@@ -0,0 +1,19 @@
+export {
+  GitHubAppClient,
+  GitHubAppError,
+  appJwt,
+  normalizePrivateKey,
+  type GitHubAppCredentials,
+  type GitHubFailureKind,
+  type Installation,
+  type InstallationRepository,
+  type InstallationToken,
+  type RegisteredApp,
+} from './github-app.client.js';
+export { GitHubAppConnection, repositoriesAsSetting, type GitHubAppConnectionOptions } from './github-app.connection.js';
+export {
+  createGitHubAppRoutes,
+  githubAppCallbackUrl,
+  githubAppManifest,
+  type GitHubAppRoutesDeps,
+} from './github-app.routes.js';

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__/remote-url.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeRepositoryAddress, sameRepository } from '../remote-url.js';
+
+/**
+ * The comparison decides whether a working copy is kept or deleted, so what
+ * it must never do is call the SAME repository a different one.
+ */
+describe('sameRepository', () => {
+  it.each([
+    ['https://github.com/org/repo', 'https://github.com/org/repo.git'],
+    ['https://github.com/org/repo', 'https://github.com/org/repo/'],
+    ['https://github.com/org/repo.git/', 'https://github.com/org/repo'],
+    ['https://GitHub.com/org/repo', 'https://github.com/org/repo'],
+    ['HTTPS://github.com/org/repo', 'https://github.com/org/repo'],
+    ['https://x-access-token:secret@github.com/org/repo', 'https://github.com/org/repo'],
+    ['  https://github.com/org/repo  ', 'https://github.com/org/repo'],
+    ['/srv/git/kb.git', '/srv/git/kb'],
+    ['C:\\git\\kb.git\\', 'C:\\git\\kb'],
+  ])('%s is %s', (a, b) => {
+    expect(sameRepository(a, b)).toBe(true);
+  });
+
+  it.each([
+    ['https://github.com/org/repo', 'https://github.com/org/other'],
+    ['https://github.com/org/repo', 'https://github.com/other/repo'],
+    ['https://github.com/org/repo', 'https://gitlab.com/org/repo'],
+    ['https://github.com/org/repo', 'https://github.com/org/repo-kb'],
+    ['https://github.com/org/Repo', 'https://github.com/org/repo'],
+  ])('%s is not %s', (a, b) => {
+    expect(sameRepository(a, b)).toBe(false);
+  });
+
+  it('never carries a credential into the normalized form', () => {
+    expect(normalizeRepositoryAddress('https://user:token@github.com/org/repo.git')).toBe(
+      'https://github.com/org/repo',
+    );
+  });
+});

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

package/src/modules/kb-fs/remote-url.ts

@@ -0,0 +1,35 @@
+/**
+ * Whether two repository addresses name the same repository.
+ *
+ * The answer decides whether a working copy on disk is KEPT or DELETED, so it
+ * errs towards "same": only differences that cannot change which repository
+ * is meant are ignored, and they are ignored on both sides.
+ *
+ *  - a trailing slash, and a `.git` suffix — hosts serve both spellings;
+ *  - the letter case of the scheme and the host — DNS does not distinguish;
+ *  - userinfo (`user:token@`) — who asks does not change what is asked for,
+ *    and a credential must never decide, or appear in, a comparison.
+ *
+ * The PATH keeps its case: hosts that fold it and hosts that do not both
+ * exist, and treating `Org/Repo` and `org/repo` as one would keep a clone of
+ * the wrong repository on a host that tells them apart — but deleting a clone
+ * of the right one is the worse error, and an operator who only changed the
+ * case gets a re-clone, not a loss: the work on that clone was pushed to the
+ * same place.
+ */
+export function normalizeRepositoryAddress(address: string): string {
+  let a = address.trim();
+  const url = /^([a-z][a-z0-9+.-]*):\/\/([^/]*)(\/.*)?$/i.exec(a);
+  if (url) {
+    const host = url[2]!.replace(/^[^@]*@/, '').toLowerCase();
+    a = `${url[1]!.toLowerCase()}://${host}${url[3] ?? ''}`;
+  }
+  return a
+    .replace(/[\\/]+$/, '')
+    .replace(/\.git$/i, '')
+    .replace(/[\\/]+$/, '');
+}
+
+export function sameRepository(a: string, b: string): boolean {
+  return normalizeRepositoryAddress(a) === normalizeRepositoryAddress(b);
+}