@intentius/chant-k8s-client 0.31.0

package/src/credentials.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Credential policy (chant #1074's managed-cluster half).
+ *
+ * The exec-plugin caching case runs a real subprocess — a two-line node script
+ * that prints an `ExecCredential` and appends a line to a temp file so the test
+ * can count invocations. It talks to no cluster and reads no ambient
+ * kubeconfig; the API server is still the injected request layer.
+ */
+
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  assertExecCredentialAllowed,
+  credentialPathOf,
+  DEFAULT_EXEC_ALLOWLIST,
+  execCommandName,
+  execConfigOf,
+} from "./credentials";
+import { ExecCredentialNotAllowedError } from "./errors";
+import { createK8sClient } from "./client";
+import { apiResourceList, fakeKubeconfig, fakeRequestLayer, statusBody } from "./testing";
+
+describe("exec credential allowlist", () => {
+  test("a bare command, an absolute path and a Windows executable all reduce to the same name", () => {
+    expect(execCommandName("aws")).toBe("aws");
+    expect(execCommandName("/usr/local/bin/aws")).toBe("aws");
+    expect(execCommandName("C:\\Program Files\\Amazon\\AWSCLIV2\\aws.exe")).toBe("aws");
+  });
+
+  test("the managed-cluster plugins pass; anything else is refused by name", () => {
+    for (const command of ["aws", "/opt/homebrew/bin/gke-gcloud-auth-plugin", "kubelogin"]) {
+      expect(() => assertExecCredentialAllowed({ name: "u", exec: { command } })).not.toThrow();
+    }
+    expect(() => assertExecCredentialAllowed({ name: "u", exec: { command: "curl" } })).toThrow(
+      ExecCredentialNotAllowedError,
+    );
+  });
+
+  test("the refusal names the command and how to allow it", () => {
+    const err = (() => {
+      try {
+        assertExecCredentialAllowed({ name: "u", exec: { command: "harvest" } });
+      } catch (e) {
+        return e as Error;
+      }
+    })()!;
+    expect(err.message).toContain('"harvest"');
+    expect(err.message).toContain("k8s.execCredentialPlugins");
+  });
+
+  test("an exec stanza hidden under authProvider is gated too", () => {
+    const user = { name: "u", authProvider: { name: "exec", config: { exec: { command: "harvest" } } } };
+    expect(execConfigOf(user)?.command).toBe("harvest");
+    expect(() => assertExecCredentialAllowed(user)).toThrow(ExecCredentialNotAllowedError);
+  });
+
+  test("a user with no exec plugin is never gated", () => {
+    expect(() => assertExecCredentialAllowed({ name: "u", token: "t" })).not.toThrow();
+    expect(() => assertExecCredentialAllowed(undefined)).not.toThrow();
+  });
+
+  test("an explicit allowlist replaces the default", () => {
+    expect(() => assertExecCredentialAllowed({ name: "u", exec: { command: "aws" } }, ["kubelogin"])).toThrow();
+    expect(() => assertExecCredentialAllowed({ name: "u", exec: { command: "custom" } }, ["custom"])).not.toThrow();
+  });
+
+  test("the default allowlist covers EKS, AKS and GKE", () => {
+    expect(DEFAULT_EXEC_ALLOWLIST).toContain("aws");
+    expect(DEFAULT_EXEC_ALLOWLIST).toContain("kubelogin");
+    expect(DEFAULT_EXEC_ALLOWLIST).toContain("gke-gcloud-auth-plugin");
+  });
+});
+
+describe("credential provenance", () => {
+  test.each([
+    [{ name: "u", exec: { command: "aws" } }, "exec-plugin"],
+    [{ name: "u", authProvider: { name: "oidc" } }, "auth-provider"],
+    [{ name: "u", token: "t" }, "token"],
+    [{ name: "u", certData: "c" }, "client-certificate"],
+    [{ name: "u", username: "admin", password: "p" }, "basic-auth"],
+    [{ name: "u" }, "none"],
+  ])("%o is %s", (user, expected) => {
+    expect(credentialPathOf(user).credential).toBe(expected);
+  });
+});
+
+describe("exec credential caching", () => {
+  test("one plugin invocation serves an entire multi-entity observation", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-execauth-"));
+    const counterFile = join(dir, "invocations.log");
+    const scriptFile = join(dir, "plugin.mjs");
+    writeFileSync(
+      scriptFile,
+      [
+        `import { appendFileSync } from "node:fs";`,
+        `appendFileSync(${JSON.stringify(counterFile)}, "x\\n");`,
+        `process.stdout.write(JSON.stringify({`,
+        `  apiVersion: "client.authentication.k8s.io/v1",`,
+        `  kind: "ExecCredential",`,
+        `  status: { token: "exec-issued-token", expirationTimestamp: "2099-01-01T00:00:00Z" },`,
+        `}));`,
+      ].join("\n"),
+    );
+
+    const deployments = apiResourceList("apps/v1", [{ name: "deployments", kind: "Deployment" }]);
+    const layer = fakeRequestLayer((req) => {
+      if (req.path === "/apis/apps/v1") return { body: deployments };
+      if (req.path.startsWith("/apis/apps/v1/namespaces/prod/deployments/")) {
+        return { body: { apiVersion: "apps/v1", kind: "Deployment", metadata: { name: "x", uid: "u" } } };
+      }
+      return { status: 404, body: statusBody(404, "NotFound", "no") };
+    });
+
+    const client = await createK8sClient({
+      // The "plugin" is this node binary running the script above — a real
+      // subprocess on the real ExecAuth path, with nothing to install.
+      kubeconfig: fakeKubeconfig({ exec: { command: process.execPath, args: [scriptFile] } }),
+      execAllowlist: [process.execPath],
+      requestLayer: layer,
+    });
+
+    await client.concurrently(
+      Array.from({ length: 20 }, (_, i) => i),
+      (i) => client.read({ apiVersion: "apps/v1", kind: "Deployment", name: `web-${i}`, namespace: "prod" }),
+    );
+
+    const invocations = existsSync(counterFile) ? readFileSync(counterFile, "utf8").trim().split("\n").length : 0;
+    rmSync(dir, { recursive: true, force: true });
+
+    // 21 requests (discovery + 20 reads) authorized by one plugin run.
+    expect(layer.requests.length).toBe(21);
+    expect(invocations).toBe(1);
+    for (const req of layer.requests) {
+      expect(req.headers.Authorization).toBe("Bearer exec-issued-token");
+    }
+  }, 30_000);
+});

