chainlesschain 0.162.177 → 0.162.178

package/src/lib/provider-http-error.js

@@ -0,0 +1,94 @@
+/**
+ * Provider HTTP error parsing shared by agent/chat streaming and `cc llm test`.
+ * Keep structured provider diagnostics while redacting credential-shaped text.
+ */
+
+function safePart(value) {
+  if (value == null) return "";
+  return String(value)
+    .replace(/\s+/g, " ")
+    .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/-]+=*\b/gi, "$1***")
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/gi, "sk-***")
+    .trim()
+    .slice(0, 400);
+}
+
+function errorDetail(payload) {
+  if (payload == null) return { code: "", message: "" };
+  const raw =
+    typeof payload === "object" && payload.error != null
+      ? payload.error
+      : payload;
+  if (typeof raw === "string") {
+    return { code: "", message: safePart(raw) };
+  }
+  if (!raw || typeof raw !== "object") {
+    return { code: "", message: safePart(raw) };
+  }
+  return {
+    code: safePart(raw.code || raw.type),
+    message: safePart(raw.message || raw.error_description || raw.detail),
+  };
+}
+
+/**
+ * A 403 is not necessarily a bad key: providers also use it for overdue
+ * accounts and model-access denials. Preserve the safe code/message so clients
+ * can show the real corrective action.
+ */
+export function formatProviderHttpError(provider, status, payload = null) {
+  const base = `${provider} API error: HTTP ${status}`;
+  const detail = errorDetail(payload);
+  const detailText = [detail.code, detail.message].filter(Boolean).join(": ");
+  const detailSentence = detailText.replace(/[.!?]+$/, "");
+  const classified = `${detail.code} ${detail.message}`.toLowerCase();
+  const authDetail =
+    /unauthori[sz]ed|authentication|invalid.*api[\s_-]*key|api[\s_-]*key.*invalid|incorrect.*api[\s_-]*key|missing.*api[\s_-]*key/.test(
+      classified,
+    );
+  const billingDetail =
+    /account.?overdue|overdue balance|insufficient.*balance|billing|payment required/.test(
+      classified,
+    );
+
+  if (status === 401 || (status === 403 && authDetail)) {
+    return (
+      `${base} — authentication failed: the API key for provider "${provider}" ` +
+      `is missing or invalid. Check "cc config get llm.provider" and ` +
+      `"cc config get llm.apiKey" (or run Configure LLM).` +
+      (detailSentence ? ` Provider response: ${detailSentence}.` : "")
+    );
+  }
+  if (status === 403 && billingDetail) {
+    return (
+      `${base} — ${detailSentence || "the provider account cannot be billed"}. ` +
+      "Check the provider account balance/billing status, then retry."
+    );
+  }
+  if (status === 403) {
+    return (
+      `${base} — access forbidden` +
+      (detailSentence ? `: ${detailSentence}` : "") +
+      ". Check the API key, model access permissions, and account status/balance."
+    );
+  }
+  if (status === 429) return `${base} — rate limited; please retry shortly.`;
+  return detailSentence ? `${base} — ${detailSentence}` : base;
+}
+
+export async function formatProviderResponseError(provider, response) {
+  let payload = null;
+  try {
+    const text = await response.text();
+    if (text) {
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = text;
+      }
+    }
+  } catch {
+    // A broken/empty body still retains the HTTP status diagnosis.
+  }
+  return formatProviderHttpError(provider, response.status, payload);
+}

package/src/lib/remote-approval-bridge.js

@@ -23,10 +23,12 @@
 
 import { randomBytes } from "crypto";
 import { WsRpcClient } from "./ws-rpc-client.js";
