@scrylog/cli 0.2.0 → 0.3.0

package/src/usage/resolvers/claude-auth.ts

@@ -1,13 +1,37 @@
-import { execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { TokenResolver } from "../resolver";
 import type { ClaudeOAuthCredentials } from "../types";
 import { IS_MAC } from "../../shared/platform";
+import { keychainCoordinator, CLAUDE_SAFE_STORAGE_ITEMS } from "./keychain-coordinator";
 import { ClaudeDesktopAuthResolver } from "./claude-desktop-auth";
 
+export const CLAUDE_KEYCHAIN_TOKEN_SERVICES = ["claude-api-oauth", "Claude Code-credentials"] as const;
+
+const DEFAULT_STALE_RESCAN_INTERVAL_MS = 10 * 60 * 1_000;
+
+export interface ClaudeAuthResolverOptions {
+  candidatesSource?: () => Promise<ClaudeOAuthCredentials[]>;
+  staleRescanIntervalMs?: number;
+  now?: () => number;
+}
+
 export class ClaudeAuthResolver implements TokenResolver<ClaudeOAuthCredentials> {
+  private cached?: ClaudeOAuthCredentials;
+  private nextScanAt = 0;
+  private readonly staleRescanIntervalMs: number;
+  private readonly now: () => number;
+  /** Last blocking keychain description seen while resolving candidates. */
+  private lastKeychainFailure: string | null = null;
+
+  constructor(
+    private readonly options: ClaudeAuthResolverOptions = {},
+  ) {
+    this.staleRescanIntervalMs = options.staleRescanIntervalMs ?? DEFAULT_STALE_RESCAN_INTERVAL_MS;
+    this.now = options.now ?? Date.now;
+  }
+
   private readonly debug = (message: string, meta?: Record<string, unknown>) => {
     // Avoid coupling to logger; stderr debug line is acceptable for resolver diagnostics.
     if (process.env.SCRYLOG_DEBUG_AUTH) {
@@ -16,12 +40,55 @@ export class ClaudeAuthResolver implements TokenResolver<ClaudeOAuthCredentials>
   };
 
   async resolve(): Promise<ClaudeOAuthCredentials | null> {
+    const cached = this.cached;
+    if (cached && !cached.isStale) return cached;
+    // Debounce full candidate scans (which include keychain reads) while a
+    // cached-but-stale credential exists, so polls never scan every cycle.
+    if (cached && this.now() < this.nextScanAt) return cached;
+    const selected = selectClaudeCredentials(await this.resolveCandidates());
+    this.cached = selected ?? undefined;
+    this.nextScanAt = this.now() + this.staleRescanIntervalMs;
+    this.lastKeychainFailure = selected
+      ? null
+      : keychainCoordinator.describeBlockingFailure([
+          { service: CLAUDE_KEYCHAIN_TOKEN_SERVICES[0]! },
+          { service: CLAUDE_KEYCHAIN_TOKEN_SERVICES[1]! },
+          ...CLAUDE_SAFE_STORAGE_ITEMS,
+        ]);
+    return this.cached ?? null;
+  }
+
+  /**
+   * Actionable keychain diagnostic for the latest resolution attempt, or null
+   * when the last attempt's failure was not keychain-related (missing items,
+   * absent caches are not surfaced).
+   */
+  describeKeychainFailure(): string | null {
+    return this.lastKeychainFailure;
+  }
+
+  /** Invalidates the daemon-lifetime credential cache (e.g. after a 401). */
+  invalidate(): void {
+    this.cached = undefined;
+    this.nextScanAt = 0;
+    for (const service of CLAUDE_KEYCHAIN_TOKEN_SERVICES) {
+      keychainCoordinator.clearMemo(service);
+    }
+  }
+
+  async resolveCandidates(): Promise<ClaudeOAuthCredentials[]> {
+    if (this.options.candidatesSource) return this.options.candidatesSource();
+    return this.resolveCandidatesUncached();
+  }
+
+  private async resolveCandidatesUncached(): Promise<ClaudeOAuthCredentials[]> {
+    const candidates: ClaudeOAuthCredentials[] = [];
+
     // 1. macOS Keychain is the primary store on macOS.
     if (IS_MAC) {
-      const services = ["claude-api-oauth", "Claude Code-credentials"];
-      for (const service of services) {
-        const creds = this.tryService(service);
-        if (creds) return creds;
+      for (const service of CLAUDE_KEYCHAIN_TOKEN_SERVICES) {
+        const creds = await this.tryService(service);
+        if (creds) candidates.push(creds);
       }
     } else {
       this.debug("Keychain not available on this platform", { platform: process.platform });
@@ -33,33 +100,34 @@ export class ClaudeAuthResolver implements TokenResolver<ClaudeOAuthCredentials>
     //    %APPDATA%/Anthropic/Claude/config.json (Windows).  This covers the
     //    common case where the user has Claude Desktop but not Claude Code CLI.
     const desktopCreds = await new ClaudeDesktopAuthResolver().resolve();
-    if (desktopCreds) return desktopCreds;
+    if (desktopCreds) candidates.push(desktopCreds);
 
     // 3. Linux/WSL/Windows: Claude Code stores credentials in ~/.claude/.credentials.json
     const fileCreds = this.tryCredentialsFile();
-    if (fileCreds) return fileCreds;
+    if (fileCreds) candidates.push(fileCreds);
 
     // 4. Universal env-var fallback
     const envToken = process.env.CLAUDE_CODE_OAUTH_TOKEN;
     if (envToken) {
-      return { accessToken: envToken };
+      candidates.push({
+        accessToken: envToken,
+        owner: "environment",
+        credentialSource: "environment",
+      });
     }
 
-    return null;
+    return candidates;
   }
 
   async isAvailable(): Promise<boolean> {
     return (await this.resolve()) !== null;
   }
 
-  private tryService(service: string): ClaudeOAuthCredentials | null {
+  private async tryService(service: string): Promise<ClaudeOAuthCredentials | null> {
     try {
-      const output = execSync(
-        `security find-generic-password -s "${service}" -w`,
-        { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }
-      ).trim();
+      const output = await keychainCoordinator.read(service);
       if (!output) return null;
-      return this.parseCredentialsJson(output);
+      return parseClaudeCredentialsJson(output, "keychain");
     } catch (error) {
       this.debug("Keychain lookup failed", { service, error: error instanceof Error ? error.message : String(error) });
       return null;
@@ -72,37 +140,69 @@ export class ClaudeAuthResolver implements TokenResolver<ClaudeOAuthCredentials>
 
     const claudeDir = process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
     const path = join(claudeDir, ".credentials.json");
-    if (!existsSync(path)) return null;
-
     try {
       const raw = readFileSync(path, "utf8");
-      return this.parseCredentialsJson(raw);
+      return parseClaudeCredentialsJson(raw, "credentials-file");
     } catch (error) {
       this.debug("Failed to read credentials file", { path, error: error instanceof Error ? error.message : String(error) });
       return null;
     }
   }
 
-  private parseCredentialsJson(input: string): ClaudeOAuthCredentials | null {
-    try {
-      const parsed = JSON.parse(input) as Record<string, unknown>;
-      // Handle nested structure: { claudeAiOauth: { accessToken, ... } }
-      const inner = parsed.claudeAiOauth && typeof parsed.claudeAiOauth === "object"
-        ? parsed.claudeAiOauth as Record<string, unknown>
-        : parsed;
-      const accessToken = inner.accessToken ?? inner.access_token;
-      if (!accessToken) return null;
-      return {
-        accessToken: String(accessToken),
-        refreshToken: inner.refreshToken ? String(inner.refreshToken) : undefined,
-        expiresAt: inner.expiresAt ? String(inner.expiresAt) : undefined,
-        scopes: Array.isArray(inner.scopes) ? inner.scopes.map(String) : undefined,
-        rateLimitTier: inner.rateLimitTier ? String(inner.rateLimitTier) : undefined,
-        subscriptionType: inner.subscriptionType ? String(inner.subscriptionType) : undefined,
-      };
-    } catch {
-      // Not JSON — treat the raw string as an access token.
-      return { accessToken: input.trim() };
-    }
+}
+
+const EXPIRY_SKEW_MS = 60_000;
+
+function parseExpiry(value: unknown): number | undefined | null {
+  if (value === undefined || value === null || value === "") return undefined;
+  const millis = typeof value === "number"
+    ? value
+    : typeof value === "string" && /^\d+$/.test(value.trim())
+      ? Number(value)
+      : typeof value === "string"
+        ? Date.parse(value)
+        : Number.NaN;
+  return Number.isFinite(millis) && millis > 0 ? millis : null;
+}
+
+export function parseClaudeCredentialsJson(
+  input: string,
+  credentialSource: "keychain" | "credentials-file",
+  now = Date.now(),
+): ClaudeOAuthCredentials | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(input);
+  } catch {
+    return null;
   }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const outer = parsed as Record<string, unknown>;
+  const inner = outer.claudeAiOauth && typeof outer.claudeAiOauth === "object" && !Array.isArray(outer.claudeAiOauth)
+    ? outer.claudeAiOauth as Record<string, unknown>
+    : outer;
+  const token = inner.accessToken ?? inner.access_token;
+  if (typeof token !== "string" || !token.trim()) return null;
+
+  const expiryMillis = parseExpiry(inner.expiresAt ?? inner.expires_at);
+  if (expiryMillis === null) return null;
+  return {
+    accessToken: token.trim(),
+    refreshToken: typeof (inner.refreshToken ?? inner.refresh_token) === "string"
+      ? inner.refreshToken as string ?? inner.refresh_token as string
+      : undefined,
+    expiresAt: expiryMillis === undefined ? undefined : new Date(expiryMillis).toISOString(),
+    owner: "claude",
+    credentialSource,
+    isStale: expiryMillis === undefined || expiryMillis <= now + EXPIRY_SKEW_MS,
+    scopes: Array.isArray(inner.scopes) && inner.scopes.every((scope) => typeof scope === "string")
+      ? inner.scopes
+      : undefined,
+    rateLimitTier: typeof inner.rateLimitTier === "string" ? inner.rateLimitTier : undefined,
+    subscriptionType: typeof inner.subscriptionType === "string" ? inner.subscriptionType : undefined,
+  };
+}
+
+export function selectClaudeCredentials(candidates: ClaudeOAuthCredentials[]): ClaudeOAuthCredentials | null {
+  return candidates.find((candidate) => !candidate.isStale) ?? candidates[0] ?? null;
 }

package/src/usage/resolvers/claude-desktop-auth.ts

@@ -5,6 +5,7 @@ import type { TokenResolver } from "../resolver";
 import type { ClaudeOAuthCredentials } from "../types";
 import { IS_MAC, IS_WINDOWS } from "../../shared/platform";
 import { getChromiumSafeStorageKey, decryptSafeStorageBlob } from "./browser-cookies";
+import { keychainCoordinator, CLAUDE_SAFE_STORAGE_ITEMS } from "./keychain-coordinator";
 
 /**
  * Shape of a single entry in the `oauth:tokenCache` field of Claude Desktop's
@@ -62,7 +63,7 @@ export class ClaudeDesktopAuthResolver implements TokenResolver<ClaudeOAuthCrede
       }
 
       const buf = Buffer.from(blobB64, "base64");
-      const key = getChromiumSafeStorageKey("Claude Safe Storage", "Claude");
+      const key = await getChromiumSafeStorageKey("Claude Safe Storage", "Claude");
       if (!key) {
         this.debug("Failed to retrieve Claude Safe Storage key from Keychain");
         return null;
@@ -94,6 +95,11 @@ export class ClaudeDesktopAuthResolver implements TokenResolver<ClaudeOAuthCrede
     return (await this.resolve()) !== null;
   }
 
+  /** Actionable keychain diagnostic for the latest resolution attempt. */
+  describeKeychainFailure(): string | null {
+    return keychainCoordinator.describeBlockingFailure(CLAUDE_SAFE_STORAGE_ITEMS);
+  }
+
   private getConfigPath(): string | null {
     const home = homedir();
     if (IS_MAC) {
@@ -124,17 +130,18 @@ export class ClaudeDesktopAuthResolver implements TokenResolver<ClaudeOAuthCrede
     const now = Date.now();
     let bestCreds: ClaudeOAuthCredentials | null = null;
     let bestExpiresAt = -Infinity;
+    let bestIsStale = true;
 
     for (const [scopeKey, entry] of Object.entries(cache)) {
       if (!entry.token) continue;
-      // Discard expired entries
-      if (entry.expiresAt !== undefined && entry.expiresAt <= now) continue;
       // Require user:profile scope for the OAuth usage endpoint
       if (!scopeKey.includes("user:profile")) continue;
 
-      const expiresAt = entry.expiresAt ?? Infinity;
-      if (expiresAt > bestExpiresAt) {
+      const isStale = entry.expiresAt === undefined || entry.expiresAt <= now + 60_000;
+      const expiresAt = entry.expiresAt ?? -Infinity;
+      if ((!isStale && bestIsStale) || (isStale === bestIsStale && expiresAt > bestExpiresAt)) {
         bestExpiresAt = expiresAt;
+        bestIsStale = isStale;
 
         // Parse space-separated scopes from the composite key.
         // Key format after the audience URL: "...:<audience>:<scopes>"
@@ -148,6 +155,9 @@ export class ClaudeDesktopAuthResolver implements TokenResolver<ClaudeOAuthCrede
             entry.expiresAt !== undefined
               ? new Date(entry.expiresAt).toISOString()
               : undefined,
+          owner: "claude",
+          credentialSource: "claude-desktop",
+          isStale,
           scopes,
           subscriptionType: entry.subscriptionType,
           rateLimitTier: entry.rateLimitTier,

package/src/usage/resolvers/claude-web.ts

@@ -1,16 +1,82 @@
 import type { TokenResolver } from "../resolver";
 import type { ClaudeWebSession } from "../types";
-import { extractCookies, buildCookieHeader } from "./browser-cookies";
+import { usageWebSessionCache } from "../web-session-cache";
+import { BrowserCookieSourceCursor, buildCookieHeader, hasBrowserCookieSources } from "./browser-cookies";
+import { keychainCoordinator, CLAUDE_SAFE_STORAGE_ITEMS } from "./keychain-coordinator";
+
+export const CLAUDE_WEB_CACHE_KEY = "claude-web";
 
 export class ClaudeWebResolver implements TokenResolver<ClaudeWebSession> {
-  async resolve(): Promise<ClaudeWebSession | null> {
-    const cookies = extractCookies("claude.ai");
-    const sessionKey = cookies.find((c) => c.name === "sessionKey");
-    if (!sessionKey) return null;
-    return { cookieHeader: buildCookieHeader(cookies) };
+  constructor(
+    private readonly cursorFactory: () => BrowserCookieSourceCursor = () =>
+      new BrowserCookieSourceCursor("claude.ai", ["sessionKey"], { preferredBrowserId: "claude-desktop" }),
+  ) {}
+
+  resolve(): Promise<ClaudeWebSession | null> {
+    return Promise.resolve().then(() => this.buildSession());
+  }
+
+  /**
+   * Cache-only resolution for planning and Web extras. Never reads a browser
+   * cookie store and never requests a Safe Storage key.
+   */
+  async resolveCached(): Promise<ClaudeWebSession | null> {
+    const observed = usageWebSessionCache.observe(CLAUDE_WEB_CACHE_KEY);
+    if (!observed.value) return null;
+    return {
+      cookieHeader: observed.value,
+      cookieCandidates: [observed.value],
+      cacheRevision: observed.revision,
+    };
+  }
+
+  /**
+   * True when an import could yield candidates: a cached value exists or some
+   * browser import source is present. Cheap existence checks only — no SQLite
+   * reads and no Keychain requests.
+   */
+  async hasImportSources(): Promise<boolean> {
+    if (usageWebSessionCache.observe(CLAUDE_WEB_CACHE_KEY).value) return true;
+    return hasBrowserCookieSources();
+  }
+
+  private async buildSession(): Promise<ClaudeWebSession | null> {
+    const observed = usageWebSessionCache.observe(CLAUDE_WEB_CACHE_KEY);
+    if (observed.value) {
+      return {
+        cookieHeader: observed.value,
+        cookieCandidates: [observed.value],
+        cacheRevision: observed.revision,
+      };
+    }
+
+    // Cache miss: import the first source. Later sources are only inspected
+    // when the client advances the cursor after a classified auth rejection.
+    const cursor = this.cursorFactory();
+    const candidate = await cursor.next();
+    if (!candidate) return null;
+    const header = buildCookieHeader(candidate.cookies);
+    if (!header) return null;
+    return {
+      cookieHeader: header,
+      cookieCandidates: [header],
+      cacheRevision: observed.revision,
+      importNext: async () => {
+        const next = await cursor.next();
+        return next ? buildCookieHeader(next.cookies) : null;
+      },
+    };
   }
 
   async isAvailable(): Promise<boolean> {
     return (await this.resolve()) !== null;
   }
+
+  /**
+   * Actionable keychain diagnostic for the latest import attempt (e.g. the
+   * Safe Storage read failed), or null when the miss was not keychain-related.
+   */
+  describeKeychainFailure(): string | null {
+    return keychainCoordinator.describeBlockingFailure(CLAUDE_SAFE_STORAGE_ITEMS);
+  }
 }

package/src/usage/resolvers/codex-auth.ts

@@ -1,8 +1,22 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { TokenResolver } from "../resolver";
 import type { CodexOAuthCredentials } from "../types";
+import { UsageError } from "../errors";
+
+const NATIVE_EXPIRY_MARGIN_MS = 5 * 60 * 1_000;
+const NATIVE_REFRESH_MAX_AGE_MS = 8 * 24 * 60 * 60 * 1_000;
+
+export class CodexCredentialSourceError extends UsageError {
+  constructor(
+    public readonly reason: "malformed" | "unreadable",
+    message: string,
+  ) {
+    super(reason === "malformed" ? "invalid-response" : "transient", message);
+    this.name = "CodexCredentialSourceError";
+  }
+}
 
 function getCodexDir(): string {
   if (process.env.CODEX_HOME) return process.env.CODEX_HOME;
@@ -11,7 +25,6 @@ function getCodexDir(): string {
 
 function readConfigToml(codexDir: string): string | undefined {
   const path = join(codexDir, "config.toml");
-  if (!existsSync(path)) return undefined;
   try {
     const content = readFileSync(path, "utf8");
     for (const line of content.split(/\r?\n/)) {
@@ -39,6 +52,38 @@ function decodeJwtClaims(token: string): { email?: string; sub?: string; org_id?
   }
 }
 
+function decodeJwtExpiry(token: string): number | undefined {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload) return undefined;
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as Record<string, unknown>;
+    return typeof claims["exp"] === "number" && Number.isFinite(claims["exp"])
+      ? claims["exp"] * 1_000
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseTimestamp(value: unknown): number | undefined {
+  if (typeof value !== "string") return undefined;
+  const timestamp = Date.parse(value);
+  return Number.isNaN(timestamp) ? undefined : timestamp;
+}
+
+export function isCodexCredentialFresh(
+  credentials: CodexOAuthCredentials,
+  now = Date.now(),
+): boolean {
+  if (credentials.tokenExpiresAt !== undefined) {
+    return credentials.tokenExpiresAt > now + NATIVE_EXPIRY_MARGIN_MS;
+  }
+  if (credentials.lastRefreshAt !== undefined) {
+    return now - credentials.lastRefreshAt < NATIVE_REFRESH_MAX_AGE_MS;
+  }
+  return false;
+}
+
 /**
  * Extract access_token and related fields from Codex auth.json.
  * Codex CLI writes credentials in a nested "tokens" object, e.g.:
@@ -56,10 +101,10 @@ function extractTokens(raw: Record<string, unknown>): {
       : undefined;
 
   const accessToken =
-    typeof raw["access_token"] === "string"
-      ? raw["access_token"]
-      : typeof tokens?.["access_token"] === "string"
-        ? tokens["access_token"]
+    typeof tokens?.["access_token"] === "string"
+      ? tokens["access_token"]
+      : typeof raw["access_token"] === "string"
+        ? raw["access_token"]
         : undefined;
 
   const accountId =
@@ -76,40 +121,52 @@ function extractTokens(raw: Record<string, unknown>): {
 }
 
 export class CodexAuthResolver implements TokenResolver<CodexOAuthCredentials> {
+  constructor(private readonly configuredBaseUrl?: string) {}
+
   async resolve(): Promise<CodexOAuthCredentials | null> {
     const codexDir = getCodexDir();
     const authPath = join(codexDir, "auth.json");
-    if (!existsSync(authPath)) return null;
+    let content: string;
+    try {
+      content = readFileSync(authPath, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw new CodexCredentialSourceError("unreadable", "Codex auth.json could not be read");
+    }
 
     try {
-      const raw = JSON.parse(readFileSync(authPath, "utf8")) as Record<string, unknown>;
+      const parsed = JSON.parse(content) as unknown;
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("expected a JSON object");
+      }
+      const raw = parsed as Record<string, unknown>;
       const tokens = extractTokens(raw);
       if (!tokens.accessToken) return null;
 
       const claims = decodeJwtClaims(tokens.accessToken);
-      const chatgptBaseUrl = readConfigToml(codexDir);
+      const tokenExpiresAt = decodeJwtExpiry(tokens.accessToken) ?? parseTimestamp(raw["expires_at"]);
+      const lastRefreshAt = parseTimestamp(raw["last_refresh"]);
+      const chatgptBaseUrl = this.configuredBaseUrl ?? readConfigToml(codexDir);
 
       return {
         accessToken: tokens.accessToken,
         refreshToken: tokens.refreshToken,
         expiresAt: typeof raw["expires_at"] === "string" ? raw["expires_at"] : undefined,
+        ...(tokenExpiresAt !== undefined ? { tokenExpiresAt } : {}),
+        ...(lastRefreshAt !== undefined ? { lastRefreshAt } : {}),
         accountEmail: claims.email ?? null,
         accountId: tokens.accountId ?? claims.sub ?? claims.org_id ?? null,
         ...(chatgptBaseUrl ? { chatgptBaseUrl } : {}),
       };
-    } catch {
-      return null;
+    } catch (error) {
+      if (error instanceof CodexCredentialSourceError) throw error;
+      throw new CodexCredentialSourceError("malformed", "Codex auth.json is malformed");
     }
   }
 
   async isAvailable(): Promise<boolean> {
-    const codexDir = getCodexDir();
-    const authPath = join(codexDir, "auth.json");
-    if (!existsSync(authPath)) return false;
     try {
-      const raw = JSON.parse(readFileSync(authPath, "utf8")) as Record<string, unknown>;
-      const { accessToken } = extractTokens(raw);
-      return typeof accessToken === "string" && accessToken.length > 0;
+      return (await this.resolve()) !== null;
     } catch {
       return false;
     }