@scrylog/cli 0.1.4 → 0.3.0

package/src/usage/resolvers/keychain-coordinator.ts

@@ -0,0 +1,397 @@
+import { execFile } from "node:child_process";
+import { UsageError } from "../errors";
+
+export interface KeychainProcessResult {
+  stdout: string;
+  code: number | null;
+  killed: boolean;
+  signal: string | null;
+  spawnErrorCode?: string;
+}
+
+export type KeychainRun = (
+  file: string,
+  args: string[],
+  options: { timeoutMs: number; signal?: AbortSignal },
+) => Promise<KeychainProcessResult>;
+
+export interface KeychainCoordinatorOptions {
+  timeoutMs?: number;
+  cooldownMs?: number;
+  timeoutCooldownMs?: number;
+  now?: () => number;
+  run?: KeychainRun;
+  allowPrompts?: () => boolean;
+  onFailure?: (failure: KeychainFailure) => void;
+}
+
+const USER_CANCELED_EXIT = 51;
+const ACCESS_DENIED_EXIT = 45;
+const ITEM_NOT_FOUND_EXIT = 44;
+/** errSecInteractionNotAllowed: the process cannot prompt for authorization. */
+const INTERACTION_NOT_ALLOWED_EXIT = 36;
+
+export type KeychainFailureCode =
+  | "interaction-not-allowed"
+  | "access-denied"
+  | "user-canceled"
+  | "prompt-unanswered"
+  | "cooldown"
+  | "item-not-found"
+  | "spawn-failure"
+  | "read-failure";
+
+export interface KeychainFailure {
+  code: KeychainFailureCode;
+  service: string;
+  account?: string;
+  at: number;
+  cooldownUntil?: number;
+}
+
+/** Safe Storage items whose cooperation decrypts Claude-side credential caches. */
+export const CLAUDE_SAFE_STORAGE_ITEMS = [{ service: "Claude Safe Storage", account: "Claude" }] as const;
+
+const FAILURE_READABLE: Record<KeychainFailureCode, string> = {
+  "interaction-not-allowed": "requires user interaction which is not allowed in this session",
+  "access-denied": "access was denied",
+  "user-canceled": "was canceled by the user",
+  "prompt-unanswered": "authorization prompt went unanswered",
+  cooldown: "is cooling down after a failed read",
+  "item-not-found": "does not exist",
+  "spawn-failure": "could not be launched",
+  "read-failure": "read failed",
+};
+
+/** Long enough for a human to read and answer the macOS authorization dialog. */
+const DEFAULT_PROMPT_TIMEOUT_MS = 90_000;
+/** Suppresses prompt re-issuing after an unanswered dialog (e.g. user is away). */
+const DEFAULT_TIMEOUT_COOLDOWN_MS = 10 * 60 * 1_000;
+
+export const defaultRun: KeychainRun = (file, args, options) =>
+  new Promise((resolve) => {
+    execFile(
+      file,
+      args,
+      {
+        timeout: options.timeoutMs,
+        killSignal: "SIGKILL",
+        signal: options.signal,
+        encoding: "utf8",
+      },
+      (error, stdout) => {
+        // execFile reports success as a null error, so the exit code must be
+        // derived from the error only for non-zero exits; a null error means
+        // the child exited 0 with the secret on stdout.
+        const err = error as (Error & { code?: string | number; killed?: boolean; signal?: string }) | null;
+        if (!err) {
+          resolve({
+            stdout: typeof stdout === "string" ? stdout : "",
+            code: 0,
+            killed: false,
+            signal: null,
+          });
+          return;
+        }
+        resolve({
+          stdout: typeof stdout === "string" ? stdout : "",
+          code: typeof err.code === "number" ? err.code : null,
+          killed: Boolean(err.killed),
+          signal: err.signal ?? null,
+          spawnErrorCode: typeof err.code === "string" ? err.code : undefined,
+        });
+      },
+    );
+  });
+
+export class KeychainCoordinator {
+  private readonly timeoutMs: number;
+  private readonly cooldownMs: number;
+  private readonly timeoutCooldownMs: number;
+  private readonly now: () => number;
+  private readonly run: KeychainRun;
+  private allowPrompts: () => boolean;
+  private onFailure?: (failure: KeychainFailure) => void;
+  private readonly inFlight = new Map<string, Promise<string | null>>();
+  private readonly cooldownUntil = new Map<string, number>();
+  private readonly values = new Map<string, string>();
+  /** Most recent blocking failure per item (cleared on success). */
+  private readonly latestFailures = new Map<string, KeychainFailure>();
+
+  constructor(options: KeychainCoordinatorOptions = {}) {
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_PROMPT_TIMEOUT_MS;
+    this.cooldownMs = options.cooldownMs ?? 6 * 60 * 60 * 1_000;
+    this.timeoutCooldownMs = options.timeoutCooldownMs ?? DEFAULT_TIMEOUT_COOLDOWN_MS;
+    this.now = options.now ?? Date.now;
+    this.run = options.run ?? defaultRun;
+    this.allowPrompts = options.allowPrompts ?? (() => true);
+  }
+
+  configure(configureOptions: Pick<KeychainCoordinatorOptions, "allowPrompts" | "onFailure">): void {
+    if (configureOptions.allowPrompts) this.allowPrompts = configureOptions.allowPrompts;
+    if (configureOptions.onFailure !== undefined) this.onFailure = configureOptions.onFailure;
+  }
+
+  isCoolingDown(service: string, account?: string): boolean {
+    const until = this.cooldownUntil.get(this.keyFor(service, account));
+    return until !== undefined && this.now() < until;
+  }
+
+  clearCooldown(service: string, account?: string): void {
+    this.cooldownUntil.delete(this.keyFor(service, account));
+  }
+
+  /** Clears the memoized value for one item so the next read spawns a query again. */
+  clearMemo(service: string, account?: string): void {
+    const key = this.keyFor(service, account);
+    if (this.values.delete(key)) this.debugMemo("cleared", key);
+  }
+
+  /** Clears every memoized keychain value (daemon restart semantics, tests). */
+  clearAllMemo(): void {
+    this.values.clear();
+  }
+
+  isMemoized(service: string, account?: string): boolean {
+    return this.values.has(this.keyFor(service, account));
+  }
+
+  resetForTesting(): void {
+    this.inFlight.clear();
+    this.cooldownUntil.clear();
+    this.values.clear();
+    this.latestFailures.clear();
+  }
+
+  async read(service: string, account?: string, options?: { signal?: AbortSignal }): Promise<string | null> {
+    const key = this.keyFor(service, account);
+    // A cooldown established by a denied read wins over a memo from an earlier
+    // success: the item was later rejected by the user, so its value must not
+    // be served until the cooldown expires.
+    if (this.isCoolingDown(service, account)) {
+      const original = this.latestFailures.get(key);
+      this.recordFailure(
+        {
+          code: "cooldown",
+          service,
+          account,
+          at: this.now(),
+          cooldownUntil: this.cooldownUntil.get(key),
+        },
+        original,
+      );
+      return null;
+    }
+    const memoized = this.values.get(key);
+    if (memoized !== undefined) {
+      this.debugMemo("hit", key);
+      return memoized;
+    }
+    if (!this.allowPrompts()) return null;
+
+    const existing = this.inFlight.get(key);
+    if (existing) return this.joinWithSignal(existing, options?.signal);
+
+    const attempt = this.readOnce(service, account, key, options).finally(() => {
+      if (this.inFlight.get(key) === attempt) this.inFlight.delete(key);
+    });
+    this.inFlight.set(key, attempt);
+    return this.joinWithSignal(attempt, options?.signal);
+  }
+
+  private async readOnce(
+    service: string,
+    account: string | undefined,
+    key: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<string | null> {
+    if (options?.signal?.aborted) throw new UsageError("cancelled", "Keychain read cancelled");
+
+    const args = ["find-generic-password", "-s", service];
+    if (account) args.push("-a", account);
+    args.push("-w");
+    const result = await this.run("/usr/bin/security", args, {
+      timeoutMs: this.timeoutMs,
+      signal: options?.signal,
+    });
+
+    if (options?.signal?.aborted) throw new UsageError("cancelled", "Keychain read cancelled");
+
+    if (result.code === 0 && result.stdout.trim()) {
+      this.cooldownUntil.delete(key);
+      this.latestFailures.delete(key);
+      const value = result.stdout.trim();
+      this.values.set(key, value);
+      this.debugMemo("stored", key);
+      return value;
+    }
+    if (result.code === USER_CANCELED_EXIT || result.code === ACCESS_DENIED_EXIT) {
+      this.cooldownUntil.set(key, this.now() + this.cooldownMs);
+      this.values.delete(key);
+      this.debugMemo("cleared", key);
+      this.recordFailure(
+        {
+          code: result.code === USER_CANCELED_EXIT ? "user-canceled" : "access-denied",
+          service,
+          account,
+          at: this.now(),
+          cooldownUntil: this.cooldownUntil.get(key),
+        },
+      );
+      return null;
+    }
+    // A timed-out (killed) read means the authorization dialog went unanswered:
+    // re-prompting every poll would hammer the user, so apply the short
+    // timeout cooldown instead of leaving the item unbounded.
+    if (result.killed) {
+      this.cooldownUntil.set(key, this.now() + this.timeoutCooldownMs);
+      this.values.delete(key);
+      this.recordFailure(
+        {
+          code: "prompt-unanswered",
+          service,
+          account,
+          at: this.now(),
+          cooldownUntil: this.cooldownUntil.get(key),
+        },
+      );
+      return null;
+    }
+    if (result.code === ITEM_NOT_FOUND_EXIT || result.spawnErrorCode !== undefined) {
+      // Item-not-found and spawn failures leave no user-visible trace, so
+      // without a cooldown the daemon would re-spawn security on every poll
+      // for an item that does not exist yet (created e.g. after a later login).
+      this.cooldownUntil.set(key, this.now() + this.timeoutCooldownMs);
+      this.values.delete(key);
+      this.debugReadFailure(key, result);
+      this.recordFailure(
+        {
+          code: result.spawnErrorCode !== undefined ? "spawn-failure" : "item-not-found",
+          service,
+          account,
+          at: this.now(),
+          cooldownUntil: this.cooldownUntil.get(key),
+        },
+      );
+      return null;
+    }
+    if (result.code === INTERACTION_NOT_ALLOWED_EXIT) {
+      this.recordFailure(
+        {
+          code: "interaction-not-allowed",
+          service,
+          account,
+          at: this.now(),
+        },
+      );
+      return null;
+    }
+    this.debugReadFailure(key, result);
+    this.recordFailure(
+      {
+        code: "read-failure",
+        service,
+        account,
+        at: this.now(),
+      },
+    );
+    return null;
+  }
+
+  /**
+   * Describes the latest blocking failure of one keychain item (cleared after
+   * a successful read), if that failure is actionable. Benign states — the
+   * item does not exist at all — are not surfaced as diagnostics.
+   */
+  describeService(service: string, account?: string): string | null {
+    const failure = this.latestFailures.get(this.keyFor(service, account));
+    if (!failure || failure.code === "item-not-found") return null;
+    return this.renderFailure(failure);
+  }
+
+  /**
+   * First actionable failure among the given items, or null when none of them
+   * has a blocking failure (missing items and other benign states are ignored).
+   */
+  describeBlockingFailure(
+    items: ReadonlyArray<{ service: string; account?: string }>,
+  ): string | null {
+    for (const { service, account } of items) {
+      const rendered = this.describeService(service, account);
+      if (rendered) return rendered;
+    }
+    return null;
+  }
+
+  /** Renders a failure without any credential material. */
+  private renderFailure(failure: KeychainFailure): string {
+    let text = `Keychain item "${failure.service}" ${FAILURE_READABLE[failure.code]}`;
+    if (failure.code === "interaction-not-allowed") {
+      text +=
+        " — the daemon is running in a non-interactive launch session (background session, pane multiplexer, or service). Start the daemon from a GUI terminal session, or add the daemon binary to the item's access list in Keychain Access";
+    }
+    if (failure.cooldownUntil) {
+      text += ` (cooling down until ${new Date(failure.cooldownUntil).toISOString()})`;
+    }
+    return text;
+  }
+
+  private recordFailure(failure: KeychainFailure, baseForCooldown?: KeychainFailure): void {
+    const key = this.keyFor(failure.service, failure.account);
+    // When a cooldown gate re-reports, carry the original blocking cause so
+    // diagnostics name the root failure, not just the cooldown.
+    const recorded: KeychainFailure = baseForCooldown && failure.code === "cooldown"
+      ? { ...baseForCooldown, at: failure.at, cooldownUntil: failure.cooldownUntil }
+      : failure;
+    if (recorded.code === "cooldown") {
+      recorded.code = baseForCooldown?.code ?? "cooldown";
+    }
+    this.latestFailures.set(key, recorded);
+    this.onFailure?.(recorded);
+  }
+
+  private debugReadFailure(key: string, result: KeychainProcessResult): void {
+    if (process.env.SCRYLOG_DEBUG_AUTH) {
+      const [service, account] = key.split("\u0000");
+      process.stderr.write(
+        `[scrylog:keychain] read failed: ${service}${account ? ` (account: ${account})` : ""}` +
+          ` code=${result.code} killed=${result.killed}` +
+          `${result.spawnErrorCode ? ` spawnError=${result.spawnErrorCode}` : ""}\n`,
+      );
+    }
+  }
+
+  private debugMemo(action: "stored" | "hit" | "cleared", key: string): void {
+    if (process.env.SCRYLOG_DEBUG_AUTH) {
+      const [service, account] = key.split("\u0000");
+      process.stderr.write(
+        `[scrylog:keychain] memo ${action}: ${service}${account ? ` (account: ${account})` : ""}\n`,
+      );
+    }
+  }
+
+  private joinWithSignal(promise: Promise<string | null>, signal?: AbortSignal): Promise<string | null> {
+    if (!signal) return promise;
+    if (signal.aborted) return Promise.reject(new UsageError("cancelled", "Keychain read cancelled"));
+    return new Promise<string | null>((resolve, reject) => {
+      const onAbort = () => reject(new UsageError("cancelled", "Keychain read cancelled"));
+      signal.addEventListener("abort", onAbort, { once: true });
+      promise.then(
+        (value) => {
+          signal.removeEventListener("abort", onAbort);
+          resolve(value);
+        },
+        (error) => {
+          signal.removeEventListener("abort", onAbort);
+          reject(error);
+        },
+      );
+    });
+  }
+
+  private keyFor(service: string, account?: string): string {
+    return `${service}\u0000${account ?? ""}`;
+  }
+}
+
+export const keychainCoordinator = new KeychainCoordinator();

package/src/usage/resolvers/opencode-go-web.ts

@@ -1,11 +1,52 @@
 import type { TokenResolver } from "../resolver";
-import { extractCookies, buildCookieHeader } from "./browser-cookies";
+import { BrowserCookieSourceCursor, buildCookieHeader } from "./browser-cookies";
 
-export class OpenCodeGoWebResolver implements TokenResolver<{ cookies: string }> {
-  async resolve(): Promise<{ cookies: string } | null> {
-    const cookies = extractCookies("opencode.ai");
-    if (cookies.length === 0) return null;
-    return { cookies: buildCookieHeader(cookies) };
+export interface OpenCodeGoWebCandidate {
+  source: string;
+  cookies: string;
+}
+
+export interface OpenCodeGoWebCredentials {
+  candidates: OpenCodeGoWebCandidate[];
+  /** Demand-driven cursor advancement after a classified auth rejection. */
+  importNext?: () => Promise<OpenCodeGoWebCandidate | null>;
+}
+
+export const OPENCODE_GO_EXCLUDED_BROWSERS: ReadonlySet<string> = new Set(["claude-desktop"]);
+
+export class OpenCodeGoWebResolver implements TokenResolver<OpenCodeGoWebCredentials> {
+  constructor(
+    private readonly cursorFactory: () => BrowserCookieSourceCursor = () =>
+      new BrowserCookieSourceCursor("opencode.ai", ["auth", "__Host-auth", "__Host-console_session"], {
+        excludeBrowsers: OPENCODE_GO_EXCLUDED_BROWSERS,
+      }),
+  ) {}
+
+  resolve(): Promise<OpenCodeGoWebCredentials | null> {
+    return Promise.resolve().then(() => this.buildCredentials());
+  }
+
+  private async buildCredentials(): Promise<OpenCodeGoWebCredentials | null> {
+    const cursor = this.cursorFactory();
+    const first = await cursor.next();
+    if (!first) return null;
+    const firstCandidate: OpenCodeGoWebCandidate = {
+      source: `${first.browser}:${first.profile}:${first.database}`,
+      cookies: buildCookieHeader(first.cookies),
+    };
+    if (!firstCandidate.cookies) return null;
+    return {
+      candidates: [firstCandidate],
+      importNext: async () => {
+        const next = await cursor.next();
+        if (!next) return null;
+        const candidate: OpenCodeGoWebCandidate = {
+          source: `${next.browser}:${next.profile}:${next.database}`,
+          cookies: buildCookieHeader(next.cookies),
+        };
+        return candidate.cookies ? candidate : null;
+      },
+    };
   }
 
   async isAvailable(): Promise<boolean> {

package/src/usage/types.ts

@@ -28,6 +28,8 @@ export interface ProviderCostSnapshot {
   currency: string;
   /** Billing period label, e.g. "Monthly" */
   period: string;
+  /** Remaining prepaid balance, independent from used/limit */
+  balance?: number;
   /** Reset timestamp (ISO 8601) */
   resetsAt?: string | null;
   /** Last update timestamp (ISO 8601) */
@@ -97,13 +99,15 @@ export interface ClaudeUsageSnapshot {
   updatedAt: Date;
   accountEmail: string | null;
   accountOrganization: string | null;
+  /** Organization UUID when the source exposes one (Web membership, OAuth profile). */
+  accountOrganizationId: string | null;
   loginMethod: string | null;
   subscriptionType: string | null;
   rateLimitTier: string | null;
 }
 
 export interface OpenCodeGoUsageSnapshot {
-  source: "web";
+  source: "web" | "local" | "api";
   hasMonthlyUsage: boolean;
   rollingUsagePercent: number;
   weeklyUsagePercent: number;
@@ -146,6 +150,11 @@ export interface ClaudeOAuthCredentials {
   accessToken: string;
   refreshToken?: string;
   expiresAt?: string;
+  /** Internal credential authority; never exposed through the usage API. */
+  owner?: "claude" | "environment";
+  /** Internal source identity used to preserve owner recovery rules. */
+  credentialSource?: "keychain" | "credentials-file" | "claude-desktop" | "environment";
+  isStale?: boolean;
   scopes?: string[];
   rateLimitTier?: string;
   subscriptionType?: string;
@@ -155,6 +164,8 @@ export interface CodexOAuthCredentials {
   accessToken: string;
   refreshToken?: string;
   expiresAt?: string;
+  tokenExpiresAt?: number;
+  lastRefreshAt?: number;
   accountEmail?: string | null;
   accountId?: string | null;
   chatgptBaseUrl?: string;
@@ -162,6 +173,15 @@ export interface CodexOAuthCredentials {
 
 export interface ClaudeWebSession {
   cookieHeader: string;
+  /** Ordered, isolated browser/profile candidates for one bounded recovery attempt. */
+  cookieCandidates?: string[];
+  /** Revision observed in the daemon-lifetime in-memory cache. */
+  cacheRevision?: number;
+  /**
+   * Demand-driven cursor advancement: imports the next browser source only
+   * after a classified authentication rejection. Never called during planning.
+   */
+  importNext?: () => Promise<string | null>;
 }
 
 export type ClaudeDataSource = "oauth" | "web" | "cli" | "auto";
@@ -170,12 +190,19 @@ export interface ClaudePlannerDecision {
   primary: ClaudeDataSource;
   fallback: ClaudeDataSource[];
   webExtras: boolean;
+  routes: ClaudePlannedRoute[];
+  webExtrasCredentials?: ClaudeWebSession;
 }
 
+export type ClaudePlannedRoute =
+  | { type: "oauth"; credentials: ClaudeOAuthCredentials }
+  | { type: "web"; credentials: ClaudeWebSession }
+  | { type: "cli"; credentials: string };
+
 export type CodexDataSource = "oauth" | "auto";
 
 export interface CodexUsageSnapshot {
-  source: "oauth";
+  source: "oauth" | "cli";
   planType: string | null;
   primaryWindow: RateWindowLegacy | null;
   secondaryWindow: RateWindowLegacy | null;
@@ -184,6 +211,14 @@ export interface CodexUsageSnapshot {
     unlimited: boolean;
     balance: number | null;
   } | null;
+  /** Monthly extra-usage credit cap when exposed by Codex. */
+  individualLimit?: {
+    used: number;
+    limit: number;
+    resetsAt: Date | null;
+  } | null;
+  /** Whether the OAuth response announced managed spend controls. */
+  spendControlPresent?: boolean;
   updatedAt: Date;
   accountEmail: string | null;
   accountId: string | null;

package/src/usage/web-session-cache.ts

@@ -0,0 +1,37 @@
+export interface WebSessionObservation {
+  value: string | null;
+  revision: number;
+}
+
+interface WebSessionEntry {
+  value: string;
+  revision: number;
+}
+
+export class WebSessionCache {
+  private readonly entries = new Map<string, WebSessionEntry>();
+  private nextRevision = 1;
+
+  observe(key: string): WebSessionObservation {
+    const entry = this.entries.get(key);
+    return entry ? { ...entry } : { value: null, revision: 0 };
+  }
+
+  store(key: string, value: string, expectedRevision?: number): WebSessionObservation | null {
+    const current = this.observe(key);
+    if (expectedRevision !== undefined && current.revision !== expectedRevision) return null;
+
+    const entry = { value, revision: this.nextRevision++ };
+    this.entries.set(key, entry);
+    return { ...entry };
+  }
+
+  clear(key: string, expectedRevision: number): boolean {
+    const current = this.observe(key);
+    if (current.revision !== expectedRevision) return false;
+    if (current.revision === 0) return true;
+    return this.entries.delete(key);
+  }
+}
+
+export const usageWebSessionCache = new WebSessionCache();

package/src/neo-blessed.d.ts

@@ -1,4 +0,0 @@
-declare module "neo-blessed" {
-  import blessed = require("blessed");
-  export = blessed;
-}