@bevel-software/platform-core-backend 0.15.1 → 0.19.0

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

@@ -44,6 +44,20 @@ export interface SecretConfigStatus {
   key: string;
   adminConfigured: boolean;
   userConfigured: boolean;
+  /**
+   * How the SHARED row is stored, or `null` when there is none. A `.tool` can be
+   * edited to turn a plain key into an OAuth variable (or back) while the old row
+   * survives, and the two kinds are not interchangeable: an OAuth flow reads the
+   * client secret off an `oauth` row and `resolve` reads a value off a `static`
+   * one. A caller that asks "is this set up?" has to mean "set up AS THE KIND THE
+   * MANUAL NOW DECLARES", or it offers an Authorize the flow will refuse.
+   *
+   * Required, not optional: "the field was left out" and "there is no row" have
+   * to be the same answer, or a caller that trusts it cannot be strict.
+   */
+  adminKind: SecretKind | null;
+  /** How the CALLER's own row is stored, or `null` when they have none. Same reason. */
+  userKind: SecretKind | null;
   /**
    * For an OAuth-backed per-user row: whether the caller has completed sign-in (a
    * token exists). `undefined` for static rows / when the caller has no row. Lets
@@ -102,7 +116,47 @@ export interface CreateOAuthSecretInput {
   provider: OAuthProviderConfig;
 }
 
+/** Secrets stored under one manual's name, counted — never a value, never whose. */
+export interface NamespaceSecretCount {
+  /** Typed values and shared client secrets. */
+  keys: number;
+  /** Per-user OAuth rows — somebody signed in (or started to). */
+  signIns: number;
+}
+
+/**
+ * Whether a vault key belongs to the namespace `prefix` (`utcpNamespacePrefix`).
+ *
+ * A bare `startsWith` is not enough: namespacing doubles every underscore, so
+ * manual `foo`'s prefix `foo_` is also the start of manual `foo_bar`'s
+ * `foo__bar_`. A remainder starting with `_` therefore belongs to a longer
+ * name.
+ *
+ * `_X` IS a legal variable name, so `foo` declaring `_bar_KEY` stores under
+ * `foo__bar_KEY` — the very key `foo_bar` declaring `KEY` stores under. The
+ * UTCP encoding makes those one row with two honest claimants, and no rule
+ * applied to the key can tell them apart. This predicate therefore answers NO
+ * for every `_`-leading remainder, with no exception for a declaring manual:
+ * the only thing it is used for is counting and WIPING a whole namespace, and
+ * an ambiguous row left standing is recoverable where one wrongly deleted is
+ * not. (Establishing that no colliding manual exists is not an option either
+ * — the tool catalog omits what it could not read, so its silence is not
+ * proof.)
+ */
+export function isKeyInNamespace(key: string, prefix: string): boolean {
+  if (!key.startsWith(prefix)) return false;
+  const rest = key.slice(prefix.length);
+  return rest.length > 0 && !rest.startsWith('_');
+}
+
 export interface ISecretsVaultService {
+  /** Count every user's secrets under one namespace prefix — see {@link isKeyInNamespace}. */
+  countNamespace(prefix: string): Promise<NamespaceSecretCount>;
+  /**
+   * Delete every secret under one namespace prefix — the shared rows and every
+   * user's. What deleting a tool wipes; returns what it removed.
+   */
+  removeNamespace(prefix: string): Promise<NamespaceSecretCount>;
   /** The caller's secrets (values omitted). */
   list(userId: string): Promise<SecretSummary[]>;
   /** One secret's summary, or null if it isn't the caller's. */
@@ -183,8 +237,27 @@ export interface ISecretsVaultService {
    * token (refreshed on demand). Returns null when missing or not-yet-authorized.
    */
   resolve(userId: string, key: string): Promise<string | null>;
+
+  /**
+   * Refresh the caller's OAuth token for `key` NOW, ignoring its stored expiry —
+   * for when a downstream server has just rejected the token (401 /
+   * `invalid_token`), which outranks whatever lifetime it was issued with.
+   * Callers own the pacing (the MCP proxy allows one per user+manual per
+   * minute); this method refreshes every time it is asked.
+   */
+  forceRefresh(userId: string, key: string): Promise<ForcedRefreshOutcome>;
 }
 
+/**
+ * What a {@link ISecretsVaultService.forceRefresh} did:
+ *   - `refreshed` — fresh tokens are stored; a retry will use them.
+ *   - `rejected` — the grant is dead (provider 400/401, or no refresh token):
+ *     the token set was wiped, client secret kept; the user must re-authorize.
+ *   - `transient` — network/timeout/5xx: tokens kept, a later call tries again.
+ *   - `skipped` — nothing to refresh (no such OAuth row, or not signed in).
+ */
+export type ForcedRefreshOutcome = 'refreshed' | 'rejected' | 'transient' | 'skipped';
+
 /** Thrown when input fails validation. Routes map to 422. */
 export class InvalidSecretError extends Error {
   constructor(message: string) {
@@ -268,3 +341,23 @@ export function missingScopes(required: string[] | undefined, granted: string |
 export function scopesCovered(required: string[] | undefined, granted: string | undefined): boolean {
   return missingScopes(required, granted).length === 0;
 }
+
+/**
+ * Is the stored row the KIND the manual now declares — i.e. would the thing the
+ * UI is about to offer actually work?
+ *
+ * A `.tool` can be edited to turn a plain key into an OAuth variable, or back,
+ * and the row set for the previous shape survives the edit. The two are not
+ * interchangeable: `beginToolOAuthByKey` refuses a `static` shared row, and
+ * `resolve` hands an OAuth row's ACCESS TOKEN to a variable whose consumer
+ * wants the value. So "a row exists" is never "this variable is set up", and
+ * every surface that asks the second question pairs the presence flag with the
+ * kind rather than re-deriving the rule.
+ */
+export function configuredAs(
+  want: SecretKind,
+  present: boolean | undefined,
+  stored: SecretKind | null | undefined,
+): boolean {
+  return present === true && stored === want;
+}

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

@@ -1,4 +1,7 @@
 import express from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('secrets');
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import {
@@ -7,6 +10,7 @@ import {
   SecretOAuthError,
   scopesCovered,
   missingScopes,
+  configuredAs,
   type ISecretsVaultService,
 } from './secrets-vault.contract.js';
 import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/tool-manuals.contract.js';
@@ -108,7 +112,7 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
     try {
       res.json({ secrets: await secretsVault.list(userId) });
     } catch (err) {
-      console.error('[secrets] list failed:', err);
+      log.error('list failed:', { err });
       res.status(500).json({ error: 'Internal error' });
     }
   });
@@ -195,8 +199,16 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
     if (!userId || !email) return void res.status(401).json({ error: 'Not authenticated' });
     try {
       const pathFilter = typeof req.query.path === 'string' ? req.query.path : null;
-      let manuals = await toolManualService.listAccessible(email);
-      if (pathFilter) manuals = manuals.filter((m) => m.path === pathFilter);
+      // The Library page's spine, so it carries the refused files too: one
+      // unparseable `.tool` costs the page that tool and nothing else, and the
+      // page can say which file and why instead of rendering a gap. Narrowed
+      // by `?path=` exactly as the manuals are — the editor sidebar asking
+      // about one file gets that file's verdict, valid or not.
+      // One scan, one access pass, one snapshot: `tools` and `invalid` cannot
+      // disagree about which files the workspace held.
+      const { tools: allManuals, invalid: allInvalid } = await toolManualService.listAccessibleCatalog(email);
+      const manuals = pathFilter ? allManuals.filter((m) => m.path === pathFilter) : allManuals;
+      const invalid = pathFilter ? allInvalid.filter((i) => i.path === pathFilter) : allInvalid;
 
       const allKeys = manuals.flatMap((m) => (m.variables ?? []).map((v) => varKey(m.name, v.name)));
       const status = await secretsVault.statusFor(userId, allKeys);
@@ -234,57 +246,97 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
           }),
         })),
       );
