Skip to content

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

17.3 KB
Raw Blame
/**
 * Call-scoped state carried on a Hono `Context`.
 *
 * A leaf: it imports only `redact.ts` (itself import-free) and Hono's types,
 * so the handlers, the proxy and the logger can all read it without a cycle.
 *
 * Context variables rather than wrappers, because `FallbackHandler` tests
 * `instanceof ComposedHandler` on its candidates: a decorated candidate loses
 * its fallback metadata with no error. Every candidate of a chain receives the
 * same `c`, so a value set here spans every hop of one inbound request.
 */

import type { Context } from "hono";
import type { CredentialArm } from "../../auth/credentials/types.js";
import { type SigningLease, acquireSigningLease } from "../../redact.js";

// ─── Signing secrets ─────────────────────────────────────────────────────────

/**
 * The Context key of a request's signing secrets. Installed by the session
 * app's lease middleware on every inbound request (`proxy-server.ts`).
 */
export const SIGNING_SECRETS_KEY = "claudishSigningSecrets" as const;

/**
 * The credential values one request signed with: kept on the Context for a
 * by-value pass over text this request returns, and held in the process-wide
 * registry (`redact.ts`) through `lease` so every log sink redacts them while
 * the request's work is alive.
 */
export interface SigningSecrets {
  values: Set<string>;
  lease: SigningLease;
}

declare module "hono" {
  interface ContextVariableMap {
    /** This request's signing secrets; see `SIGNING_SECRETS_KEY`. */
    claudishSigningSecrets: SigningSecrets;
  }
}

/** A fresh, empty set with its own registry lease. The caller releases it. */
export function createSigningSecrets(): SigningSecrets {
  return { values: new Set<string>(), lease: acquireSigningLease() };
}

/**
 * The secrets installed on `c`, or a lazily created set when nothing installed
 * one. Every production request path installs one (the session app's
 * middleware); the lazy set exists for callers that build a Context of their
 * own, such as tests. Its lease is never released: there is no point at which
 * such a caller's work is known to have ended, and a fixed timer could expire
 * under a stream that is still logging. Retention costs redaction, never
 * exposure.
 */
export function signingSecretsOf(c: Context): SigningSecrets {
  const installed = readCallVar<SigningSecrets>(c, SIGNING_SECRETS_KEY);
  if (installed) return installed;
  const lazy = createSigningSecrets();
  writeCallVar(c, SIGNING_SECRETS_KEY, lazy);
  return lazy;
}

// ─── Context variable access ─────────────────────────────────────────────────

/**
 * Variables of a context that has no `get`/`set` of its own: a hand-built
 * stand-in for Hono's `Context` (tests pass `{ req, json }` objects). Keyed
 * weakly by the object, so nothing outlives it. A real Context always uses its
 * own variable store.
 */
const detachedCallVars = new WeakMap<object, Map<string, unknown>>();

interface ContextVarStore {
  get?: (key: string) => unknown;
  set?: (key: string, value: unknown) => void;
}

/** Read a call-scoped variable; `undefined` when unset or `c` is not an object. */
export function readCallVar<T>(c: Context | undefined, key: string): T | undefined {
  if (!c || typeof c !== "object") return undefined;
  const store = c as unknown as ContextVarStore;
  if (typeof store.get === "function") return store.get(key) as T | undefined;
  return detachedCallVars.get(c)?.get(key) as T | undefined;
}

/** Write a call-scoped variable; a no-op when `c` is not an object. */
export function writeCallVar(c: Context | undefined, key: string, value: unknown): void {
  if (!c || typeof c !== "object") return;
  const store = c as unknown as ContextVarStore;
  if (typeof store.set === "function") {
    store.set(key, value);
    return;
  }
  let vars = detachedCallVars.get(c);
  if (!vars) {
    vars = new Map();
    detachedCallVars.set(c, vars);
  }
  vars.set(key, value);
}

/** Register `values` on `c`'s set AND its registry lease. */
export function addSigningSecrets(c: Context, values: Iterable<string>): void {
  const secrets = signingSecretsOf(c);
  const list = [...values].filter((v) => typeof v === "string" && v.length > 0);
  for (const value of list) secrets.values.add(value);
  secrets.lease.add(list);
}

