Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

14.6 KB
Raw Blame
/**
 * This process's copy of ONE credential file, kept in step with the file on disk.
 *
 * A long-lived claudish (`claudish --mcp`, `serve`, a pane child) used to read its OAuth
 * login once, in a constructor, and keep that copy for its whole life. After
 * `claudish login grok` rewrote `~/.claudish/grok-oauth.json` in another terminal, an
 * older MCP server kept presenting the revoked refresh token and answering `Grok token
 * refresh failed: Refresh token has been revoked` until it was restarted
 * (model-failures-2026-10-21.md, D1).
 *
 * There is no timer. The file is checked with one path `stat` at the moments a caller
 * asks (before signing, before refreshing, before reporting a dead login), and re-read
 * only when its stamp moved. The stamp is recorded per path, so a test seam that swaps
 * the path always reads the new file.
 *
 * Four disk states, and why the fourth exists: an OLDER claudish on the same machine
 * writes this file in place (`openSync(path, "w")`), so between its truncate and its
 * write a reader sees a 0-byte or partial file. If that read meant "no credentials", one
 * torn read would sign a subscription user out, and the routing chain would walk the
 * request onto a metered provider. So a file that exists but cannot be read, parsed or
 * validated is `unreadable`: the last good credentials are kept, the new stamp is NOT
 * recorded (the next call reads again), and only ENOENT means `removed`.
 *
 * Never logs a credential value: log lines carry the label and the path only.
 */
import { randomBytes } from "node:crypto";
import {
  closeSync,
  fsyncSync,
  mkdirSync,
  openSync,
  readFileSync,
  renameSync,
  statSync,
  unlinkSync,
  writeSync,
} from "node:fs";
import { dirname } from "node:path";
import { log } from "../logger.js";

/** What identifies one version of a file without reading it. */
export interface FileStamp {
  ino: number;
  size: number;
  mtimeMs: number;
  ctimeMs: number;
}

/**
 * `null` = the file does not exist (ENOENT only). Any other stat error (EACCES, EIO …)
 * is `{ error }`, which a caller treats as "unreadable", never as "removed".
 */
export function statCredentialFile(path: string): FileStamp | null | { error: string } {
  try {
    const st = statSync(path);
    return { ino: st.ino, size: st.size, mtimeMs: st.mtimeMs, ctimeMs: st.ctimeMs };
  } catch (err) {
    const code = (err as NodeJS.ErrnoException | null)?.code;
    if (code === "ENOENT") return null;
    return { error: code ?? String(err) };
  }
}

/** Whether two stamps describe the same version of a file. */
export function sameStamp(a: FileStamp, b: FileStamp): boolean {
  return a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
}

/**
 * Write `data` as JSON: a new temp file (`<path>.tmp-<pid>-<hex>`, opened "wx", mode
 * 0600), fsync, rename onto `path`. A reader sees the old file or the new one, never a
 * partial one. Returns the new stamp. Throws with the old file intact on any failure.
 */
