@bjoernrochel/sevro 0.1.0-rc.7 → 1.0.0

package/src/hosts/claude-login-recovery.ts

@@ -0,0 +1,85 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isRecord } from "../value-guards";
+import { rotatedOAuth, tokenDigest, type ClaudeLogin } from "./claude-login";
+
+const FORMAT = "sevro.claude-login-recovery.v1";
+
+/** A rotated pair retained until its canonical store verifiably holds it. */
+export interface PendingRotation {
+  /** Digest of the refresh token the rotation consumed. */
+  replaces: string;
+  oauth: Record<string, unknown>;
+}
+
+/** Private, per-origin recovery slot for one refreshed login. */
+export class ClaudeLoginRecovery {
+  readonly path: string;
+  readonly workRoot: string;
+
+  constructor(root: string, origin: string) {
+    const key = createHash("sha256").update(origin).digest("hex");
+    this.path = join(root, `${key}.json`);
+    this.workRoot = join(root, "work");
+  }
+
+  async pending(): Promise<PendingRotation | undefined> {
+    let text: string;
+    try {
+      text = await readFile(this.path, "utf8");
+    } catch {
+      return undefined;
+    }
+    return pendingRotation(text);
+  }
+
+  /** Durably retain the rotation before any canonical write is attempted. */
+  async retain(replaced: ClaudeLogin, rotated: ClaudeLogin): Promise<void> {
+    const record: PendingRotation & { format: string } = {
+      format: FORMAT,
+      replaces: tokenDigest(replaced.refreshToken),
+      oauth: rotatedOAuth(rotated),
+    };
+    const temporary = `${this.path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify(record), {
+      flag: "wx",
+      mode: 0o600,
+    });
+    await rename(temporary, this.path);
+  }
+
+  async discard(): Promise<void> {
+    await rm(this.path, { force: true });
+  }
+}
+
+function pendingRotation(text: string): PendingRotation | undefined {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  return isPendingRecord(value)
+    ? { replaces: value.replaces, oauth: value.oauth }
+    : undefined;
+}
+
+function isPendingRecord(value: unknown): value is PendingRotation {
+  return (
+    isRecord(value) &&
+    value.format === FORMAT &&
+    typeof value.replaces === "string" &&
+    isRecord(value.oauth)
+  );
+}
+
+export async function claudeLoginRecovery(
+  stateRoot: string,
+  origin: string,
+): Promise<ClaudeLoginRecovery> {
+  const root = join(stateRoot, "claude-login-recovery");
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  return new ClaudeLoginRecovery(root, origin);
+}

package/src/hosts/claude-login-refresh.ts

@@ -0,0 +1,178 @@
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { delimiter, join } from "node:path";
+import { parseClaudeLogin, type ClaudeLogin } from "./claude-login";
+import { MAX_CREDENTIAL_BYTES } from "./claude-login-store";
+
+/** First Claude Code release verified to provide refresh-token login. */
+export const CLAUDE_REFRESH_MINIMUM_VERSION = "2.1.284";
+const MINIMUM_VERSION = [2, 1, 284] as const;
+const VERSION_TIMEOUT_MS = 10_000;
+const HELPER_TIMEOUT_MS = 60_000;
+/** Network settings the operator may need to reach Anthropic's token endpoint. */
+const FORWARDED_VARIABLES = [
+  "HTTPS_PROXY",
+  "https_proxy",
+  "HTTP_PROXY",
+  "http_proxy",
+  "NO_PROXY",
+  "no_proxy",
+  "NODE_EXTRA_CA_CERTS",
+  "SSL_CERT_FILE",
+] as const;
+/**
+ * Claude resolves `security` through PATH. Refusing it makes the helper keep
+ * the rotated login in its private credential file instead of a Keychain item.
+ */
+const SECURITY_STUB =
+  '#!/bin/sh\n[ "$1" = find-generic-password ] && exit 44\nexit 1\n';
+
+/**
+ * Exchange the login's refresh token with Claude Code's documented
+ * `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` login in a disposable configuration.
+ * The caller owns the lock, durable writeback, and recovery.
+ */
+export async function refreshClaudeLogin(
+  binary: string,
+  login: ClaudeLogin & { refreshToken: string },
+  workRoot: string,
+): Promise<ClaudeLogin> {
+  await requireRefreshCapableClaude(binary);
+  await mkdir(workRoot, { recursive: true, mode: 0o700 });
+  const helper = await mkdtemp(join(workRoot, "refresh-"));
+  try {
+    const paths = await prepareHelper(helper);
+    const code = await runHelper(binary, helperEnvironment(paths, login));
+    return await storedRotation(paths.config, login, code);
+  } finally {
+    await rm(helper, { recursive: true, force: true });
+  }
+}
+
+async function requireRefreshCapableClaude(binary: string): Promise<void> {
+  const version = await claudeVersion(binary);
+  if (!version || !atLeastMinimum(version))
+    throw new Error(
+      `Refreshing the saved Claude login requires Claude Code ${CLAUDE_REFRESH_MINIMUM_VERSION} or later`,
+    );
+}
+
+async function claudeVersion(binary: string): Promise<number[] | undefined> {
+  const proc = Bun.spawn([binary, "--version"], {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  const timer = setTimeout(() => {
+    proc.kill("SIGKILL");
+  }, VERSION_TIMEOUT_MS);
+  try {
+    const [output, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      proc.exited,
+    ]);
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(output.trim());
+    return code === 0 && match ? match.slice(1).map(Number) : undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function atLeastMinimum(version: number[]): boolean {
+  for (const [index, minimum] of MINIMUM_VERSION.entries()) {
+    const part = version[index] ?? 0;
+    if (part !== minimum) return part > minimum;
+  }
+  return true;
+}
+
+async function prepareHelper(helper: string) {
+  const paths = {
+    config: join(helper, "config"),
+    home: join(helper, "home"),
+    bin: join(helper, "bin"),
+  };
+  await Promise.all(
+    Object.values(paths).map((path) => mkdir(path, { mode: 0o700 })),
+  );
+  await writeFile(join(paths.bin, "security"), SECURITY_STUB, {
+    flag: "wx",
+    mode: 0o700,
+  });
+  return paths;
+}
+
+function helperEnvironment(
+  paths: Awaited<ReturnType<typeof prepareHelper>>,
+  login: ClaudeLogin & { refreshToken: string },
+): Record<string, string> {
+  const forwarded = Object.fromEntries(
+    FORWARDED_VARIABLES.flatMap((name) => {
+      const value = process.env[name];
+      return value ? [[name, value]] : [];
+    }),
+  );
+  return {
+    ...forwarded,
+    PATH: [paths.bin, process.env.PATH ?? "/usr/bin:/bin"].join(delimiter),
+    HOME: paths.home,
+    TMPDIR: paths.home,
+    LANG: process.env.LANG ?? "C",
+    NO_COLOR: "1",
+    CLAUDE_CONFIG_DIR: paths.config,
+    CLAUDE_CODE_OAUTH_REFRESH_TOKEN: login.refreshToken,
+    CLAUDE_CODE_OAUTH_SCOPES: login.scopes.join(" "),
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
+  };
+}
+
+/** Output is discarded: it is never needed and must not reach evidence. */
+async function runHelper(
+  binary: string,
+  env: Record<string, string>,
+): Promise<number> {
+  const proc = Bun.spawn([binary, "auth", "login"], {
+    env,
+    cwd: env.HOME,
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  const timer = setTimeout(() => {
+    proc.kill("SIGKILL");
+  }, HELPER_TIMEOUT_MS);
+  try {
+    return await proc.exited;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Accept only a persisted rotation; exit status alone proves nothing. */
+async function storedRotation(
+  config: string,
+  login: ClaudeLogin,
+  code: number,
+): Promise<ClaudeLogin> {
+  const rotated = await helperLogin(join(config, ".credentials.json"));
+  if (!rotated?.refreshToken || rotated.accessToken === login.accessToken)
+    throw new Error(
+      `Claude could not refresh the saved login (helper exit ${String(code)}); run claude and /login if it has expired`,
+    );
+  return rotated;
+}
+
+async function helperLogin(path: string): Promise<ClaudeLogin | undefined> {
+  try {
+    if ((await stat(path)).size > MAX_CREDENTIAL_BYTES) return undefined;
+    return parseClaudeLogin(await readFile(path));
+  } catch {
+    return undefined;
+  }
+}

package/src/hosts/claude-login-store.ts

@@ -0,0 +1,162 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  readFile,
+  realpath,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { homedir, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+
+export const MAX_CREDENTIAL_BYTES = 1024 * 1024;
+
+/** The authoritative store that holds one saved Claude login. */
+export interface ClaudeLoginStore {
+  /** Credential-free identity of the store, used in errors and recovery. */
+  origin: string;
+  /** Claude configuration directory whose refresh lock guards this store. */
+  lockRoot: string;
+  read(): Promise<Buffer>;
+  write(bytes: Buffer): Promise<void>;
+}
+
+/** Keychain operations; the macOS module supplies them only on Darwin. */
+export interface ClaudeKeychain {
+  read(service: string, account: string): Promise<Buffer | undefined>;
+  write(service: string, account: string, bytes: Buffer): Promise<void>;
+}
+
+/** Resolve the store Claude Code itself uses for the selected login. */
+export async function claudeLoginStore(
+  sourceFile?: string,
+  keychain?: ClaudeKeychain,
+): Promise<ClaudeLoginStore> {
+  if (sourceFile) return fileLoginStore(sourceFile, dirname(sourceFile));
+  const configRoot = claudeConfigRoot();
+  const file = join(configRoot, ".credentials.json");
+  const saved = await keychainLoginStore(configRoot, keychain).catch(
+    async (cause: unknown) => {
+      // Claude falls back to its saved file when the Keychain cannot be read.
+      if (await savedFileExists(file)) return undefined;
+      throw cause;
+    },
+  );
+  if (saved) return saved;
+  await requireSavedFile(file);
+  return fileLoginStore(file, configRoot);
+}
+
+async function savedFileExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function claudeConfigRoot(): string {
+  return (
+    process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude")
+  ).normalize("NFC");
+}
+
+/** Claude keys a non-default configuration's Keychain item by its path. */
+export function claudeKeychainService(): string {
+  const configured = process.env.CLAUDE_CONFIG_DIR;
+  if (!configured) return "Claude Code-credentials";
+  const digest = createHash("sha256")
+    .update(configured.normalize("NFC"))
+    .digest("hex");
+  return `Claude Code-credentials-${digest.substring(0, 8)}`;
+}
+
+export function claudeKeychainAccount(): string {
+  let account: string;
+  try {
+    account = process.env.USER || userInfo().username;
+  } catch {
+    return "claude-code-user";
+  }
+  return /^[a-zA-Z0-9._-]+$/.test(account) ? account : "claude-code-user";
+}
+
+async function keychainLoginStore(
+  configRoot: string,
+  keychain: ClaudeKeychain | undefined,
+): Promise<ClaudeLoginStore | undefined> {
+  if (!keychain) return undefined;
+  const service = claudeKeychainService();
+  const account = claudeKeychainAccount();
+  if (!(await keychain.read(service, account))) return undefined;
+  return {
+    origin: `macOS Keychain item "${service}"`,
+    lockRoot: configRoot,
+    read: async () => requireStoredLogin(await keychain.read(service, account)),
+    write: (bytes) => keychain.write(service, account, bytes),
+  };
+}
+
+async function requireSavedFile(path: string): Promise<void> {
+  try {
+    await stat(path);
+  } catch (cause) {
+    const code = (cause as NodeJS.ErrnoException).code;
+    throw new Error(
+      code === "ENOENT"
+        ? "Claude saved login is unavailable; run claude and /login"
+        : "Claude saved credential is unreadable or unavailable",
+      { cause },
+    );
+  }
+}
+
+function requireStoredLogin(bytes: Buffer | undefined): Buffer {
+  if (!bytes) throw new Error("Claude credential is unreadable or unavailable");
+  return bytes;
+}
+
+export function requireBoundedCredential(credential: Buffer): Buffer {
+  if (
+    credential.byteLength === 0 ||
+    credential.byteLength > MAX_CREDENTIAL_BYTES ||
+    !credential.toString("utf8").trim()
+  )
+    throw new Error("Claude credential is empty or oversized");
+  return credential;
+}
+
+function fileLoginStore(path: string, lockRoot: string): ClaudeLoginStore {
+  return {
+    origin: path,
+    lockRoot,
+    read: () => readLoginFile(path),
+    write: (bytes) => replaceLoginFile(path, bytes),
+  };
+}
+
+async function readLoginFile(path: string): Promise<Buffer> {
+  try {
+    if ((await stat(path)).size > MAX_CREDENTIAL_BYTES)
+      throw new Error("oversized credential");
+    return await readFile(path);
+  } catch (cause) {
+    throw new Error("Claude credential is unreadable or unavailable", {
+      cause,
+    });
+  }
+}
+
+/** Replace atomically so concurrent Claude readers never see a partial login. */
+async function replaceLoginFile(path: string, bytes: Buffer): Promise<void> {
+  const target = await realpath(path);
+  const temporary = join(dirname(target), `.sevro-login-${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, bytes, { flag: "wx", mode: 0o600 });
+    await rename(temporary, target);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}

package/src/hosts/claude-login.ts

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { isRecord, isStringArray } from "../value-guards";
+
+/** A claude.ai OAuth login in the document form Claude Code persists. */
+export interface ClaudeLogin {
+  document: Record<string, unknown>;
+  oauth: Record<string, unknown>;
+  accessToken: string;
+  refreshToken: string | undefined;
+  expiresAt: number | undefined;
+  scopes: string[];
+}
+
+/** Fields replaced by a rotation; every other stored field is preserved. */
+const ROTATED_FIELDS = [
+  "accessToken",
+  "refreshToken",
+  "expiresAt",
+  "scopes",
+  "refreshTokenExpiresAt",
+] as const;
+
+/** Parse a stored login without echoing any of its bytes in errors. */
+export function parseClaudeLogin(bytes: Buffer): ClaudeLogin {
+  const document = loginDocument(bytes);
+  const oauth = document.claudeAiOauth;
+  if (!isRecord(oauth) || !nonblank(oauth.accessToken))
+    throw new Error("Claude credential has no claude.ai login");
+  return {
+    document,
+    oauth,
+    accessToken: oauth.accessToken,
+    refreshToken: nonblank(oauth.refreshToken) ? oauth.refreshToken : undefined,
+    expiresAt: loginExpiry(oauth.expiresAt),
+    scopes: isStringArray(oauth.scopes) ? oauth.scopes : [],
+  };
+}
+
+function loginDocument(bytes: Buffer): Record<string, unknown> {
+  let value: unknown;
+  try {
+    value = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    // Parser messages quote input, so the cause is deliberately not retained.
+    throw new Error("Claude credential is not a JSON login document");
+  }
+  if (!isRecord(value))
+    throw new Error("Claude credential is not a JSON login document");
+  return value;
+}
+
+function nonblank(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function loginExpiry(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+/** A login without a recorded expiry is treated as not expiring. */
+export function coversLifetime(
+  login: ClaudeLogin,
+  lifetimeMs: number,
+  now = Date.now(),
+): boolean {
+  return login.expiresAt === undefined || login.expiresAt - now >= lifetimeMs;
+}
+
+/** Apply a rotated token pair to the latest stored document. */
+export function rotatedLoginBytes(
+  latest: ClaudeLogin,
+  rotated: ClaudeLogin,
+): Buffer {
+  const oauth = { ...latest.oauth };
+  for (const field of ROTATED_FIELDS)
+    if (Object.hasOwn(rotated.oauth, field))
+      oauth[field] = rotated.oauth[field];
+  return Buffer.from(
+    JSON.stringify({ ...latest.document, claudeAiOauth: oauth }),
+  );
+}
+
+/** Rotated token fields, as retained for recovery. */
+export function rotatedOAuth(login: ClaudeLogin): Record<string, unknown> {
+  return Object.fromEntries(
+    ROTATED_FIELDS.filter((field) => Object.hasOwn(login.oauth, field)).map(
+      (field) => [field, login.oauth[field]],
+    ),
+  );
+}
+
+export function sameTokens(left: ClaudeLogin, right: ClaudeLogin): boolean {
+  return (
+    left.accessToken === right.accessToken &&
+    left.refreshToken === right.refreshToken &&
+    left.expiresAt === right.expiresAt
+  );
+}
+
+/** Identify a refresh token without retaining its value. */
+export function tokenDigest(token: string | undefined): string {
+  return createHash("sha256")
+    .update(token ?? "")
+    .digest("hex");
+}

package/src/hosts/claude-native-goal.ts

@@ -1,17 +1,17 @@
+import { parseClaudeEvents, type ClaudeEvents } from "./claude-events";
 import { lstat, readdir, readFile } from "node:fs/promises";
 import { basename, join } from "node:path";
+import { requireRecord } from "../value-guards";
 
 type RecordValue = Record<string, unknown>;
 function record(value: unknown): RecordValue {
-  if (!value || typeof value !== "object" || Array.isArray(value))
-    throw new Error("Malformed native session record");
-  return value as RecordValue;
+  return requireRecord(value, "Malformed native session record");
 }
-function records(text: string): RecordValue[] {
-  return text
-    .split("\n")
-    .filter((line) => line.trim())
-    .map((line) => record(JSON.parse(line)));
+function records(text: string | ClaudeEvents): RecordValue[] {
+  return parseClaudeEvents(text).lines.map((line) => {
+    if (!line.parsed) throw line.error;
+    return record(line.value);
+  });
 }
 
 function goalAttachment(event: RecordValue) {
@@ -44,7 +44,10 @@ function attachmentStatus(attachment: RecordValue): string {
   return attachment.sentinel === true ? "cleared" : "complete";
 }
 
-function requireSuccessfulResult(stream: string, sessionId: string): void {
+function requireSuccessfulResult(
+  stream: string | ClaudeEvents,
+  sessionId: string,
+): void {
   const result = records(stream)
     .filter((event) => event.type === "result")
     .at(-1);
@@ -59,7 +62,7 @@ function requireSuccessfulResult(stream: string, sessionId: string): void {
 
 /** Claude's native persisted goal attachments; sentinel clearance is not success. */
 export function claudeNativeGoalEvidence(
-  stream: string,
+  stream: string | ClaudeEvents,
   transcript: string,
   sessionId: string,
 ) {
@@ -111,7 +114,7 @@ async function sessionPaths(
 /** Read only this trial's original native session; never manufacture a goal. */
 export async function observeClaudeNativeGoal(
   configRoot: string,
-  stream: string,
+  stream: string | ClaudeEvents,
 ): Promise<{
   id: string;
   completeness: "complete" | "unavailable";
@@ -144,7 +147,7 @@ export async function observeClaudeNativeGoal(
   }
 }
 
-function originalSessionId(stream: string): string {
+function originalSessionId(stream: string | ClaudeEvents): string {
   const initializations = records(stream).filter(
     (event) => event.type === "system" && event.subtype === "init",
   );

package/src/hosts/claude-process.ts

@@ -1,52 +1,12 @@
-import {
-  awaitHostProcess,
-  boundedProcessText,
-  MAX_EVENT_BYTES,
-} from "./process-lifecycle";
+import { runHostProcess, type HostProcessOptions } from "./process-lifecycle";
 
-const MAX_STDERR_BYTES = 64 * 1024;
-
-function stop(proc: Bun.Subprocess): void {
-  try {
-    if (process.platform !== "win32") process.kill(-proc.pid, "SIGKILL");
-    else proc.kill("SIGKILL");
-  } catch {
-    proc.kill("SIGKILL");
-  }
-}
-
-export async function runClaudeProcess(options: {
-  argv: string[];
-  cwd: string;
-  env: Record<string, string>;
-  timeoutMs: number;
-  signal?: AbortSignal;
-}): Promise<{ code: number; out: string; err: string }> {
-  if (options.signal?.aborted) throw new Error("Claude run cancelled");
-  const proc = Bun.spawn(options.argv, {
-    cwd: options.cwd,
-    env: options.env,
-    detached: process.platform !== "win32",
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const completed = Promise.all([
-    boundedProcessText(
-      proc.stdout,
-      MAX_EVENT_BYTES,
-      "Claude process output exceeds its limit",
-    ),
-    boundedProcessText(
-      proc.stderr,
-      MAX_STDERR_BYTES,
-      "Claude process output exceeds its limit",
-    ),
-    proc.exited,
-  ]).then(([out, err, code]) => ({ out, err, code }));
-  return awaitHostProcess(proc, completed, {
-    ...options,
-    host: "Claude",
-    stop,
-  });
+export async function runClaudeProcess(
+  options: Omit<HostProcessOptions, "host" | "input" | "phase">,
+) {
+  const result = await runHostProcess({ ...options, host: "Claude" });
+  return {
+    code: result.code,
+    out: result.out,
+    err: Buffer.from(result.stderr).toString("utf8"),
+  };
 }