agent-shim 7.13.1 → 7.14.0

package/dist/types/frontdoor/capability.d.ts

@@ -1,19 +0,0 @@
-/**
- * How a launch's capability token is presented and checked. The token reaches the child twice: as the `x-agent-shim-auth` header on every request it sends (see `AUTH_HEADER`), and as the password in the `HTTPS_PROXY` URL an OAuth launch gets, which every proxy-aware client turns into `Proxy-Authorization: Basic ...` on its CONNECT request. Both are checked against the same live registry with the same constant-time comparison.
- */
-/** The user name in the proxy URL. A label only: the surface checks the password, which is the capability, and ignores the user name, so nothing depends on how a client spells it. */
-export declare const CONNECT_PROXY_USER = "agent-shim";
-/** The realm the CONNECT surface's 407 challenge names, so a client that waits for a challenge before sending credentials knows which ones to send. */
-export declare const CONNECT_PROXY_REALM = "agent-shim front door";
-/**
- * The `HTTPS_PROXY` value for a launch: the CONNECT surface's loopback address with the capability as the URL's password. Both userinfo halves are percent-encoded, because a client percent-decodes userinfo before it builds the `Proxy-Authorization` value, so the surface receives exactly the token whatever characters it holds.
- */
-export declare function connectProxyUrl(port: number, token: string): string;
-/**
- * The capability a `Proxy-Authorization` header value presents: the password half of a Basic credential (everything after the first colon of the decoded user-pass, since RFC 7617 forbids a colon in the user name and permits one in the password). Undefined for any other scheme, a credential with no colon, or an empty password.
- */
-export declare function capabilityFromProxyAuthorization(value: string): string | undefined;
-/**
- * Whether `presented` is one of the live capabilities, compared in constant time: every live token is compared against the presented one in full, with no early exit on a match or a mismatching prefix, so the time a check takes reveals neither which token matched nor how much of a guess was right.
- */
-export declare function isLiveCapability(presented: string, live: Readonly<Iterable<string>>): boolean;

package/dist/types/frontdoor/capture.d.ts

@@ -1,58 +0,0 @@
-import type { IncomingHttpHeaders } from "node:http";
-/**
- * How much of any one chunk is logged. A chunk excerpt only has to identify what the traffic is and carry the first frames of a stream, and 8 KiB is already the head budget this surface applies elsewhere (`MAX_CONNECT_HEAD_BYTES`), so one budget serves both notions of "a diagnostic excerpt".
- */
-export declare const CHUNK_LOG_CAP_BYTES = 8192;
-/**
- * How many body bytes each direction of one request may log in total. Enough to hold a full Remote Control handshake and a long run of its frames, while bounding the file against an unbounded SSE stream that could otherwise grow it without limit. Bytes past the cap are counted, never stored.
- */
-export declare const STREAM_LOG_CAP_BYTES = 262144;
-/** The request facts a capture sees, shaped so both a real `IncomingMessage` and a test's plain object satisfy it. */
-interface CapturedRequestShape {
-    readonly method?: string;
-    readonly url?: string;
-    readonly headers: IncomingHttpHeaders;
-}
-/** The callbacks one piped request's forwarding drives, all optional callers except, so a fake or a partial observer fits the same seam. */
-export interface PassthroughObserver {
-    readonly onRequestChunk: (chunk: Buffer) => void;
-    readonly onResponse: (status: number, headers: IncomingHttpHeaders) => void;
-    readonly onResponseChunk: (chunk: Buffer) => void;
-    readonly onEnd: () => void;
-}
-/** The direction one tapped byte chunk flowed, named from the session's point of view. */
-type StreamDirection = "client-to-server" | "server-to-client";
-/** The byte-level tap for one terminated stream whose protocol the surface does not parse: every chunk both directions, then the end. */
-export interface StreamTap {
-    readonly onChunk: (direction: StreamDirection, chunk: Readonly<Buffer>) => void;
-    readonly onEnd: () => void;
-}
-/** The tap the connect surface drives. `undefined` everywhere means "not capturing"; one object covers the whole door process. */
-export interface ConnectCapture {
-    /** Opens the byte-level tap for one host's terminated stream, whose chunks are recorded verbatim (text, or base64 when not valid UTF-8) under the same caps as piped bodies. Optional because a capture can be stream-silent by construction. */
-    readonly tapStream?: (host: string) => StreamTap;
-    /** Records one authenticated CONNECT target: the host and port only, since a blind tunnel's bytes are unreadable by construction. */
-    readonly connect: (target: {
-        readonly host: string;
-        readonly port: number;
-    }, intercepted: boolean) => void;
-    /** Records one non-routed request's head and returns the observer its forwarding drives, so the capture correlates every later chunk with the request it belongs to. */
-    readonly observePassthrough: (request: CapturedRequestShape) => PassthroughObserver;
-    /** Records one HTTP upgrade request arriving on a terminated session. The surface destroys the socket afterwards either way, with or without a capture, matching Node's own no-listener behaviour exactly. */
-    readonly upgrade: (request: CapturedRequestShape) => void;
-}
-/** Replaces every header value whose name looks like a credential with a marker, keeping every other header verbatim. Returns a fresh object. */
-export declare function redactHeaders(headers: Readonly<IncomingHttpHeaders>): IncomingHttpHeaders;
-/**
- * Redacts one body excerpt for the capture file. A body that parses as JSON is redacted structurally (key-named credentials go even when their shape matches no pattern); anything else gets the substring patterns, which still catch the bearer and JWT forms an OAuth refresh or a Remote Control frame carries. Invalid UTF-8 decodes with replacement characters, which is fine: the excerpt exists to be read, not to be re-encoded.
- */
-export declare function redactBody(chunk: Readonly<Buffer>): string;
-/**
- * The capture the door runs with, or undefined when the environment did not ask for one. Anything but `1` means off, the same exact-value vocabulary the other `AGENT_SHIM_*` diagnostics use, so a stray value never silently records traffic.
- */
-export declare function captureFromEnv(env: NodeJS.ProcessEnv, logsDir: string): ConnectCapture | undefined;
-/**
- * Builds the file-backed capture: one JSON object per line, appended to `file` (conventionally `logs/frontdoor-capture.jsonl`), never read back by the door itself. The directory is created up front rather than per record, so a capture started against a fresh state root cannot race its own first append.
- */
-export declare function createFileCapture(file: string, now?: () => Date): ConnectCapture;
-export {};