package/src/credentials.ts

@@ -0,0 +1,117 @@
+/**
+ * Credential policy — chant #1074's managed-cluster half.
+ *
+ * On EKS, AKS and GKE, kubeconfig authentication is an **exec credential
+ * plugin**: `aws eks get-token`, `kubelogin`, `gke-gcloud-auth-plugin`. So on
+ * the clusters most people actually run, a "native" client still spawns a
+ * process — once per token instead of once per resource read. That is still
+ * the win the issue is after, but it is worth stating rather than implying,
+ * because an exec plugin runs an arbitrary binary named in a file chant did
+ * not write.
+ *
+ * Three things are chant's to decide, and they live here:
+ *
+ * 1. **Allowlist.** The plugin's command must be on a list, not merely present
+ *    in the kubeconfig. The default covers the three managed providers.
+ * 2. **Caching.** `@kubernetes/client-node`'s `ExecAuth` caches a credential
+ *    until its `expirationTimestamp`, keyed by kubeconfig user. The client
+ *    builds one `KubeConfig` per session and reuses it for every request, so a
+ *    200-entity observation invokes `aws eks get-token` once rather than 200
+ *    times. That is a property of not rebuilding the config, so it is asserted
+ *    in this package's tests rather than reimplemented here.
+ * 3. **Provenance.** Which credential path authorized a read is recorded on
+ *    the client and travels with the observation.
+ */
+
+import { ExecCredentialNotAllowedError } from "./errors";
+import type { CredentialPath } from "./types";
+
+/**
+ * Exec credential plugins chant will execute without being asked twice.
+ *
+ * The three managed-Kubernetes providers plus `kubectl`, which is what
+ * `kubectl config set-credentials --exec-command` writes for OIDC setups that
+ * shell back through the binary the user already trusts. Anything else has to
+ * be named explicitly in `k8s.execCredentialPlugins`.
+ */
+export const DEFAULT_EXEC_ALLOWLIST: readonly string[] = [
+  "aws", // EKS — `aws eks get-token`
+  "aws-iam-authenticator", // EKS, pre-`aws eks get-token`
+  "gke-gcloud-auth-plugin", // GKE
+  "kubelogin", // AKS
+  "kubectl", // OIDC via `kubectl oidc-login`, and k3d/kind setups
+];
+
+/** The exec stanza of a kubeconfig user, as far as this module cares. */
+export interface ExecConfig {
+  command?: string;
+  args?: string[];
+  env?: Array<{ name: string; value: string }>;
+}
+
+/** The kubeconfig user fields this module reads. */
+export interface KubeConfigUser {
+  name?: string;
+  exec?: ExecConfig;
+  authProvider?: { name?: string; config?: { exec?: ExecConfig } };
+  token?: string;
+  certData?: string;
+  certFile?: string;
+  username?: string;
+  password?: string;
+}
+
+/**
+ * The exec stanza this user authenticates with, if any. `authProvider` can
+ * carry one too — client-node's `ExecAuth.isAuthProvider` accepts both shapes,
+ * so the gate has to look in both places or it is trivially bypassed.
+ */
+export function execConfigOf(user: KubeConfigUser | null | undefined): ExecConfig | undefined {
+  if (!user) return undefined;
+  if (user.exec) return user.exec;
+  const providerExec = user.authProvider?.config?.exec;
+  if (providerExec) return providerExec;
+  return undefined;
+}
+
+/**
+ * Reduce a plugin command to the name that is allowlisted: `aws` for `aws`,
+ * for `/usr/local/bin/aws`, and for `C:\\tools\\aws.exe`. Matching the bare
+ * name rather than the full path is deliberate — the path varies per machine,
+ * and pinning it would make the allowlist unusable — but it does mean the
+ * allowlist expresses "which tool", not "which file".
+ */
+export function execCommandName(command: string): string {
+  const base = command.split(/[\\/]/).pop() ?? command;
+  return base.replace(/\.(exe|cmd|bat)$/i, "");
+}
+
+/**
+ * Throw unless the user's exec plugin (if it has one) is allowlisted. Called
+ * before the client issues its first request, so a refusal happens before any
+ * binary runs — the check is worthless if it fires after the spawn.
+ */
+export function assertExecCredentialAllowed(
+  user: KubeConfigUser | null | undefined,
+  allowlist: readonly string[] = DEFAULT_EXEC_ALLOWLIST,
+): void {
+  const exec = execConfigOf(user);
+  if (!exec?.command) return;
+  const name = execCommandName(exec.command);
+  if (allowlist.some((entry) => execCommandName(entry) === name)) return;
+  throw new ExecCredentialNotAllowedError(exec.command, allowlist);
+}
+
+/** Which credential path a kubeconfig user represents, for provenance. */
+export function credentialPathOf(user: KubeConfigUser | null | undefined): {
+  credential: CredentialPath;
+  execCommand?: string;
+} {
+  const exec = execConfigOf(user);
+  if (exec?.command) return { credential: "exec-plugin", execCommand: exec.command };
+  if (user?.authProvider?.name) return { credential: "auth-provider" };
+  if (user?.token) return { credential: "token" };
+  if (user?.certData || user?.certFile) return { credential: "client-certificate" };
+  if (user?.username) return { credential: "basic-auth" };
+  return { credential: "none" };
+}

