@nimbus-dev/connectors 0.7.0 → 0.8.0

package/shared/consent-kit.ts

@@ -2,8 +2,9 @@ import type { McpListResult, ZodObjectSchema } from "@nimbus-dev/sdk/connector-k
 
 import { type AuditOutcome, appendAuditEntry } from "./audit-chain.ts";
 import { getConnectorMode } from "./connector-mode.ts";
+import { isPrepareToolId } from "./prepare-tool-ids.ts";
 import { createWriteBudget, parseWriteBudget, WRITE_BUDGET_ENV } from "./write-budget.ts";
-import { parseWriteScope, scopeAllows } from "./write-scope.ts";
+import { parseWriteScope, type ScopeTerm, scopeAllows } from "./write-scope.ts";
 
 /** The subset of the SDK's `RegisteredTool` this kit needs. */
 export type ToolHandle = { disable(): void };
@@ -158,40 +159,35 @@ function registerOn<T>(
   handles.push(handle);
 }
 
+/** What both registrars share: the parsed write scope and the audit/log record. */
+type ConsentContext = {
+  readonly scope: readonly ScopeTerm[];
+  readonly record: (
+    tool: string,
+    outcome: AuditOutcome,
+    detail: Record<string, unknown>,
+  ) => Promise<void>;
+};
+
+type RegistrarConfig = {
+  readonly connector: string;
+  readonly scopeEnv: string;
+  /**
+   * Scope kinds this connector accepts. Declared once per connector rather than per tool: the
+   * allow-list is parsed at registrar construction, before any tool has registered, so a
+   * per-tool declaration would arrive too late to validate the env value.
+   */
+  readonly scopeKinds: readonly string[];
+};
+
 /**
- * Build a connector's write-tool registrar.
- *
- * In `"gateway"` mode the raw handler is registered immediately: `executor.ts` (I2) is the gate
- * there, client capabilities are irrelevant, and the connector adds nothing.
- *
- * In `"standalone"` mode registration is QUEUED and flushed on `oninitialized`, because client
- * capabilities are not knowable at module scope — verified against the real SDK, where
- * `getClientCapabilities()` returns `undefined` before `initialize`. Deciding at registration time
- * would register nothing, for every client, forever.
+ * The scope parse and the record function, built once per registrar. Extracted (not copied) so the
+ * write registrar and the prepare registrar cannot drift apart on what a scope term means or on
+ * which channels a record reaches.
  */