package/dist/types/frontdoor/connect.d.ts

@@ -1,209 +0,0 @@
-import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
-import type * as net from "node:net";
-import type { Duplex } from "node:stream";
-import type { ConnectCapture, PassthroughObserver } from "./capture";
-/**
- * The front door's CONNECT surface, so an OAuth session can have agent-shim's routing AND Claude Code's Remote Control at once: Remote Control refuses any `ANTHROPIC_BASE_URL` other than the real API, but happily honours `HTTPS_PROXY`, so OAuth launches route at the proxy layer instead.
- *
- * Nothing is tunnelled or intercepted for a client that has not authenticated: every CONNECT request must present a live launch's capability as its proxy credential (`Proxy-Authorization: Basic`, which clients derive from the credential in the `HTTPS_PROXY` URL the launcher sets), or it is answered 407 before any target is dialled, so the port is no open proxy for other local processes. Pending and authenticated connections are bounded by `ConnectLimits`.
- *
- * Every authenticated CONNECT target is blind-tunnelled byte for byte EXCEPT the intercept hosts (Claude Code's own API and the claude.ai control plane), whose TLS this surface terminates with leaf certificates signed by a locally generated CA. On the API host's terminated session, the paths the front door routes (`/v1/`) are handed to the same ordered pipeline the provider listener serves (the client's Authorization header passes through untouched), and every other path there, and every path on the control plane's session, is piped by this surface to that session's own real upstream over TLS, so Remote Control's streaming, OAuth refreshes, and unknown endpoints bypass the pipeline entirely. When a `capture` is configured, those piped exchanges and every CONNECT target are recorded through it (see `./capture.ts`); the forwarding itself is identical either way.
- */
-/** The API host: Claude Code's own upstream, the one host whose `/v1/` paths the routed pipeline serves. */
-export declare const CONNECT_INTERCEPT_HOST = "api.anthropic.com";
-/**
- * Every CONNECT host whose TLS this surface terminates, each with its own leaf and its own HTTP parser: the API host above, and `platform.claude.com`, the claude.ai control plane where Remote Control's long-lived channel and its handshake live. Terminating the second one is what makes a Remote Control login rejection observable at all: its bytes cross this surface either way, and blind-tunnelling them hides exactly the exchange that failed. Only the API host's `/v1/` paths ever reach the routed pipeline; everything else on either session is piped to that session's own real upstream, so the pipeline's identification and authorisation are never asked to serve another host's traffic.
- */
-export declare const CONNECT_INTERCEPT_HOSTS: readonly string[];
-/**
- * The intercept hosts the surface never parses as HTTP: terminated with ALPN for HTTP/2 and HTTP/1.1 both offered, pumped byte for byte to the real host over TLS (offering upstream only the protocol the client negotiated), and teed into the capture's stream tap when capturing is on. The claude.ai control plane's channel mixes an HTTP/1.1-shaped request with binary HTTP/2 frames, so parsing it as either protocol would destroy or distort it; tapping preserves the channel exactly as a blind tunnel served it while making its bytes observable.
- */
-export declare const CONNECT_TAP_HOSTS: readonly string[];
-/** Paths under this prefix are what the routed pipeline serves; everything else on the terminated session goes to the real upstream. */
-export declare const ROUTED_PATH_PREFIX = "/v1/";
-/** The port HTTPS is served on, both the default when a CONNECT authority names none and the port non-headroom paths are piped to on the real upstream. */
-export declare const HTTPS_PORT = 443;
-/** What the forwarding effect answers with when the upstream is unreachable. */
-export declare const HTTP_BAD_GATEWAY = 502;
-/** Largest CONNECT request head accepted before the connection is refused: a real head is a request line and a few short headers (Host, the proxy credential, a User-Agent), so anything this size is a confused or hostile client. 8 KiB is also the per-header-line limit common HTTP servers apply by default (nginx's `large_client_header_buffers` buffer, Apache's `LimitRequestFieldSize` of 8190 bytes), so no client is built to need a longer line, and a CONNECT head is a few such lines at most. */
-export declare const MAX_CONNECT_HEAD_BYTES = 8192;
-/**
- * The surface's connection deadlines and caps. Production passes `CONNECT_LIMITS`; tests pass small values so a deadline or a cap is reached in milliseconds.
- *
- * A connection is pending from accept until its CONNECT head has arrived, and authenticated once that head presented a live launch's capability. Pending connections are bounded twice, by `headDeadlineMs` and by `maxPendingHeads` (reaching the cap evicts the oldest pending connection rather than refusing the newest, so a squatter holding open half-sent heads cannot lock live launches out: a real client's head arrives in its first segment and is authenticated long before that many newer connections could push it out). Authenticated connections are bounded by `maxTunnels` and revoked when their launch ends; they have no idle timeout (see `CONNECT_LIMITS`).
- */
-export interface ConnectLimits {
-    /** How long a connection may take to deliver its whole CONNECT head before it is answered 408 and closed. */
-    readonly headDeadlineMs: number;
-    /** How many connections may be waiting for their head at once; one more evicts the oldest. */
-    readonly maxPendingHeads: number;
-    /** How many authenticated connections (blind tunnels and terminated sessions together) may be open at once; one more is answered 503 and closed. */
-    readonly maxTunnels: number;
-    /** How often every authenticated connection's capability is re-checked, closing the connections of any launch that has since ended. */
-    readonly revalidateMs: number;
-}
-/**
- * The production limits, each derived from what the surface's real clients do.
- *
- * `headDeadlineMs`: every client checked (Claude Code, curl, Node's own proxy support, Python's urllib) sends its whole CONNECT head, credential included, the moment the TCP connection opens, without waiting for anything from the proxy, so on loopback the head arrives within milliseconds. The deadline only has to outlast a door process stalled by a loaded machine, and ten seconds is three orders of magnitude above any such stall while still ending a slowloris connection quickly.
- *
- * `maxPendingHeads`: since a real head arrives in the first segment, the pending set at any instant holds only connections opened in the same instant. The largest real burst is a package manager or similar running inside a session, which opens its parallel downloads through HTTPS_PROXY at once; 64 covers the defaults of npm (`maxsockets` 15) and pnpm (`network-concurrency` 16) several times over, and eviction means even a larger burst only costs a retry, never a lockout.
- *
- * `maxTunnels`: each authenticated connection holds two descriptors (the client's and the upstream's). Node raises its soft descriptor limit to the hard limit at start, and 4096 is the smallest hard limit common Linux distributions ship (macOS's is far higher), so 1024 tunnels keep the surface to half of it, leaving the provider and direct listeners room to serve rather than all three failing with EMFILE. It is still many times what concurrent sessions hold: each keeps a handful of tunnels plus whatever bursts its tools make.
- *
- * `revalidateMs`: the supervisor prunes dead launches from the registry once per `FRONTDOOR_POLL_MS`, so re-checking more often than that could never find anything newly dead.
- *
- * There is deliberately no idle timeout on an authenticated connection: Remote Control and other long-lived streams can sit silent for as long as the far end chooses between events, at an interval the surface cannot know, so any idle timeout would cut legitimate sessions. Authenticated connections are bounded instead by who can open them (only a live launch's process tree holds the capability), by `maxTunnels`, and by revocation: a launch that ends loses every connection it opened at the next revalidation.
- */
-export declare const CONNECT_LIMITS: ConnectLimits;
-/** One parsed CONNECT authority, the host lowercased and the port defaulted. */
-export interface ConnectTarget {
-    readonly host: string;
-    readonly port: number;
-}
-/** Parses a CONNECT authority (`host:port`, or a bare `host` meaning 443), or undefined when it names no host or a non-numeric port. */
-export declare function parseConnectTarget(authority: string): ConnectTarget | undefined;
-/** Whether a CONNECT target's host (port already stripped) is one whose TLS this proxy terminates. */
-export declare function isInterceptedHost(host: string, interceptHosts: readonly string[]): boolean;
-/** Whether a request path on the terminated session is one the routed pipeline serves. The query string stays part of the path: `/v1/messages?beta=true` is still the pipeline's. */
-export declare function servedByPipeline(path: string | undefined): boolean;
-/**
- * Headers a forwarded HTTP message keeps: everything except the hop-by-hop set, which belongs to whichever connection carried it and must not leak onto the next one. The `Connection` header's own value can name further hop-by-hop headers (RFC 9110 section 7.6.1), so those go too. Returns a fresh object; the input is the live parser's map and is never mutated.
- */
-export declare function forwardableHeaders(headers: Readonly<IncomingHttpHeaders>): IncomingHttpHeaders;
-/** A CA certificate and its private key, both as PEM. */
-export interface CaMaterial {
-    readonly certPem: string;
-    readonly keyPem: string;
-}
-/** A TLS leaf certificate and its private key, both as PEM. */
-export interface LeafCert {
-    readonly certPem: string;
-    readonly keyPem: string;
-}
-/** Generates the local CA: one RSA keypair, self-signed, CA-only by basicConstraints and keyUsage, with a random serial. Built on `node:crypto` alone (see `x509.ts`), no openssl, so the same code works on every platform agent-shim ships to. */
-export declare function generateCa(now: Readonly<Date>): CaMaterial;
-/** The names the front door's provider listener answers to: the loopback address every provider session's base URL names, plus the loopback hostname for a client that spells it that way. */
-export declare const LOOPBACK_LEAF_NAMES: readonly string[];
-/**
- * Mints a TLS leaf signed by the CA: its own RSA keypair, server-auth usage only, the first name as the subject's common name and every name in the SAN. A name that parses as an IP address goes in as an IP SAN, because TLS clients match an IP host only against IP SANs, never against a DNS SAN spelling the same digits.
- */
-export declare function mintLeaf(ca: CaMaterial, names: readonly string[], now: Readonly<Date>): LeafCert;
-/** Mints each host's leaf once from the CA and reuses it, because generating a 2048-bit RSA keypair costs noticeable time and nothing about the certificate changes between sessions. */
-export declare function createLeafCache(ca: CaMaterial, now: () => Date): (host: string) => LeafCert;
-/**
- * Persistence for the CA: generated once on the machine's first headroom start and reused forever after, because regenerating it would invalidate every child's `NODE_EXTRA_CA_CERTS` pointing at the old file. The real implementation writes the key with mode 0600; injected fakes keep it in memory.
- */
-export interface ConnectCertStore {
-    /** The persisted CA, or undefined when none exists yet (or only half of it does: a cert without its key can sign nothing, so it counts as absent). */
-    readonly loadCa: () => CaMaterial | undefined;
-    /** Persists both halves of the CA, the key unreadable to other users. */
-    readonly writeCa: (ca: CaMaterial) => void;
-}
-/**
- * Loads the persisted CA, generating and persisting one when no usable CA exists. A stored pair that `node:crypto` cannot parse is treated as absent and replaced: a truncated write is the one failure mode a regeneration can actually repair, and every child that trusted the old file needs a new `NODE_EXTRA_CA_CERTS` anyway once its CA stops parsing.
- */
-export declare function ensureCa(store: ConnectCertStore, generate: () => CaMaterial): CaMaterial;
-/** Where one forwarded request goes, and how: the connect surface's own forwards go to the real upstream over TLS, while a local hop over plain HTTP is what tests redirect to. */
-interface ConnectForwardTarget {
-    readonly host: string;
-    readonly port: number;
-    readonly tls: boolean;
-    /** The SNI name to present; defaults to `host`. Separated so a test can connect to a local fake while presenting the production hostname. */
-    readonly servername?: string;
-    /** Extra trust anchors for the target's certificate, when it is not system-trusted (a test's local fake upstream). */
-    readonly ca?: readonly string[];
-    /** Overrides certificate verification; production leaves it at the Node default (verify against system trust or `ca`). */
-    readonly rejectUnauthorized?: boolean;
-}
-/** Handles one parsed HTTP request on a terminated TLS session. */
-type ConnectRequestHandler = (request: IncomingMessage, response: ServerResponse) => void;
-/** A bound loopback listener and how to stop it. */
-export interface ConnectListenerHandle {
-    readonly port: number;
-    /** Stops accepting, ends every live connection, and resolves once the port is released. */
-    readonly close: () => Promise<void>;
-}
-/** Presents one leaf's server-side TLS on CONNECTed sockets. */
-interface TlsAcceptor {
-    /** Starts the TLS handshake on a socket that has just received its CONNECT response, carrying `context` to the handshake's completion untouched: whatever the caller knows about this connection (its tunnel's capability) reaches `onSecure` without the acceptor interpreting it. */
-    readonly accept: (socket: net.Socket, context: string) => void;
-    /** Drops every session this acceptor is terminating. */
-    readonly close: () => void;
-}
-/** Parses HTTP over terminated sockets and serves each request through the handler, keep-alive included. */
-interface HttpParserSession {
-    readonly serve: (socket: net.Socket) => void;
-    readonly close: () => void;
-}
-/**
- * Every effect the MITM proxy performs, injected so the routing decisions and lifecycle run against fakes in unit tests (the SupervisorPorts pattern): TCP listening, TLS termination, HTTP parsing, plain TCP tunnels, and request forwarding. The real implementation is `realConnectEffects`; the TLS round-trip test uses it with redirected targets.
- */
-export interface ConnectEffects {
-    /** Binds a loopback TCP listener; `preferredPort` is tried first and any free port used when it is taken (bind, do not probe: check-then-bind races). Resolves with the bound port and a close handle. */
-    readonly listenLoopback: (preferredPort: number | undefined, onSocket: (socket: net.Socket) => void) => Promise<ConnectListenerHandle>;
-    /** Builds the TLS terminator for one leaf, handing each successfully handshaked session to `onSecure` together with the context its `accept` call carried. `alpnProtocols`, when given, is advertised during the handshake, which is how a tap host's session can offer HTTP/2 the way its real server does. */
-    readonly createTlsAcceptor: (leaf: LeafCert, onSecure: (secure: net.Socket, context: string) => void, alpnProtocols?: readonly string[]) => TlsAcceptor;
-    /** Opens a TLS connection to a real host, presenting its name as SNI, for a tap session's upstream half. `clientAlpn`, when given, is the protocol the client negotiated with the surface and the only one offered upstream, so the tap never changes the channel's protocol. */
-    readonly connectTlsUpstream: (host: string, port: number, clientAlpn: string | undefined) => Promise<net.Socket>;
-    /** Builds the HTTP parser bound to one request handler. `onUpgrade`, when given, owns every HTTP upgrade request arriving on a terminated session, socket and already-read bytes included; a session without one lets Node destroy the upgrade, its own no-listener behaviour. */
-    readonly createHttpSession: (handler: ConnectRequestHandler, onUpgrade?: (request: IncomingMessage, socket: Duplex, head: Buffer) => void) => HttpParserSession;
-    /** Opens a raw TCP connection for a blind tunnel. */
-    readonly connectTcp: (host: string, port: number) => Promise<net.Socket>;
-    /** Streams one request to `target` and the response back, never buffering a body. When `observer` is given, the forwarding drives it with additive listeners (request and response chunks arrive to both the pipe and the observer) so capturing never changes the forwarding's own flow control. */
-    readonly forwardHttp: (target: ConnectForwardTarget, request: IncomingMessage, response: ServerResponse, observer?: PassthroughObserver) => void;
-}
-/** Everything the connect surface needs to route, resolved before it starts. */
-export interface ConnectServerConfig {
-    /** The CONNECT hosts whose TLS get terminated, each with its own leaf, its own HTTP parser and its own upstream. */
-    readonly interceptHosts: readonly string[];
-    /**
-     * The one intercept host whose `/v1/` paths `serveRouted` handles: the API host, whose pipeline identification, authorisation and headroom hop are about Anthropic sessions and no other host's traffic.
-     */
-    readonly routedHost: string;
-    /**
-     * Serves one routed path (`/v1/...`) from the terminated session: the same ordered pipeline the provider listener hands requests to, so an OAuth session and a provider session run identical identification, middleware and routing.
-     */
-    readonly serveRouted: ConnectRequestHandler;
-    /** The leaf to terminate each intercept host with, minted and cached per host. */
-    readonly leafFor: (host: string) => LeafCert;
-    /** Where non-routed paths on one host's terminated session are piped: that host's own real upstream over TLS. */
-    readonly upstreamFor: (host: string) => ConnectForwardTarget;
-    /** Whether a capability presented as a CONNECT request's proxy credential belongs to a live launch: the same constant-time check against the same registry the routed pipeline's admission makes, read fresh on every call because launches come and go. */
-    readonly isLiveCapability: (token: string) => boolean;
-    /**
-     * Binds a second listener that serves the intercept hosts' sessions to connections arriving pre-established, with no CONNECT handshake to authenticate: what an operating-system redirect (a pf rule sending the real hosts' address to this port) delivers. Only the API host's session is reachable this way, never a tap host's, because a redirect can name only addresses and the control plane shares the API host's address today; if that ever splits, the transparent listener must not follow it blindly. There is no capability to check on this surface: the connection carried no proxy credential, so every request rides the pipeline anonymously, admitted the way a tunnel's own header-less requests are (by nothing, which is exactly what they present), and the surface exists solely for clients that ignore proxies and would otherwise be invisible to the door entirely.
-     */
-    readonly transparentPort?: number;
-    /**
-     * The capability the transparent surface's sessions carry: a real, registered token minted by the door for its own pid, so header-less traffic that arrives by redirect is admitted and attributed like any launch's instead of being refused for a credential it cannot possibly present. Absent along with `transparentPort`.
-     */
-    readonly transparentCapability?: string;
-    /** The intercept hosts that are never HTTP-parsed: terminated, tapped at the byte level, and pumped to their real host. */
-    readonly tapHosts: readonly string[];
-    /** The connection deadlines and caps; production passes `CONNECT_LIMITS`. */
-    readonly limits: ConnectLimits;
-    /** The diagnostic tap, when capturing is enabled; absent means nothing is recorded. */
-    readonly capture?: ConnectCapture;
-}
-/** A running connect surface. */
-export interface ConnectServerHandle {
-    readonly port: number;
-    /** The transparent listener's port, when one was requested: what an operating-system redirect should point at. */
-    readonly transparentPort?: number;
-    /** Stops the listener, drops every live tunnel and terminated session, and resolves once the port is released. */
-    readonly close: () => Promise<void>;
-}
-/**
- * Starts the connect surface: binds the listener, mints the intercept host's leaf, and wires the per-connection routing. Resolves once the listener is bound.
- *
- * The connection flow: read the CONNECT head within the deadline (never more of the stream than that, so an early ClientHello glued to the head is pushed back with `unshift` and still seen by whatever consumes the socket next), authenticate it, then either blind-tunnel the target or terminate its TLS and parse HTTP on the session. Every network effect flows through `effects`; nothing here touches the network or filesystem itself.
- */
-export declare function startConnectServer(config: ConnectServerConfig, effects: ConnectEffects, preferredPort: number | undefined): Promise<ConnectServerHandle>;
-/** The real `ConnectCertStore` on the filesystem: `ca.pem` world-readable (it is public material), `ca.key` mode 0600 exactly, chmod'ed after the write because a create's mode bits pass through the process umask. */
-export declare function realConnectCertStore(paths: {
-    readonly frontdoorCaDir: string;
-    readonly frontdoorCaCertFile: string;
-    readonly frontdoorCaKeyFile: string;
-}): ConnectCertStore;
-export {};