-      res.json({ tools });
+      res.json({ tools, invalid });
     } catch (err) {
-      console.error('[secrets] list tools failed:', err);
+      log.error('list tools failed:', { err });
       res.status(500).json({ error: 'Internal error' });
     }
   });
 
   // The aggregated "connect your tools" view for a single user: every accessible
-  // tool with ONLY its per-user (`user`-scoped) variables and whether the caller
-  // has set each, plus the caller's OAuth secrets and their authorized state. This
-  // is the surface an external-agent user lands on from the needs-authorization
-  // link — it shows exactly what THEY must provide, never the admin/shared items.
+  // tool with the variables still standing between the caller and using it, plus
+  // the caller's OAuth secrets and their authorized state. This is the surface an
+  // external-agent user lands on from the needs-authorization link.
+  //
+  // It reports the WORKSPACE-scoped (`admin`) values too, and not because the
+  // reader can always set them: the Library's plugin banner COUNTS an integration
+  // that needs one, so a page that left them out told the reader four things
+  // needed setup and then showed two. An `admin` value the caller may not write
+  // is flagged `ownerOnly` — the page greys it and names who has to act — and one
+  // that is already set is nobody's outstanding work, so it is dropped. What is
+  // not relaxed is readability: the listing is still built from `listAccessible`,
+  // so a tool the caller may not read is named here in no state at all.
   router.get('/connect/pending', async (req, res) => {
     const userId = req.userId;
     const email = req.userEmail;
     if (!userId || !email) return void res.status(401).json({ error: 'Not authenticated' });
     try {
       const manuals = await toolManualService.listAccessible(email);
-      const allKeys = manuals.flatMap((m) =>
-        (m.variables ?? []).filter((v) => v.scope === 'user').map((v) => varKey(m.name, v.name)),
-      );
+      // BOTH tiers now — the workspace values are reported as well, so their
+      // stored state has to be asked for.
+      const allKeys = manuals.flatMap((m) => (m.variables ?? []).map((v) => varKey(m.name, v.name)));
       const status = await secretsVault.statusFor(userId, allKeys);
       const statusByKey = new Map(status.map((s) => [s.key, s]));
+      // Who may set a tool's workspace values — writers of its `.tool` file, the
+      // same verdict the admin write route enforces. Resolved once per manual
+      // because both the key rows and the sign-in rows ask it.
+      const canWriteBySlug = new Map(
+        await Promise.all(
+          manuals.map(
+            async (m) =>
+              [m.slug, await accessControl.canWrite(defaultWs(), email, m.path)] as const,
+          ),
+        ),
+      );
 
       const tools = manuals
-        .map((m) => ({
-          slug: m.slug,
-          name: m.name,
-          path: m.path,
-          type: m.type,
-          // Plain (non-OAuth) per-user vars render as key inputs under "Keys".
-          variables: (m.variables ?? [])
-            .filter((v) => v.scope === 'user' && !v.oauth)
-            .map((v) => {
-              const key = varKey(m.name, v.name);
-              return {
-                name: v.name,
-                label: v.label ?? null,
-                key,
-                configured: statusByKey.get(key)?.userConfigured ?? false,
-              };
-            }),
-        }))
-        // Only surface tools that actually have per-user items to configure.
+        .map((m) => {
+          const canWrite = canWriteBySlug.get(m.slug) ?? false;
+          return {
+            slug: m.slug,
+            name: m.name,
+            path: m.path,
+            type: m.type,
+            canWrite,
+            // Plain (non-OAuth) vars render as key rows under "Keys".
+            variables: (m.variables ?? [])
+              .filter((v) => !v.oauth)
+              .map((v) => {
+                const key = varKey(m.name, v.name);
+                const st = statusByKey.get(key);
+                return {
+                  name: v.name,
+                  label: v.label ?? null,
+                  key,
+                  scope: v.scope,
+                  // "Is there a value this caller's agent would resolve?" — the
+                  // workspace's for an `admin` var, the caller's own for a `user`
+                  // one. A row of the WRONG KIND does not count: this var is not
+                  // oauth, so an `oauth` row left behind by an earlier `.tool`
+                  // edit holds a token set where `resolve` wants a value, and
+                  // calling that configured hides the key nobody has set.
+                  configured:
+                    v.scope === 'admin'
+                      ? configuredAs('static', st?.adminConfigured, st?.adminKind)
+                      : configuredAs('static', st?.userConfigured, st?.userKind),
+                  ownerOnly: v.scope === 'admin' && !canWrite,
+                };
+              })
+              // A workspace value already set is outstanding for nobody. The
+              // caller's own vars stay listed once set, because this page is also
+              // where they replace one.
+              .filter((v) => v.scope !== 'admin' || !v.configured),
+          };
+        })
+        // Only surface tools that actually have something to show.
         .filter((t) => t.variables.length > 0);
 
       // OAuth-backed per-user vars render as Authorize buttons under "Sign-ins".
       // Keyed by slug+var (the caller's row may not exist yet), with authorized
       // state from the oauth-aware status.
-      const toolOAuth = manuals.flatMap((m) =>
-        (m.variables ?? [])
+      const toolOAuth = manuals.flatMap((m) => {
+        const canWrite = canWriteBySlug.get(m.slug) ?? false;
+        return (m.variables ?? [])
           .filter((v) => v.scope === 'user' && v.oauth)
           .map((v) => {
             const st = statusByKey.get(varKey(m.name, v.name));
@@ -293,6 +345,13 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
             // tool declares → surface as needing re-authorization, not as connected.
             const needsReauth =
               authorized && !scopesCovered(v.oauth?.scopes, st?.grantedScopes);
+            // On an oauth var the ADMIN row is the provider registration — the
+            // client secret — without which nobody's Authorize can work. It is a
+            // workspace value like any other, so it carries the same flag. It
+            // must be an OAUTH row: `beginToolOAuthByKey` refuses a static one,
+            // so a shared key left over from before this var was made OAuth
+            // would otherwise light up Authorize with nothing behind it.
+            const ownerConfigured = configuredAs('oauth', st?.adminConfigured, st?.adminKind);
             return {
               slug: m.slug,
               varName: v.name,
@@ -301,9 +360,11 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
               label: v.label ?? null,
               authorized,
               needsReauth,
+              ownerConfigured,
+              ownerOnly: !ownerConfigured && !canWrite,
             };
-          }),
-      );
+          });
+      });
 
       // Standalone sign-ins = oauth secrets the user registered directly on the
       // Secrets page. A TOOL sign-in provisions a per-user row in the same
@@ -318,7 +379,7 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
 
       res.json({ tools, oauth, toolOAuth });
     } catch (err) {
-      console.error('[secrets] connect/pending failed:', err);
+      log.error('connect/pending failed:', { err });
       res.status(500).json({ error: 'Internal error' });
     }
   });
