sproutboat 0.2.0

package/src/build.ts

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { walkAssets, type AssetManifest } from "./assets";
+import type { SproutboatConfig } from "./config";
+import { compileWorker } from "./compile";
+import { ARTIFACT_SCHEMA_VERSION, CAPABILITY_PROFILE, RUNTIME, type ArtifactManifest } from "./manifest";
+import { ensureZig, esbuildVersion, porfforVersion, toolchainStamp } from "./toolchain";
+
+export type BuildInput = {
+  projectDir: string;
+  config: SproutboatConfig;
+  sourcePath: string;
+};
+
+export type BuildOutput = {
+  artifactDir: string;
+  manifest: ArtifactManifest;
+};
+
+function digest(value: Uint8Array | string): `sha256:${string}` {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+/**
+ * Cross-compile a handler into a linux-x86_64 native-fetch server binary with
+ * Porffor + Zig — no Docker. The binary is not run here (the build host may not
+ * be linux); the control plane starts it once on deploy and rejects it if it
+ * does not come up.
+ */
+export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
+  const source = await readFile(input.sourcePath);
+  const sourceHash = digest(source);
+  const artifactId = sourceHash.slice("sha256:".length, 24);
+  const artifactDir = resolve(input.projectDir, ".sproutboat/dist", artifactId);
+  const workerPath = resolve(artifactDir, "worker");
+  await mkdir(artifactDir, { recursive: true });
+
+  const bindings = {
+    kv: input.config.kv_namespaces ?? [],
+    secrets: input.config.secrets ?? [],
+    outbound: input.config.outbound ?? [],
+    d1: input.config.d1_databases ?? [],
+    r2: input.config.r2_buckets ?? [],
+    queues: input.config.queues ?? [],
+    analytics: input.config.analytics_engine_datasets ?? [],
+    do: Object.entries(input.config.durable_objects ?? {}).map(([binding, className]) => ({ binding, className })),
+    crons: input.config.triggers?.crons ?? [],
+    assets: input.config.assets?.binding ?? "",
+  };
+
+  const zigBin = await ensureZig();
+  await compileWorker({
+    sourcePath: input.sourcePath,
+    outPath: workerPath,
+    vars: input.config.vars ?? {},
+    bindings,
+    zigBin,
+  });
+
+  const worker = await readFile(workerPath);
+  const manifest: ArtifactManifest = {
+    schemaVersion: ARTIFACT_SCHEMA_VERSION,
+    project: input.config.name,
+    target: "linux-x86_64",
+    runtime: RUNTIME,
+    capabilityProfile: CAPABILITY_PROFILE,
+    porfforVersion: porfforVersion(),
+    esbuildVersion: esbuildVersion(),
+    buildImage: toolchainStamp(),
+    sourceHash,
+    binaryHash: digest(worker),
+    binarySize: (await stat(workerPath)).size,
+    builtAt: new Date().toISOString(),
+  };
+  await writeFile(resolve(artifactDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+  // Bindings live beside the manifest, not in it: the artifact manifest schema is
+  // frozen at v2. The control plane reads this to configure the per-deployment
+  // broker (KV / D1 / R2 / queue names, secret names, outbound allowlist, cron
+  // schedules, Durable Object classes).
+  if (Object.values(bindings).some((names) => names.length > 0)) {
+    await writeFile(resolve(artifactDir, "bindings.json"), `${JSON.stringify(bindings, null, 2)}\n`);
+  }
+
+  // Static assets: copy the directory next to the artifact and record a manifest
+  // the edge serves from directly (assets-first) and the broker reads for
+  // `env.<ASSETS>.fetch()`.
+  if (input.config.assets) {
+    const srcDir = resolve(input.projectDir, input.config.assets.directory);
+    const outDir = resolve(artifactDir, "assets");
+    if (!(await stat(srcDir).then((s) => s.isDirectory()).catch(() => false))) {
+      throw new Error(`assets.directory "${input.config.assets.directory}" not found — run your site build first`);
+    }
+    await cp(srcDir, outDir, { recursive: true });
+    const assetManifest: AssetManifest = {
+      notFound: input.config.assets.not_found_handling ?? "none",
+      runSproutFirst: input.config.assets.run_sprout_first ?? false,
+      files: walkAssets(outDir),
+    };
+    await writeFile(resolve(artifactDir, "assets.json"), `${JSON.stringify(assetManifest, null, 2)}\n`);
+  }
+  return { artifactDir, manifest };
+}

package/src/compile.ts

@@ -0,0 +1,132 @@
+/**
+ * Compile `export default { fetch }` into a linux-x86_64 native-fetch server
+ * binary. Porffor renders the handler to C; with `--musl` it cross-compiles via
+ * `zig cc -target x86_64-linux-musl` and statically links, so the same command
+ * works from macOS, Linux, or WSL with no Docker.
+ *
+ * One-time per machine: Porffor git-clones uWebSockets and builds `uSockets.a`
+ * into ~/.cache/porffor/deps/ (needs `git` and `make` on PATH). Later builds
+ * reuse it and take a few seconds.
+ */
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { ensurePorfforPatched } from "./patch-porffor";
+import { porfforRoot } from "./toolchain";
+
+const preludePath = new URL("./native-fetch-prelude.js", import.meta.url);
+// The server honours $PORT at runtime (patches/porffor-render.patch); this baked
+// value is only a fallback for a directly-run binary.
+const DEFAULT_PORT = 8080;
+const COMPILE_TIMEOUT_MS = Number(process.env.SPROUTBOAT_COMPILE_TIMEOUT_MS || 600_000);
+
+/**
+ * Binding names a project declares. `do` maps a binding name to a Durable Object
+ * class name; `crons` are schedule expressions with no name.
+ */
+export type Bindings = {
+  kv: string[];
+  secrets: string[];
+  outbound: string[];
+  d1: string[];
+  r2: string[];
+  queues: string[];
+  analytics: string[];
+  do: Array<{ binding: string; className: string }>;
+  crons: string[];
+  /** Static-asset binding name for `env.<NAME>.fetch(request)`; `""` when assets are edge-only. */
+  assets: string;
+};
+
+const EMPTY_BINDINGS: Bindings = { kv: [], secrets: [], outbound: [], d1: [], r2: [], queues: [], analytics: [], do: [], crons: [], assets: "" };
+
+function hasBindings(b: Bindings): boolean {
+  return (
+    b.kv.length > 0 || b.secrets.length > 0 || b.outbound.length > 0 || b.d1.length > 0 || b.r2.length > 0 ||
+    b.queues.length > 0 || b.analytics.length > 0 || b.do.length > 0 || b.assets !== ""
+  );
+}
+
+/**
+ * Build the final native-fetch module: the prelude (Web API shims + the broker
+ * binding shim + the trigger dispatcher), then `const env = {…}` with the baked
+ * `vars`, then — if any binding is declared — one `__sbInstallBindings(env, …)`
+ * line, then the user's source with its `export` keywords neutralised (so its
+ * `export default {…}` becomes a plain object we can hand to the dispatcher),
+ * then our single `export default { fetch }` that routes every request through
+ * `__sbEntry` (HTTP → `handlers.fetch`; `x-sb-trigger` → scheduled / queue / DO).
+ *
+ * With no bindings and no `scheduled`/`queue`/DO the output behaves exactly like
+ * a plain `export default { fetch }` worker.
+ */
+export function wrapNativeFetchHandler(
+  source: string,
+  prelude: string,
+  vars: Record<string, string> = {},
+  bindings: Bindings = EMPTY_BINDINGS,
+): string {
+  if (!/\bexport\s+default\s*\{/.test(source) || !/\bfetch\s*\(/.test(source)) {
+    throw new Error("handler must default-export an object with a fetch(request) method");
+  }
+  // Neutralise the module's exports: its default object becomes `__sbHandlers`,
+  // and any `export class`/`function`/`const` (Durable Object classes, helpers)
+  // becomes a plain top-level declaration. Imports are already rejected upstream.
+  const neutralised = source
+    .replace(/^(\s*)export\s+default\s*/m, "$1const __sbHandlers = ")
+    .replace(/^export\s+(async\s+function|function|class|const|let|var)\b/gm, "$1");
+
+  const env = `const env = ${JSON.stringify(vars)};\nglobalThis.env = env;\n`;
+  const wire = hasBindings(bindings) ? `__sbInstallBindings(env, ${JSON.stringify(bindings)});\n` : "";
+  const registerDO = bindings.do.length
+    ? `__sbRegisterDO({ ${bindings.do.map((d) => `${d.className}: ${d.className}`).join(", ")} });\n`
+    : "";
+
+  return (
+    `${prelude}\n${env}${wire}` +
+    `${neutralised}\n` +
+    `${registerDO}` +
+    `export default {\n  port: ${DEFAULT_PORT},\n  fetch(request) { return __sbEntry(__sbHandlers, request); }\n};\n`
+  );
+}
+
+export type CompileInput = {
+  sourcePath: string;
+  outPath: string;
+  vars: Record<string, string>;
+  bindings?: Bindings;
+  zigBin: string;
+};
+
+/** Compile `sourcePath` to a native binary at `outPath` (mode 0555). */
+export async function compileWorker(input: CompileInput): Promise<void> {
+  await ensurePorfforPatched();
+  const outDir = dirname(input.outPath);
+  await mkdir(outDir, { recursive: true });
+  const generatedPath = resolve(outDir, "worker.generated.js");
+  const [source, prelude] = await Promise.all([readFile(input.sourcePath, "utf8"), readFile(preludePath, "utf8")]);
+  await writeFile(generatedPath, wrapNativeFetchHandler(source, prelude, input.vars, input.bindings ?? EMPTY_BINDINGS));
+
+  const porffor = porfforRoot();
+  const launcher = resolve(porffor, "runtime/index.js");
+  // Porffor shells bare `zig` and `esbuild`; put both on PATH for the child.
+  const binDir = resolve(porffor, "../.bin");
+  const path = `${dirname(input.zigBin)}:${binDir}:${process.env.PATH ?? ""}`;
+
+  const child = Bun.spawn(
+    [process.execPath, launcher, "native", generatedPath, "-o", input.outPath, "--musl"],
+    { cwd: outDir, stdout: "pipe", stderr: "pipe", env: { ...process.env, PATH: path } },
+  );
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; child.kill(); }, COMPILE_TIMEOUT_MS);
+  const [code, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ]);
+  clearTimeout(timer);
+
+  if (timedOut) throw new Error(`compile timed out after ${COMPILE_TIMEOUT_MS}ms`);
+  if (code !== 0 || !(await Bun.file(input.outPath).exists())) {
+    throw new Error(`Porffor compile failed: ${(stderr || stdout).trim() || `exit ${code}`}`);
+  }
+  await chmod(input.outPath, 0o555);
+}

package/src/config.ts

@@ -0,0 +1,241 @@
+const slugPattern = /^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])?$/;
+
+export type SproutboatConfig = {
+  $schema?: string;
+  name: string;
+  main: string;
+  compatibility_date: string;
+  vars?: Record<string, string>;
+  /** KV namespace binding names, exposed as `env.<NAME>`. */
+  kv_namespaces?: string[];
+  /** Secret binding names, exposed as `env.<NAME>` (value fetched at use). */
+  secrets?: string[];
+  /** Hostnames the worker's `fetch()` may reach (exact host match). */
+  outbound?: string[];
+  /** D1 (SQLite) database binding names, exposed as `env.<NAME>`. */
+  d1_databases?: string[];
+  /** R2 (object storage) bucket binding names, exposed as `env.<NAME>`. */
+  r2_buckets?: string[];
+  /** Queue producer binding names, exposed as `env.<NAME>.send()`. A `queue(batch)` handler consumes them. */
+  queues?: string[];
+  /** Analytics Engine dataset binding names, exposed as `env.<NAME>.writeDataPoint()`. */
+  analytics_engine_datasets?: string[];
+  /** Durable Object bindings: `{ BINDING_NAME: "ClassName" }`. The class is defined in the handler module. */
+  durable_objects?: Record<string, string>;
+  /** Scheduled triggers, e.g. `{ "crons": ["0 3 * * *"] }` — a `scheduled(event)` handler runs on each tick. */
+  triggers?: { crons?: string[] };
+  /** Static assets: a directory served edge-first (like Cloudflare), optionally bound as `env.<BINDING>.fetch(request)`. */
+  assets?: AssetsConfig;
+};
+
+export type AssetsConfig = {
+  /** Project-relative directory of files to publish with the artifact. */
+  directory: string;
+  /** Optional binding name for `env.<BINDING>.fetch(request)`. */
+  binding?: string;
+  /** What to serve when a request matches no file (applied by the broker on `env.<BINDING>.fetch`). */
+  not_found_handling?: "none" | "single-page-application" | "404-page";
+  /** `true` = run the worker before serving any asset; string[] = selective route patterns (`!` negates). */
+  run_sprout_first?: boolean | string[];
+};
+
+export type ConfigValidation =
+  | { ok: true; value: SproutboatConfig }
+  | { ok: false; errors: string[] };
+
+type JsonValue = string | number | boolean | null | ConfigJsonObject | JsonValue[];
+
+interface ConfigJsonObject {
+  readonly [key: string]: JsonValue;
+}
+
+type ConfigInput = JsonValue | undefined;
+
+function isRecord(value: ConfigInput): value is ConfigJsonObject {
+  return value !== null && Object(value) === value && !Array.isArray(value)
+    && !(value instanceof Function);
+}
+
+function isString(value: ConfigInput): value is string {
+  return Object(value) !== value && value === String(value);
+}
+
+function isProjectSlug(value: string): boolean {
+  return slugPattern.test(value);
+}
+
+function validateConfig(value: ConfigInput): ConfigValidation {
+  const errors: string[] = [];
+  if (!isRecord(value)) return { ok: false, errors: ["config must be an object"] };
+  const allowed = new Set([
+    "$schema", "name", "main", "compatibility_date", "vars",
+    "kv_namespaces", "secrets", "outbound", "d1_databases", "r2_buckets",
+    "queues", "analytics_engine_datasets", "durable_objects", "triggers", "assets",
+  ]);
+  for (const key of Object.keys(value)) if (!allowed.has(key)) errors.push(`unsupported config field: ${key}`);
+  const name = isString(value.name) && isProjectSlug(value.name) ? value.name : null;
+  if (name === null) {
+    errors.push("name must be a 3–32 character lowercase slug");
+  }
+  const main = isString(value.main) && value.main.startsWith("src/") && !value.main.includes("..") ? value.main : null;
+  if (main === null) {
+    errors.push("main must be a relative entry point under src/");
+  }
+  const compatibility_date = isString(value.compatibility_date) && /^\d{4}-\d{2}-\d{2}$/.test(value.compatibility_date) ? value.compatibility_date : null;
+  if (compatibility_date === null) {
+    errors.push("compatibility_date must use YYYY-MM-DD");
+  }
+  const schema = value.$schema === undefined ? undefined : isString(value.$schema) ? value.$schema : null;
+  if (schema === null) errors.push("$schema must be a string");
+  let vars: Record<string, string> | undefined;
+  if (value.vars !== undefined) {
+    if (!isRecord(value.vars)) errors.push("vars must be an object of plain string values");
+    else {
+      vars = {};
+      for (const [key, item] of Object.entries(value.vars)) {
+        if (!/^[A-Z][A-Z0-9_]*$/.test(key) || !isString(item)) errors.push(`vars.${key} must be a string environment name`);
+        else vars[key] = item;
+      }
+    }
+  }
+  const bindingName = /^[A-Z][A-Z0-9_]*$/;
+  const hostPattern = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+  const stringArray = (
+    field: "kv_namespaces" | "secrets" | "outbound" | "d1_databases" | "r2_buckets" | "queues" | "analytics_engine_datasets",
+    item: RegExp,
+    label: string,
+  ): string[] | undefined => {
+    if (value[field] === undefined) return undefined;
+    const raw = value[field];
+    if (!Array.isArray(raw)) {
+      errors.push(`${field} must be an array of ${label}`);
+      return undefined;
+    }
+    const out: string[] = [];
+    for (const entry of raw) {
+      if (!isString(entry) || !item.test(entry)) errors.push(`${field} entries must be ${label}`);
+      else out.push(entry);
+    }
+    return out;
+  };
+  const kv_namespaces = stringArray("kv_namespaces", bindingName, "binding names (UPPER_SNAKE_CASE)");
+  const secrets = stringArray("secrets", bindingName, "binding names (UPPER_SNAKE_CASE)");
+  const outbound = stringArray("outbound", hostPattern, "hostnames");
+  const d1_databases = stringArray("d1_databases", bindingName, "binding names (UPPER_SNAKE_CASE)");
+  const r2_buckets = stringArray("r2_buckets", bindingName, "binding names (UPPER_SNAKE_CASE)");
+  const queues = stringArray("queues", bindingName, "binding names (UPPER_SNAKE_CASE)");
+  const analytics_engine_datasets = stringArray("analytics_engine_datasets", bindingName, "binding names (UPPER_SNAKE_CASE)");
+
+  let durable_objects: Record<string, string> | undefined;
+  if (value.durable_objects !== undefined) {
+    if (!isRecord(value.durable_objects)) {
+      errors.push("durable_objects must be an object of { BINDING_NAME: \"ClassName\" }");
+    } else {
+      durable_objects = {};
+      for (const [binding, className] of Object.entries(value.durable_objects)) {
+        if (!bindingName.test(binding) || !isString(className) || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(className)) {
+          errors.push(`durable_objects.${binding} must map an UPPER_SNAKE binding to a class identifier`);
+        } else durable_objects[binding] = className;
+      }
+    }
+  }
+
+  let triggers: { crons?: string[] } | undefined;
+  if (value.triggers !== undefined) {
+    if (!isRecord(value.triggers)) {
+      errors.push("triggers must be an object with an optional `crons` array");
+    } else {
+      triggers = {};
+      if (value.triggers.crons !== undefined) {
+        const raw = value.triggers.crons;
+        if (!Array.isArray(raw) || raw.some((c) => !isString(c) || c.trim().split(/\s+/).length !== 5)) {
+          errors.push("triggers.crons must be an array of 5-field cron expressions");
+        } else triggers.crons = raw.map((c) => String(c).trim());
+      }
+    }
+  }
+
+  let assets: AssetsConfig | undefined;
+  if (value.assets !== undefined) {
+    if (!isRecord(value.assets)) {
+      errors.push("assets must be an object with a `directory`");
+    } else {
+      const raw = value.assets;
+      const dir = isString(raw.directory) && raw.directory.length > 0 && !raw.directory.includes("..")
+        ? raw.directory.replace(/^\.\//, "").replace(/\/$/, "")
+        : null;
+      if (dir === null) errors.push("assets.directory must be a project-relative path");
+      const binding = raw.binding === undefined ? undefined
+        : isString(raw.binding) && bindingName.test(raw.binding) ? raw.binding : null;
+      if (binding === null) errors.push("assets.binding must be a binding name (UPPER_SNAKE_CASE)");
+      const nfh = raw.not_found_handling === "none" || raw.not_found_handling === "single-page-application"
+        || raw.not_found_handling === "404-page" ? raw.not_found_handling : undefined;
+      if (raw.not_found_handling !== undefined && nfh === undefined) {
+        errors.push('assets.not_found_handling must be "none", "single-page-application", or "404-page"');
+      }
+      let rwf: boolean | string[] | undefined;
+      const rwfRaw = raw.run_sprout_first;
+      if (rwfRaw === true || rwfRaw === false) rwf = rwfRaw;
+      else if (Array.isArray(rwfRaw) && rwfRaw.every((p) => isString(p) && /^!?\//.test(p))) {
+        rwf = rwfRaw.map((p) => String(p));
+      } else if (rwfRaw !== undefined) {
+        errors.push("assets.run_sprout_first must be a boolean or an array of route patterns");
+      }
+      if (dir !== null && binding !== null) {
+        assets = { directory: dir };
+        if (binding !== undefined) assets.binding = binding;
+        if (nfh !== undefined) assets.not_found_handling = nfh;
+        if (rwf !== undefined) assets.run_sprout_first = rwf;
+      }
+    }
+  }
+
+  const bindingSlots = [
+    ...(kv_namespaces ?? []), ...(secrets ?? []), ...(d1_databases ?? []), ...(r2_buckets ?? []),
+    ...(queues ?? []), ...(analytics_engine_datasets ?? []), ...Object.keys(durable_objects ?? {}), ...Object.keys(vars ?? {}),
+    ...(assets?.binding ? [assets.binding] : []),
+  ];
+  if (new Set(bindingSlots).size !== bindingSlots.length) errors.push("vars and binding names must not collide");
+
+  if (errors.length || name === null || main === null || compatibility_date === null || schema === null) return { ok: false, errors };
+  const config: SproutboatConfig = { name, main, compatibility_date };
+  if ("$schema" in value) config.$schema = schema;
+  if ("vars" in value) config.vars = vars;
+  if ("kv_namespaces" in value) config.kv_namespaces = kv_namespaces;
+  if ("secrets" in value) config.secrets = secrets;
+  if ("outbound" in value) config.outbound = outbound;
+  if ("d1_databases" in value) config.d1_databases = d1_databases;
+  if ("r2_buckets" in value) config.r2_buckets = r2_buckets;
+  if ("queues" in value) config.queues = queues;
+  if ("analytics_engine_datasets" in value) config.analytics_engine_datasets = analytics_engine_datasets;
+  if ("durable_objects" in value) config.durable_objects = durable_objects;
+  if ("triggers" in value) config.triggers = triggers;
+  if ("assets" in value) config.assets = assets;
+  return { ok: true, value: config };
+}
+
+export function parseConfig(source: string): ConfigValidation {
+  try {
+    // Config files intentionally support comments and trailing commas, but not
+    // arbitrary JavaScript expressions.
+    let json = "";
+    let quoted = false;
+    for (let index = 0; index < source.length; index++) {
+      const character = source[index];
+      if (character === '"' && source[index - 1] !== "\\") quoted = !quoted;
+      if (!quoted && character === "/" && source[index + 1] === "/") {
+        index = source.indexOf("\n", index);
+        if (index < 0) break;
+        json += "\n";
+      } else if (!quoted && character === "/" && source[index + 1] === "*") {
+        index = source.indexOf("*/", index + 2);
+        if (index < 0) throw new SyntaxError("unterminated block comment");
+        index++;
+      } else json += character;
+    }
+    json = json.replace(/,\s*([}\]])/g, "$1");
+    return validateConfig(JSON.parse(json));
+  } catch (error) {
+    return { ok: false, errors: [`invalid sproutboat.jsonc: ${error instanceof Error ? error.message : String(error)}`] };
+  }
+}