-export function createWriteToolRegistrar(
-  server: ConsentServer,
-  cfg: {
-    readonly connector: string;
-    readonly scopeEnv: string;
-    /**
-     * Scope kinds this connector accepts. Declared once per connector rather than per tool: the
-     * allow-list is parsed at registrar construction, before any tool has registered, so a
-     * per-tool declaration would arrive too late to validate the env value.
-     */
-    readonly scopeKinds: readonly string[];
-  },
-): WriteToolRegistrar {
-  const handles: ToolHandle[] = [];
-  const pending: Array<() => void> = [];
-  let flushed = false;
-
+function createConsentContext(server: ConsentServer, cfg: RegistrarConfig): ConsentContext {
   const scope = parseWriteScope(process.env[cfg.scopeEnv], cfg.scopeKinds);
   const auditLog = process.env["NIMBUS_MCP_AUDIT_LOG"];
-  // Throws on a value that is not plain digits, an empty one included, as the scope parse above
-  // does on a malformed term: read with `Number()`, `abc` became NaN, which `remaining <= 0` never
-  // refused.
-  const budget = createWriteBudget(parseWriteBudget(process.env[WRITE_BUDGET_ENV]));
 
   async function record(
     tool: string,
@@ -227,6 +223,34 @@ export function createWriteToolRegistrar(
     }
   }
 
+  return { scope, record };
+}
+
+/**
+ * Build a connector's write-tool registrar.
+ *
+ * In `"gateway"` mode the raw handler is registered immediately: `executor.ts` (I2) is the gate
+ * there, client capabilities are irrelevant, and the connector adds nothing.
+ *
+ * In `"standalone"` mode registration is QUEUED and flushed on `oninitialized`, because client
+ * capabilities are not knowable at module scope — verified against the real SDK, where
+ * `getClientCapabilities()` returns `undefined` before `initialize`. Deciding at registration time
+ * would register nothing, for every client, forever.
+ */
+export function createWriteToolRegistrar(
+  server: ConsentServer,
+  cfg: RegistrarConfig,
+): WriteToolRegistrar {
+  const handles: ToolHandle[] = [];
+  const pending: Array<() => void> = [];
+  let flushed = false;
+
+  const { scope, record } = createConsentContext(server, cfg);
+  // Throws on a value that is not plain digits, an empty one included, as the scope parse above
+  // does on a malformed term: read with `Number()`, `abc` became NaN, which `remaining <= 0` never
+  // refused.
+  const budget = createWriteBudget(parseWriteBudget(process.env[WRITE_BUDGET_ENV]));
+
   /**
    * Take one unit of budget if any is left. Spending the last unit disables every write tool and
    * tells the client.
@@ -398,3 +422,89 @@ export function createWriteToolRegistrar(
     });
   };
 }
+
+/** What a prepare tool declares: only the scope target, since it mutates nothing. */
+export type PrepareToolConfig<T> = {
+  /** The scope target this invocation reads on behalf of, checked against the allow-list. */
+  readonly scopeTargetOf: (args: T) => { kind: string; value: string };
+};
+
+export type PrepareToolRegistrar = <T>(
+  name: string,
+  cfg: PrepareToolConfig<T>,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  handler: (args: T) => Promise<McpListResult>,
+) => void;
+
+/**
+ * Build a connector's prepare-tool registrar.
+ *
+ * A prepare tool reads the state a write is bound to (the head a commit is prepared against) and is
+ * called by the gateway BEFORE the write's approval prompt. It is not a write: it is registered
+ * under its own registrar so the gateway's manifest scan, which follows the write registrar's data
+ * flow, does not list it as one. And it is not an ordinary read either: a tool is accepted only when
+ * its name is in {@link PREPARE_TOOL_IDS} (shared/prepare-tool-ids.ts), so the class is one literal
+ * list and not a naming convention.
+ *
+ * In `"gateway"` mode the raw handler is registered: the executor's prepare step is the gate there.
+ * In `"standalone"` mode it is registered at once for EVERY client (a prepare tool prompts no one,
+ * so no elicitation capability is needed), behind the same write scope as the writes it serves, and
+ * each in-scope run is audited as `prepared`. It spends no write budget and is never disabled by
+ * the budget running out: a second prompt before the apply prompt would only train click-through.
+ */
+export function createPrepareToolRegistrar(
+  server: ConsentServer,
+  cfg: RegistrarConfig,
+): PrepareToolRegistrar {
+  const { scope, record } = createConsentContext(server, cfg);
+  // Prepare tools are not budget-gated, so nothing ever disables them; the handles are not kept.
+  const handles: ToolHandle[] = [];
+
+  return <T>(
+    name: string,
+    toolCfg: PrepareToolConfig<T>,
+    description: string,
+    schema: ZodObjectSchema<T>,
+    handler: (args: T) => Promise<McpListResult>,
+  ): void => {
+    if (!isPrepareToolId(name)) {
+      throw new Error(
+        `${name}: not a listed prepare tool — add the id to PREPARE_TOOL_IDS in ` +
+          "shared/prepare-tool-ids.ts, or register it as a read or a write",
+      );
+    }
+
+    if (getConnectorMode() === "gateway") {
+      registerOn(server, name, description, schema, handler, handles);
+      return;
+    }
+
+    const guarded = async (args: T): Promise<McpListResult> => {
+      const target = toolCfg.scopeTargetOf(args);
+      if (!scopeAllows(scope, target.kind, target.value)) {
+        await record(name, "refused", { reason: "out of scope", target });
+        return refused(`out of scope: ${target.kind}:${target.value} is not in ${cfg.scopeEnv}`);
+      }
+      let result: McpListResult;
+      try {
+        result = await handler(args);
+      } catch (e) {
+        // As a write does: record the failure, and if recording it fails too, the tool's own error
+        // still leads, since an audit error alone would read as a prepare that never started.
+        try {
+          await record(name, "failed", { target, error: messageOf(e) });
+        } catch (error_) {
+          throw new Error(
+            `${name} failed: ${messageOf(e)}. Recording that failure also failed: ${messageOf(error_)}`,
+            { cause: e },
+          );
+        }
+        throw e;
+      }
+      await record(name, "prepared", { target });
+      return result;
+    };
+    registerOn(server, name, description, schema, guarded, handles);
+  };
+}

package/shared/github-files.ts

@@ -0,0 +1,195 @@
+/**
+ * github-files: read files at a commit through the Git Data API, for the batch read
+ * (`github_files_get`), the prepare tool (`github_commit_prepare`) and the commit
+ * (`github_file_commit`), so what the owner was shown and what is committed come from one reader.
+ *
+ * Sources (https://docs.github.com/en/rest/git/{commits,trees,blobs,refs}):
+ * - `GET /git/commits/{sha}` returns `tree.sha`.
+ * - `GET /git/trees/{sha}` (non-recursive) lists `path, mode, type, sha, size`, with a top-level
+ *   `truncated` and the advice to "fetch subtrees one at a time": a path is walked one level at a
+ *   time, and a truncated level is an error, never a guess that the file is absent.
+ * - `GET /git/blobs/{sha}` returns base64 `content`.
+ * - `PATCH /git/refs/heads/{branch}` with `force` false must be a fast-forward; the documented
+ *   statuses are 200, 409 and 422.
+ */
+
+import { decodeBase64Text } from "./commit-files.ts";
+import { ghFetch, ghRepoPath } from "./github-rest.ts";
+
+type TreeEntry = { path: string; mode: string; type: string; sha: string; size?: number };
+
+export type GithubFileRead =
+  | { readonly path: string; readonly exists: false }
+  | {
+      readonly path: string;
+      readonly exists: true;
+      readonly kind: "text";
+      readonly mode: string;
+      readonly sha: string;
+      readonly size: number;
+      /** Present only when content was asked for. */
+      readonly content?: string;
+    }
+  | {
+      readonly path: string;
+      readonly exists: true;
+      readonly kind: "binary" | "not-regular" | "too-large" | "budget";
+      readonly mode: string;
+      readonly sha: string;
+      readonly size?: number;
+    };
+
+function fail(res: { status: number; text: string }): never {
+  throw new Error(`GitHub ${String(res.status)}: ${res.text.slice(0, 300)}`);
+}
+
+async function getJson(token: string, path: string): Promise<unknown> {
+  const res = await ghFetch(token, path);
+  if (!res.ok) fail(res);
+  return res.json;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** `tree.sha` of a commit. */
+export async function commitTreeSha(
+  token: string,
+  owner: string,
+  repo: string,
+  commitSha: string,
+): Promise<string> {
+  const json = await getJson(token, `${ghRepoPath(owner, repo)}/git/commits/${commitSha}`);
+  const tree = isRecord(json) && isRecord(json["tree"]) ? json["tree"]["sha"] : undefined;
+  if (typeof tree !== "string") throw new Error("GitHub returned no tree for the commit");
+  return tree;
+}
+
+function parseTree(json: unknown): TreeEntry[] {
+  if (!isRecord(json)) throw new Error("GitHub returned no tree");
+  if (json["truncated"] === true) {
+    throw new Error("GitHub truncated a directory listing; refusing to guess a file is absent");
+  }
+  const entries = Array.isArray(json["tree"]) ? json["tree"] : [];
+  const out: TreeEntry[] = [];
+  for (const e of entries) {
+    if (
+      isRecord(e) &&
+      typeof e["path"] === "string" &&
+      typeof e["mode"] === "string" &&
+      typeof e["type"] === "string" &&
+      typeof e["sha"] === "string"
+    ) {
+      out.push({
+        path: e["path"],
+        mode: e["mode"],
+        type: e["type"],
+        sha: e["sha"],
+        ...(typeof e["size"] === "number" ? { size: e["size"] } : {}),
+      });
+    }
+  }
+  return out;
+}
+
+/** The tree entry for `path` under `rootTreeSha`, one directory level at a time; undefined if absent. */
+async function findEntry(
+  token: string,
+  owner: string,
+  repo: string,
+  rootTreeSha: string,
+  path: string,
+  cache: Map<string, TreeEntry[]>,
+): Promise<TreeEntry | undefined> {
+  const segments = path.split("/");
+  let treeSha = rootTreeSha;
+  for (const [i, segment] of segments.entries()) {
+    let entries = cache.get(treeSha);
+    if (entries === undefined) {
+      entries = parseTree(await getJson(token, `${ghRepoPath(owner, repo)}/git/trees/${treeSha}`));
+      cache.set(treeSha, entries);
+    }
+    const entry = entries.find((e) => e.path === segment);
+    if (entry === undefined) return undefined;
+    if (i === segments.length - 1) return entry;
+    if (entry.type !== "tree") {
+      // A file sits where a directory is needed: the path cannot exist, and a commit cannot create it.
+      throw new Error(`${path}: ${segments.slice(0, i + 1).join("/")} is a file, not a directory`);
+    }
+    treeSha = entry.sha;
+  }
+  return undefined;
+}
+
+/**
+ * Read `paths` at `commitSha`, returning the commit's root tree sha beside the files. With `withContent`, each text file's content is fetched (a file over
+ * `maxReadBytes` is reported `too-large` without fetching it); without, only the tree entry is read,
+ * which is enough for a mode, a blob sha and a size.
+ *
+ * `totalBudget` caps the content of ALL the files together. The first file that does not fit in what
+ * is left, and every file after it, is reported `budget` with its metadata and no content, and its
+ * blob is not fetched; the read as a whole is not refused.
+ */
+export async function readGithubFilesAt(
+  token: string,
+  owner: string,
+  repo: string,
+  commitSha: string,
+  paths: readonly string[],
+  opts: {
+    readonly withContent: boolean;
+    readonly maxReadBytes: number;
+    readonly totalBudget?: number;
+  },
+): Promise<{ readonly treeSha: string; readonly files: GithubFileRead[] }> {
+  const rootTree = await commitTreeSha(token, owner, repo, commitSha);
+  const cache = new Map<string, TreeEntry[]>();
+  const out: GithubFileRead[] = [];
+  let used = 0;
+  let exhausted = false;
+  for (const path of paths) {
+    const entry = await findEntry(token, owner, repo, rootTree, path, cache); // NOSONAR S9382: sequential on purpose; the tree cache makes later paths cheap.
+    if (entry === undefined) {
+      out.push({ path, exists: false });
+      continue;
+    }
+    if (entry.type !== "blob" || entry.mode === "120000") {
+      out.push({ path, exists: true, kind: "not-regular", mode: entry.mode, sha: entry.sha });
+      continue;
+    }
+    const size = entry.size ?? 0;
+    if (size > opts.maxReadBytes) {
+      out.push({ path, exists: true, kind: "too-large", mode: entry.mode, sha: entry.sha, size });
+      continue;
+    }
+    if (!opts.withContent) {
+      out.push({ path, exists: true, kind: "text", mode: entry.mode, sha: entry.sha, size });
+      continue;
+    }
+    if (opts.totalBudget !== undefined && (exhausted || used + size > opts.totalBudget)) {
+      exhausted = true;
+      out.push({ path, exists: true, kind: "budget", mode: entry.mode, sha: entry.sha, size });
+      continue;
+    }
+    used += size;
+    const blob = await getJson(token, `${ghRepoPath(owner, repo)}/git/blobs/${entry.sha}`); // NOSONAR S9382
+    const b64 = isRecord(blob) && blob["encoding"] === "base64" ? blob["content"] : undefined;
+    if (typeof b64 !== "string") throw new Error(`GitHub returned no base64 content for ${path}`);
+    const decoded = decodeBase64Text(b64);
+    out.push(
+      "binary" in decoded
+        ? { path, exists: true, kind: "binary", mode: entry.mode, sha: entry.sha, size }
+        : {
+            path,
+            exists: true,
+            kind: "text",
+            mode: entry.mode,
+            sha: entry.sha,
+            size,
+            content: decoded.text,
+          },
+    );
+  }
+  return { treeSha: rootTree, files: out };
+}

package/shared/github-rest.ts

@@ -172,6 +172,18 @@ function refCandidates(ref: string): { readonly name: string; readonly kind: "br
   ];
 }
 
+/**
+ * The names to ask `GET /commits/<name>` for, in order, for a user-supplied `ref`. A full sha is one
+ * name; a 7 to 39 hex string is tried as an abbreviated sha first and then as a branch and a tag;
+ * anything else is the `heads/` / `tags/` forms of {@link refCandidates}. `ref` must already
+ * satisfy {@link isSafeGitRef}.
+ */
+export function commitRefCandidates(ref: string): string[] {
+  if (FULL_SHA.test(ref)) return [ref];
+  const named = refCandidates(ref).map((c) => c.name);
+  return /^[0-9a-f]{7,39}$/i.test(ref) ? [ref, ...named] : named;
+}
+
 /**
  * Resolve a branch, tag or commit to a COMMIT sha. `ref` must already satisfy {@link isSafeGitRef}.
  *

package/shared/k8s-deployment-view.ts

@@ -0,0 +1,68 @@
+/**
+ * k8s-deployment-view: the one projection of `kubectl get deployment -o json` that the
+ * `kubernetes` and `gcp` before-state reads share, so a rollout restart or a scale is previewed
+ * from the same fields whichever connector runs it.
+ *
+ * Field sources: apps/v1 Deployment (https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/).
+ * `status.readyReplicas` is omitted by the API server when zero (the Go field is `omitempty`), so an
+ * absent value is reported as 0; `spec.replicas` is reported as given and is absent when the server
+ * did not return one. The restart time is the annotation `kubectl rollout restart` sets.
+ */
+
+export type DeploymentView = {
+  readonly name: string;
+  readonly namespace: string;
+  readonly replicas?: number;
+  readonly readyReplicas: number;
+  readonly generation?: number;
+  readonly observedGeneration?: number;
+  readonly restartedAt?: string;
+  readonly images: readonly string[];
+};
+
+const RESTARTED_AT = "kubectl.kubernetes.io/restartedAt";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function num(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+/** Project a Deployment object; throws when `raw` is not one (no name). */
+export function projectDeployment(raw: unknown): DeploymentView {
+  if (!isRecord(raw)) throw new Error("deployment not found");
+  const meta = isRecord(raw["metadata"]) ? raw["metadata"] : {};
+  const spec = isRecord(raw["spec"]) ? raw["spec"] : {};
+  const status = isRecord(raw["status"]) ? raw["status"] : {};
+  const name = meta["name"];
+  if (typeof name !== "string" || name === "") throw new Error("deployment not found");
+  const template = isRecord(spec["template"]) ? spec["template"] : {};
+  const tmeta = isRecord(template["metadata"]) ? template["metadata"] : {};
+  const annotations = isRecord(tmeta["annotations"]) ? tmeta["annotations"] : {};
+  const podSpec = isRecord(template["spec"]) ? template["spec"] : {};
+  const containers = Array.isArray(podSpec["containers"]) ? podSpec["containers"] : [];
+  const images = containers
+    .map((c) => (isRecord(c) && typeof c["image"] === "string" ? c["image"] : undefined))
+    .filter((i): i is string => i !== undefined);
+  const replicas = num(spec["replicas"]);
+  const generation = num(meta["generation"]);
+  const observedGeneration = num(status["observedGeneration"]);
+  const restartedAt = annotations[RESTARTED_AT];
+  return {
+    name,
+    namespace: typeof meta["namespace"] === "string" ? meta["namespace"] : "",
+    ...(replicas === undefined ? {} : { replicas }),
+    readyReplicas: num(status["readyReplicas"]) ?? 0,
+    ...(generation === undefined ? {} : { generation }),
+    ...(observedGeneration === undefined ? {} : { observedGeneration }),
+    ...(typeof restartedAt === "string" ? { restartedAt } : {}),
+    images,
+  };
+}
+
+/** Whether a kubectl failure message says the object does not exist. */
+export function isKubectlNotFound(message: string): boolean {
+  return /NotFound|not found/i.test(message);
+}

package/shared/prepare-tool-ids.ts

@@ -0,0 +1,21 @@
+/**
+ * The prepare class: tools the gateway calls BEFORE a write's approval prompt to read the state the
+ * write is bound to (the branch head a commit was prepared against).
+ *
+ * This is ONE literal list on purpose. The gateway reads it as text, the way it scans the write
+ * manifest, and `createPrepareToolRegistrar` (consent-kit.ts) registers a tool only when its name
+ * is here. A naming convention would not do: a suffix rule passes `*_files_get`-style names that
+ * the gateway treats as plain reads, and ids of the same class do not share a suffix.
+ *
+ * Grows per release: this one lists the two commit tools; the IaC, CloudFormation and Kubernetes
+ * ones are added by the PR that registers them. `prepare-tool-ids.test.ts` requires every id here
+ * to be registered exactly once, through `createPrepareToolRegistrar` and nothing else.
+ */
+export const PREPARE_TOOL_IDS = ["github_commit_prepare", "gitlab_commit_prepare"] as const;
+
+export type PrepareToolId = (typeof PREPARE_TOOL_IDS)[number];
+
+/** Whether `name` is a listed prepare tool id. */
+export function isPrepareToolId(name: string): name is PrepareToolId {
+  return (PREPARE_TOOL_IDS as readonly string[]).includes(name);
+}

package/shared/private-kubeconfig.ts

@@ -0,0 +1,110 @@
+/**
+ * private-kubeconfig — one kubeconfig file per tool call, never the owner's own.
+ *
+ * `kubectl` and `gcloud container clusters get-credentials` both read AND write a kubeconfig:
+ * gcloud writes `$HOME/.kube/config` unless `KUBECONFIG` is set (first path if it is a list), and
+ * kubectl takes the file `KUBECONFIG` names, or merges a list of them. Handed the owner's real
+ * file, a tool call could change it, and two concurrent calls would share and race on it. So each
+ * call works on a private copy in its own 0700 directory, removed afterwards, success or failure.
+ *
+ * Sources: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/
+ * (`--kubeconfig` set: only that file; else `KUBECONFIG` is a list, `:` on Linux and macOS, `;` on
+ * Windows) and https://docs.cloud.google.com/sdk/gcloud/reference/container/clusters/get-credentials
+ * (writes `HOME/.kube/config` unless `KUBECONFIG` is set).
+ *
+ * The copy is a plain file copy, not `kubectl config view --flatten`. One consequence is stated in
+ * the connector READMEs: a kubeconfig whose certificate paths are RELATIVE resolves them against the
+ * file's own directory, so a copy of such a file does not find them. Use absolute paths or
+ * embedded certificate data.
+ */
+
+import { constants } from "node:fs";
+import { lstat, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { delimiter, isAbsolute, join } from "node:path";
+
+/** Names the directory private kubeconfigs are made in; an absolute path, else `os.tmpdir()`. */
+export const SCRATCH_DIR_ENV = "NIMBUS_CONNECTOR_SCRATCH_DIR";
+
+/**
+ * The one path `raw` (a `KUBECONFIG` value) names. A list of paths throws: a tool that cannot say
+ * which file it works on cannot copy it. `separator` is the platform's `path.delimiter`, so a
+ * Windows drive path (`C:\Users\me\config`, whose `:` is not a separator there) is one path, and
+ * a `;` list is refused there; elsewhere a `:` list is.
+ */
+export function singleKubeconfigPath(
+  raw: string | undefined,
+  separator: string = delimiter,
+): string {
+  const p = raw?.trim();
+  if (p === undefined || p === "") {
+    throw new Error("KUBECONFIG env must be set to a kubeconfig file path");
+  }
+  const pieces = p
+    .split(separator)
+    .map((piece) => piece.trim())
+    .filter((piece) => piece !== "");
+  if (pieces.length > 1) {
+    throw new Error(
+      `KUBECONFIG names more than one file (separator "${separator}"); set it to ONE kubeconfig path`,
+    );
+  }
+  // A value that is only separators names no file at all.
+  const only = pieces[0];
+  if (only === undefined) throw new Error("KUBECONFIG env must be set to a kubeconfig file path");
+  // The one piece that remains, not the raw value: `/a/config:` names `/a/config`, and the copy is
+  // made from that path, never from a string with a separator in it.
+  return only;
+}
+
+/** The base directory private kubeconfigs are made under. */
+function scratchBase(): string {
+  const configured = process.env[SCRATCH_DIR_ENV]?.trim();
+  if (configured === undefined || configured === "") return tmpdir();
+  if (!isAbsolute(configured)) {
+    throw new Error(`${SCRATCH_DIR_ENV} must be an absolute path`);
+  }
+  return configured;
+}
+
+/** Refuse a source that is not a plain file: a symlink, a directory, a device. */
+async function assertRegularFile(path: string): Promise<void> {
+  const st = await lstat(path).catch(() => undefined);
+  if (st === undefined) throw new Error("KUBECONFIG names a file that does not exist");
+  if (st.isSymbolicLink() || !st.isFile()) {
+    throw new Error("KUBECONFIG must name a regular file (not a symlink or a directory)");
+  }
+}
+
+/**
+ * Run `body` with a private kubeconfig.
+ *
+ * With `source` (a `KUBECONFIG` value, ONE path): the file is copied, mode 0600, and `body` gets
+ * `{ KUBECONFIG: <copy> }`. Without it, the copy starts EMPTY, for `get-credentials` to fill.
+ * The directory is removed when `body` settles.
+ */
+export async function withPrivateKubeconfig<T>(
+  opts: { readonly source?: string | undefined },
+  body: (env: { readonly KUBECONFIG: string }) => Promise<T>,
+): Promise<T> {
+  // Everything that can refuse does so BEFORE a directory exists.
+  let content: Buffer | undefined;
+  if (opts.source !== undefined) {
+    const sourcePath = singleKubeconfigPath(opts.source);
+    await assertRegularFile(sourcePath);
+    content = await readFile(sourcePath);
+  }
+  const base = scratchBase();
+  const dir = await mkdtemp(join(base, "nimbus-kubeconfig-"));
+  try {
+    const file = join(dir, "config");
+    // `wx`: the file is new by construction, and an existing one is an error, not a reuse.
+    await writeFile(file, content ?? "", {
+      mode: 0o600,
+      flag: constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY,
+    });
+    return await body({ KUBECONFIG: file });
+  } finally {
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+  }
+}