@bevel-software/platform-core-backend 0.4.1 → 0.5.0

package/src/modules/secrets-vault/secrets-vault.routes.ts

@@ -33,6 +33,37 @@ function redirectUriFor(publicBackendUrl: string): string {
   return `${publicBackendUrl}/api/secrets/oauth/callback`;
 }
 
+/**
+ * Is this a SAME-ORIGIN path we're willing to bounce the browser back to after a
+ * sign-in? The callback builds `${publicFrontendUrl}${dest}#…`, so anything that
+ * survives this check gets concatenated onto our own origin — which makes every
+ * rule here an open-redirect rule, not a formatting preference:
+ *  - must start with a single `/` — `//evil.com` is a protocol-relative URL and
+ *    `https://evil.com` an absolute one; both would leave our origin entirely.
+ *  - no `\` — WHATWG folds a backslash to a slash for http(s), so `/\evil.com`
+ *    is `//evil.com` by another spelling.
+ *  - no `#` — the callback appends its own fragment; a caller-supplied one would
+ *    swallow the `#authorized=…`/`#error=…` the landing page reads.
+ *  - no CR/LF — never let a caller-controlled string reach a `Location` header
+ *    with a line break in it (response splitting).
+ *  - ≤512 chars — a signed `state` rides in the provider's authorize URL, and
+ *    some providers cap its length; this keeps the round-trip inside every
+ *    budget without needing to know each provider's limit.
+ * Exported for the route tests: this predicate IS the security boundary, so it
+ * is pinned by a unit table rather than only exercised end-to-end.
+ */
+export function isSafeReturnPath(returnTo: unknown): returnTo is string {
+  return (
+    typeof returnTo === 'string' &&
+    returnTo.length <= 512 &&
+    returnTo.startsWith('/') &&
+    !returnTo.startsWith('//') &&
+    !returnTo.includes('\\') &&
+    !returnTo.includes('#') &&
+    !/[\r\n]/.test(returnTo)
+  );
+}
+
 /**
  * Authenticated Secrets Vault CRUD + OAuth start. Every route is scoped to
  * `req.userId` — secrets are private per user. Mounted behind the JWT middleware.
@@ -40,7 +71,14 @@ function redirectUriFor(publicBackendUrl: string): string {
 export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.Router {
   const { secretsVault, toolManualService, accessControl } = deps;
   const router = express.Router();
-  const defaultWs = workspaceIdForBranch(DEFAULT_BRANCH);
+  // A FUNCTION, not a constant. Routers are constructed at boot, and on a
+  // deployment configured through the setup screen the branch model does not
+  // exist yet at that moment — `DEFAULT_BRANCH` is still ''. The live binding
+  // updates when setup applies the model, but only reads INSIDE a function
+  // body see it; a construction-time capture would keep handing an empty
+  // workspace id to the access resolver until the next restart ("Invalid
+  // workspace ID" on every /secrets/tools call).
+  const defaultWs = () => workspaceIdForBranch(DEFAULT_BRANCH);
 
   // The vault key = the exact key UTCP looks the var up under (doubles underscores
   // in the manual namespace), so storage and resolution agree for snake_case ids.
@@ -165,7 +203,7 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
           path: m.path,
           type: m.type,
           setup: m.setup ?? null,
-          canWrite: await accessControl.canWrite(defaultWs, email, m.path),
+          canWrite: await accessControl.canWrite(defaultWs(), email, m.path),
           variables: (m.variables ?? []).map((v) => {
             const key = varKey(m.name, v.name);
             const st = statusByKey.get(key);
@@ -290,7 +328,7 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
       if (found.variable.scope !== 'admin') {
         return void res.status(422).json({ error: 'This variable is set by each user, not the tool owner.' });
       }
-      if (!(await accessControl.canWrite(defaultWs, email, found.manual.path))) {
+      if (!(await accessControl.canWrite(defaultWs(), email, found.manual.path))) {
         return void res.status(403).json({ error: 'You need write access to this tool to set its shared secrets.' });
       }
       const body = req.body ?? {};
@@ -343,7 +381,7 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
       if (!found.variable.oauth) {
         return void res.status(422).json({ error: 'This variable is not an OAuth sign-in.' });
       }
-      if (!(await accessControl.canWrite(defaultWs, email, found.manual.path))) {
+      if (!(await accessControl.canWrite(defaultWs(), email, found.manual.path))) {
         return void res.status(403).json({ error: 'You need write access to this tool to set its client secret.' });
       }
       const clientSecret = (req.body ?? {}).clientSecret;
@@ -369,7 +407,9 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
 
   // Start sign-in for a tool's OAuth-backed variable. Provisions the caller's row
   // from the owner-set secret and returns the provider consent URL; the callback
-  // bounces back to /connect (via `r` in the signed state).
+  // bounces back to wherever the flow started (via `r` in the signed state) — an
+  // optional `{ returnTo }` body when the caller asks for a specific page, else
+  // /connect, which is where every caller came from before `returnTo` existed.
   router.post('/secrets/tools/:slug/vars/:var/oauth/start', async (req, res) => {
     const userId = req.userId;
     const email = req.userEmail;
@@ -395,11 +435,17 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
         // on the next sign-in. The secret/clientId/addresses stay owner-pinned.
         scopes: found.variable.oauth.scopes,
       });
+      // The return path is signed INTO the state (HMAC-SHA256) rather than kept
+      // in a query param or a cookie: the callback arrives un-authenticated from
+      // the provider, so the state is the only thing it can trust. An absent or
+      // unsafe `returnTo` falls back to the legacy `'connect'` marker, which
+      // keeps a body-less start byte-identical to what it produced before.
+      const returnTo: unknown = (req.body ?? {}).returnTo;
       const state = signState(deps.stateSecret, {
         u: userId,
         i: id,
         n: randomBytes(8).toString('hex'),
-        r: 'connect',
+        r: isSafeReturnPath(returnTo) ? returnTo : 'connect',
       });
       const consentUrl = new URL(url);
       consentUrl.searchParams.set('state', state);
@@ -416,7 +462,7 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
     try {
       const found = await findManualVar(email, req.params.slug, req.params.var);
       if (!found) return void res.status(404).json({ error: 'Tool or variable not found' });
-      if (!(await accessControl.canWrite(defaultWs, email, found.manual.path))) {
+      if (!(await accessControl.canWrite(defaultWs(), email, found.manual.path))) {
         return void res.status(403).json({ error: 'You need write access to this tool to remove its shared secrets.' });
       }
       await secretsVault.removeShared(varKey(found.manual.name, found.variable.name));
@@ -456,16 +502,21 @@ export function createSecretsVaultPublicRoutes(deps: SecretsVaultRoutesDeps): ex
     const code = typeof req.query.code === 'string' ? req.query.code : '';
     const stateRaw = typeof req.query.state === 'string' ? req.query.state : '';
     // The landing page depends on where the flow started (the `r` field in the
-    // signed state): a tool-var sign-in returns to /connect, the standalone
-    // Secrets page to /secrets. Pre-verification errors can't know `r`, so they
-    // fall back to /secrets.
+    // signed state): an explicit same-origin path returns there, the legacy
+    // `'connect'` marker to /connect, the standalone Secrets page to /secrets.
+    // Pre-verification errors can't know `r`, so they fall back to /secrets.
     const back = (frag: string, dest = '/secrets') =>
       res.redirect(`${deps.publicFrontendUrl}${dest}#${frag}`);
     if (!code || !stateRaw) return void back(`error=${encodeURIComponent('Invalid OAuth callback.')}`);
 
     const state = verifyState(deps.stateSecret, stateRaw);
     if (!state) return void back(`error=${encodeURIComponent('OAuth state mismatch.')}`);
-    const dest = state.r === 'connect' ? '/connect' : '/secrets';
+    // Re-validated HERE even though `r` was validated on the way in and is
+    // HMAC-signed: this is the line that concatenates a stored string onto our
+    // public origin and hands it to the browser as a `Location`. Defense in
+    // depth — the check costs nothing, and it means an open redirect would need
+    // BOTH the signing key and a validation bug, not either one.
+    const dest = isSafeReturnPath(state.r) ? state.r : state.r === 'connect' ? '/connect' : '/secrets';
 
     try {
       await secretsVault.completeOAuth(state.u, state.i, code, redirectUriFor(deps.publicBackendUrl));
@@ -494,7 +545,12 @@ interface OAuthState {
   i: string; // secret id
   n: string; // nonce
   iat: number; // issued-at (epoch ms)
-  r?: string; // return path hint ('connect' → land on /connect; else /secrets)
+  /**
+   * Return path hint: a same-origin path (`isSafeReturnPath`) → land there; the
+   * legacy marker `'connect'` → /connect; anything else (incl. absent) →
+   * /secrets. Signed, so the callback can trust it — but re-validated anyway.
+   */
+  r?: string;
 }
 
 const OAUTH_STATE_MAX_AGE_MS = 10 * 60_000;

