@nimbus-dev/connectors 0.7.0 → 0.9.0

package/shared/private-kubeconfig.ts

@@ -0,0 +1,111 @@
+/**
+ * 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, join } from "node:path";
+import { configuredScratchBase } from "./private-scratch.ts";
+
+/** Names the directory private kubeconfigs are made in; an absolute path, else `os.tmpdir()`. */
+export { SCRATCH_DIR_ENV } from "./private-scratch.ts";
+
+/**
+ * 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: the configured scratch base, else
+ * `os.tmpdir()` on every platform. Unlike `withScratchDir` (private-scratch.ts) this does NOT
+ * refuse on Windows under the gateway: the before-state reads shipped in 0.8.0 run there today
+ * without the env var, and the gateway grants it with the Kubernetes write rows (D3).
+ */
+function scratchBase(): string {
+  return configuredScratchBase() ?? tmpdir();
+}
+
+/** 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 });
+  }
+}

package/shared/private-scratch.ts

@@ -0,0 +1,68 @@
+/**
+ * private-scratch — a private directory for one tool call's files, removed when the call settles.
+ *
+ * The CLI-backed write tools hand their CLI a file rather than an argument: a CloudFormation
+ * template, a Kubernetes manifest. Each call gets its own 0700 directory under the configured
+ * scratch base, so concurrent calls never share a file and nothing outlives the call.
+ *
+ * The base is `NIMBUS_CONNECTOR_SCRATCH_DIR` (absolute) when set. When it is not, `os.tmpdir()`,
+ * with one exception: a Windows connector running under the gateway REFUSES. The gateway sandboxes
+ * a Windows connector in an AppContainer and grants it a per-action directory through that env
+ * var; the user temp directory is not that grant, so a file written there is either refused by
+ * the sandbox or, worse, shared with every other process of the user. Failing closed names the
+ * missing grant instead.
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { getConnectorMode } from "./connector-mode.ts";
+
+/** Names the directory scratch directories are made in; an absolute path. */
+export const SCRATCH_DIR_ENV = "NIMBUS_CONNECTOR_SCRATCH_DIR";
+
+/**
+ * The configured scratch base, or `undefined` when none is configured. Throws on a relative
+ * value: a relative base would resolve against whatever the connector's cwd happens to be.
+ */
+export function configuredScratchBase(): string | undefined {
+  const configured = process.env[SCRATCH_DIR_ENV]?.trim();
+  if (configured === undefined || configured === "") return undefined;
+  if (!isAbsolute(configured)) {
+    throw new Error(`${SCRATCH_DIR_ENV} must be an absolute path`);
+  }
+  return configured;
+}
+
+/**
+ * The base a {@link withScratchDir} directory is made under (see the module comment for the
+ * Windows-under-the-gateway refusal). `platform` is a parameter so both sides are testable.
+ */
+export function scratchDirBase(platform: NodeJS.Platform = process.platform): string {
+  const configured = configuredScratchBase();
+  if (configured !== undefined) return configured;
+  if (platform === "win32" && getConnectorMode() === "gateway") {
+    throw new Error(
+      `${SCRATCH_DIR_ENV} is not set: on Windows the gateway must grant this connector a scratch ` +
+        "directory, and the user temp directory is not one",
+    );
+  }
+  return tmpdir();
+}
+
+/**
+ * Run `body` with a fresh 0700 directory of its own, removed when `body` settles, success or
+ * failure. `prefix` names the directory (`nimbus-cfn-`, `nimbus-k8s-`).
+ */
+export async function withScratchDir<T>(
+  prefix: string,
+  body: (dir: string) => Promise<T>,
+): Promise<T> {
+  const base = scratchDirBase();
+  const dir = await mkdtemp(join(base, prefix));
+  try {
+    return await body(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+  }
+}

package/shared/run-cli-json.ts

@@ -1,4 +1,4 @@
-import { nimbusSpawn } from "./nimbus-spawn.ts";
+import { nimbusSpawn, type SpawnResult } from "./nimbus-spawn.ts";
 
 export type RunCliJsonResult = { ok: true; data: unknown } | { ok: false; message: string };
 
@@ -75,3 +75,19 @@ export async function runCliJsonThrowing(
   }
   return r.data;
 }
+
+/**
+ * Spawn `command` and hand back its exit code with its output, for a CLI whose non-zero exits are
+ * answers rather than failures (`terraform plan -detailed-exitcode` exits 2 for "changes";
+ * `kubectl diff` exits 1 for "differences"). The caller maps every code itself, so an
+ * unexpected one is never taken for success. An empty command is code 1, as nimbusSpawn reports.
+ */
+export async function runCliCode(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): Promise<SpawnResult> {
+  if (command.length === 0) {
+    return { code: 1, stdout: "", stderr: "empty command" };
+  }
+  return nimbusSpawn(command, env);
+}