@openparachute/agent 0.1.1 → 0.2.0

package/src/credentials.test.ts

@@ -0,0 +1,274 @@
+/**
+ * Per-channel Claude OAuth credential store (design §6).
+ *
+ * Covers: store/retrieve round-trip, 0600 on the secret file, redaction (the
+ * raw token never appears in the inspection helper / serialized output), and
+ * default-vs-override resolution (override wins, falls back to default, errors
+ * when neither). All hermetic under a throwaway state dir.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, existsSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  setDefaultClaudeCredential,
+  setChannelClaudeCredential,
+  removeChannelClaudeCredential,
+  resolveClaudeCredential,
+  describeClaudeCredentials,
+  readCredentialsFile,
+  credentialsFilePath,
+  CredentialNotConfiguredError,
+  setChannelEnvVar,
+  removeChannelEnvVar,
+  resolveChannelEnv,
+  describeChannelEnv,
+  DenylistedEnvError,
+  DENYLISTED_ENV,
+} from "./credentials.ts";
+
+const DEFAULT_TOKEN = "oat_DEFAULT-OPERATOR-TOKEN-SECRET";
+const OVERRIDE_TOKEN = "oat_PER-CHANNEL-OVERRIDE-SECRET";
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "channel-creds-"));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("store / retrieve round-trip", () => {
+  test("default token: set then resolve returns it", () => {
+    setDefaultClaudeCredential(DEFAULT_TOKEN, dir);
+    expect(resolveClaudeCredential("any-channel", dir)).toBe(DEFAULT_TOKEN);
+  });
+
+  test("per-channel override: set then resolve returns it for that channel", () => {
+    setChannelClaudeCredential("aaron-dev", OVERRIDE_TOKEN, dir);
+    expect(resolveClaudeCredential("aaron-dev", dir)).toBe(OVERRIDE_TOKEN);
+  });
+
+  test("setting one slice preserves the other (read-modify-write)", () => {
+    setDefaultClaudeCredential(DEFAULT_TOKEN, dir);
+    setChannelClaudeCredential("aaron-dev", OVERRIDE_TOKEN, dir);
+    setChannelClaudeCredential("ops", "oat_OPS", dir);
+    const file = readCredentialsFile(dir);
+    expect(file.claude!.default).toBe(DEFAULT_TOKEN);
+    expect(file.claude!.channels!["aaron-dev"]).toBe(OVERRIDE_TOKEN);
+    expect(file.claude!.channels!["ops"]).toBe("oat_OPS");
+  });
+
+  test("empty token is rejected (never persists a blank credential)", () => {
+    expect(() => setDefaultClaudeCredential("", dir)).toThrow(/non-empty token/);
+    expect(() => setChannelClaudeCredential("c", "", dir)).toThrow(/non-empty token/);
+    expect(existsSync(credentialsFilePath(dir))).toBe(false);
+  });
+});
+
+describe("0600 on the secret file", () => {
+  test("the credentials file is written 0600 (holds a secret)", () => {
+    setDefaultClaudeCredential(DEFAULT_TOKEN, dir);
+    const file = credentialsFilePath(dir);
+    expect(existsSync(file)).toBe(true);
+    expect(statSync(file).mode & 0o777).toBe(0o600);
+  });
+
+  test("a subsequent write keeps it 0600 (chmod is unconditional)", () => {
+    setDefaultClaudeCredential(DEFAULT_TOKEN, dir);
+    // Loosen perms behind the store's back, then write again → must re-tighten.
+    const fs = require("fs") as typeof import("fs");
+    fs.chmodSync(credentialsFilePath(dir), 0o644);
+    setChannelClaudeCredential("c", OVERRIDE_TOKEN, dir);
+    expect(statSync(credentialsFilePath(dir)).mode & 0o777).toBe(0o600);
+  });
+});
+
+describe("redaction — the raw token never leaks via the inspection helper", () => {
+  test("describeClaudeCredentials reports presence + channel names, NOT the token", () => {
+    setDefaultClaudeCredential(DEFAULT_TOKEN, dir);
+    setChannelClaudeCredential("aaron-dev", OVERRIDE_TOKEN, dir);
+    setChannelClaudeCredential("ops", "oat_OPS", dir);
+    const desc = describeClaudeCredentials(dir);
+    expect(desc.defaultSet).toBe(true);
+    expect(desc.channels).toEqual(["aaron-dev", "ops"]); // sorted, names only
+    const serialized = JSON.stringify(desc);
+    expect(serialized).not.toContain(DEFAULT_TOKEN);
+    expect(serialized).not.toContain(OVERRIDE_TOKEN);
+    expect(serialized).not.toContain("oat_OPS");
+  });
+
+  test("describe on an empty store: defaultSet false, no channels", () => {
+    const desc = describeClaudeCredentials(dir);
+    expect(desc).toEqual({ defaultSet: false, channels: [] });
+  });
+});
+
+describe("default-vs-override resolution", () => {
+  test("override WINS over the default for its channel", () => {
+    setDefaultClaudeCredential(DEFAULT_TOKEN, dir);
+    setChannelClaudeCredential("aaron-dev", OVERRIDE_TOKEN, dir);
+    expect(resolveClaudeCredential("aaron-dev", dir)).toBe(OVERRIDE_TOKEN);
+    // A different channel with no override falls back to the default.
+    expect(resolveClaudeCredential("other", dir)).toBe(DEFAULT_TOKEN);
+  });
+
+  test("falls back to the default when the channel has no override", () => {
+    setDefaultClaudeCredential(DEFAULT_TOKEN, dir);
+    expect(resolveClaudeCredential("never-configured", dir)).toBe(DEFAULT_TOKEN);
+  });
+
+  test("ERRORS when neither an override nor a default is set", () => {
+    expect(() => resolveClaudeCredential("ghost", dir)).toThrow(CredentialNotConfiguredError);
+    expect(() => resolveClaudeCredential("ghost", dir)).toThrow(/no Claude credential for channel "ghost"/);
+  });
+
+  test("removing an override falls back to the default; removing a missing one is a no-op", () => {
+    setDefaultClaudeCredential(DEFAULT_TOKEN, dir);
+    setChannelClaudeCredential("aaron-dev", OVERRIDE_TOKEN, dir);
+    expect(removeChannelClaudeCredential("aaron-dev", dir)).toBe(true);
+    expect(resolveClaudeCredential("aaron-dev", dir)).toBe(DEFAULT_TOKEN); // back to default
+    expect(removeChannelClaudeCredential("aaron-dev", dir)).toBe(false); // already gone
+    // The default is untouched by an override removal.
+    expect(readCredentialsFile(dir).claude!.default).toBe(DEFAULT_TOKEN);
+  });
+
+  test("resolution is read dynamically — a rotate takes effect on the next resolve", () => {
+    setDefaultClaudeCredential(DEFAULT_TOKEN, dir);
+    expect(resolveClaudeCredential("c", dir)).toBe(DEFAULT_TOKEN);
+    setDefaultClaudeCredential("oat_ROTATED", dir);
+    expect(resolveClaudeCredential("c", dir)).toBe("oat_ROTATED");
+  });
+});
+
+// ===========================================================================
+// Generic per-channel env store (GH_TOKEN / CLOUDFLARE_API_TOKEN / …)
+// ===========================================================================
+const GH = "ghp_GITHUB-TOKEN-SECRET";
+const CF = "cf_CLOUDFLARE-TOKEN-SECRET";
+
+describe("env store — set / resolve / channel-over-default merge", () => {
+  test("default var: set with null channel, resolves for any channel", () => {
+    setChannelEnvVar(null, "GH_TOKEN", GH, dir);
+    expect(resolveChannelEnv("anything", dir)).toEqual({ GH_TOKEN: GH });
+    // An empty-string channel also targets the default layer.
+    setChannelEnvVar("", "CF_TOKEN", CF, dir);
+    expect(resolveChannelEnv("anything", dir)).toEqual({ GH_TOKEN: GH, CF_TOKEN: CF });
+  });
+
+  test("per-channel override WINS over the default for that channel; others see only the default", () => {
+    setChannelEnvVar(null, "GH_TOKEN", "ghp_DEFAULT", dir);
+    setChannelEnvVar("aaron-dev", "GH_TOKEN", "ghp_AARON", dir);
+    setChannelEnvVar("aaron-dev", "CLOUDFLARE_API_TOKEN", CF, dir);
+    // channel layer wins on GH_TOKEN, plus its own CF token, plus inherits nothing extra.
+    expect(resolveChannelEnv("aaron-dev", dir)).toEqual({ GH_TOKEN: "ghp_AARON", CLOUDFLARE_API_TOKEN: CF });
+    // a different channel falls back to the default only.
+    expect(resolveChannelEnv("other", dir)).toEqual({ GH_TOKEN: "ghp_DEFAULT" });
+  });
+
+  test("resolves to {} when nothing is configured (env injection is optional)", () => {
+    expect(resolveChannelEnv("ghost", dir)).toEqual({});
+  });
+
+  test("setting an env var preserves the Claude slice (independent namespaces)", () => {
+    setDefaultClaudeCredential(DEFAULT_TOKEN, dir);
+    setChannelEnvVar(null, "GH_TOKEN", GH, dir);
+    const file = readCredentialsFile(dir);
+    expect(file.claude!.default).toBe(DEFAULT_TOKEN); // untouched
+    expect(file.env!.default!.GH_TOKEN).toBe(GH);
+  });
+
+  test("read dynamically — a value change takes effect on the next resolve", () => {
+    setChannelEnvVar("c", "GH_TOKEN", "ghp_OLD", dir);
+    expect(resolveChannelEnv("c", dir).GH_TOKEN).toBe("ghp_OLD");
+    setChannelEnvVar("c", "GH_TOKEN", "ghp_NEW", dir);
+    expect(resolveChannelEnv("c", dir).GH_TOKEN).toBe("ghp_NEW");
+  });
+
+  test("the env store file is written 0600 (holds secrets)", () => {
+    setChannelEnvVar(null, "GH_TOKEN", GH, dir);
+    expect(statSync(credentialsFilePath(dir)).mode & 0o777).toBe(0o600);
+  });
+});
+
+describe("env store — remove", () => {
+  test("remove a default var; remove a missing one is a no-op (false)", () => {
+    setChannelEnvVar(null, "GH_TOKEN", GH, dir);
+    setChannelEnvVar(null, "CF_TOKEN", CF, dir);
+    expect(removeChannelEnvVar(null, "GH_TOKEN", dir)).toBe(true);
+    expect(resolveChannelEnv("any", dir)).toEqual({ CF_TOKEN: CF });
+    expect(removeChannelEnvVar(null, "GH_TOKEN", dir)).toBe(false); // already gone
+  });
+
+  test("remove a channel override; the default for that name re-emerges", () => {
+    setChannelEnvVar(null, "GH_TOKEN", "ghp_DEFAULT", dir);
+    setChannelEnvVar("aaron-dev", "GH_TOKEN", "ghp_AARON", dir);
+    expect(removeChannelEnvVar("aaron-dev", "GH_TOKEN", dir)).toBe(true);
+    expect(resolveChannelEnv("aaron-dev", dir)).toEqual({ GH_TOKEN: "ghp_DEFAULT" }); // back to default
+  });
+
+  test("removing the last var of a channel prunes the empty channel map", () => {
+    setChannelEnvVar("c", "GH_TOKEN", GH, dir);
+    removeChannelEnvVar("c", "GH_TOKEN", dir);
+    const file = readCredentialsFile(dir);
+    // The channel (and the now-empty channels map) is pruned, not left as {}.
+    expect(file.env?.channels).toBeUndefined();
+  });
+});
+
+describe("env store — redaction (describeChannelEnv returns NAMES only)", () => {
+  test("describe reports names per layer, never the values", () => {
+    setChannelEnvVar(null, "GH_TOKEN", GH, dir);
+    setChannelEnvVar("aaron-dev", "CLOUDFLARE_API_TOKEN", CF, dir);
+    setChannelEnvVar("aaron-dev", "GH_TOKEN", "ghp_AARON", dir);
+    const desc = describeChannelEnv(dir);
+    expect(desc.default).toEqual(["GH_TOKEN"]);
+    expect(desc.channels["aaron-dev"]).toEqual(["CLOUDFLARE_API_TOKEN", "GH_TOKEN"]); // sorted
+    const serialized = JSON.stringify(desc);
+    expect(serialized).not.toContain(GH);
+    expect(serialized).not.toContain(CF);
+    expect(serialized).not.toContain("ghp_AARON");
+  });
+
+  test("describe on an empty store: no default, no channels", () => {
+    expect(describeChannelEnv(dir)).toEqual({ default: [], channels: {} });
+  });
+});
+
+describe("env store — denylist (the Claude-auth trio is never settable)", () => {
+  test("the denylist is exactly the Claude-auth vars", () => {
+    expect([...DENYLISTED_ENV].sort()).toEqual(
+      ["ANTHROPIC_API_KEY", "CLAUDE_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"].sort(),
+    );
+  });
+
+  test("setter REJECTS each denylisted name (default + channel), nothing persisted", () => {
+    for (const name of DENYLISTED_ENV) {
+      expect(() => setChannelEnvVar(null, name, "x", dir)).toThrow(DenylistedEnvError);
+      expect(() => setChannelEnvVar("c", name, "x", dir)).toThrow(DenylistedEnvError);
+    }
+    expect(existsSync(credentialsFilePath(dir))).toBe(false);
+  });
+
+  test("setter rejects a malformed name + an empty value", () => {
+    expect(() => setChannelEnvVar(null, "9BAD", "x", dir)).toThrow(/invalid/);
+    expect(() => setChannelEnvVar(null, "has space", "x", dir)).toThrow(/invalid/);
+    expect(() => setChannelEnvVar(null, "GH_TOKEN", "", dir)).toThrow(/non-empty/);
+    expect(existsSync(credentialsFilePath(dir))).toBe(false);
+  });
+
+  test("resolve defensively STRIPS a denylisted key planted by a hand-edited file", () => {
+    // Plant a denylisted key directly on disk (bypassing the setter), then prove
+    // resolveChannelEnv never returns it — the injection defense's first line.
+    setChannelEnvVar(null, "GH_TOKEN", GH, dir);
+    const fs = require("fs") as typeof import("fs");
+    const file = JSON.parse(fs.readFileSync(credentialsFilePath(dir), "utf8")) as {
+      env: { default: Record<string, string> };
+    };
+    file.env.default.ANTHROPIC_API_KEY = "sk-ant-SMUGGLED";
+    fs.writeFileSync(credentialsFilePath(dir), JSON.stringify(file));
+    const resolved = resolveChannelEnv("any", dir);
+    expect(resolved.GH_TOKEN).toBe(GH);
+    expect(resolved.ANTHROPIC_API_KEY).toBeUndefined();
+  });
+});

package/src/credentials.ts

@@ -0,0 +1,380 @@
+/**
+ * Per-channel Claude OAuth credential store (design §6).
+ *
+ * The Claude `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`, the documented
+ * 1-year headless/CI auth path) is the credential a launched agent session runs
+ * on — injected into the sandbox at launch as the session's auth (NEVER
+ * `ANTHROPIC_API_KEY`, which would silently route onto API billing; see
+ * `spawn-agent.ts`). This module persists that secret, following the SAME
+ * file-store discipline `registry.ts` uses for per-channel transport tokens:
+ * a read-modify-write JSON file, written 0600 and `chmod`-ed 0600 unconditionally
+ * (so an existing file created under a looser umask is tightened on every write).
+ *
+ * Two principal levels (design §6 — "default one operator token; per-channel
+ * override"):
+ *
+ *   - a **default / operator-level** token, used when a channel has no override,
+ *   - a **per-channel override**, the multi-principal seam (multi-user isn't a
+ *     rewrite — just populating per-channel, eventually per-principal, tokens).
+ *
+ * Resolution (`resolveClaudeCredential`): channel override ?? default ?? error.
+ *
+ * The secret lives in its OWN file (`credentials.json`), separate from
+ * `channels.json`: the default/operator token isn't tied to any single channel,
+ * and the credential lifecycle (set the operator token once, override per
+ * channel) is distinct from the channel-registry lifecycle. The file is
+ * NAMESPACED by credential type (`{ claude: { ... } }`) so a future credential
+ * type can coexist without a schema migration.
+ *
+ * Redaction discipline: the raw token is NEVER returned by the listing/inspection
+ * helper (`describeClaudeCredentials`) and NEVER logged — exactly the posture the
+ * config API + transports already keep for `config.token` / `webhookSecret`.
+ */
+
+import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync } from "fs";
+import { join } from "path";
+import { defaultStateDir } from "./registry.ts";
+
+/** The Claude-credential slice of the store. */
+export interface ClaudeCredentialStore {
+  /** Default / operator-level OAuth token, used when a channel has no override. */
+  default?: string;
+  /** Per-channel overrides, keyed by channel name. */
+  channels?: Record<string, string>;
+}
+
+/**
+ * The generic per-channel ENVIRONMENT-VARIABLE slice (`env`). Same two-principal
+ * shape as the Claude slice (an operator-level default layer + per-channel
+ * overrides), but each layer is a NAME→VALUE map rather than a single token: an
+ * operator scopes a channel's spawned agent a `GH_TOKEN`, `CLOUDFLARE_API_TOKEN`,
+ * etc. {@link resolveChannelEnv} flattens the two layers into one map (channel
+ * wins) at spawn time, and {@link buildAgentChildEnv} (spawn-agent.ts) merges that
+ * into the sandboxed child's env so the agent's `gh`/`git`/build tooling sees the
+ * tokens — while Claude's own auth (`CLAUDE_CODE_OAUTH_TOKEN`) stays untouched.
+ */
+export interface ChannelEnvStore {
+  /** Operator-level default env vars, used by every channel (lowest precedence). */
+  default?: Record<string, string>;
+  /** Per-channel env overrides, keyed by channel name (wins over the default). */
+  channels?: Record<string, Record<string, string>>;
+}
+
+/** The on-disk `credentials.json` shape (namespaced by credential type). */
+export interface CredentialsFile {
+  claude?: ClaudeCredentialStore;
+  /** Generic per-channel env-var injection (the GH_TOKEN/CLOUDFLARE_* slice). */
+  env?: ChannelEnvStore;
+}
+
+/**
+ * Env-var names that MUST NEVER be settable through the env store — they'd break
+ * the module's two load-bearing guarantees:
+ *
+ *   - `ANTHROPIC_API_KEY` / `CLAUDE_API_KEY` would route the spawned session onto
+ *     METERED API billing instead of the interactive subscription (the exact thing
+ *     `buildAgentChildEnv` deliberately scrubs — see spawn-agent.ts §6).
+ *   - `CLAUDE_CODE_OAUTH_TOKEN` is the session's MANAGED auth, resolved per-channel
+ *     from the Claude slice; letting the generic env store override it would let an
+ *     operator (or a future less-trusted caller) silently swap the session's
+ *     identity out from under the credential resolver.
+ *
+ * The setters REJECT these (throw {@link DenylistedEnvError}); the injection step
+ * (`buildAgentChildEnv`) ALSO drops them defensively, so even a hand-edited
+ * credentials.json can't smuggle one through.
+ *
+ * `PATH`/`HOME` are deliberately NOT denylisted: `buildAgentChildEnv` layers the
+ * resolved channel env UNDER its own structural passthrough + the seeded-HOME
+ * overrides, so a channel-set PATH/HOME can't clobber the sandbox's own (the
+ * passthrough copies the real PATH/HOME after, and seedAgentHome's CLAUDE_CONFIG_DIR
+ * /XDG/TMP win last). Rejecting them would only deny a harmless no-op; allowing
+ * them keeps the denylist focused on the keys that actually matter (the Claude-auth
+ * trio). See the layering comment in `buildAgentChildEnv`.
+ */
+export const DENYLISTED_ENV: ReadonlySet<string> = new Set([
+  "ANTHROPIC_API_KEY",
+  "CLAUDE_API_KEY",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+]);
+
+/** A basic POSIX-ish env-var name guard (letters/digits/underscore, no leading digit). */
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Thrown when a setter is asked to set/override a denylisted env-var name. */
+export class DenylistedEnvError extends Error {
+  constructor(name: string) {
+    super(
+      `env var "${name}" is not settable here: it controls Claude auth / billing ` +
+        `(ANTHROPIC_API_KEY, CLAUDE_API_KEY, CLAUDE_CODE_OAUTH_TOKEN are reserved by ` +
+        `the managed subscription-billing path). Set the Claude credential via ` +
+        `POST /api/credentials/claude instead.`,
+    );
+    this.name = "DenylistedEnvError";
+  }
+}
+
+/** The default credential reference an unspecified spec resolves against. */
+export const DEFAULT_CREDENTIAL_REF = "operator" as const;
+
+/** Absolute path to the credentials.json store in a state dir. */
+export function credentialsFilePath(stateDir?: string): string {
+  return join(stateDir ?? defaultStateDir(), "credentials.json");
+}
+
+/**
+ * Read `credentials.json` as a plain `CredentialsFile`. Returns an empty `{}` if
+ * the file is absent. Mirrors `registry.readChannelsFile` — the read half of the
+ * read-modify-write the setters use.
+ */
+export function readCredentialsFile(stateDir?: string): CredentialsFile {
+  const file = credentialsFilePath(stateDir);
+  if (!existsSync(file)) return {};
+  const parsed = JSON.parse(readFileSync(file, "utf8")) as CredentialsFile;
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`credentials: ${file} must be a JSON object`);
+  }
+  return parsed;
+}
+
+/**
+ * Persist the store back to `credentials.json` with 0600 perms — the file holds
+ * the Claude OAuth secret. Creates the state dir if needed. `chmod`s 0600
+ * unconditionally (writeFileSync's `mode` only applies on CREATE, so an existing
+ * file created under a looser umask is tightened on every write) — the exact
+ * discipline `registry.upsertChannelEntry` keeps for the secret-bearing
+ * channels.json.
+ */
+function writeCredentialsFile(file: CredentialsFile, stateDir?: string): void {
+  const dir = stateDir ?? defaultStateDir();
+  mkdirSync(dir, { recursive: true });
+  const path = credentialsFilePath(dir);
+  writeFileSync(path, JSON.stringify(file, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
+/**
+ * Set the default / operator-level Claude OAuth token. Used by any channel that
+ * has no per-channel override. Read-modify-write so existing per-channel
+ * overrides are preserved.
+ */
+export function setDefaultClaudeCredential(token: string, stateDir?: string): void {
+  if (typeof token !== "string" || token.length === 0) {
+    throw new Error("credentials: a non-empty token is required");
+  }
+  const file = readCredentialsFile(stateDir);
+  const claude = file.claude ?? {};
+  claude.default = token;
+  file.claude = claude;
+  writeCredentialsFile(file, stateDir);
+}
+
+/**
+ * Set a per-channel Claude OAuth override. Wins over the default for that channel.
+ * Read-modify-write so the default + other channels' overrides are preserved.
+ */
+export function setChannelClaudeCredential(
+  channel: string,
+  token: string,
+  stateDir?: string,
+): void {
+  if (typeof channel !== "string" || channel.length === 0) {
+    throw new Error("credentials: a channel name is required");
+  }
+  if (typeof token !== "string" || token.length === 0) {
+    throw new Error("credentials: a non-empty token is required");
+  }
+  const file = readCredentialsFile(stateDir);
+  const claude = file.claude ?? {};
+  const channels = claude.channels ?? {};
+  channels[channel] = token;
+  claude.channels = channels;
+  file.claude = claude;
+  writeCredentialsFile(file, stateDir);
+}
+
+/**
+ * Remove a per-channel override (the channel falls back to the default after
+ * this). Returns true if an override existed, false if there was nothing to
+ * remove. The default token is untouched.
+ */
+export function removeChannelClaudeCredential(channel: string, stateDir?: string): boolean {
+  const file = readCredentialsFile(stateDir);
+  const channels = file.claude?.channels;
+  if (!channels || !(channel in channels)) return false;
+  delete channels[channel];
+  writeCredentialsFile(file, stateDir);
+  return true;
+}
+
+/** Thrown when neither a per-channel override nor a default token is configured. */
+export class CredentialNotConfiguredError extends Error {
+  constructor(channel: string) {
+    super(
+      `no Claude credential for channel "${channel}": set a per-channel override or the ` +
+        `default/operator token (POST /api/credentials/claude). Get one with ` +
+        `\`claude setup-token\`.`,
+    );
+    this.name = "CredentialNotConfiguredError";
+  }
+}
+
+/**
+ * Resolve the Claude OAuth token a session on `channel` should run on:
+ *
+ *   channel override ?? default ?? throw CredentialNotConfiguredError
+ *
+ * Read at resolve time (not cached) so a token set/rotated via the config API
+ * takes effect on the next spawn without a daemon restart — the dynamic-read
+ * discipline. Throwing (rather than returning empty) means a misconfigured
+ * install fails loud BEFORE a session launches with no auth.
+ */
+export function resolveClaudeCredential(channel: string, stateDir?: string): string {
+  const claude = readCredentialsFile(stateDir).claude;
+  const override = claude?.channels?.[channel];
+  if (override) return override;
+  const fallback = claude?.default;
+  if (fallback) return fallback;
+  throw new CredentialNotConfiguredError(channel);
+}
+
+/**
+ * Describe the credential store for an operator-facing read WITHOUT leaking the
+ * secret: whether a default is set, and which channels carry an override (names
+ * only). The raw token is never returned — same redaction posture the config
+ * API keeps for transport tokens. (`GET /api/credentials/claude`.)
+ */
+export function describeClaudeCredentials(
+  stateDir?: string,
+): { defaultSet: boolean; channels: string[] } {
+  const claude = readCredentialsFile(stateDir).claude;
+  return {
+    defaultSet: Boolean(claude?.default),
+    channels: Object.keys(claude?.channels ?? {}).sort(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Generic per-channel env-var store (the GH_TOKEN / CLOUDFLARE_API_TOKEN slice).
+//
+// Mirrors the Claude helpers exactly: read-modify-write JSON, 0600 + unconditional
+// chmod, sibling-preserving, dynamic-read-at-resolve. A `null`/`undefined` channel
+// targets the operator-level DEFAULT layer; a channel name targets that channel's
+// override layer. Every setter enforces DENYLISTED_ENV (the Claude-auth trio) so
+// the subscription-billing guarantee can't be subverted via this surface.
+// ---------------------------------------------------------------------------
+
+/** Validate an env-var NAME for the setters: non-denylisted + a sane shape. */
+function assertSettableEnvName(name: string): void {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("credentials: an env var name is required");
+  }
+  if (DENYLISTED_ENV.has(name)) throw new DenylistedEnvError(name);
+  if (!ENV_NAME_RE.test(name)) {
+    throw new Error(
+      `credentials: env var name "${name}" is invalid (letters, digits, underscore; no leading digit)`,
+    );
+  }
+}
+
+/**
+ * Set ONE env var on the operator-level default layer (`channel` is null/undefined)
+ * or on a specific channel's override layer. Read-modify-write so the Claude slice,
+ * the other layer, and other vars are preserved. Rejects denylisted names
+ * ({@link DenylistedEnvError}) and an empty value.
+ */
+export function setChannelEnvVar(
+  channel: string | null | undefined,
+  name: string,
+  value: string,
+  stateDir?: string,
+): void {
+  assertSettableEnvName(name);
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error("credentials: a non-empty env var value is required");
+  }
+  const file = readCredentialsFile(stateDir);
+  const env = file.env ?? {};
+  if (channel === null || channel === undefined || channel === "") {
+    const def = env.default ?? {};
+    def[name] = value;
+    env.default = def;
+  } else {
+    const channels = env.channels ?? {};
+    const forChannel = channels[channel] ?? {};
+    forChannel[name] = value;
+    channels[channel] = forChannel;
+    env.channels = channels;
+  }
+  file.env = env;
+  writeCredentialsFile(file, stateDir);
+}
+
+/**
+ * Remove ONE env var from the operator-level default layer (`channel` null/undefined)
+ * or a channel's override layer. Returns true if it existed, false if there was
+ * nothing to remove. Prunes an emptied channel map so a removed-everything channel
+ * doesn't linger as `{}`. Read-modify-write; the Claude slice + other vars untouched.
+ */
+export function removeChannelEnvVar(
+  channel: string | null | undefined,
+  name: string,
+  stateDir?: string,
+): boolean {
+  const file = readCredentialsFile(stateDir);
+  const env = file.env;
+  if (!env) return false;
+  if (channel === null || channel === undefined || channel === "") {
+    if (!env.default || !(name in env.default)) return false;
+    delete env.default[name];
+    if (Object.keys(env.default).length === 0) delete env.default;
+  } else {
+    const forChannel = env.channels?.[channel];
+    if (!forChannel || !(name in forChannel)) return false;
+    delete forChannel[name];
+    if (Object.keys(forChannel).length === 0) delete env.channels![channel];
+    if (env.channels && Object.keys(env.channels).length === 0) delete env.channels;
+  }
+  writeCredentialsFile(file, stateDir);
+  return true;
+}
+
+/**
+ * Resolve the FLATTENED env a session on `channel` should run with:
+ *
+ *   { ...env.default, ...env.channels[channel] }   (the channel layer wins)
+ *
+ * Read at resolve time (not cached), like the Claude resolver — so a var set via the
+ * config API takes effect on the next spawn (or per-session restart) without a daemon
+ * restart. Defensively SKIPS any denylisted key that somehow landed on disk (a
+ * hand-edited file): the setter blocks them, but the resolver never returns one
+ * either, so `buildAgentChildEnv`'s own denylist drop is a belt to this suspenders.
+ * Returns an empty map when nothing is configured (a channel with no env is fine).
+ */
+export function resolveChannelEnv(channel: string, stateDir?: string): Record<string, string> {
+  const env = readCredentialsFile(stateDir).env;
+  const merged: Record<string, string> = { ...(env?.default ?? {}), ...(env?.channels?.[channel] ?? {}) };
+  for (const k of Object.keys(merged)) {
+    if (DENYLISTED_ENV.has(k)) delete merged[k];
+  }
+  return merged;
+}
+
+/**
+ * Describe the env store for an operator-facing read WITHOUT leaking values: the
+ * NAMES set on the default layer, and the names set per channel. The raw values are
+ * NEVER returned (`GET /api/credentials/env`) — same redaction posture as
+ * `describeClaudeCredentials`.
+ */
+export function describeChannelEnv(
+  stateDir?: string,
+): { default: string[]; channels: Record<string, string[]> } {
+  const env = readCredentialsFile(stateDir).env;
+  const channels: Record<string, string[]> = {};
+  for (const [ch, vars] of Object.entries(env?.channels ?? {})) {
+    channels[ch] = Object.keys(vars).sort();
+  }
+  return {
+    default: Object.keys(env?.default ?? {}).sort(),
+    channels,
+  };
+}