package/dist/types/frontdoor/connectEffects.d.ts

@@ -1,3 +0,0 @@
-import { type ConnectEffects } from "./connect";
-/** The real `ConnectEffects` over node's own net, tls, and http. `connectTcp` opens real connections to the CONNECTed host, so tests that want a blind tunnel redirect it. */
-export declare function realConnectEffects(): ConnectEffects;

package/dist/types/frontdoor/custody.d.ts

@@ -1,32 +0,0 @@
-import type { IncomingHttpHeaders } from "node:http";
-/** What stands in for a credential while its request crosses headroom: an opaque word that authenticates nothing anywhere. */
-export declare const SEQUESTERED_CREDENTIAL = "agent-shim-sequestered";
-/** The credential headers one custody record holds, exactly as the client sent them. */
-type HeldCredentials = Readonly<Record<string, string | readonly string[]>>;
-/** One request's headers with its credentials swapped out, and the id that redeems them. */
-interface Sequestered {
-    readonly hopId: string;
-    readonly headers: Record<string, string | string[] | undefined>;
-}
-/**
- * Holds a provider session's real credentials in this process's memory while its request takes the headroom hop, so the credential never crosses headroom or the plain-HTTP leg back to the door.
- *
- * The hop calls `sequester`, sends headroom the placeholder headers plus the hop id, and calls `release` once its response to the client has finished or the client has gone. The direct listener calls `redeem` with the hop id and the provider its request path names: a live id recorded for that same provider yields the real headers, anything else yields nothing and the request is refused. A process that binds the direct port therefore receives only placeholders and an id that is worthless once the hop ends, and nothing outside this process can mint an id.
- *
- * An id stays redeemable for the whole hop rather than exactly once, because headroom legitimately sends one client request upstream more than once: it retries 429, 529 and 5xx answers, and its memory-tool and CCR continuations call the upstream again inside the same client turn, all with the headers it was handed.
- */
-export interface CredentialCustody {
-    /** Takes custody of `headers`' credential headers for one hop to `provider`, returning the headers to send headroom (placeholders where the credentials were) and the hop id that redeems them. */
-    readonly sequester: (headers: Readonly<IncomingHttpHeaders>, provider: string) => Sequestered;
-    /** Ends a hop: its id stops redeeming. Idempotent. */
-    readonly release: (hopId: string) => void;
-    /** The real credential headers for a live hop to `provider`, or undefined for an unknown, released or mismatched id. */
-    readonly redeem: (hopId: string, provider: string) => HeldCredentials | undefined;
-}
-/** Creates an empty custody store. `randomId` must be unguessable (a v4 UUID or better): the id is the only thing that redeems a credential. */
-export declare function createCredentialCustody(randomId: () => string): CredentialCustody;
-/**
- * The headers a redeemed request is routed with: every credential header headroom forwarded (placeholders, or anything else headroom chose to send) is dropped, and the held originals take their place. Whatever the hop's request carried in those headers is never trusted; only what the client sent is.
- */
-export declare function restoreCredentials(headers: Readonly<IncomingHttpHeaders>, credentials: HeldCredentials): IncomingHttpHeaders;
-export {};