/** Header names whose whole value is a credential. Compared lowercase. */
const CREDENTIAL_HEADER_NAMES = new Set([
  "authorization",
  "proxy-authorization",
  "x-api-key",
  "api-key",
  "x-goog-api-key",
  "cookie",
]);

/** Fragments that mark any other header as credential-bearing. */
const CREDENTIAL_HEADER_FRAGMENTS = ["token", "secret", "key"];

/** Query parameters that carry a credential (Gemini's `?key=`). */
const CREDENTIAL_QUERY_NAMES = new Set(["key", "api_key", "token", "access_token"]);

/** An auth scheme word in front of a credential. Not global: no `lastIndex`. */
const AUTH_SCHEME_PREFIX = /^(?:Bearer|Basic|Token)\s+/i;

function isCredentialHeader(name: string): boolean {
  const lower = name.toLowerCase();
  if (CREDENTIAL_HEADER_NAMES.has(lower)) return true;
  return CREDENTIAL_HEADER_FRAGMENTS.some((fragment) => lower.includes(fragment));
}

/** The secret parts of one credential header value. */
function credentialPartsOf(name: string, value: string): string[] {
  const parts = [value];
  const bare = value.replace(AUTH_SCHEME_PREFIX, "");
  if (bare !== value) parts.push(bare);
  if (name.toLowerCase() === "cookie") {
    for (const pair of value.split(";")) {
      const eq = pair.indexOf("=");
      if (eq > 0) parts.push(pair.slice(eq + 1).trim());
    }
  }
  return parts;
}

/**
 * The credential values in one signed request: every credential-bearing
 * header (scheme word removed as well as kept) and the endpoint's credential
 * query parameters. Values only; names never leave this function.
 */
export function credentialValuesFromRequest(
  headers: Record<string, string> | undefined,
  endpoint?: string
): string[] {
  const out: string[] = [];
  for (const [name, value] of Object.entries(headers ?? {})) {
    if (typeof value !== "string" || !value || !isCredentialHeader(name)) continue;
    out.push(...credentialPartsOf(name, value));
  }
  if (endpoint) {
    try {
      for (const [name, value] of new URL(endpoint).searchParams) {
        if (value && CREDENTIAL_QUERY_NAMES.has(name.toLowerCase())) out.push(value);
      }
    } catch {
      // Not an absolute URL: no query to read.
    }
  }
  return out;
}

/**
 * Call `release` once `response`'s body has been fully read, cancelled or has
 * errored; at once when there is no body. The returned Response carries the
 * same status, headers and bytes, pulled through one chunk at a time
 * (`highWaterMark: 0`), so nothing is buffered ahead of the consumer.
 *
 * A cancel is forwarded to the source reader FIRST, so an upstream still
 * generating stops, and whatever it logs while stopping is still redacted.
 * `release` waits for that cancel's promise, and every stream parser resolves
 * it only after cancelling its upstream reader AND after its read loop has
 * settled (`cancelEndsUpstreamWork`, `stream-parsers/upstream-cancel.ts`); a
 * flag-only parser cancel let the loop keep reading and logging frames after
 * the lease was gone.
 *
 * One finalizer decides, and a cancel owns it once it has begun. Cancelling a
 * stream resolves every read outstanding on it with `done` BEFORE the source's
 * own cancel has settled, so a `pull` waiting in `reader.read()` wakes up with
 * `done` while `reader.cancel()` is still waiting for the parser's loop. Were
 * that pull to release, the lease would end before the parser's teardown
 * logging (native-handler's whole-stream log, a parser's usage lines). So
 * `cancelling` is set before `reader.cancel()` is called, and from then on
 * only the cancel path releases, after that cancel has resolved.
 */
export function releaseWhenBodyEnds(response: Response, release: () => void): Response {
  const source = response.body;
  if (!source) {
    release();
    return response;
  }
  const reader = source.getReader();
  let cancelling = false;
  const stream = new ReadableStream<Uint8Array>(
    {
      async pull(controller) {
        let result: Awaited<ReturnType<typeof reader.read>>;
        try {
          result = await reader.read();
        } catch (err) {
          if (cancelling) return;
          release();
          controller.error(err);
          return;
        }
        // A read the cancel below woke up: the cancel path releases, once the
        // upstream work has settled, and this stream is already closed.
        if (cancelling) return;
        if (result.done) {
          release();
          controller.close();
          return;
        }
        controller.enqueue(result.value);
      },
      async cancel(reason) {
        cancelling = true;
        try {
          await reader.cancel(reason);
        } catch {
          // The source is already gone; the release below is what matters.
        } finally {
          release();
        }
      },
    },
    { highWaterMark: 0 }
  );
  return new Response(stream, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  });
}