package/src/errors.ts

@@ -0,0 +1,168 @@
+/**
+ * Typed failures — chant #1074.
+ *
+ * The kubectl path this client replaces reported failures as a non-zero exit
+ * plus a line of English on stderr, which every caller then had to pattern
+ * match (`classifyKubectlFailure` in core is that pattern matcher). The API
+ * server already sends a machine-readable `Status` object with a numeric code
+ * and a `reason` enum; these errors carry it through instead of re-deriving it
+ * from prose.
+ */
+
+/** The `Status` object a Kubernetes API server returns on a failed request. */
+export interface K8sStatus {
+  kind?: string;
+  apiVersion?: string;
+  status?: string;
+  message?: string;
+  /** e.g. "NotFound", "Forbidden", "Unauthorized", "Conflict", "AlreadyExists". */
+  reason?: string;
+  code?: number;
+  details?: unknown;
+}
+
+/**
+ * The API server answered, and the answer was a failure. `statusCode` and
+ * `reason` come from the response, not from parsing text.
+ */
+export class K8sApiError extends Error {
+  constructor(
+    public readonly statusCode: number,
+    public readonly reason: string | undefined,
+    public readonly apiMessage: string,
+    /** What was being addressed, e.g. `apps/v1 Deployment prod/web`. */
+    public readonly target?: string,
+    public readonly status?: K8sStatus,
+  ) {
+    super(
+      `${target ? `${target}: ` : ""}${apiMessage || "request failed"} ` +
+        `(HTTP ${statusCode}${reason ? `, ${reason}` : ""})`,
+    );
+    this.name = "K8sApiError";
+  }
+
+  /** The object is not there. The only failure that establishes absence. */
+  get notFound(): boolean {
+    return this.statusCode === 404 || this.reason === "NotFound";
+  }
+
+  /** RBAC denied the read. Proves nothing about whether the object exists. */
+  get forbidden(): boolean {
+    return this.statusCode === 403 || this.reason === "Forbidden";
+  }
+
+  /** No usable credentials for this cluster. */
+  get unauthorized(): boolean {
+    return this.statusCode === 401 || this.reason === "Unauthorized";
+  }
+
+  /** Server-side-apply field-ownership conflict (chant #1075 surfaces these properly). */
+  get conflict(): boolean {
+    return this.statusCode === 409 || this.reason === "Conflict";
+  }
+
+  /**
+   * Build from a raw response body, which is a `Status` on every well-behaved
+   * Kubernetes error and occasionally plain text from a proxy in front of one.
+   */
+  static fromResponse(statusCode: number, body: string, target?: string): K8sApiError {
+    let status: K8sStatus | undefined;
+    try {
+      const parsed: unknown = JSON.parse(body);
+      if (parsed && typeof parsed === "object" && (parsed as K8sStatus).kind === "Status") {
+        status = parsed as K8sStatus;
+      }
+    } catch {
+      /* not JSON — a proxy or ingress error page */
+    }
+    const message = status?.message ?? firstLine(body) ?? "";
+    return new K8sApiError(statusCode, status?.reason, message, target, status);
+  }
+}
+
+/**
+ * The request never reached an API server — DNS, TCP, TLS, proxy, or an
+ * aborted signal. Distinct from {@link K8sApiError} because "I could not
+ * connect" and "the server said no" are different observations.
+ */
+export class K8sTransportError extends Error {
+  constructor(
+    message: string,
+    public readonly target?: string,
+    options?: { cause?: unknown },
+  ) {
+    super(target ? `${target}: ${message}` : message);
+    this.name = "K8sTransportError";
+    if (options && "cause" in options) (this as { cause?: unknown }).cause = options.cause;
+  }
+}
+
+/**
+ * `@kubernetes/client-node` is not installed. It is an ordinary dependency of
+ * this package, so this only happens when the package tree was pruned
+ * (`npm install --omit=optional`, a slimmed container image). Named separately
+ * so the k8s lexicon can tell a missing dependency from a broken cluster.
+ */
+export class K8sClientUnavailableError extends Error {
+  constructor(cause?: unknown) {
+    super(
+      "the Kubernetes API client is unavailable — @kubernetes/client-node could not be loaded. " +
+        "Install it with `npm i @intentius/chant-k8s-client` (it is an optional dependency of " +
+        "@intentius/chant-lexicon-k8s, so `--omit=optional` installs skip it).",
+    );
+    this.name = "K8sClientUnavailableError";
+    if (cause !== undefined) (this as { cause?: unknown }).cause = cause;
+  }
+}
+
+/**
+ * The kubeconfig names an exec credential plugin that is not on the allowlist.
+ *
+ * An exec plugin is an arbitrary binary named in a file chant did not write,
+ * run with the CLI's privileges. EKS/AKS/GKE all need one, so refusing them
+ * outright would make this client useless on managed clusters — but executing
+ * whatever the file names is not a default worth having either.
+ */
+export class ExecCredentialNotAllowedError extends Error {
+  constructor(
+    public readonly command: string,
+    public readonly allowed: readonly string[],
+  ) {
+    super(
+      `k8s: the kubeconfig for this context authenticates with the exec credential plugin ` +
+        `"${command}", which is not on chant's allowlist (${allowed.join(", ")}). ` +
+        `An exec plugin is an arbitrary binary named in a file chant did not write. ` +
+        `If "${command}" is expected, add it to k8s.execCredentialPlugins in chant.config.ts.`,
+    );
+    this.name = "ExecCredentialNotAllowedError";
+  }
+}
+
+/** The kubeconfig could not be read, or names no usable cluster/context. */
+export class KubeConfigError extends Error {
+  constructor(message: string) {
+    super(`k8s: ${message}`);
+    this.name = "KubeConfigError";
+  }
+}
+
+/**
+ * The cluster's own discovery does not serve this kind. Distinct from a 404 on
+ * an instance: no instance of an unserved kind can exist, which is a real
+ * absence rather than an unread hole.
+ */
+export class UnknownResourceError extends Error {
+  constructor(
+    public readonly selectorText: string,
+    message?: string,
+  ) {
+    super(message ?? `k8s: the cluster's API discovery reports no resource matching "${selectorText}"`);
+    this.name = "UnknownResourceError";
+  }
+}
+
+function firstLine(text: string, max = 300): string | undefined {
+  const line = text.split("\n").find((l) => l.trim().length > 0)?.trim();
+  if (!line) return undefined;
+  return line.length > max ? `${line.slice(0, max - 3)}...` : line;
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * `@intentius/chant-k8s-client` — the typed Kubernetes API client behind the
+ * k8s lexicon's read and write paths (chant #1074, epic #1073).
+ *
+ * It is a package rather than a directory inside the lexicon for one reason:
+ * this is the first chant code that holds live cluster credentials, and the
+ * synthesis-purity boundary around it should be structural rather than a lint
+ * rule. `chant build` cannot resolve this package, because nothing on the
+ * build path imports it — the lexicon reaches it through a dynamic import from
+ * modules that are themselves only loaded by the observation and Op paths, and
+ * `examples/k8s-client-boundary.test.ts` walks the static import graph to prove
+ * it stays that way.
+ */
+
+export {
+  createK8sClient,
+  readAmbientContext,
+  loadClientNode,
+  isK8sClientAvailable,
+  apiVersionPath,
+  splitApiVersion,
+  selectorText,
+  refText,
+} from "./client";
+export type { K8sClient, ReadOptions, ApplyOptions } from "./client";
+
+export {
+  K8sApiError,
+  K8sTransportError,
+  K8sClientUnavailableError,
+  ExecCredentialNotAllowedError,
+  KubeConfigError,
+  UnknownResourceError,
+} from "./errors";
+export type { K8sStatus } from "./errors";
+
+export {
+  DEFAULT_EXEC_ALLOWLIST,
+  assertExecCredentialAllowed,
+  credentialPathOf,
+  execConfigOf,
+  execCommandName,
+} from "./credentials";
+export type { ExecConfig, KubeConfigUser } from "./credentials";
+
+export { mapConcurrent, DEFAULT_CONCURRENCY } from "./concurrency";
+
+export type {
+  ApiResourceInfo,
+  ClientProvenance,
+  CredentialPath,
+  K8sClientOptions,
+  K8sObject,
+  ObjectRef,
+  RequestContextLike,
+  RequestLayer,
+  ResourceSelector,
+  ResponseContextLike,
+} from "./types";

package/src/testing.ts

@@ -0,0 +1,188 @@
+/**
+ * Test doubles for the one seam this package exposes.
+ *
+ * A fake here replaces `@kubernetes/client-node`'s HTTP send and nothing
+ * above it: the handler receives the real, fully built request — the URL the
+ * client constructed from discovery, the method, and the headers the
+ * kubeconfig's auth path wrote, `Authorization` included. So a test that uses
+ * it still exercises kubeconfig parsing, context selection, credential policy,
+ * discovery and path construction for real.
+ *
+ * It exists in the shipped package rather than in a test helper because both
+ * this package's tests and the k8s lexicon's tests need it, and because a
+ * consumer wiring chant into their own harness needs the same thing.
+ */
+
+import type { RequestContextLike, RequestLayer, ResponseContextLike } from "./types";
+
+/** What a {@link FakeRequestHandler} sees. */
+export interface RecordedRequest {
+  method: string;
+  /** Full URL including query string. */
+  url: string;
+  /** Path only, query stripped. */
+  path: string;
+  query: Record<string, string>;
+  headers: Record<string, string>;
+  body: unknown;
+}
+
+/** What a handler returns. `body` is stringified when it is not already a string. */
+export interface FakeResponse {
+  status?: number;
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+export type FakeRequestHandler = (request: RecordedRequest) => FakeResponse | Promise<FakeResponse>;
+
+/** A recording {@link RequestLayer} driven by `handler`. */
+export interface FakeRequestLayer extends RequestLayer {
+  /** Every request the client issued, in order. */
+  readonly requests: RecordedRequest[];
+  /** Paths only, in order — the usual assertion target. */
+  paths(): string[];
+}
+
+/**
+ * Build a fake request layer. Anything the handler does not answer 200s with
+ * an empty object, so a test only has to describe the responses it cares about.
+ */
+export function fakeRequestLayer(handler: FakeRequestHandler): FakeRequestLayer {
+  const requests: RecordedRequest[] = [];
+
+  return {
+    requests,
+    paths: () => requests.map((r) => r.path),
+    async send(request: RequestContextLike): Promise<ResponseContextLike> {
+      const url = request.getUrl();
+      const parsed = new URL(url, "http://placeholder.invalid");
+      const recorded: RecordedRequest = {
+        method: String(request.getHttpMethod()),
+        url,
+        path: parsed.pathname,
+        query: Object.fromEntries(parsed.searchParams.entries()),
+        headers: request.getHeaders(),
+        body: request.getBody(),
+      };
+      requests.push(recorded);
+
+      const result = await handler(recorded);
+      const status = result.status ?? 200;
+      const body =
+        result.body === undefined ? "" : typeof result.body === "string" ? result.body : JSON.stringify(result.body);
+      return {
+        httpStatusCode: status,
+        headers: { "content-type": "application/json", ...(result.headers ?? {}) },
+        body: { text: async () => body },
+      };
+    },
+  };
+}
+
+/** A Kubernetes `Status` failure body, for driving typed-error assertions. */
+export function statusBody(code: number, reason: string, message: string): Record<string, unknown> {
+  return {
+    kind: "Status",
+    apiVersion: "v1",
+    metadata: {},
+    status: "Failure",
+    message,
+    reason,
+    code,
+  };
+}
+
+/** Options for {@link fakeKubeconfig}. */
+export interface FakeKubeconfigOptions {
+  contexts?: Array<{ name: string; cluster?: string; user?: string; namespace?: string }>;
+  currentContext?: string;
+  server?: string;
+  /** Static bearer token. Mutually exclusive with `exec` in practice. */
+  token?: string;
+  /** An exec credential plugin stanza, for allowlist and caching tests. */
+  exec?: { command: string; args?: string[]; env?: Array<{ name: string; value: string }> };
+}
+
+/**
+ * A literal kubeconfig, so no test ever reads the developer's real one. Every
+ * test in this repo that builds a client passes one of these.
+ */
+export function fakeKubeconfig(options: FakeKubeconfigOptions = {}): string {
+  const server = options.server ?? "https://cluster.test:6443";
+  const contexts = options.contexts ?? [{ name: "test-context" }];
+  const current = options.currentContext ?? contexts[0].name;
+  const userStanza = options.exec
+    ? [
+        "      exec:",
+        "        apiVersion: client.authentication.k8s.io/v1",
+        `        command: ${JSON.stringify(options.exec.command)}`,
+        ...(options.exec.args?.length
+          ? ["        args:", ...options.exec.args.map((a) => `          - ${JSON.stringify(a)}`)]
+          : []),
+        ...(options.exec.env?.length
+          ? [
+              "        env:",
+              ...options.exec.env.flatMap((e) => [
+                `          - name: ${e.name}`,
+                `            value: ${JSON.stringify(e.value)}`,
+              ]),
+            ]
+          : []),
+      ]
+    : [`      token: ${JSON.stringify(options.token ?? "test-token")}`];
+
+  const users = [...new Set(contexts.map((c) => c.user ?? "test-user"))];
+  const clusters = [...new Set(contexts.map((c) => c.cluster ?? "test-cluster"))];
+
+  return [
+    "apiVersion: v1",
+    "kind: Config",
+    `current-context: ${current}`,
+    "clusters:",
+    ...clusters.flatMap((name) => [
+      `  - name: ${name}`,
+      "    cluster:",
+      `      server: ${server}`,
+      "      insecure-skip-tls-verify: true",
+    ]),
+    "users:",
+    ...users.flatMap((name) => [`  - name: ${name}`, "    user:", ...userStanza]),
+    "contexts:",
+    ...contexts.flatMap((c) => [
+      `  - name: ${c.name}`,
+      "    context:",
+      `      cluster: ${c.cluster ?? "test-cluster"}`,
+      `      user: ${c.user ?? "test-user"}`,
+      ...(c.namespace ? [`      namespace: ${c.namespace}`] : []),
+    ]),
+    "",
+  ].join("\n");
+}
+
+/** An `APIResourceList` body, the discovery response the client resolves against. */
+export function apiResourceList(
+  groupVersion: string,
+  resources: Array<{
+    name: string;
+    kind: string;
+    namespaced?: boolean;
+    singularName?: string;
+    shortNames?: string[];
+    verbs?: string[];
+  }>,
+): Record<string, unknown> {
+  return {
+    kind: "APIResourceList",
+    apiVersion: "v1",
+    groupVersion,
+    resources: resources.map((r) => ({
+      name: r.name,
+      singularName: r.singularName ?? "",
+      namespaced: r.namespaced ?? true,
+      kind: r.kind,
+      verbs: r.verbs ?? ["get", "list", "watch", "create", "update", "patch", "delete"],
+      ...(r.shortNames ? { shortNames: r.shortNames } : {}),
+    })),
+  };
+}