package/src/credentials.ts

@@ -0,0 +1,79 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+
+type Credentials = { version: 1; activeApiUrl?: string; profiles: Record<string, { token: string }> };
+
+type JsonValue = string | number | boolean | null | JsonObject | JsonValue[];
+type JsonObject = { [key: string]: JsonValue };
+
+function isString(value: JsonValue | undefined): value is string {
+  return value !== undefined && value === String(value);
+}
+
+type CredentialsInput = JsonObject;
+type ProfileInput = JsonObject;
+
+function parseCredentials(value: JsonValue): Credentials | undefined {
+  if (!(value instanceof Object) || Array.isArray(value)) return undefined;
+  const input: CredentialsInput = value;
+  if (input.version !== 1 || !(input.profiles instanceof Object) || Array.isArray(input.profiles)) return undefined;
+  const profiles: Record<string, { token: string }> = {};
+  for (const [apiUrl, profileValue] of Object.entries(input.profiles)) {
+    if (!(profileValue instanceof Object) || Array.isArray(profileValue)) return undefined;
+    const profile: ProfileInput = profileValue;
+    if (!isString(profile.token)) return undefined;
+    profiles[apiUrl] = { token: profile.token };
+  }
+  return { version: 1, activeApiUrl: isString(input.activeApiUrl) ? input.activeApiUrl : undefined, profiles };
+}
+
+function configDirectory(): string {
+  const configured = process.env.SPROUTBOAT_CONFIG_DIR || process.env.XDG_CONFIG_HOME;
+  if (configured && isAbsolute(configured)) return resolve(configured, "sproutboat");
+  return resolve(homedir(), ".config", "sproutboat");
+}
+
+function credentialsPath(): string {
+  return resolve(configDirectory(), "credentials.json");
+}
+
+function emptyCredentials(): Credentials {
+  return { version: 1, profiles: {} };
+}
+
+async function readCredentials(): Promise<Credentials> {
+  try {
+    return parseCredentials(JSON.parse(await readFile(credentialsPath(), "utf8"))) || emptyCredentials();
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return emptyCredentials();
+    throw new Error("could not read local Sproutboat credentials");
+  }
+}
+
+export async function savedToken(apiUrl: string): Promise<string | undefined> {
+  return (await readCredentials()).profiles[apiUrl]?.token;
+}
+
+export async function activeApiUrl(): Promise<string | undefined> {
+  return (await readCredentials()).activeApiUrl;
+}
+
+export async function saveToken(apiUrl: string, token: string): Promise<void> {
+  const directory = configDirectory();
+  const path = credentialsPath();
+  const credentials = await readCredentials();
+  credentials.profiles[apiUrl] = { token };
+  credentials.activeApiUrl = apiUrl;
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+  const temporary = `${path}.tmp-${crypto.randomUUID()}`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    await chmod(temporary, 0o600);
+    await rename(temporary, path);
+    await chmod(path, 0o600);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}