@@ -574,7 +635,7 @@ export function createSecretsVaultPublicRoutes(deps: SecretsVaultRoutesDeps): ex
       await secretsVault.completeOAuth(state.u, state.i, code, redirectUriFor(deps.publicBackendUrl));
       back(`authorized=${encodeURIComponent(state.i)}`, dest);
     } catch (err) {
-      console.error('[secrets] oauth callback failed:', err instanceof Error ? err.message : String(err));
+      log.error('oauth callback failed:', { err });
       back(`error=${encodeURIComponent('Authorization failed. Check the provider configuration and try again.')}`, dest);
     }
   });
@@ -586,7 +647,7 @@ function mapError(err: unknown, res: express.Response, op: string): void {
   if (err instanceof InvalidSecretError) return void res.status(422).json({ error: err.message });
   if (err instanceof SecretNotFoundError) return void res.status(404).json({ error: err.message });
   if (err instanceof SecretOAuthError) return void res.status(409).json({ error: err.message });
-  console.error(`[secrets] ${op} failed:`, err);
+  log.error(`${op} failed:`, { err });
   res.status(500).json({ error: 'Internal error' });
 }
 

package/src/modules/settings/__tests__/connection-check.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, it } from 'vitest';
+import {
+  checkRepositoryConnection,
+  classifyReadFailure,
+  classifyWriteFailure,
+  type GitRunner,
+} from '../connection-check.js';
+
+const CONNECTION = {
+  url: 'https://github.com/acme/kb.git',
+  token: 'ghp_verysecret',
+  username: 'x-access-token',
+};
+
+/** How execFile reports a failed git: the command line, then git's stderr. */
+const gitError = (stderr: string) => new Error(`Command failed: git ...\n${stderr}`);
+
+/**
+ * A fake git: `ls-remote` answers with `listing` (or throws), the scratch
+ * `init` succeeds, and the dry-run `push` answers with `push` (or throws).
+ * Records every call so a test can see what was — and was not — asked.
+ */
+function fakeGit(opts: { listing?: string | Error; push?: string | Error }) {
+  const calls: string[][] = [];
+  const run: GitRunner = async (args) => {
+    calls.push(args);
+    const answer = args.includes('ls-remote')
+      ? (opts.listing ?? '')
+      : args.includes('push')
+        ? (opts.push ?? '')
+        : '';
+    if (answer instanceof Error) throw answer;
+    return { stdout: answer };
+  };
+  return { run, calls };
+}
+
+/**
+ * The write probe's whole premise: a host that lets git into receive-pack
+ * answers the deletion of an absent ref with "remote ref does not exist" —
+ * that is a YES — while a host refusing the push side says so at that door.
+ * Mixing the two up either refuses every working token or saves read-only ones.
+ */
+describe('classifyWriteFailure — a receive-pack refusal vs "remote ref does not exist"', () => {
+  it('reads "remote ref does not exist" as write access', () => {
+    const text =
+      "error: unable to delete 'hexis-write-check-1a2b': remote ref does not exist\n" +
+      "error: failed to push some refs to 'https://github.com/acme/kb.git'";
+    expect(classifyWriteFailure(text)).toBe('writable');
+  });
+
+  it.each([
+    [
+      'GitHub classic',
+      "remote: Permission to acme/kb.git denied to octocat.\nfatal: unable to access 'https://github.com/acme/kb.git/': The requested URL returned error: 403",
+    ],
+    [
+      'GitHub fine-grained',
+      "remote: Write access to repository not granted.\nfatal: unable to access 'https://github.com/acme/kb.git/': The requested URL returned error: 403",
+    ],
+    [
+      'GitLab',
+      "remote: You are not allowed to push code to this project.\nfatal: unable to access 'https://gitlab.com/acme/kb.git/': The requested URL returned error: 403",
+    ],
+    ['Azure DevOps', "remote: TF401027: You need the Git 'GenericContribute' permission to perform this action."],
+    ['a bare 403', "fatal: unable to access 'https://git.example.com/kb.git/': The requested URL returned error: 403"],
+  ])('reads a receive-pack refusal (%s) as read-only', (_host, text) => {
+    expect(classifyWriteFailure(text)).toBe('read-only');
+  });
+
+  /**
+   * A public repository reads anonymously, so the push is where a token is
+   * first presented — a made-up one fails THERE, and that is bad credentials,
+   * not a permission to grant.
+   */
+  it.each([
+    [
+      'GitHub invalid token',
+      "remote: Invalid username or token. Password authentication is not supported for Git operations.\nfatal: Authentication failed for 'https://github.com/Bevel-Software/Hexis.git/'",
+    ],
+    ['a bare 401', "fatal: unable to access 'https://git.example.com/kb.git/': The requested URL returned error: 401"],
+    ['no credential offered', "fatal: could not read Username for 'https://github.com': terminal prompts disabled"],
+  ])('reads an authentication failure at push (%s) as credentials, not read-only', (_case, text) => {
+    expect(classifyWriteFailure(text)).toBe('credentials');
+  });
+
+  /**
+   * The probe reads failures with the shared classifier, not a table of its
+   * own: a wording only that table names (GitHub's protected-branch refusal)
+   * is understood here without this module ever having learned it.
+   */
+  it('reads the write probe with the shared classifier — a policy refusal is read-only too', () => {
+    expect(
+      classifyWriteFailure('remote: error: GH006: Protected branch update failed for refs/heads/hexis-write-check-1a2b.'),
+    ).toBe('read-only');
+  });
+
+  it('keeps an unreachable host unreachable, not read-only', () => {
+    expect(
+      classifyWriteFailure("fatal: unable to access 'https://x/': Could not resolve host: x"),
+    ).toBe('unreachable');
+    expect(classifyWriteFailure('Error: Command failed: git push — timed out')).toBe('unreachable');
+  });
+});
+
+describe('classifyReadFailure', () => {
+  it('tells credentials, a missing repository and an unreachable host apart', () => {
+    expect(
+      classifyReadFailure("fatal: Authentication failed for 'https://github.com/acme/kb.git/'"),
+    ).toBe('credentials');
+    expect(
+      classifyReadFailure("fatal: unable to access 'https://h/': The requested URL returned error: 403"),
+    ).toBe('credentials');
+    expect(classifyReadFailure("remote: Repository not found.\nfatal: repository 'https://h/' not found")).toBe(
+      'not-found',
+    );
+    expect(classifyReadFailure("fatal: unable to access 'https://h/': Could not resolve host: h")).toBe(
+      'unreachable',
+    );
+    expect(
+      classifyReadFailure("fatal: unable to access 'https://h/': SSL certificate problem: self signed certificate"),
+    ).toBe('unreachable');
+  });
+});
+
+describe('checkRepositoryConnection', () => {
+  it('is connected when the token reads and the dry-run push gets in', async () => {
+    const git = fakeGit({
+      listing: 'ref: refs/heads/main\tHEAD\nabc\tHEAD\nabc\trefs/heads/main\ndef\trefs/heads/dev\n',
+      push: gitError("error: unable to delete 'hexis-write-check-x': remote ref does not exist"),
+    });
+    const result = await checkRepositoryConnection(CONNECTION, git.run);
+    expect(result).toEqual({ outcome: 'connected', branches: ['main', 'dev'], defaultBranch: 'main', empty: false });
+    // `--heads` would drop the HEAD symref, and with it the default branch.
+    const listing = git.calls.find((args) => args.includes('ls-remote'))!;
+    expect(listing).toContain('--symref');
+    expect(listing).not.toContain('--heads');
+    expect(listing.slice(-2)).toEqual(['HEAD', 'refs/heads/*']);
+    // The write probe is a DRY RUN deleting a scratch ref — never a real push.
+    const push = git.calls.find((args) => args.includes('push'))!;
+    expect(push).toContain('--dry-run');
+    expect(push.at(-1)).toMatch(/^:refs\/heads\/hexis-write-check-[0-9a-f]+$/);
+    expect(push).toContain(CONNECTION.url);
+  });
+
+  it('counts an empty repository as connected', async () => {
+    const git = fakeGit({ listing: '', push: gitError("error: unable to delete 'x': remote ref does not exist") });
+    expect(await checkRepositoryConnection(CONNECTION, git.run)).toMatchObject({
+      outcome: 'connected',
+      empty: true,
+      branches: [],
+    });
+  });
+
+  it('is read-only when the host refuses the push side, naming the permission to grant', async () => {
+    const git = fakeGit({
+      listing: 'abc\trefs/heads/main\n',
+      push: gitError('remote: Write access to repository not granted.\nfatal: ... error: 403'),
+    });
+    const result = await checkRepositoryConnection(CONNECTION, git.run);
+    expect(result.outcome).toBe('read-only');
+    if (result.outcome !== 'read-only') return;
+    expect(result.field).toBe('gitToken');
+    expect(result.error).toMatch(/Contents: Read and write/);
+  });
+
+  it('is rejected as bad credentials when a public repository reads but the push fails authentication', async () => {
+    const git = fakeGit({
+      // Anonymous read of a public repository: the token was never asked for.
+      listing: 'abc\trefs/heads/main\n',
+      push: gitError(
+        "remote: Invalid username or token. Password authentication is not supported for Git operations.\nfatal: Authentication failed for 'https://github.com/acme/kb.git/'",
+      ),
+    });
+    const result = await checkRepositoryConnection(CONNECTION, git.run);
+    expect(result).toMatchObject({ outcome: 'rejected', reason: 'credentials', field: 'gitToken' });
+    if (result.outcome === 'rejected') {
+      expect(result.error).toMatch(/rejected those credentials/);
+      expect(result.error).not.toMatch(/Read and write/);
+    }
+  });
+
+  it('is rejected, against the token, when the read is refused — and never tries to write', async () => {
+    const git = fakeGit({ listing: gitError("fatal: Authentication failed for 'https://github.com/acme/kb.git/'") });
+    const result = await checkRepositoryConnection(CONNECTION, git.run);
+    expect(result).toMatchObject({ outcome: 'rejected', reason: 'credentials', field: 'gitToken' });
+    expect(git.calls.some((args) => args.includes('push'))).toBe(false);
+  });
+
+  it('is rejected, against the address, when the host cannot be reached', async () => {
+    const git = fakeGit({ listing: gitError("fatal: unable to access 'https://h/': Could not resolve host: h") });
+    const result = await checkRepositoryConnection(CONNECTION, git.run);
+    expect(result).toMatchObject({ outcome: 'rejected', reason: 'unreachable', field: 'kbRepoUrl' });
+    if (result.outcome === 'rejected') expect(result.error).toMatch(/could not reach that host/i);
+  });
+
+  /** How execFile reports its own timeout: SIGTERM, and nothing about time in the message. */
+  it('is rejected as unreachable when git is killed by the timeout', async () => {
+    const killed = Object.assign(new Error('Command failed: git ls-remote\n'), {
+      killed: true,
+      signal: 'SIGTERM',
+      code: null,
+    });
+    const git = fakeGit({ listing: killed });
+    const result = await checkRepositoryConnection(CONNECTION, git.run);
+    expect(result).toMatchObject({ outcome: 'rejected', reason: 'unreachable', field: 'kbRepoUrl' });
+  });
+
+  it('rejects a URL carrying credentials against the address, in the rule’s words, without running git', async () => {
+    const git = fakeGit({ listing: '' });
+    const result = await checkRepositoryConnection(
+      { ...CONNECTION, url: 'https://u:secret@github.com/acme/kb.git' },
+      git.run,
+    );
+    expect(result).toMatchObject({ outcome: 'rejected', reason: 'invalid-address', field: 'kbRepoUrl' });
+    if (result.outcome === 'rejected') {
+      expect(result.error).toMatch(/Remove the username and token from the URL/);
+    }
+    expect(git.calls).toEqual([]);
+  });
+
+  it('never quotes the token back, even in an unrecognised failure', async () => {
+    const git = fakeGit({ listing: gitError(`something odd happened near ${CONNECTION.token}`) });
+    const result = await checkRepositoryConnection(CONNECTION, git.run);
+    expect(JSON.stringify(result)).not.toContain(CONNECTION.token);
+  });
+
+  it('keeps the token out of argv', async () => {
+    const git = fakeGit({ listing: '', push: '' });
+    await checkRepositoryConnection(CONNECTION, git.run);
+    expect(JSON.stringify(git.calls)).not.toContain(CONNECTION.token);
+  });
+});