package/dist/types/frontdoor/ensure.d.ts

@@ -1,36 +0,0 @@
-import { CliError } from "../cliError";
-import type { LayoutPaths } from "../paths";
-import { type HeadroomFs } from "../headroom/state";
-import type { ListenerVerdict } from "./probe";
-/** Raised when the front door cannot be brought up in time or has recorded a fatal error: a routed launch has no other way to reach its provider, so it must fail rather than start a session that can never answer. */
-export declare class FrontDoorStartError extends CliError {
-    constructor(message: string);
-}
-/** Every effect the ensure step performs, injected so it runs against fakes in tests. */
-export interface EnsureFrontDoorPorts {
-    readonly fs: HeadroomFs;
-    /** Zombie-aware liveness (see `realIsProcessRunning`). */
-    readonly isRunning: (pid: number) => boolean;
-    readonly now: () => number;
-    readonly sleep: (ms: number) => void;
-    /** Spawns the detached front-door supervisor, returning its pid. */
-    readonly spawnSupervisor: (paths: LayoutPaths) => number;
-    /** Authenticates the provider listener on `port`: a TLS handshake chaining to agent-shim's CA and a healthy answer, with no capability sent (see `probeFrontDoorSync`). */
-    readonly verifyListener: (port: number) => ListenerVerdict;
-    /** Asks a running front-door supervisor to exit, without waiting for it to: the caller polls `isRunning`. Only ever called for a pid whose recorded listener has just authenticated as agent-shim's own. */
-    readonly stopSupervisor: (pid: number) => void;
-}
-/**
- * Brings the front door up for this launch, or finds it serving, and registers this launcher pid in its session registry: the fact that keeps the door from idling out while this session lives, and the record that holds this launch's capability token. The same lock-and-poll coordination as headroom's and the old codex daemon's ensure: the exclusive-create start lock decides which of several concurrent launches spawns the one supervisor, everyone waits on state.json, and a lock whose holder died is removed and retried. Ready means state names a live supervisor and both listeners' ports, which the supervisor writes only after both have bound (and the provider listener has answered its own health probe).
- *
- * A live pid in state proves nothing about who holds the port it names: the door may have crashed and left the port to anyone, or the pid may have been reused by an unrelated process. So before anything is registered or returned, the provider listener is authenticated over TLS against agent-shim's CA. A listener that fails (wrong certificate, nothing answering, a bad answer) is treated as a stale or hostile owner: its pid is distrusted for the rest of this call and a replacement supervisor is spawned, which binds a free port when the sticky one is held and is then verified in turn. If a supervisor this call spawned also fails verification, the launch is refused naming the reason and the daemon log; no capability is written and no address is handed to the child.
- */
-export declare function ensureFrontDoor(params: {
-    readonly paths: LayoutPaths;
-    readonly launcherPid: number;
-    readonly ports: EnsureFrontDoorPorts;
-}): {
-    readonly port: number;
-    readonly connectPort: number;
-    readonly token: string;
-};