export function writeCredentialFileAtomic(path: string, data: unknown): FileStamp {
  mkdirSync(dirname(path), { recursive: true });
  const tmp = `${path}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
  try {
    const fd = openSync(tmp, "wx", 0o600);
    try {
      writeSync(fd, JSON.stringify(data, null, 2));
      fsyncSync(fd);
    } finally {
      closeSync(fd);
    }
    renameSync(tmp, path);
  } catch (err) {
    try {
      unlinkSync(tmp);
    } catch {
      // Never created, or already renamed.
    }
    throw err;
  }
  const stamp = statCredentialFile(path);
  if (!stamp || "error" in stamp) throw new Error(`credential file vanished after write: ${path}`);
  return stamp;
}

/**
 * Which login a credential belongs to. A refresh keeps the lineage when the server
 * does not rotate the refresh token and moves it when it does; a NEW login always
 * moves it. With no refresh token the access token stands in.
 */
function lineageOf(credentials: { access_token: string; refresh_token?: string }): string {
  return credentials.refresh_token
    ? `refresh:${credentials.refresh_token}`
    : `access:${credentials.access_token}`;
}

/** What became of a refreshed credential this process tried to write back. */
export type SaveRefreshedResult<T> =
  /** The file still held `base`'s lineage; `next` was written. */
  | { outcome: "saved" }
  /** Another process wrote a different login during the exchange; nothing written. */
  | { outcome: "newer-on-disk"; onDisk: T }
  /** The file was deleted during the exchange (a logout); nothing written. */
  | { outcome: "removed" }
  /** Still unreadable after the bounded re-read: it may be a newer login caught mid-write. */
  | { outcome: "unreadable" }
  /** The atomic write itself failed (EACCES, ENOSPC); the old file is intact. */
  | { outcome: "write-failed" };

/**
 * unchanged  : same path, same stamp as the last GOOD read
 * reloaded   : the stamp moved; the file parsed and validated; `value` replaced
 * removed    : ENOENT; `value` becomes null
 * unreadable : the file exists but cannot be read, parsed or validated; `value` keeps
 *              the last good credentials and the stamp is not recorded
 */
export type DiskSync = "unchanged" | "reloaded" | "removed" | "unreadable";

/** Re-reads of an unreadable file before `settle()` gives up, and the pause between them. */
const SETTLE_RETRIES = 3;
const SETTLE_DELAY_MS = 25;

export interface CredentialFileOptions<T> {
  /** Read per call, so a test path seam works. */
  path: () => string;
  validate: (data: unknown) => data is T;
  /** Log label: "GrokOAuth", "KimiOAuth". */
  label: string;
}

export class CredentialFileState<T extends { access_token: string; refresh_token?: string }> {
  private current: T | null = null;
  /** The path and stamp of the last GOOD read (or of a confirmed absence). */
  private recorded: { path: string; stamp: FileStamp | null } | null = null;

  constructor(private readonly opts: CredentialFileOptions<T>) {}

  /** The last GOOD credentials, or null when never loaded or removed. No I/O. */
  get value(): T | null {
    return this.current;
  }

  /** stat; compare with the recorded {path, stamp}; read only when either differs. */
  syncFromDisk(): DiskSync {
    const path = this.opts.path();
    const label = this.opts.label;
    const stamp = statCredentialFile(path);

    if (stamp === null) {
      if (this.current !== null) log(`[${label}] credential file removed on disk; signed out`);
      this.current = null;
      this.recorded = { path, stamp: null };
      return "removed";
    }
    if ("error" in stamp) return this.unreadable(path);

    const recorded = this.recorded;
    if (recorded && recorded.path === path && recorded.stamp && sameStamp(recorded.stamp, stamp)) {
      return "unchanged";
    }

    let data: unknown;
    try {
      data = JSON.parse(readFileSync(path, "utf-8"));
    } catch {
      return this.unreadable(path);
    }
    if (!this.opts.validate(data)) return this.unreadable(path);

    const firstLoad = recorded === null || recorded.path !== path;
    this.current = data;
    this.recorded = { path, stamp };
    log(
      firstLoad
        ? `[${label}] Loaded credentials from file`
        : `[${label}] credential file changed on disk; reloaded`
    );
    return "reloaded";
  }

  /** `syncFromDisk()`, and on "unreadable" re-read up to 3 times, 25 ms apart. */
  async settle(): Promise<DiskSync> {
    let result = this.syncFromDisk();
    for (let i = 0; i < SETTLE_RETRIES && result === "unreadable"; i++) {
      await new Promise((resolve) => setTimeout(resolve, SETTLE_DELAY_MS));
      result = this.syncFromDisk();
    }
    return result;
  }

  /** A login: the user's intent, written unconditionally (atomic). */
  saveLogin(next: T): void {
    const path = this.opts.path();
    const stamp = writeCredentialFileAtomic(path, next);
    this.current = next;
    this.recorded = { path, stamp };
  }

  /**
   * Hold `next` in memory WITHOUT writing it or recording a stamp: the next sync
   * reads the file again, and a newer login that finished writing wins.
   */
  keepInMemory(next: T): void {
    this.current = next;
  }

  /**
   * A refresh result. Settles first, then writes `next` ONLY if the file still holds
   * `base`'s lineage (compare-and-set on the login, not on the stamp: our own
   * previous write also moves the stamp). A refresh that raced a login therefore
   * cannot undo the login. Never throws.
   */
  async saveRefreshed(base: T, next: T): Promise<SaveRefreshedResult<T>> {
    const label = this.opts.label;
    const sync = await this.settle();
    if (sync === "unreadable") {
      log(
        `[${label}] credential file unreadable after the token refresh; kept the refreshed token in memory, not written`
      );
      return { outcome: "unreadable" };
    }
    const onDisk = this.current;
    if (sync === "removed" || onDisk === null) return { outcome: "removed" };
    if (lineageOf(onDisk) !== lineageOf(base)) {
      log(`[${label}] credential file changed during the token refresh; kept the newer file`);
      return { outcome: "newer-on-disk", onDisk };
    }
    const path = this.opts.path();
    try {
      const stamp = writeCredentialFileAtomic(path, next);
      this.current = next;
      this.recorded = { path, stamp };
      log(`[${label}] Credentials saved to ${path}`);
      return { outcome: "saved" };
    } catch (err) {
      const code = (err as NodeJS.ErrnoException | null)?.code ?? "error";
      log(
        `[${label}] could not write the refreshed credentials (${path}, ${code}); kept them in memory`
      );
      return { outcome: "write-failed" };
    }
  }

  /**
   * A rejected login (Kimi): delete the file ONLY if it still holds `base`'s lineage.
   * A login another process wrote since `base` was read is never deleted, and an
   * unreadable file (possibly a newer login caught mid-write) is left alone.
   */
  async deleteIfUnchanged(
    base: T
  ): Promise<"deleted" | "newer-on-disk" | "removed" | "unreadable"> {
    const label = this.opts.label;
    const sync = await this.settle();
    if (sync === "removed") return "removed";
    if (sync === "unreadable") {
      log(`[${label}] login rejected, but the credential file is unreadable; not deleting it`);
      return "unreadable";
    }
    const onDisk = this.current;
    if (onDisk === null) return "removed";
    if (lineageOf(onDisk) !== lineageOf(base)) {
      log(`[${label}] login rejected, but the credential file changed on disk; not deleting it`);
      return "newer-on-disk";
    }
    const path = this.opts.path();
    try {
      unlinkSync(path);
    } catch (err) {
      if ((err as NodeJS.ErrnoException | null)?.code !== "ENOENT") return "unreadable";
    }
    this.current = null;
    this.recorded = { path, stamp: null };
    return "deleted";
  }

  /** Forget the in-memory credentials (a logout in this process). */
  forget(): void {
    this.current = null;
  }

  private unreadable(path: string): DiskSync {
    log(
      `[${this.opts.label}] credential file unreadable (${path}); kept the last good credentials`
    );
    return "unreadable";
  }
}

export interface RefreshAndCommitOptions<T> {
  /** Whether a credential's access token can still be used without a refresh. */
  isValid: (credentials: T) => boolean;
  /** The terminal "No … credentials found. Please run `claudish login …`" error. */
  noCredentials: () => Error;
}

/**
 * Refresh this process's credentials and commit the result to the file, without ever
 * undoing a login another process wrote meanwhile. ONE implementation, shared by
 * `OAuthManager` and `KimiOAuth`, so the adopt and retry-once rules cannot drift.
 *
 * - `refresh(current)` does the network exchange only and returns the next
 *   credentials; it never writes.
 * - A failed refresh is not reported yet: the file is settled first. If it now holds
 *   a different login (`claudish login` ran elsewhere), that login is used: its token
 *   when still valid, else ONE refresh from its refresh token. Otherwise the original
 *   error is rethrown unchanged (same object), so its classification at the auth
 *   sites is untouched and no status is invented.
 * - The result is committed with `saveRefreshed`: written only if the file still holds
 *   the lineage we refreshed from; a newer login on disk is adopted instead; a deleted
 *   file (logout) is not recreated; an unreadable file or a failed write keeps the
 *   refreshed token in memory and signs with it.
 *
 * Returns the access token to sign with.
 */
export async function refreshAndCommit<T extends { access_token: string; refresh_token?: string }>(
  state: CredentialFileState<T>,
  refresh: (current: T) => Promise<T>,
  opts: RefreshAndCommitOptions<T>,
  label = "credentials"
): Promise<string> {
  const base = state.value;
  if (!base) throw opts.noCredentials();

  let next: T;
  try {
    next = await refresh(base);
  } catch (err) {
    await state.settle();
    const now = state.value;
    if (now && lineageOf(now) !== lineageOf(base)) {
      log(
        `[${label}] token refresh failed, but the credential file changed on disk; using the newer login`
      );
      return useLogin(state, now, refresh, opts, label, false);
    }
    throw err;
  }
  return commit(state, base, next, refresh, opts, label, true);
}

/** Sign with `login` (a login another process wrote): its token if valid, else refresh once. */
async function useLogin<T extends { access_token: string; refresh_token?: string }>(
  state: CredentialFileState<T>,
  login: T,
  refresh: (current: T) => Promise<T>,
  opts: RefreshAndCommitOptions<T>,
  label: string,
  mayRetry: boolean
): Promise<string> {
  if (opts.isValid(login)) return login.access_token;
  const next = await refresh(login);
  return commit(state, login, next, refresh, opts, label, mayRetry);
}

async function commit<T extends { access_token: string; refresh_token?: string }>(
  state: CredentialFileState<T>,
  base: T,
  next: T,
  refresh: (current: T) => Promise<T>,
  opts: RefreshAndCommitOptions<T>,
  label: string,
  mayRetry: boolean
): Promise<string> {
  const result = await state.saveRefreshed(base, next);
  switch (result.outcome) {
    case "saved":
      return next.access_token;
    case "newer-on-disk":
      // Discard our result. A newer login that is already expired is refreshed once;
      // past that one retry, our fresh token signs this request from memory.
      if (opts.isValid(result.onDisk) || mayRetry) {
        return useLogin(state, result.onDisk, refresh, opts, label, false);
      }
      state.keepInMemory(next);
      return next.access_token;
    case "removed":
      // A logout during the exchange is not undone.
      throw opts.noCredentials();
    case "unreadable":
    case "write-failed":
      state.keepInMemory(next);
      return next.access_token;
  }
}