package/src/modules/settings/__tests__/deployment-settings.service.test.ts

@@ -0,0 +1,256 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import {
+  DeploymentSettingsService,
+  SettingsValidationError,
+  CORE_SETTINGS,
+} from '../deployment-settings.service.js';
+import type { Database } from '../../database/connection.js';
+
+const ENC_KEY = randomBytes(32).toString('base64');
+
+/**
+ * An in-memory stand-in for the one table this service owns. Enough of the
+ * drizzle surface to exercise load/save round-trips without a live Postgres —
+ * the SQL itself is one insert with an upsert target, which the migration
+ * covers.
+ */
+function makeDb() {
+  const rows: { key: string; value: string; encrypted: boolean }[] = [];
+  const db = {
+    select: () => ({ from: () => Promise.resolve(rows.map((r) => ({ ...r }))) }),
+    insert: () => ({
+      values: (v: { key: string; value: string; encrypted: boolean }) => ({
+        onConflictDoUpdate: () => {
+          const existing = rows.find((r) => r.key === v.key);
+          if (existing) Object.assign(existing, v);
+          else rows.push({ key: v.key, value: v.value, encrypted: v.encrypted });
+          return Promise.resolve();
+        },
+      }),
+    }),
+    delete: () => ({ where: () => Promise.resolve() }),
+  } as unknown as Database;
+  return { db, rows };
+}
+
+let saved: NodeJS.ProcessEnv;
+beforeEach(() => {
+  saved = { ...process.env };
+  for (const def of CORE_SETTINGS) delete process.env[def.envVar];
+  delete process.env.GITHUB_TOKEN;
+});
+afterEach(() => {
+  process.env = saved;
+});
+
+describe('DeploymentSettingsService — precedence', () => {
+  /**
+   * The rule the whole design rests on: a stored row is a FALLBACK for a
+   * variable nobody set, never an override of one they did. It is what lets an
+   * existing deployment adopt this table with no behaviour change, and what
+   * stops a value typed into a browser outranking the infrastructure config
+   * someone is reviewing in a repo.
+   */
+  it('lets the environment win over a stored value', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ kbRepoUrl: 'https://example.com/stored.git' }, null);
+
+    process.env.KB_REPO_URL = 'https://example.com/from-env.git';
+    expect(settings.resolve('kbRepoUrl')).toBe('https://example.com/from-env.git');
+    expect(settings.sourceOf('kbRepoUrl')).toBe('env');
+
+    delete process.env.KB_REPO_URL;
+    expect(settings.resolve('kbRepoUrl')).toBe('https://example.com/stored.git');
+    expect(settings.sourceOf('kbRepoUrl')).toBe('stored');
+  });
+
+  /**
+   * Refused, not silently accepted. Storing it would write a row that can never
+   * take effect, and leave the screen implying it had.
+   */
+  it('refuses to store a setting the environment already supplies', async () => {
+    process.env.KB_REPO_URL = 'https://example.com/from-env.git';
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await expect(
+      settings.save({ kbRepoUrl: 'https://example.com/other.git' }, null),
+    ).rejects.toBeInstanceOf(SettingsValidationError);
+  });
+});
+
+describe('DeploymentSettingsService — secrets', () => {
+  it('stores the token as ciphertext and reads it back', async () => {
+    const { db, rows } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ gitToken: 'ghp_verysecret' }, null);
+
+    const row = rows.find((r) => r.key === 'gitToken');
+    expect(row?.encrypted).toBe(true);
+    expect(row?.value).not.toContain('ghp_verysecret');
+
+    // A fresh instance decrypts from the same rows — the round trip, not just
+    // the in-memory cache.
+    const reloaded = new DeploymentSettingsService(db, ENC_KEY);
+    await reloaded.load();
+    expect(reloaded.resolve('gitToken')).toBe('ghp_verysecret');
+  });
+
+  it('never puts a secret value in what the screen is sent', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ gitToken: 'ghp_verysecret' }, null);
+
+    const described = settings.describe();
+    expect(JSON.stringify(described)).not.toContain('ghp_verysecret');
+    const token = described.find((s) => s.key === 'gitToken');
+    // Configured is all a client learns — enough to render "replace it?".
+    expect(token).toMatchObject({ secret: true, configured: true });
+    expect(token).not.toHaveProperty('value');
+  });
+
+  it('publishes a stored token as GITHUB_TOKEN, which is what git reads', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ gitToken: 'ghp_fromsetup' }, null);
+    expect(process.env.GITHUB_TOKEN).toBe('ghp_fromsetup');
+  });
+
+  it('does not overwrite a git token the environment supplied', async () => {
+    process.env.GIT_TOKEN = 'ghp_fromenv';
+    process.env.GITHUB_TOKEN = 'ghp_fromenv';
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    settings.syncGitTokenEnv();
+    expect(process.env.GITHUB_TOKEN).toBe('ghp_fromenv');
+  });
+
+  it('refuses to store a secret with no encryption key rather than writing plaintext', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, '');
+    await expect(settings.save({ gitToken: 'ghp_verysecret' }, null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+  });
+
+  /**
+   * A rotated or mistyped key must not stop the server booting — the screen
+   * where it gets fixed is on the other side of that boot.
+   */
+  it('survives an undecryptable row instead of failing to start', async () => {
+    const { db, rows } = makeDb();
+    rows.push({ key: 'gitToken', value: 'not-a-valid-blob', encrypted: true });
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    await expect(settings.load()).resolves.toBeUndefined();
+    expect(settings.resolve('gitToken')).toBe('');
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe('DeploymentSettingsService — validation', () => {
+  it('rejects the whole batch when one field is wrong', async () => {
+    const { db, rows } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await expect(
+      settings.save({ kbRepoUrl: 'not-a-url', gitToken: 'ghp_ok' }, null),
+    ).rejects.toBeInstanceOf(SettingsValidationError);
+    // Nothing written: a URL saved without its token is a deployment that
+    // fails at the first clone.
+    expect(rows).toHaveLength(0);
+  });
+
+  it('rejects a non-https remote', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await expect(
+      settings.save({ kbRepoUrl: 'git@github.com:acme/kb.git' }, null),
+    ).rejects.toThrow(/Invalid settings/);
+  });
+
+  it('rejects a directory name that could escape the workspace', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await expect(settings.save({ kbDirName: '../elsewhere' }, null)).rejects.toThrow(
+      /Invalid settings/,
+    );
+  });
+
+  it('rejects a username that would break out of the credential-helper snippet', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await expect(settings.save({ gitUsername: 'x"; rm -rf /; #' }, null)).rejects.toThrow(
+      /Invalid settings/,
+    );
+  });
+
+  /**
+   * A blank field means "leave it alone". Treating it as a delete would let a
+   * stray Enter on a half-filled form unconfigure a running deployment.
+   */
+  it('treats a blank field as no change, not as an erase', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ gitToken: 'ghp_keepme' }, null);
+    await settings.save({ gitToken: '   ' }, null);
+    expect(settings.resolve('gitToken')).toBe('ghp_keepme');
+  });
+
+  /**
+   * The branch pair is the one rule no per-field check can express: the default
+   * has to appear in the protected list, so each name is only valid in the
+   * other's company. If it were not checked, the pair would be rejected far
+   * later — by `configureBranchModel` at the NEXT BOOT, which is a deployment
+   * that saved successfully and then would not start.
+   */
+  it('refuses a default branch that is not in the protected list', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await expect(
+      settings.save({ defaultBranch: 'main', protectedBranches: 'release' }, null),
+    ).rejects.toBeInstanceOf(SettingsValidationError);
+  });
+
+  it('accepts a pair that agrees', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ defaultBranch: 'main', protectedBranches: 'main, release' }, null);
+    expect(settings.resolve('defaultBranch')).toBe('main');
+  });
+
+  /**
+   * Judged on the model the save WOULD produce, not on the input: setting one
+   * half against an existing other half has to be checked against the result.
+   */
+  it('checks a half-save against what is already in effect', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ defaultBranch: 'main', protectedBranches: 'main' }, null);
+    // Narrowing the protected list to one that excludes the standing default.
+    await expect(settings.save({ protectedBranches: 'release' }, null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+    // …and the other way: a default that the standing list does cover.
+    await settings.save({ protectedBranches: 'main, release' }, null);
+    await expect(settings.save({ defaultBranch: 'release' }, null)).resolves.toBeTruthy();
+  });
+
+  it('seals the SSO client secret like the git token', async () => {
+    const { db, rows } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ oidcClientSecret: 'sso-very-secret' }, null);
+    expect(rows.find((r) => r.key === 'oidcClientSecret')?.encrypted).toBe(true);
+    expect(JSON.stringify(settings.describe())).not.toContain('sso-very-secret');
+  });
+
+  it('reports a restart only for a setting a running server cannot pick up', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    const live = await settings.save({ kbRepoUrl: 'https://example.com/kb.git' }, null);
+    expect(live.restartRequired).toBe(false);
+    const staged = await settings.save({ kbDirName: 'company-brain' }, null);
+    expect(staged.restartRequired).toBe(true);
+  });
+});