package/dist/types/frontdoor/headroomHop.d.ts

@@ -1,22 +0,0 @@
-import type { CredentialCustody } from "./custody";
-import { type RoutedRequest, type RoutedResponse } from "./route";
-/** Everything the headroom hop depends on, injected so the pipeline's ordering tests can point it at a scripted daemon. */
-export interface HeadroomHopDeps {
-    /**
-     * The headroom daemon's loopback port, read per request rather than captured at start-up: the daemon can crash and restart on a different port while this door keeps listening, and the hop must follow it. Undefined while the daemon is down (the restart window).
-     */
-    readonly headroomPort: () => number | undefined;
-    /**
-     * The per-generation secret the direct listener requires on what the hop forwards back. Headroom passes non-x-headroom headers through untouched, so the secret survives the round trip and arrives where this process can check it, while no loopback process outside this door ever holds it.
-     */
-    readonly hopSecret: string;
-    /** Holds a provider session's real credentials while its request crosses headroom; the direct listener redeems them by the hop id. */
-    readonly custody: CredentialCustody;
-    readonly log: (line: string) => void;
-}
-/**
- * Applies the headroom hop: forwards the request, still Anthropic-shaped, to the headroom daemon as a backend hop and streams its response back to the client. The hop ALWAYS sits before the route's own serving (a translator needs the request headroom has compressed, never the reverse), which is why this runs in the pipeline and not inside any route.
- *
- * `upstream` is what headroom is told to forward to once it has done its work (its per-request base URL header). When it is set it is always this door's direct listener (every provider route declares exactly that), and the provider credential is then taken into custody for the hop: headroom receives placeholders and a hop id, and the direct listener restores the real headers when headroom forwards the request back. Neither headroom nor anything that binds a port on that plain-HTTP round trip ever holds the credential. Undefined leaves headroom's default upstream (Claude Code's API) in charge, which is exactly what an OAuth session wants, and the OAuth bearer then passes through untouched: headroom forwards it straight to that API, never back here, and uses it for its subscription tracking. The session's project identity is re-set here, and only here: the identity step stripped it from everything that leaves the machine, and headroom is the one consumer that needs it.
- */
-export declare function applyHeadroomHop(request: RoutedRequest, response: RoutedResponse, upstream: string | undefined, deps: HeadroomHopDeps): Promise<void>;