+import { ORIGIN, approvalBindingDigest } from "./agent-authority.js";
 import {
-  fingerprintsMatch,
-  OperationApprovalRegistry,
-} from "./operation-fingerprint.js";
+  ApprovalAuthorityStore,
+  defaultApprovalAuthorityStatePath,
+} from "./approval-authority-store.js";
+import { OperationApprovalRegistry } from "./operation-fingerprint.js";
 import {
   buildDirectPairingUri,
   pickLanAddress,
@@ -46,6 +48,9 @@ export class RemoteApprovalBridge {
     decisionTimeoutMs = DEFAULT_DECISION_TIMEOUT_MS,
     createClient = null,
     now = Date.now,
+    approvalStore = undefined,
+    approvalStateFile = null,
+    onSecurityError = null,
   } = {}) {
     if (!wsUrl) throw new Error("wsUrl is required");
     if (!agentSessionId) throw new Error("agentSessionId is required");
@@ -63,12 +68,65 @@ export class RemoteApprovalBridge {
     this._pending = new Map(); // requestId → { resolve, timer, fingerprint }
     this._counter = 0;
     this._closed = false;
+    this._securityErrors = [];
+    this._onSecurityError =
+      typeof onSecurityError === "function" ? onSecurityError : null;
+    const durableStore =
+      approvalStore === undefined
+        ? new ApprovalAuthorityStore({
+            filePath:
+              approvalStateFile ||
+              defaultApprovalAuthorityStatePath(agentSessionId),
+            now: () => this._now(),
+          })
+        : approvalStore;
+    if (
+      !durableStore ||
+      typeof durableStore.issueRequest !== "function" ||
+      typeof durableStore.resolveRequest !== "function" ||
+      typeof durableStore.cancelRequest !== "function"
+    ) {
+      throw new Error(
+        "approvalStore must implement issueRequest/resolveRequest/cancelRequest",
+      );
+    }
     // §8.2 cross-device approval registry: full-tuple operation fingerprints,
     // single-winner across concurrent cards for one logical operation, at-most-
     // once resolution, and validity-window enforcement — all fail-closed.
     this._registry = new OperationApprovalRegistry({
       clock: () => this._now(),
+      store: durableStore,
     });
+    this._approvalStore = durableStore;
+  }
+
+  _recordSecurityError({ action, requestId = null, reason, errorCode = null }) {
+    const entry = {
+      timestamp: this._now(),
+      action: String(action || "approval"),
+      requestId: requestId ? String(requestId) : null,
+      reason: String(reason || "rejected"),
+      errorCode: errorCode ? String(errorCode) : null,
+    };
+    this._securityErrors.push(entry);
+    if (this._securityErrors.length > 1000) this._securityErrors.shift();
+    if (this._onSecurityError) {
+      try {
+        this._onSecurityError({ ...entry });
+      } catch {
+        // Observability is advisory; the approval remains denied.
+      }
+    }
+    return entry;
+  }
+
+  getSecurityErrors(limit = this._securityErrors.length) {
+    const count = Math.max(
+      0,
+      Math.min(Math.floor(Number(limit) || 0), this._securityErrors.length),
+    );
+    if (count === 0) return [];
+    return this._securityErrors.slice(-count).map((entry) => ({ ...entry }));
   }
 
   /** Connect, register the client-hosted remote session, start listening. */
@@ -123,34 +181,76 @@ export class RemoteApprovalBridge {
     const requestId = message.event.requestId || message.event.approvalId;
     const pending = requestId ? this._pending.get(requestId) : null;
     if (!pending) return;
-    // Confused-deputy guard: a resolve that echoes a fingerprint must match the
-    // operation this ask published. A mismatch (stale card / replayed / swapped
-    // body / different session·workspace·env·policy) is rejected — the ask stays
-    // pending and fails closed on timeout. An absent fingerprint is a legacy
-    // device: resolved via this ask's own fingerprint (still window-guarded).
-    if (
-      message.event.fingerprint != null &&
-      !fingerprintsMatch(pending.fingerprint, message.event.fingerprint)
-    ) {
+    // The device must echo the complete durable capability tuple. Missing,
+    // mismatched, stale, duplicate, or expired resolutions never settle an
+    // approval; only the store's successful CAS can return approved=true.
+    const rawAnswer = message.event.answer ?? message.event.approved;
+    const hasDecision =
+      rawAnswer === true ||
+      rawAnswer === false ||
+      rawAnswer === "true" ||
+      rawAnswer === "false" ||
+      rawAnswer === "yes" ||
+      rawAnswer === "no";
+    if (!hasDecision) {
+      this._recordSecurityError({
+        action: "approval.resolve",
+        requestId,
+        reason: "decision-required",
+      });
       return;
     }
-    // Fail-closed §8.2 enforcement: single-winner (superseded card), at-most-once
-    // (duplicate), and validity window (not-yet-valid / expired). A rejected
-    // verdict leaves the ask pending so it still fails closed on timeout.
+    const decision =
+      rawAnswer === true || rawAnswer === "true" || rawAnswer === "yes";
+    const authority = {
+      origin: ORIGIN.REMOTE,
+      authenticated: true,
+      scopes: ["approve"],
+      principalId: message.from || "paired-device",
+      sessionId: this.agentSessionId,
+    };
     const verdict = this._registry.resolve(pending.fingerprint, {
+      requestId,
+      fingerprint: message.event.fingerprint,
+      binding: message.event.binding,
+      sessionId: this.agentSessionId,
+      decision,
+      authority,
+      expectedRevision: message.event.revision,
       now: this._now(),
     });
-    if (!verdict.ok) return;
+    if (!verdict.ok) {
+      this._recordSecurityError({
+        action: "approval.resolve",
+        requestId,
+        reason: verdict.reason,
+        errorCode: verdict.errorCode,
+      });
+      if (verdict.reason === "state-unavailable") {
+        this._settleDeniedForStateFailure(requestId, pending, verdict);
+      }
+      return;
+    }
     this._pending.delete(requestId);
     clearTimeout(pending.timer);
-    const answer = message.event.answer ?? message.event.approved;
     pending.resolve({
-      approved: answer === true || answer === "true" || answer === "yes",
+      approved: verdict.ok === true && verdict.approved === true,
       via: "remote",
       from: message.from || null,
     });
   }
 
+  _settleDeniedForStateFailure(requestId, pending, verdict) {
+    this._pending.delete(requestId);
+    clearTimeout(pending.timer);
+    pending.resolve({
+      approved: false,
+      via: "state-error",
+      from: null,
+      errorCode: verdict?.errorCode || null,
+    });
+  }
+
   /** Number of devices that can approve (excludes this host). */
   async approverCount() {
     try {
@@ -202,7 +302,42 @@ export class RemoteApprovalBridge {
           ? askedAt + effectiveTimeout
           : null,
     };
-    const card = this._registry.issue(desc);
+    const binding = approvalBindingDigest({
+      toolCallId: requestId,
+      args: {
+        tool: tool || null,
+        action,
+        detail,
+        workspace,
+        session: desc.session,
+        targetEnv,
+      },
+      policyDigest: policyVersion,
+    });
+    let card;
+    try {
+      // Persist first. A card that was not durably issued must never become
+      // visible to a device and can therefore never authorize a side effect.
+      card = this._registry.issue(desc, {
+        requestId,
+        binding,
+        now: askedAt,
+      });
+    } catch (error) {
+      const errorCode = error?.code || "CC_APPROVAL_STATE_UNKNOWN";
+      this._recordSecurityError({
+        action: "approval.request",
+        requestId,
+        reason: "state-unavailable",
+        errorCode,
+      });
+      return Promise.resolve({
+        approved: false,
+        via: "state-error",
+        from: null,
+        errorCode,
+      });
+    }
     if (onRequestId) {
       try {
         onRequestId(requestId);
@@ -212,6 +347,20 @@ export class RemoteApprovalBridge {
     }
     return new Promise((resolve) => {
       const timer = setTimeout(() => {
+        const verdict = this._registry.cancel(card.fingerprint, {
+          requestId,
+          expectedRevision: card.revision,
+          reason: "timeout",
+          now: this._now(),
+        });
+        if (!verdict.ok) {
+          this._recordSecurityError({
+            action: "approval.cancel",
+            requestId,
+            reason: verdict.reason,
+            errorCode: verdict.errorCode,
+          });
+        }
         this._pending.delete(requestId);
         this._publish({
           type: "permission.resolved",
@@ -225,6 +374,8 @@ export class RemoteApprovalBridge {
       this._pending.set(requestId, {
         timer,
         fingerprint: card.fingerprint,
+        binding,
+        revision: card.revision,
         resolve: (decision) => {
           this._publish({
             type: "permission.resolved",
@@ -244,6 +395,8 @@ export class RemoteApprovalBridge {
         // Full fingerprint (protocol) + short id / secret-free summary (what the
         // operator eyeballs on the device to confirm it is the SAME card).
         fingerprint: card.fingerprint,
+        binding,
+        revision: card.revision,
         shortId: card.shortId,
         summary: card.summary,
         notBefore: desc.notBefore,
@@ -257,12 +410,39 @@ export class RemoteApprovalBridge {
   resolveLocally(requestId, approved) {
     const pending = this._pending.get(requestId);
     if (!pending) return false;
+    const verdict = this._registry.resolve(pending.fingerprint, {
+      requestId,
+      fingerprint: pending.fingerprint,
+      binding: pending.binding,
+      sessionId: this.agentSessionId,
+      decision: approved === true,
+      authority: {
+        origin: ORIGIN.USER,
+        principalId: "local-terminal",
+        sessionId: this.agentSessionId,
+      },
+      expectedRevision: pending.revision,
+      now: this._now(),
+    });
+    if (!verdict.ok) {
+      this._recordSecurityError({
+        action: "approval.resolve",
+        requestId,
+        reason: verdict.reason,
+        errorCode: verdict.errorCode,
+      });
+      if (verdict.reason === "state-unavailable") {
+        this._settleDeniedForStateFailure(requestId, pending, verdict);
+      }
+      return false;
+    }
     this._pending.delete(requestId);
     clearTimeout(pending.timer);
-    // Consume the registry card so a late remote resolve for the SAME operation
-    // is a `duplicate`, never a second settle.
-    this._registry.resolve(pending.fingerprint, { now: this._now() });
-    pending.resolve({ approved, via: "local", from: null });
+    pending.resolve({
+      approved: verdict.ok === true && verdict.approved === true,
+      via: "local",
+      from: null,
+    });
     return true;
   }
 
@@ -327,10 +507,12 @@ export class RemoteApprovalBridge {
       const decision = await Promise.race([remote, local]);
       // Local answer won → settle the remote ask too (publishes
       // permission.resolved so device UIs clear the pending card).
-      if (decision.via === "local" && requestId) {
-        this.resolveLocally(requestId, decision.approved);
+      if (decision.via === "local") {
+        if (!requestId) return false;
+        const persisted = this.resolveLocally(requestId, decision.approved);
+        return persisted && decision.approved === true;
       }
-      return decision.approved;
+      return decision.approved === true;
     };
   }
 
@@ -338,6 +520,20 @@ export class RemoteApprovalBridge {
     this._closed = true;
     for (const [requestId, pending] of this._pending) {
       clearTimeout(pending.timer);
+      const verdict = this._registry.cancel(pending.fingerprint, {
+        requestId,
+        expectedRevision: pending.revision,
+        reason: "closed",
+        now: this._now(),
+      });
+      if (!verdict.ok) {
+        this._recordSecurityError({
+          action: "approval.cancel",
+          requestId,
+          reason: verdict.reason,
+          errorCode: verdict.errorCode,
+        });
+      }
       pending.resolve({ approved: false, via: "closed", from: null });
       this._pending.delete(requestId);
     }

package/src/lib/side-effect-ledger-store.js

@@ -26,41 +26,82 @@ export const _deps = {
   readEvents: storeReadEvents,
 };
 
+export class SideEffectLedgerPersistenceError extends Error {
+  constructor(operation, sessionId, cause) {
+    const detail = cause?.message || String(cause || "unknown persistence error");
+    super(`Side-effect ledger ${operation} failed for ${sessionId}: ${detail}`, {
+      cause,
+    });
+    this.name = "SideEffectLedgerPersistenceError";
+    this.code =
+      operation === "read"
+        ? "SIDE_EFFECT_LEDGER_READ_FAILED"
+        : "SIDE_EFFECT_LEDGER_PERSIST_FAILED";
+    this.operation = operation;
+    this.sessionId = sessionId;
+  }
+}
+
+function persistenceFailure(operation, sessionId, cause, failIfUnavailable) {
+  if (!failIfUnavailable) return false;
+  throw new SideEffectLedgerPersistenceError(operation, sessionId, cause);
+}
+
 /**
- * Append the current ledger as a chained event. Best-effort — a persistence
- * failure must not crash the operation it is guarding.
+ * Append the current ledger as a chained event. This is Critical state:
+ * persistence failures reject by default so the guarded operation cannot run.
+ * Diagnostic callers may explicitly request advisory best-effort behavior.
  *
  * @param {string} sessionId
  * @param {SideEffectLedger|object} ledger
+ * @param {{failIfUnavailable?:boolean}} [opts]
  * @returns {boolean}
  */
-export function persistSideEffectLedger(sessionId, ledger) {
-  if (!sessionId || !ledger) return false;
-  const snapshot =
-    ledger instanceof SideEffectLedger ? ledger.toJSON() : ledger;
-  if (!snapshot || !Array.isArray(snapshot.ops)) return false;
+export function persistSideEffectLedger(sessionId, ledger, opts = {}) {
+  const failIfUnavailable = opts.failIfUnavailable !== false;
+  if (!sessionId || !ledger) {
+    return persistenceFailure(
+      "write",
+      sessionId || "<missing-session>",
+      new TypeError("sessionId and ledger are required"),
+      failIfUnavailable,
+    );
+  }
+
   try {
+    const snapshot =
+      ledger instanceof SideEffectLedger ? ledger.toJSON() : ledger;
+    if (!snapshot || !Array.isArray(snapshot.ops)) {
+      throw new TypeError("ledger snapshot must contain an ops array");
+    }
     _deps.appendEvent(sessionId, SIDE_EFFECT_LEDGER_EVENT, snapshot);
     return true;
-  } catch {
-    return false;
+  } catch (error) {
+    return persistenceFailure("write", sessionId, error, failIfUnavailable);
   }
 }
 
 /**
  * Rebuild the ledger from the LATEST persisted snapshot, or an empty ledger when
- * the session never persisted one (or on read error).
+ * the session never persisted one. Read/corruption errors reject by default.
  *
  * @param {string} sessionId
- * @param {{clock?:Function}} [opts]
+ * @param {{clock?:Function,failIfUnavailable?:boolean}} [opts]
  * @returns {SideEffectLedger}
  */
 export function loadSideEffectLedger(sessionId, opts = {}) {
+  const failIfUnavailable = opts.failIfUnavailable !== false;
   let events = [];
   try {
     events = _deps.readEvents(sessionId) || [];
-  } catch {
-    return new SideEffectLedger(opts);
+  } catch (error) {
+    const fallback = persistenceFailure(
+      "read",
+      sessionId || "<missing-session>",
+      error,
+      failIfUnavailable,
+    );
+    if (fallback === false) return new SideEffectLedger(opts);
   }
   for (let i = events.length - 1; i >= 0; i--) {
     const e = events[i];
@@ -70,7 +111,17 @@ export function loadSideEffectLedger(sessionId, opts = {}) {
       e.data &&
       Array.isArray(e.data.ops)
     ) {
-      return SideEffectLedger.fromJSON(e.data, opts);
+      try {
+        return SideEffectLedger.fromJSON(e.data, opts);
+      } catch (error) {
+        const fallback = persistenceFailure(
+          "read",
+          sessionId || "<missing-session>",
+          error,
+          failIfUnavailable,
+        );
+        if (fallback === false) return new SideEffectLedger(opts);
+      }
     }
   }
   return new SideEffectLedger(opts);