@skaile/forge-settings 0.0.0-stage → 1.0.0

package/src/runtime/server/credential-store.ts

@@ -0,0 +1,473 @@
+/**
+ * The forge credential store — secrets at rest, keyed by credential-reference
+ * identity, plus resolution of the reference forms forge itself can serve.
+ *
+ * A registry entry never holds a secret: it holds a `credential.ref`
+ * (`env:NAME`, `cmd:<shell>`, `platform:<configId>`, `keyring:<service>/<account>`).
+ * This module is the backend for the two forms a forge server owns:
+ *
+ *   - `env:NAME`     — read from the process environment.
+ *   - `keyring:s/a`  — read from this store: an AES-256-GCM encrypted JSON file
+ *                      whose keys are the reference strings themselves. A forge
+ *                      app runs headless on a server with no OS keychain, so the
+ *                      encrypted file *is* the keyring the grammar names.
+ *
+ * `cmd:` is resolved by the runtime that owns the shell (the spawned
+ * `skaile serve` reads its own `providers.yml`), and `platform:` by the control
+ * plane that injects the session secret; both are reported, never guessed.
+ *
+ * Encryption is bound to reference identity: the reference string is the GCM
+ * additional-authenticated-data, so a blob stored for one reference cannot be
+ * replayed under another — moving `keyring:forge/anthropic` onto
+ * `keyring:forge/openai` fails authentication instead of silently handing the
+ * wrong endpoint a working key.
+ *
+ * Blob format: `enc:<base64(iv[16] + tag[16] + ciphertext)>`.
+ *
+ * Key format: `FORGE_CREDENTIAL_KEY` must be a 64-char hex string (32 bytes).
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { globalSettingsPath } from "@skaile/workspaces/sdk/core";
+import type { AIProviderEntry, AIProviderRegistryView } from "../shared/provider-registry";
+import { isEntryEnabled, parseCredentialRef, registryEntries } from "../shared/provider-registry";
+import {
+  type CredentialPolicy,
+  credentialRefRefusal,
+  entryPolicyRefusal,
+} from "./credential-policy";
+
+export const CREDENTIAL_PREFIX = "enc:" as const;
+
+/** Filename of the local keyring, next to the user's `settings.json`. */
+const STORE_FILENAME = "forge-credentials.json";
+
+const ALGORITHM = "aes-256-gcm" as const;
+const IV_LENGTH = 16; // bytes
+const TAG_LENGTH = 16; // bytes
+
+/**
+ * The credential key is missing or unusable. Only operations that need the
+ * encrypted store raise it; `env:` and `cmd:` references never touch the key.
+ * `statusCode` is 503 so a host can map it straight to an HTTP answer.
+ */
+export class CredentialKeyError extends Error {
+  readonly code: "missing" | "invalid";
+  readonly statusCode = 503 as const;
+  constructor(code: "missing" | "invalid", message: string) {
+    super(message);
+    this.name = "CredentialKeyError";
+    this.code = code;
+  }
+}
+
+/**
+ * A stored blob did not authenticate: the key is wrong, the data was altered,
+ * or the blob was encrypted for a different reference (the reference is the
+ * GCM additional data). The message names no secret and no plaintext.
+ */
+export class CredentialDecryptError extends Error {
+  constructor() {
+    super(
+      "Encrypted credential could not be authenticated: wrong key, altered data, " +
+        "or it belongs to a different reference.",
+    );
+    this.name = "CredentialDecryptError";
+  }
+}
+
+/** Validate that `key` is a 64-character hex string (32 bytes). */
+function parseKey(key: string): Buffer {
+  if (key.length !== 64) {
+    throw new CredentialKeyError(
+      "invalid",
+      `FORGE_CREDENTIAL_KEY must be a 64-character hex string (32 bytes). Got ${key.length} chars.`,
+    );
+  }
+  if (!/^[0-9a-fA-F]{64}$/.test(key)) {
+    throw new CredentialKeyError(
+      "invalid",
+      "FORGE_CREDENTIAL_KEY contains non-hex characters. Provide a 64-char hex string.",
+    );
+  }
+  return Buffer.from(key, "hex");
+}
+
+/**
+ * Encrypt a credential for storage under one reference.
+ *
+ * @param plaintext - The secret. Must not be empty.
+ * @param hexKey    - 64-char hex key (32 bytes) from `FORGE_CREDENTIAL_KEY`.
+ * @param ref       - The credential reference this blob belongs to; bound into
+ *                    the ciphertext as GCM additional data.
+ * @returns         `enc:<base64(iv + tag + ciphertext)>`
+ */
+export function encryptCredential(plaintext: string, hexKey: string, ref: string): string {
+  if (!plaintext) throw new Error("plaintext must not be empty");
+  if (!ref) throw new Error("ref must not be empty — credentials are encrypted per reference");
+  const key = parseKey(hexKey);
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  cipher.setAAD(Buffer.from(ref, "utf8"));
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag(); // 16 bytes for GCM
+  return `${CREDENTIAL_PREFIX}${Buffer.concat([iv, tag, encrypted]).toString("base64")}`;
+}
+
+function splitBlob(ciphertext: string): { iv: Buffer; tag: Buffer; body: Buffer } {
+  if (!ciphertext.startsWith(CREDENTIAL_PREFIX)) {
+    throw new Error(
+      `Value is not encrypted (missing '${CREDENTIAL_PREFIX}' prefix). ` +
+        "Pass plaintext through encryptCredential() first.",
+    );
+  }
+  const blob = Buffer.from(ciphertext.slice(CREDENTIAL_PREFIX.length), "base64");
+  if (blob.length < IV_LENGTH + TAG_LENGTH + 1) {
+    throw new Error("Encrypted blob is too short — data is corrupted.");
+  }
+  return {
+    iv: blob.subarray(0, IV_LENGTH),
+    tag: blob.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH),
+    body: blob.subarray(IV_LENGTH + TAG_LENGTH),
+  };
+}
+
+/**
+ * Decrypt a credential stored under `ref`.
+ *
+ * @param ciphertext - `enc:<base64(iv + tag + ciphertext)>` string.
+ * @param hexKey     - 64-char hex key (32 bytes) from `FORGE_CREDENTIAL_KEY`.
+ * @param ref        - The reference the blob was encrypted for.
+ * @returns          The original plaintext.
+ * @throws           If the blob is tampered with, the key is wrong, the value is
+ *                   not encrypted, or the blob belongs to a different reference.
+ */
+export function decryptCredential(ciphertext: string, hexKey: string, ref: string): string {
+  const { iv, tag, body } = splitBlob(ciphertext);
+  const decipher = createDecipheriv(ALGORITHM, parseKey(hexKey), iv);
+  decipher.setAAD(Buffer.from(ref, "utf8"));
+  decipher.setAuthTag(tag);
+  try {
+    return decipher.update(body) + decipher.final("utf8");
+  } catch {
+    throw new CredentialDecryptError();
+  }
+}
+
+// ── The local keyring ──────────────────────────────────────────────────────
+
+/** Where and with what a credential-store call reads or writes. */
+export interface CredentialStoreOptions {
+  /** 64-char hex key; defaults to `FORGE_CREDENTIAL_KEY` of the environment. */
+  key?: string;
+  /** Store file; defaults to `FORGE_CREDENTIAL_STORE` or `<skaile home>/forge-credentials.json`. */
+  path?: string;
+  /**
+   * Environment `env:` references (and the key and store path variables) read
+   * from. Without a {@link policy} it defaults to `process.env`; with one it
+   * defaults to an empty environment, so a policy-bound host never reads the
+   * ambient process by accident.
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Which references may be resolved. A refused reference is reported as an
+   * error and never read. Absent: no restriction.
+   */
+  policy?: CredentialPolicy;
+}
+
+/** The environment a call reads: the explicit one, else the process (unless a policy binds it). */
+function envOf(options: CredentialStoreOptions): Record<string, string | undefined> {
+  return options.env ?? (options.policy ? {} : process.env);
+}
+
+interface StoreFile {
+  version: 1;
+  /** Credential reference → `enc:` blob. */
+  credentials: Record<string, string>;
+}
+
+/**
+ * Path of the local keyring file.
+ *
+ * Lives beside the user's `settings.json` so it follows `$SKAILE_HOME`, and is
+ * overridable per app with `FORGE_CREDENTIAL_STORE`.
+ */
+export function credentialStorePath(options: CredentialStoreOptions = {}): string {
+  if (options.path) return options.path;
+  const fromEnv = envOf(options).FORGE_CREDENTIAL_STORE;
+  if (fromEnv) return fromEnv;
+  return join(dirname(globalSettingsPath()), STORE_FILENAME);
+}
+
+function requireKey(options: CredentialStoreOptions): string {
+  const key = options.key ?? envOf(options).FORGE_CREDENTIAL_KEY;
+  if (!key) {
+    throw new CredentialKeyError(
+      "missing",
+      "FORGE_CREDENTIAL_KEY is not set — the forge credential store cannot encrypt or " +
+        "decrypt stored credentials. Set it to a 64-char hex string (32 bytes).",
+    );
+  }
+  return key;
+}
+
+function readStore(path: string): StoreFile {
+  if (!existsSync(path)) return { version: 1, credentials: {} };
+  const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+  const credentials =
+    typeof parsed === "object" && parsed !== null
+      ? (parsed as { credentials?: unknown }).credentials
+      : undefined;
+  if (typeof credentials !== "object" || credentials === null || Array.isArray(credentials)) {
+    return { version: 1, credentials: {} };
+  }
+  return { version: 1, credentials: credentials as Record<string, string> };
+}
+
+function writeStore(path: string, store: StoreFile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+
+/**
+ * Store `value` under `ref` in the local keyring, encrypted against `ref`.
+ *
+ * @param ref   - A `keyring:<service>/<account>` reference.
+ * @param value - The secret.
+ * @returns     The store path that was written.
+ */
+export function storeCredential(
+  ref: string,
+  value: string,
+  options: CredentialStoreOptions = {},
+): string {
+  const parsed = parseCredentialRef(ref);
+  if (parsed?.form !== "keyring") {
+    throw new Error(
+      `'${ref}' is not a keyring reference — the local store only backs ` +
+        "keyring:<service>/<account>. env:/cmd:/platform: references live outside forge.",
+    );
+  }
+  const path = credentialStorePath(options);
+  const store = readStore(path);
+  store.credentials[ref] = encryptCredential(value, requireKey(options), ref);
+  writeStore(path, store);
+  return path;
+}
+
+/** Read and decrypt the credential stored under `ref`, if any. */
+export function readStoredCredential(
+  ref: string,
+  options: CredentialStoreOptions = {},
+): string | undefined {
+  const blob = readStore(credentialStorePath(options)).credentials[ref];
+  if (!blob) return undefined;
+  return decryptCredential(blob, requireKey(options), ref);
+}
+
+/** Remove the credential stored under `ref`. Returns whether anything was removed. */
+export function deleteStoredCredential(ref: string, options: CredentialStoreOptions = {}): boolean {
+  const path = credentialStorePath(options);
+  const store = readStore(path);
+  if (store.credentials[ref] === undefined) return false;
+  delete store.credentials[ref];
+  writeStore(path, store);
+  return true;
+}
+
+/** Every reference the local keyring holds a credential for. */
+export function listStoredCredentialRefs(options: CredentialStoreOptions = {}): string[] {
+  return Object.keys(readStore(credentialStorePath(options)).credentials);
+}
+
+// ── Resolving references ───────────────────────────────────────────────────
+
+/** Where a resolved credential came from, or why it is missing. */
+export type CredentialSource = "env" | "keyring" | "cmd" | "platform" | "ambient" | "none";
+
+/** Outcome of a resolution attempt. Never carries the secret in `error`. */
+export interface ResolvedCredential {
+  /** The secret, when this layer could produce one. */
+  value?: string;
+  /** Which reference form answered — `ambient` means the cloud SDK chain signs. */
+  source: CredentialSource;
+  /** Why there is no value. Secret-free, safe to log and to show in the UI. */
+  error?: string;
+}
+
+/**
+ * Resolve one `credential.ref` to a value.
+ *
+ * `env:` and `keyring:` resolve here. `cmd:` and `platform:` are named as
+ * belonging to another layer rather than being silently treated as missing:
+ * the spawned runtime runs the command against its own `providers.yml`, and the
+ * control plane injects platform secrets into the session.
+ */
+export function resolveCredentialRef(
+  ref: string,
+  options: CredentialStoreOptions = {},
+): ResolvedCredential {
+  const parsed = parseCredentialRef(ref);
+  if (!parsed) {
+    return {
+      source: "none",
+      error:
+        "credential.ref is not a reference (expected env:NAME, cmd:<shell>, " +
+        "platform:<configId> or keyring:<service>/<account>)",
+    };
+  }
+  const refusal = options.policy ? credentialRefRefusal(ref, options.policy) : undefined;
+  if (refusal) return { source: parsed.form, error: refusal };
+  switch (parsed.form) {
+    case "env": {
+      const value = envOf(options)[parsed.name];
+      if (!value) {
+        return { source: "env", error: `environment variable ${parsed.name} is not set` };
+      }
+      return { source: "env", value };
+    }
+    case "keyring": {
+      try {
+        const value = readStoredCredential(ref, options);
+        if (!value) {
+          return { source: "keyring", error: `no credential is stored for '${ref}'` };
+        }
+        return { source: "keyring", value };
+      } catch (err) {
+        return { source: "keyring", error: (err as Error).message };
+      }
+    }
+    case "cmd":
+      return {
+        source: "cmd",
+        error:
+          "cmd: references are run by the runtime that owns the shell — the spawned " +
+          "session resolves this reference itself",
+      };
+    case "platform":
+      return {
+        source: "platform",
+        error: "platform: references are injected by the control plane into the session",
+      };
+  }
+}
+
+/**
+ * Resolve a registry entry's credential.
+ *
+ * `kind: none` needs nothing; `sigv4`, `google_adc` and `azure_entra` without a
+ * reference sign from the ambient AWS/Google/Azure chain, so there is no value
+ * for this layer to hand over and that is not an error.
+ */
+export function resolveEntryCredential(
+  entry: AIProviderEntry,
+  options: CredentialStoreOptions = {},
+): ResolvedCredential {
+  const refusal = options.policy ? entryPolicyRefusal(entry, options.policy) : undefined;
+  if (refusal) return { source: "none", error: refusal };
+  const credential = entry.credential;
+  if (!credential || credential.kind === "none") return { source: "none" };
+  if (!credential.ref) {
+    if (
+      credential.kind === "sigv4" ||
+      credential.kind === "google_adc" ||
+      credential.kind === "azure_entra"
+    ) {
+      return { source: "ambient" };
+    }
+    return { source: "none", error: `credential.ref is missing for kind '${credential.kind}'` };
+  }
+  return resolveCredentialRef(credential.ref, options);
+}
+
+// ── Delivering credentials to a child process ──────────────────────────────
+
+/** Prefix of the per-entry credential variable the harness adapters read. */
+export const PROVIDER_CREDENTIAL_ENV_PREFIX = "SKAILE_AIP_" as const;
+
+/** Suffix of the per-entry credential variable. */
+export const PROVIDER_CREDENTIAL_ENV_SUFFIX = "_KEY" as const;
+
+/**
+ * Canonical environment variable name carrying one entry's credential.
+ *
+ * `SKAILE_AIP_<ID>_KEY`, with every non-alphanumeric character in the id mapped
+ * to `_` (`my-gw.eu` → `SKAILE_AIP_MY_GW_EU_KEY`). The runtime's harness
+ * adapters write this *name* into the config they render (omp's `models.yml`
+ * `apiKey:`, Codex's `env_key`) and read the *value* from the child
+ * environment, which is what this function's callers fill in. The platform's
+ * secret-env allowlist is the `SKAILE_AIP_` prefix rule over the same names, so
+ * the transform must not drift.
+ */
+export function providerCredentialEnvName(providerId: string): string {
+  const slug = providerId.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+  return `${PROVIDER_CREDENTIAL_ENV_PREFIX}${slug}${PROVIDER_CREDENTIAL_ENV_SUFFIX}`;
+}
+
+/** One entry's credential delivery outcome. */
+export interface CredentialDelivery {
+  providerId: string;
+  /** Variable names this entry contributed to the child environment. */
+  names: string[];
+  source: CredentialSource;
+  /** Why nothing was delivered. Secret-free. */
+  error?: string;
+}
+
+/** Result of {@link registryCredentialEnv}. */
+export interface RegistryCredentialEnv {
+  /** Variable name → secret. Pass into the child environment, never into a file. */
+  env: Record<string, string>;
+  /** Per-entry outcome, in registry order — for logging and settings UIs. */
+  deliveries: CredentialDelivery[];
+}
+
+/**
+ * Resolve every enabled entry's credential into a child-process environment.
+ *
+ * Each resolved entry contributes `SKAILE_AIP_<ID>_KEY`; an entry whose
+ * reference is `env:NAME` also re-exports `NAME`, so a harness that still reads
+ * its vendor's conventional variable keeps working without forge owning a
+ * vendor table. The first entry in registry order wins a name collision.
+ *
+ * Entries that resolve elsewhere (`cmd:` in the runtime, `platform:` in the
+ * control plane) or sign from an ambient chain contribute nothing and say so in
+ * {@link RegistryCredentialEnv.deliveries} — the spawned session resolves those
+ * itself from the same registry.
+ */
+export function registryCredentialEnv(
+  registry: AIProviderRegistryView,
+  options: CredentialStoreOptions = {},
+): RegistryCredentialEnv {
+  const env: Record<string, string> = {};
+  const deliveries: CredentialDelivery[] = [];
+
+  for (const [providerId, entry] of registryEntries(registry)) {
+    if (!isEntryEnabled(entry)) continue;
+    const resolved = resolveEntryCredential(entry, options);
+    const names: string[] = [];
+    if (resolved.value) {
+      const canonical = providerCredentialEnvName(providerId);
+      if (env[canonical] === undefined) {
+        env[canonical] = resolved.value;
+        names.push(canonical);
+      }
+      const parsed = entry.credential?.ref ? parseCredentialRef(entry.credential.ref) : undefined;
+      if (parsed?.form === "env" && env[parsed.name] === undefined) {
+        env[parsed.name] = resolved.value;
+        names.push(parsed.name);
+      }
+    }
+    deliveries.push({
+      providerId,
+      names,
+      source: resolved.source,
+      ...(resolved.error ? { error: resolved.error } : {}),
+    });
+  }
+
+  return { env, deliveries };
+}