@semanticist14/clco 0.1.0

package/src/stream.ts

@@ -0,0 +1,235 @@
+// OpenAI chunks -> Anthropic SSE, shared by chat and Responses routes.
+import type { OpenAIChoice, OpenAIUsage, OpenAIResponse, StreamEventData } from "./wire"
+import { mapStopReason, usageFromOpenAI } from "./translate"
+
+function debugWarn(message: string): void {
+  if (process.env.CLCO_DEBUG) console.error("[clco:debug]", message)
+}
+
+interface ToolTrack {
+  anthropicIndex: number
+  id: string
+  name: string
+  bufferedArgs: string
+  started: boolean
+  open: boolean
+}
+
+export class StreamTranslator {
+  private messageStartSent = false
+  private textOpen = false
+  private textIndex = -1
+  private nextIndex = 0
+  private toolCalls = new Map<number, ToolTrack>()
+  private anyToolStarted = false
+  private latestUsage: OpenAIUsage | undefined
+  private lastFinishReason: OpenAIChoice["finish_reason"] = null
+  private finished = false
+
+  constructor(private model: string) {}
+
+  pushChunk(chunk: OpenAIResponse): StreamEventData[] {
+    // Nothing may be emitted after the message closed.
+    if (this.finished) return []
+    const events: StreamEventData[] = []
+    // Usage may arrive in a dedicated terminal chunk with empty choices
+    // (stream_options include_usage convention); track it from any chunk.
+    if (chunk.usage) this.latestUsage = chunk.usage
+    const choices = Array.isArray(chunk.choices) ? chunk.choices : []
+    const choice = choices[0]
+    if (!choice) return events
+    const delta = choice.delta
+
+    if (!this.messageStartSent) {
+      events.push(this.messageStart(chunk.model || this.model))
+    }
+
+    if (delta?.content) {
+      // Tool blocks must all close before a text block starts (Anthropic
+      // blocks are strictly sequential).
+      this.closeOpenTools(events)
+      if (!this.textOpen) {
+        this.textIndex = this.nextIndex++
+        events.push({
+          event: "content_block_start",
+          data: {
+            type: "content_block_start",
+            index: this.textIndex,
+            content_block: { type: "text", text: "" },
+          },
+        })
+        this.textOpen = true
+      }
+      events.push({
+        event: "content_block_delta",
+        data: {
+          type: "content_block_delta",
+          index: this.textIndex,
+          delta: { type: "text_delta", text: delta.content },
+        },
+      })
+    }
+
+    if (delta?.tool_calls) {
+      for (const call of delta.tool_calls) {
+        let track = this.toolCalls.get(call.index)
+        if (!track) {
+          track = {
+            anthropicIndex: -1,
+            id: "",
+            name: "",
+            bufferedArgs: "",
+            started: false,
+            open: false,
+          }
+          this.toolCalls.set(call.index, track)
+        }
+        // id and name may arrive in separate fragments; only start the block
+        // once both are known.
+        if (call.id) track.id = call.id
+        if (call.function?.name) track.name = call.function.name
+        if (!track.started && track.id && track.name) {
+          if (this.textOpen) {
+            events.push({
+              event: "content_block_stop",
+              data: { type: "content_block_stop", index: this.textIndex },
+            })
+            this.textOpen = false
+          }
+          track.anthropicIndex = this.nextIndex++
+          track.started = true
+          track.open = true
+          this.anyToolStarted = true
+          events.push({
+            event: "content_block_start",
+            data: {
+              type: "content_block_start",
+              index: track.anthropicIndex,
+              content_block: {
+                type: "tool_use",
+                id: track.id,
+                name: track.name,
+                input: {},
+              },
+            },
+          })
+          if (track.bufferedArgs) {
+            events.push(this.jsonDelta(track.anthropicIndex, track.bufferedArgs))
+            track.bufferedArgs = ""
+          }
+        }
+        if (call.function?.arguments) {
+          if (track.started && track.open) {
+            events.push(this.jsonDelta(track.anthropicIndex, call.function.arguments))
+          } else if (track.started) {
+            debugWarn(
+              `dropped ${call.function.arguments.length} chars of late tool arguments (block ${track.anthropicIndex} already closed)`,
+            )
+          } else {
+            // Arguments before id/name: buffer until the block starts.
+            track.bufferedArgs += call.function.arguments
+          }
+        }
+      }
+    }
+
+    // Do NOT close here: with stream_options.include_usage the usage-only
+    // terminal chunk arrives AFTER the finish_reason chunk, and close()
+    // needs it. Store the reason and let finish() (stream end) close.
+    if (choice.finish_reason) {
+      this.lastFinishReason = choice.finish_reason
+    }
+    return events
+  }
+
+  // Upstream ended. Use the stored finish_reason; without one the generation
+  // may be truncated. Keep max_tokens even when a tool block has started:
+  // neither partial arguments nor valid JSON prove the tool turn completed.
+  finish(): StreamEventData[] {
+    if (this.finished) return []
+    return this.close(this.lastFinishReason ?? "length")
+  }
+
+  private jsonDelta(index: number, partialJson: string): StreamEventData {
+    return {
+      event: "content_block_delta",
+      data: {
+        type: "content_block_delta",
+        index,
+        delta: { type: "input_json_delta", partial_json: partialJson },
+      },
+    }
+  }
+
+  private messageStart(model: string): StreamEventData {
+    this.messageStartSent = true
+    const usage = this.latestUsage
+    const cached = usage?.prompt_tokens_details?.cached_tokens
+    return {
+      event: "message_start",
+      data: {
+        type: "message_start",
+        message: {
+          id: `msg_${crypto.randomUUID()}`,
+          type: "message",
+          role: "assistant",
+          content: [],
+          model,
+          stop_reason: null,
+          stop_sequence: null,
+          usage: {
+            input_tokens: Math.max(0, (usage?.prompt_tokens ?? 0) - (cached ?? 0)),
+            output_tokens: 0,
+            ...(cached !== undefined && { cache_read_input_tokens: cached }),
+          },
+        },
+      },
+    }
+  }
+
+  private closeOpenTools(events: StreamEventData[]): void {
+    const open = [...this.toolCalls.values()]
+      .filter((t) => t.open)
+      .sort((a, b) => a.anthropicIndex - b.anthropicIndex)
+    for (const track of open) {
+      events.push({
+        event: "content_block_stop",
+        data: { type: "content_block_stop", index: track.anthropicIndex },
+      })
+      track.open = false
+    }
+  }
+
+  private close(
+    reason: NonNullable<OpenAIChoice["finish_reason"]>,
+  ): StreamEventData[] {
+    if (this.finished) return []
+    this.finished = true
+    const events: StreamEventData[] = []
+    if (!this.messageStartSent) {
+      events.push(this.messageStart(this.model))
+    }
+    this.closeOpenTools(events)
+    if (this.textOpen) {
+      events.push({
+        event: "content_block_stop",
+        data: { type: "content_block_stop", index: this.textIndex },
+      })
+      this.textOpen = false
+    }
+    let stopReason = mapStopReason(reason)
+    if (stopReason === "tool_use" && !this.anyToolStarted) {
+      stopReason = "end_turn"
+    }
+    events.push({
+      event: "message_delta",
+      data: {
+        type: "message_delta",
+        delta: { stop_reason: stopReason, stop_sequence: null },
+        usage: usageFromOpenAI(this.latestUsage),
+      },
+    })
+    events.push({ event: "message_stop", data: { type: "message_stop" } })
+    return events
+  }
+}