// ─── Call abort ──────────────────────────────────────────────────────────────

/**
 * The Context key of an internal call's abort signal. Installed ONLY by a
 * caller that issues requests of its own with a deadline (the advisor panel
 * gateway); never on a request from Claude Code. Every reach point reads it
 * through `callAbortSignal`, which returns `undefined` for a main request, so
 * each composition below collapses to the code that ran before it existed.
 *
 * A Context variable, not `c.req.raw.signal`: the inbound request's signal is
 * the CLIENT going away, which the recovery ladder already reads with its own
 * meaning, and a main request must not acquire a second one.
 */
export const CALL_ABORT_SIGNAL_KEY = "claudishCallAbortSignal" as const;

/** Header on the answer to an aborted call. Produced, never compared by status. */
export const CALL_ABORTED_HEADER = "x-claudish-call-aborted";

declare module "hono" {
  interface ContextVariableMap {
    /** An internal call's deadline; see `CALL_ABORT_SIGNAL_KEY`. */
    claudishCallAbortSignal: AbortSignal;
  }
}

/** The call's abort signal, or `undefined` (every main request). */
export function callAbortSignal(c: Context | undefined): AbortSignal | undefined {
  return readCallVar<AbortSignal>(c, CALL_ABORT_SIGNAL_KEY);
}

/** True once the call's deadline has passed. Always false on a main request. */
export function callAborted(c: Context | undefined): boolean {
  return callAbortSignal(c)?.aborted === true;
}

/** The error a stopped reach point rejects with: a DOM `AbortError`. */
export function callAbortError(): Error {
  return new DOMException("the call's deadline passed; claudish stopped its work", "AbortError");
}

/**
 * Stop WAITING for `p` once `signal` aborts; `p` itself is not cancelled. For
 * work that is shared or unbilled (a single-flight token refresh, a quota
 * read), where cancelling would hurt other requests and waiting would hold
 * this one past its deadline. Without a signal, `p` is returned unchanged.
 *
 * The losing promise's rejection is owned here (a no-op `catch`), so a refresh
 * that fails after the abort won never surfaces as an unhandled rejection.
 */
export function raceCallAbort<T>(p: Promise<T>, signal?: AbortSignal): Promise<T> {
  if (!signal) return p;
  p.catch(() => {});
  if (signal.aborted) return Promise.reject(callAbortError());
  return new Promise<T>((resolve, reject) => {
    const onAbort = () => reject(callAbortError());
    signal.addEventListener("abort", onAbort, { once: true });
    p.then(
      (value) => {
        signal.removeEventListener("abort", onAbort);
        resolve(value);
      },
      (err) => {
        signal.removeEventListener("abort", onAbort);
        reject(err);
      }
    );
  });
}

/**
 * Wait `ms`, or less if `signal` aborts first. Resolves `true` when it was
 * aborted. The timer is cleared on abort and the listener removed on expiry,
 * so neither outlives the wait.
 */
export function sleepUnlessAborted(ms: number, signal?: AbortSignal): Promise<boolean> {
  if (signal?.aborted) return Promise.resolve(true);
  return new Promise<boolean>((resolve) => {
    const onAbort = () => {
      clearTimeout(timer);
      resolve(true);
    };
    const timer = setTimeout(() => {
      signal?.removeEventListener("abort", onAbort);
      resolve(false);
    }, ms);
    signal?.addEventListener("abort", onAbort, { once: true });
  });
}

/** `sig` composed with the call's signal; either alone when the other is absent. */
export function withCallSignal(
  sig: AbortSignal | undefined,
  callSignal: AbortSignal | undefined
): AbortSignal | undefined {
  if (!callSignal) return sig;
  if (!sig) return callSignal;
  return AbortSignal.any([sig, callSignal]);
}