package/dist/types/frontdoor/pipeline.d.ts

@@ -1,109 +0,0 @@
-import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
-import { type HeadroomHopDeps } from "./headroomHop";
-import { type FrontDoorRoute, type RoutedRequest, type RoutedResponse, type SessionIdentity } from "./route";
-/** What one routed response looked like as it started back to the client: the typed event response middleware observes. */
-export interface RoutedResponseEvent {
-    readonly session: SessionIdentity;
-    /** The route that served the response. */
-    readonly route: string;
-    /** The request's method. */
-    readonly method: string;
-    /** The request target's path, without its query string. */
-    readonly path: string;
-    /** When the pipeline received the request, in epoch milliseconds from the injected clock. */
-    readonly receivedAt: number;
-    readonly status: number;
-    readonly headers: Readonly<Record<string, string>>;
-}
-/** How a routed response's body finished: written to the end, or cut short (the client went away, or the route destroyed the response after an upstream failure). */
-export type ResponseOutcome = "completed" | "aborted";
-/**
- * Follows one response's body as the client receives it. `chunk` sees each chunk after it has been handed to the client's socket, so observing never holds a byte back; `end` is called exactly once, when the body has finished either way. Like the observer that returned it, a body observer that throws is logged and dropped for the rest of that response, never allowed to break it.
- */
-export interface ResponseBodyObserver {
-    readonly chunk: (chunk: Uint8Array) => void;
-    readonly end: (outcome: ResponseOutcome) => void;
-}
-/**
- * Response middleware: called once per routed response, in registration order, once the route's response head is known and before any of it is written to the client. It returns a body observer when it wants to follow the body, or undefined when the head was all it needed. Observing must be side-effect-only: an observer that throws is logged and skipped, never allowed to break routing, and an observer must not block the response.
- *
- * Usage tracking registers here (see `src/usage/middleware.ts`): the head carries the rate-limit headers, and the body carries the token usage.
- */
-export type ResponseObserver = (event: RoutedResponseEvent) => ResponseBodyObserver | undefined;
-/** The outcome of resolving a request's target to a route. */
-export type RouteResolution = {
-    readonly ok: true;
-    readonly route: FrontDoorRoute;
-} | {
-    readonly ok: false;
-    readonly status: number;
-    readonly message: string;
-};
-/** Everything the ordered pipeline depends on, injected so it runs against fakes in tests. */
-export interface PipelineDeps {
-    /** Resolves the route a request's target names, reading whatever configuration the route needs. */
-    readonly resolveRoute: (request: RoutedRequest) => Promise<RouteResolution>;
-    /** The response middleware chain, run in order at each response head. This is where usage capture registers. */
-    readonly responseObservers: readonly ResponseObserver[];
-    /**
-     * The headroom hop, applied BEFORE a route whose declaration admits it whenever the session's launch resolved headroom on: headroom needs the Anthropic-shaped request, so it always sits in front of a translator, never behind one. Omitted by a listener that serves routes directly (the direct listener headroom forwards an in-process route back to), or when no headroom is wired.
-     */
-    readonly headroom?: HeadroomHopDeps;
-    /** The clock response middleware times requests by, in epoch milliseconds. */
-    readonly now: () => number;
-    readonly log: (line: string) => void;
-    /**
-     * The listener's admission step, run after identification and before anything is routed: it decides whether the request may be routed at all and with which headers. A client-facing listener admits a request carrying the per-launch capability of a live registered session, unchanged; the direct listener admits only what this process's own headroom hop sent back (the generation's hop secret plus a live custody id for the provider the path names) and swaps the hop's placeholder credentials for the real ones. A refused request is answered 401 without ever reaching a route, so a loopback process that never launched through agent-shim cannot spend a session's credentials or quota.
-     */
-    readonly admit: (request: AdmissionRequest) => Admission;
-}
-/** What the admission step sees of one request. */
-interface AdmissionRequest {
-    /** The request target exactly as received. */
-    readonly url: string;
-    /** Every header as received, internal ones included: the capability and hop headers live here. */
-    readonly headers: Readonly<IncomingHttpHeaders>;
-    /** The headers the identity step judged forwardable, internal ones stripped. */
-    readonly forwardable: Readonly<IncomingHttpHeaders>;
-}
-/** The admission step's verdict: route with these headers, or refuse with this message. */
-type Admission = {
-    readonly ok: true;
-    readonly headers: IncomingHttpHeaders;
-} | {
-    readonly ok: false;
-    readonly message: string;
-};
-/** One request as a transport hands it to the pipeline, before anything has been identified or routed. */
-export interface PipelineRequest {
-    readonly method: string;
-    /** The request target exactly as received, path and query together. */
-    readonly url: string;
-    readonly headers: IncomingHttpHeaders;
-    /** The request's body stream. */
-    readonly body: IncomingMessage;
-    /** Aborted the moment the client goes away. */
-    readonly signal: AbortSignal;
-    readonly response: ServerResponse;
-}
-/** What the response middleware learns about the request a routed response answers. */
-interface ObservedRequest {
-    readonly method: string;
-    /** The request target's path, without its query string. */
-    readonly path: string;
-    readonly receivedAt: number;
-}
-/**
- * Builds the response half a route writes through. The head is what runs the response middleware: `start` invokes every observer, in order, with the session, the request and the route's name before a byte reaches the client, and keeps the body observers they return. Each body chunk reaches those observers only after it has been handed to the client's socket, and their `end` runs once when the response ends, is destroyed, or the client goes away first, so following the body never holds a byte back and never misses how it finished. Body writes apply backpressure by waiting for the socket to drain, and resolve without writing once the client is gone, so a route streaming to a dead client finishes promptly rather than filling a buffer.
- */
-export declare function createRoutedResponse(response: ServerResponse, context: {
-    readonly deps: PipelineDeps;
-    readonly session: SessionIdentity;
-    readonly route: string;
-    readonly request: ObservedRequest;
-}): RoutedResponse;
-/**
- * The ordered pipeline every routed session's request runs through: identify the session (splitting the launcher-injected headers out of what may leave the machine), then route, with the response middleware running at each response head. A route that cannot be resolved is answered as an Anthropic-shaped error, and the observers see that error like any other response, since quota and rate-limit state lives in exactly those.
- */
-export declare function serveRouted(request: PipelineRequest, deps: PipelineDeps): Promise<void>;
-export {};