package/src/tls.ts

@@ -0,0 +1,234 @@
+// Trust for TLS-inspecting corporate networks (ZTNA, MITM proxies).
+//
+// Every outbound HTTPS call clco makes happens in THIS process — the claude
+// child only ever talks plaintext to the local adapter. So the CA has to be
+// trusted here, and a failure surfaces to the user as an adapter 502 rendered
+// inside claude's UI rather than as a TLS error from claude itself.
+//
+// We pass the bundle per request via Bun's `tls.ca`, which unions with the
+// default trust store rather than replacing it, and needs nothing decided
+// before the process starts. NODE_USE_SYSTEM_CA is a no-op on Bun, whose
+// default set already merges the bundled and system roots.
+//
+// NODE_EXTRA_CA_CERTS is reported to REPLACE the system store rather than add
+// to it on some builds. That did not reproduce here - measured on bun 1.3.14
+// and node 24, adding a private CA left registry.npmjs.org validating - so it
+// is stated as an unconfirmed report rather than as fact. clco uses it for the
+// MCP child, which has no per-request hook, and `tls.ca` for itself.
+
+import { readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join, resolve } from "node:path"
+import { getCACertificates } from "node:tls"
+
+/**
+ * The paths CLCO_CA_BUNDLE names, absolute.
+ *
+ * The single parser, because there used to be two: this one trimmed the raw
+ * value before splitting and the one handing a path to the MCP child did not,
+ * so " /a/ca.pem " worked in-process and reached the child as a cwd-joined
+ * nonsense path - clco's own probe passing while the child could not fetch,
+ * which is the asymmetry that whole code path exists to remove. Absolute
+ * because the child resolves relative paths against its own cwd, and `~` is
+ * expanded because the README documents that spelling and only an unquoted
+ * shell was expanding it.
+ */
+export function caPaths(raw = process.env.CLCO_CA_BUNDLE): string[] {
+  return (raw ?? "")
+    .split(":")
+    .map((path) => path.trim())
+    // A bare "~" is the home DIRECTORY, which readFileSync then reports as
+    // EISDIR - a confusing line for a value that can never be a certificate.
+    .filter((path) => path !== "" && path !== "~")
+    .map((path) =>
+      path === "~" || path.startsWith("~/")
+        ? join(homedir(), path.slice(1))
+        : resolve(path),
+    )
+}
+
+let resolved: string[] | null | undefined
+let readablePath: string | undefined
+
+/**
+ * The default trust store plus any CA named by CLCO_CA_BUNDLE (one path, or
+ * several separated by ":"). Undefined when no extra CA is configured, so the
+ * request keeps Bun's own default handling.
+ */
+export function caBundle(): string[] | undefined {
+  if (resolved !== undefined) return resolved ?? undefined
+  const paths = caPaths()
+  if (paths.length === 0) {
+    resolved = null
+    return undefined
+  }
+  const extra: string[] = []
+  for (const path of paths) {
+    try {
+      extra.push(readFileSync(path, "utf8"))
+      readablePath ??= path
+    } catch (err) {
+      console.error(
+        `[clco] could not read CA bundle: ${path} (${err instanceof Error ? err.message : String(err)})`,
+      )
+    }
+  }
+  if (extra.length === 0) {
+    resolved = null
+    return undefined
+  }
+  try {
+    // Union, never replace.
+    resolved = [...getCACertificates("default"), ...extra]
+  } catch {
+    // An older Bun without the default store: still better to trust the extra
+    // CA than to let the throw turn every upstream request into a 502.
+    resolved = extra
+  }
+  return resolved
+}
+
+/**
+ * The first CLCO_CA_BUNDLE path that actually read, for handing to a child
+ * process that can only take one.
+ *
+ * "First that read", not "first listed": clco used to log ENOENT for a path
+ * and then forward that same path to the MCP server anyway, where bun's only
+ * complaint is a warning on a stderr claude's UI does not show.
+ */
+export function caChildPath(): string | undefined {
+  caBundle()
+  return readablePath
+}
+
+/** Test seam: forget a cached bundle so a changed env is picked up. */
+export function resetCaBundle(): void {
+  resolved = undefined
+  readablePath = undefined
+}
+
+/**
+ * OpenSSL verify codes that mean "I do not trust this chain" - which is what a
+ * TLS-inspecting proxy produces, and what CLCO_CA_BUNDLE fixes. Bun populates
+ * `code` on the thrown error, so this is the reliable discriminator; the
+ * message text is not. Matching on text alone missed
+ * UNABLE_TO_VERIFY_LEAF_SIGNATURE, whose message is "unable to verify the
+ * first certificate" - a proxy presenting a leaf without shipping its
+ * intermediate, i.e. the most ordinary corporate shape there is. It was
+ * reported as an unreachable host, sending the user to their firewall team
+ * instead of to their CA.
+ */
+/**
+ * Codes where the chain and the name are fine but the clock is not. No CA
+ * bundle fixes these, so they are not trust failures - but the host answered,
+ * so they are not "cannot reach" either, which is how an expired MITM
+ * certificate used to send the user to their firewall team.
+ */
+const VALIDITY_CODES = new Set(["CERT_HAS_EXPIRED", "CERT_NOT_YET_VALID"])
+
+/** Whether a failure is an expired or not-yet-valid certificate. */
+export function isCertValidityError(err: unknown): boolean {
+  if (typeof err === "object" && err !== null) {
+    const code = (err as { code?: unknown }).code
+    if (typeof code === "string" && VALIDITY_CODES.has(code)) return true
+  }
+  const message = typeof err === "string" ? err : String((err as Error)?.message ?? err)
+  // The message path matters as much as the code: server.ts classifies a
+  // stringified upstream detail, so a code-only check would leave the new
+  // wording unreachable there.
+  return /certificate has expired|certificate is not yet valid|\bCERT_(HAS_EXPIRED|NOT_YET_VALID)\b/i.test(
+    message,
+  )
+}
+
+const TRUST_CODES = new Set([
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "UNABLE_TO_GET_ISSUER_CERT",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  "CERT_UNTRUSTED",
+  // Deliberately NOT ERR_TLS_CERT_ALTNAME_INVALID: that chain verified and
+  // only the name did not match, so no CA bundle can fix it. Including it made
+  // clco tell a user whose bundle worked perfectly that their bundle did not
+  // cover the chain, and print the whole CA hint besides.
+])
+
+/**
+ * Whether a failure is a broken trust chain rather than an unreachable host.
+ *
+ * Accepts the thrown error (preferred - it carries `code`) or just a message,
+ * since some call sites only have the string.
+ */
+export function isTlsTrustError(err: unknown): boolean {
+  // The depth budget is deliberately not a public parameter: as a second
+  // argument, `msgs.some(isTlsTrustError)` fed it the array index and silently
+  // disabled the cause walk from index 4 on.
+  return trustError(err, 0)
+}
+
+function trustError(err: unknown, depth: number): boolean {
+  if (typeof err === "object" && err !== null) {
+    const code = (err as { code?: unknown }).code
+    if (typeof code === "string" && TRUST_CODES.has(code)) return true
+    // Bounded: a cyclic `cause` chain used to overflow the stack, and since
+    // every caller is an error handler the RangeError escaped the catch that
+    // was about to render a 502 or print the user's real error.
+    if (depth < 4) {
+      const cause = (err as { cause?: unknown }).cause
+      if (cause !== undefined && cause !== err && trustError(cause, depth + 1)) {
+        return true
+      }
+      // undici reports a multi-address failure as an AggregateError, so the
+      // real trust error is in `errors`, not in `cause`.
+      const nested = (err as { errors?: unknown }).errors
+      if (Array.isArray(nested)) {
+        for (const one of nested) {
+          if (one !== err && trustError(one, depth + 1)) return true
+        }
+      }
+    }
+  }
+  const message = typeof err === "string" ? err : String((err as Error)?.message ?? err)
+  // Fallback for a stringified error, or a Bun/Node build that omits the code.
+  // Anchored to the codes and the exact OpenSSL phrasings: a bare /CERT_/ or
+  // /certificate chain/ matched ordinary prose, so an upstream error body
+  // echoed into the adapter's 502 ("rotating certificate chain nightly") drew
+  // the whole CA hint onto a failure that had nothing to do with trust.
+  return (
+    /self[- ]signed certificate( in certificate chain)?|unable to (get local issuer certificate|get issuer certificate|verify the first certificate)/i.test(
+      message,
+    ) ||
+    /\b(DEPTH_ZERO_SELF_SIGNED_CERT|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE|UNABLE_TO_GET_ISSUER_CERT(_LOCALLY)?|CERT_UNTRUSTED)\b/.test(
+      message,
+    )
+  )
+}
+
+/**
+ * What to tell the user about a trust failure.
+ *
+ * Adapts to whether a bundle actually loaded: telling someone who already
+ * exported a CA to export a CA is the advice this message exists to replace,
+ * and the one-line browser status already got this right.
+ */
+export function tlsHint(caLoaded = caBundle() !== undefined): string {
+  if (caLoaded) {
+    return (
+      "\nYour CLCO_CA_BUNDLE loaded, but nothing in it signed this chain.\n" +
+      "  - Export the ISSUING CA, not the leaf certificate the proxy presents.\n" +
+      '  - macOS: security find-certificate -a -p -c "<CA name>" > ca.pem\n' +
+      "  - Several CAs can be joined with \":\" - clco unions them all.\n" +
+      "Never disable TLS verification: your GitHub token goes over that connection."
+    )
+  }
+  return (
+    "\nThis looks like a corporate proxy re-signing TLS. To fix it:\n" +
+    "  1) Get your company CA as a file, then:\n" +
+    "       CLCO_CA_BUNDLE=/path/ca.pem clco ...\n" +
+    "     It is ADDED to the OS trust store, never replaces it.\n" +
+    '  2) Export it from the macOS keychain:\n' +
+    '       security find-certificate -a -p -c "<CA name>" > ca.pem\n' +
+    "Never disable TLS verification: your GitHub token goes over that connection."
+  )
+}