/**
 * The answer to a call whose deadline passed: 408 with `CALL_ABORTED_HEADER`.
 * Its caller has already stopped waiting; this exists so every path returns a
 * Response instead of throwing, and so nothing downstream classifies it.
 */
export function abortedResponse(): Response {
  return new Response(
    JSON.stringify({
      type: "error",
      error: {
        type: "timeout_error",
        message: "claudish stopped this call: its deadline passed",
      },
    }),
    {
      status: 408,
      headers: { "content-type": "application/json", [CALL_ABORTED_HEADER]: "1" },
    }
  );
}

// ─── Hop log ─────────────────────────────────────────────────────────────────

/**
 * The Context key of an internal call's hop log. Installed ONLY by a caller
 * that needs to know which hop served it and on which credential arm (the
 * advisor panel gateway); a main request has none and records nothing.
 */
export const HOP_LOG_KEY = "claudishHopLog" as const;

/** How a hop bills, decided right after signing (see `HopAttempt.billing`). */
export type HopBilling = "subscription" | "metered";

/**
 * One `handle()` entry of one hop. A closed set of non-secret fields: no
 * header, no credential, no request body, so a log of these can be printed
 * or serialised as it is.
 */
export interface HopAttempt {
  /** The handler's claudish provider (`provider.name`). */
  provider: string;
  /** The model id this hop sends upstream. */
  wireModel: string;
  /** The arm that signed (`RequestAuth.arm`); null until signed, or when the transport names none. */
  arm: CredentialArm | null;
  /**
   * Set right after signing; null until signed. For a credential-decided
   * provider (`openai-codex`) it is the arm that signed (`oauth` =
   * subscription); for every other provider its `SUBSCRIPTION_PROVIDERS`
   * membership (`ComposedHandler.markHopSigned`).
   */
  billing: HopBilling | null;
  /**
   * The planned hop's provider uid, stamped by a caller that knows which
   * planned hop this entry ran under (the advisor's built-pending hops), so it
   * is never reconstructed from `provider`: a pending `google` hop serves
   * through a transport named `gemini`.
   */
  plannedUid?: string;
}

declare module "hono" {
  interface ContextVariableMap {
    /** An internal call's hop log; see `HOP_LOG_KEY`. */
    claudishHopLog: HopAttempt[];
    /** The planned hop a pending advisor hop runs under; see `PLANNED_HOP_KEY`. */
    claudishPlannedHop: string | undefined;
  }
}

/** The installed hop log, or `undefined` (every main request). */
export function hopLogOf(c: Context | undefined): HopAttempt[] | undefined {
  return readCallVar<HopAttempt[]>(c, HOP_LOG_KEY);
}

/**
 * Append an unsigned entry for a hop whose `handle()` was just entered, and
 * return it so the handler can fill `arm` and `billing` once it has signed.
 * `undefined`, and nothing recorded, when no hop log is installed.
 */
export function recordHopEntry(
  c: Context | undefined,
  provider: string,
  wireModel: string
): HopAttempt | undefined {
  const hops = hopLogOf(c);
  if (!hops) return undefined;
  const plannedUid = readCallVar<string>(c, PLANNED_HOP_KEY);
  const entry: HopAttempt = {
    provider,
    wireModel,
    arm: null,
    billing: null,
    ...(plannedUid ? { plannedUid } : {}),
  };
  hops.push(entry);
  return entry;
}

/**
 * The Context key of the planned hop uid a pending advisor hop is running
 * under. Set only by `withPlannedHop`, only while a hop log is installed.
 */
export const PLANNED_HOP_KEY = "claudishPlannedHop" as const;

/**
 * Run `work` with `plannedUid` on `c`, so every hop-log entry it records
 * carries it; the previous value is restored when the work settles (the next
 * candidate of a chain must not inherit it). Without a hop log, `work` runs
 * unchanged and nothing is written.
 */
export async function withPlannedHop<T>(
  c: Context,
  plannedUid: string,
  work: () => Promise<T>
): Promise<T> {
  if (!hopLogOf(c)) return work();
  const previous = readCallVar<string>(c, PLANNED_HOP_KEY);
  writeCallVar(c, PLANNED_HOP_KEY, plannedUid);
  try {
    return await work();
  } finally {
    writeCallVar(c, PLANNED_HOP_KEY, previous);
  }
}