package/dist/types/frontdoor/probe.d.ts

@@ -1,13 +0,0 @@
-/** The outcome of authenticating the listener a front-door state file names. */
-export type ListenerVerdict = {
-    readonly ok: true;
-} | {
-    readonly ok: false;
-    readonly reason: string;
-};
-/**
- * Authenticates the front door's provider listener before a launch trusts it: a TLS handshake that must chain to agent-shim's CA (whose key only this user can read) for 127.0.0.1, then a healthy answer. A process that merely holds the port (a stale state file's port re-bound by someone else, or a reused pid's listener) cannot complete that handshake, so it fails here and the launch never hands its child that address.
- *
- * Synchronous because the launcher is synchronous right through to `spawnSync`: the HTTPS request runs on a worker thread and this thread blocks on a shared buffer until the worker posts its verdict.
- */
-export declare function probeFrontDoorSync(port: number, caPem: string): ListenerVerdict;

package/dist/types/frontdoor/realFrontDoorPort.d.ts

@@ -1,5 +0,0 @@
-import type { FrontDoorPort } from "../launcher/ports";
-import type { LayoutPaths } from "../paths";
-import { type DaemonSpawner } from "../realPorts";
-/** The real `FrontDoorPort` for one launch: `ensure` runs the lock-and-poll coordination, authenticates the listener and registers this launcher; `release` removes its registration. */
-export declare function realFrontDoorPort(paths: LayoutPaths, spawnDaemon: DaemonSpawner): FrontDoorPort;