package/src/modules/settings/__tests__/setup.routes.test.ts

@@ -0,0 +1,201 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createSetupRoutes } from '../setup.routes.js';
+import { DeploymentSettingsService } from '../deployment-settings.service.js';
+import type { Database } from '../../database/connection.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+
+const ENC_KEY = 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=';
+
+let server: HttpServer | null = null;
+
+/**
+ * These suites clear the KB variables so `settings.resolve` falls through to
+ * the stored layer. They are RESTORED afterwards rather than left deleted: the
+ * repo `.env` is loaded into `process.env` by the vitest config, so a suite
+ * that runs later in the same worker would otherwise see a different
+ * environment than the one it was written against.
+ */
+const KB_ENV = ['KB_REPO_URL', 'GIT_TOKEN', 'GIT_USERNAME', 'KB_DIR_NAME'] as const;
+let savedEnv: Partial<Record<(typeof KB_ENV)[number], string | undefined>> = {};
+
+beforeEach(() => {
+  savedEnv = {};
+  for (const k of KB_ENV) {
+    savedEnv[k] = process.env[k];
+    delete process.env[k];
+  }
+});
+
+afterEach(() => {
+  server?.close();
+  server = null;
+  for (const k of KB_ENV) {
+    const original = savedEnv[k];
+    if (original === undefined) delete process.env[k];
+    else process.env[k] = original;
+  }
+});
+
+/** Mount the setup router on a throwaway port and hand back its base URL. */
+function listen(isAdmin = true) {
+  const db = {
+    select: () => ({ from: () => Promise.resolve([]) }),
+    insert: () => ({ values: () => ({ onConflictDoUpdate: () => Promise.resolve() }) }),
+    delete: () => ({ where: () => Promise.resolve() }),
+  } as unknown as Database;
+  const settings = new DeploymentSettingsService(db, ENC_KEY);
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userEmail = 'root@example.com';
+    req.userId = 'user-1';
+    next();
+  });
+  app.use('/api', createSetupRoutes(settings, { isAdmin: async () => isAdmin } as IAdminAccessService));
+  server = app.listen(0);
+  const { port } = server.address() as AddressInfo;
+  return { base: `http://127.0.0.1:${port}`, settings };
+}
+
+const post = (base: string, path: string, body: unknown) =>
+  fetch(`${base}${path}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+/**
+ * The connection test hands its input to `git`. Anything reaching that command
+ * unvalidated is argument injection — admin-only, but "admin" is not "may run
+ * arbitrary commands as the server process".
+ */
+describe('POST /setup/test-connection — what may reach git', () => {
+  it('refuses a value git would read as an option', async () => {
+    const { base } = listen();
+    const res = await post(base, '/api/setup/test-connection', {
+      kbRepoUrl: '--upload-pack=touch /tmp/pwned',
+    });
+    expect(res.status).toBe(400);
+    expect((await res.json()).ok).toBe(false);
+  });
+
+  /** `ext::` is a git transport whose whole purpose is to run a command. */
+  it('refuses the ext:: transport', async () => {
+    const { base } = listen();
+    const res = await post(base, '/api/setup/test-connection', {
+      kbRepoUrl: 'ext::sh -c "touch /tmp/pwned"',
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it('refuses a non-https scheme', async () => {
+    const { base } = listen();
+    const res = await post(base, '/api/setup/test-connection', { kbRepoUrl: 'file:///etc/passwd' });
+    expect(res.status).toBe(400);
+  });
+
+  it('refuses a username that would break out of the credential-helper snippet', async () => {
+    const { base } = listen();
+    const res = await post(base, '/api/setup/test-connection', {
+      kbRepoUrl: 'https://example.com/acme/kb.git',
+      gitUsername: 'x"; touch /tmp/pwned; #',
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it('is admins-only', async () => {
+    const { base } = listen(false);
+    const res = await post(base, '/api/setup/test-connection', {
+      kbRepoUrl: 'https://example.com/acme/kb.git',
+    });
+    expect(res.status).toBe(403);
+  });
+});
+
+/**
+ * The stored token is deliberately unreadable — `describe()` omits it — so an
+ * endpoint that would send it to a caller-named host hands it straight back.
+ */
+describe('POST /setup/test-connection — where the saved token may go', () => {
+  it('refuses to test a different repository with the saved token', async () => {
+    const { base, settings } = listen();
+    await settings.save(
+      { kbRepoUrl: 'https://example.com/acme/kb.git', gitToken: 'ghp_verysecret' },
+      null,
+    );
+    const res = await post(base, '/api/setup/test-connection', {
+      kbRepoUrl: 'https://attacker.example/collector.git',
+    });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error).toMatch(/access token for that repository/i);
+  });
+
+  it('still lets an admin re-test the repository that IS configured', async () => {
+    const { base, settings } = listen();
+    await settings.save(
+      { kbRepoUrl: 'https://127.0.0.1:1/acme/kb.git', gitToken: 'ghp_verysecret' },
+      null,
+    );
+    // No credentials in the body: the saved pair is used together, which is the
+    // "does the token I saved last week still work?" case.
+    const res = await post(base, '/api/setup/test-connection', {});
+    // Port 1 refuses instantly — reaching a connection error proves the request
+    // got past the guards and ran git, rather than being rejected up front.
+    expect(res.status).toBe(200);
+    expect((await res.json()).ok).toBe(false);
+  });
+
+  it('accepts a different repository when the request brings its own token', async () => {
+    const { base, settings } = listen();
+    await settings.save(
+      { kbRepoUrl: 'https://example.com/acme/kb.git', gitToken: 'ghp_verysecret' },
+      null,
+    );
+    const res = await post(base, '/api/setup/test-connection', {
+      kbRepoUrl: 'https://127.0.0.1:1/other/kb.git',
+      gitToken: 'ghp_its_own',
+    });
+    expect(res.status).toBe(200);
+  });
+});
+
+/**
+ * The arguments the route builds have to be ones git actually accepts —
+ * `--end-of-options` among them. A rejected FLAG and a refused CONNECTION look
+ * alike from the outside (`ok: false`), so this aims at a port nothing listens
+ * on: reaching a connection error proves git parsed the command line.
+ */
+describe('POST /setup/test-connection — the command git is given', () => {
+  it('builds a command git accepts', async () => {
+    const { base } = listen();
+    const res = await post(base, '/api/setup/test-connection', {
+      kbRepoUrl: 'https://127.0.0.1:1/acme/kb.git',
+      gitToken: 'ghp_whatever',
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(false);
+    expect(body.error).not.toMatch(/unknown option|usage: git/i);
+  });
+});
+
+describe('GET /setup/status', () => {
+  it('tells a non-admin whether setup is done, and nothing else', async () => {
+    const { base } = listen(false);
+    const res = await fetch(`${base}/api/setup/status`);
+    const body = await res.json();
+    expect(body).toEqual({ complete: false, isAdmin: false });
+    // No catalogue, so no variable names and no hint at what is missing.
+    expect(JSON.stringify(body)).not.toContain('KB_REPO_URL');
+  });
+
+  it('never includes a stored secret, even for an admin', async () => {
+    const { base, settings } = listen();
+    await settings.save({ gitToken: 'ghp_verysecret' }, null);
+    const res = await fetch(`${base}/api/setup/status`);
+    expect(JSON.stringify(await res.json())).not.toContain('ghp_verysecret');
+  });
+});