@dianshuv/copilot-api 0.9.1 → 0.10.0

package/README.md

@@ -80,6 +80,7 @@ make down
 | `--context-editing` | Context editing mode: off, clear-thinking, clear-tooluse, clear-both | off |
 | `--timezone-offset` | Timezone offset in hours from UTC for log timestamps (e.g., +8, -5, 0) | +8 |
 | `--posthog-key` | PostHog API key for token usage analytics (opt-in) | none |
+| `--api-key` | Proxy API key for inbound authentication (see [Authentication](#authentication)). Empty = disabled | none |
 
 ### Hidden Models
 
@@ -157,6 +158,130 @@ When enabled (default), auto-truncate automatically compacts conversation histor
 - **Smart compression**: With `--compress-tool-results`, old tool results are compressed before removing messages, preserving more conversation context.
 - **Orphan filtering**: After truncation, orphaned tool results (without matching tool calls) are automatically removed.
 
+## Authentication
+
+By default the proxy is **unauthenticated**: every endpoint is open and any
+request passes through unchanged. You can optionally protect the proxy's
+*inbound* surface with a **Proxy API key** (this is your own secret for this
+proxy — it is unrelated to the GitHub OAuth / Copilot token the proxy uses
+upstream). When a key is configured, all endpoints **except `/` and `/health`**
+require it (fail-closed: any route not on that exemption list — including future
+ones — is protected). Genuine CORS preflight `OPTIONS` requests are also let
+through (they carry no payload), so browser clients aren't tripped by an opaque
+preflight failure.
+
+### Enabling it
+
+Provide the key via either source:
+
+- `--api-key <key>` flag
+- `COPILOT_API_KEY` environment variable
+
+Rules:
+
+- **Precedence**: when both are set to a non-empty value, the **flag wins** and
+  the env value is ignored.
+- **Trim + empty disables**: each source is trimmed first; a value that is empty
+  or whitespace-only (`--api-key ""`, `COPILOT_API_KEY=`) counts as *not
+  provided*. If neither source yields a non-empty value, auth stays **disabled**
+  (the default).
+
+The startup banner prints whether auth is on/off and, when on, the source
+(`flag` / `env`) — but **never** the key value itself.
+
+> [!CAUTION]
+> **Ambient `COPILOT_API_KEY` footgun.** Because the env var is read on every
+> start, a `COPILOT_API_KEY` exported anywhere the process can see it (your
+> shell profile, a `.env` sourced into the environment, a systemd unit, a
+> container env) **silently enables authentication** for that instance — even
+> when you did not pass `--api-key`. If a previously-open instance suddenly
+> returns `401`, check for an inherited `COPILOT_API_KEY`. The startup banner's
+> `source: env` line makes this visible.
+
+### Network binding
+
+The proxy **binds all interfaces (`0.0.0.0`) by default**, so a key-less
+instance is reachable from anywhere on your network. For a local-only,
+unauthenticated instance, bind loopback explicitly:
+
+```sh
+copilot-api start --host 127.0.0.1
+```
+
+The startup banner reports the **real** bind address (`0.0.0.0` for an
+all-interfaces bind, or the narrowed host you passed), so a wide-open bind is
+never hidden.
+
+### Choosing a key
+
+Use a **high-entropy** secret (e.g. `openssl rand -hex 32`), not a guessable
+word. The comparison is constant-time, but a weak key can still be guessed
+offline or brute-forced over the network.
+
+### Migrating clients
+
+Once a key is configured, clients that previously sent a placeholder must send
+the real key. Two header shapes are accepted and **either** is sufficient:
+
+- **OpenAI-compatible clients** → `Authorization: Bearer <key>` (the scheme is
+  matched case-insensitively; a bare value with no `Bearer ` prefix is also
+  tolerated).
+- **Anthropic-native clients** → `x-api-key: <key>`.
+
+If both headers are present, a match on *either* one is accepted.
+
+Per client:
+
+- **opencode** (`opencode.json`): set `provider.<name>.options.apiKey` from
+  `"dummy"` to your real key (the `@ai-sdk/openai-compatible` provider sends it
+  as `Authorization: Bearer`).
+- **Claude Code** (`.claude/settings.json`, see [below](#using-with-claude-code)):
+  change `ANTHROPIC_AUTH_TOKEN` from `"dummy"` to your real key. Claude Code
+  talks to the proxy's `/v1/messages` (Anthropic) surface; the auth gate accepts
+  the token from either header. `--claude-code` keeps emitting the `"dummy"`
+  placeholder on purpose (so the secret never lands in your clipboard / shell
+  history) and prints a reminder to replace it when auth is on.
+- **Raw OpenAI SDK** → `Authorization: Bearer <key>`; **raw Anthropic SDK** →
+  `x-api-key: <key>`.
+
+> [!TIP]
+> **Keep the key out of shell history.** Don't paste the literal key onto a
+> command line (e.g. `curl -H "Authorization: Bearer sk-real-key" …`), or it
+> lands in `~/.zsh_history`. Read it from an env var or a file instead:
+>
+> ```sh
+> # Put the key in an env var read from a non-echoed prompt or a 0600 file,
+> # then reference the var — the literal secret never appears in argv/history.
+> read -rs COPILOT_API_KEY            # typed key is not echoed or saved
+> export COPILOT_API_KEY
+> curl -H "Authorization: Bearer $COPILOT_API_KEY" http://127.0.0.1:4141/v1/models
+> ```
+
+A failed auth returns `401` with a client-appropriate body: requests to the
+Anthropic surface (`/v1/messages`, `/v1/messages/count_tokens`) get
+`{"type":"error","error":{"type":"authentication_error", …}}`; every other
+endpoint gets the OpenAI-style `{"error":{"code":"invalid_api_key", …}}`.
+Missing and wrong keys return the identical body (no oracle), always with a
+`WWW-Authenticate: Bearer` header.
+
+### Browser tools when auth is on
+
+The request logger does **not** record the `Authorization` / `x-api-key`
+headers, so your key never lands in logs. But the browser-based tools can't send
+a custom header, so when auth is on they stop working:
+
+- **History UI** (`/history`) and its live-update WebSocket (`/history/ws`) — the
+  page load and socket upgrade are gated like any other protected route.
+- **External Usage Viewer** (the `ericc-ch.github.io` link in the banner) — it
+  fetches `/usage`, which is now protected, so it can't load your data.
+
+Workarounds:
+
+- Run a **separate local, unauthenticated instance** (`--host 127.0.0.1` with no
+  `--api-key`) for the browser UI, or
+- Hit the history JSON API directly with a key, e.g.
+  `curl -H "Authorization: Bearer $COPILOT_API_KEY" http://127.0.0.1:4141/history/api/entries`.
+
 ## Using with Claude Code
 
 Create `.claude/settings.json` in your project:

package/dist/main.mjs

@@ -6,7 +6,7 @@ import os from "node:os";
 import path, { dirname, join } from "node:path";
 import { getProxyForUrl } from "proxy-from-env";
 import { Agent, ProxyAgent, setGlobalDispatcher } from "undici";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import clipboard from "clipboardy";
 import { serve } from "srvx";
@@ -1348,7 +1348,7 @@ const patchClaude = defineCommand({
 
 //#endregion
 //#region package.json
-var version = "0.9.1";
+var version = "0.10.0";
 
 //#endregion
 //#region src/lib/adaptive-rate-limiter.ts
@@ -1657,6 +1657,315 @@ async function executeWithAdaptiveRateLimit(fn) {
 	return rateLimiterInstance.execute(fn);
 }
 
+//#endregion
+//#region src/lib/auth-gate.ts
+/**
+* Auth gate — the inbound authentication decision point for the proxy.
+*
+* Protects this proxy's *inbound* surface with a configured **Proxy API key**
+* (NOT the outbound GitHub OAuth token or Copilot token). The decision logic
+* is expressed as pure functions so it can be unit-tested without booting the
+* server or reaching upstream.
+*/
+/**
+* Extract candidate presented credential values from request headers.
+*
+* Two header shapes are read, and **both** contribute candidates when present
+* (compare-all-present) so neither is silently ignored in favor of the other —
+* a later any-match over the candidates decides acceptance:
+*  - `Authorization`: the scheme prefix is stripped case-insensitively
+*    (`Bearer ` / `bearer ` …) because the scheme is case-insensitive per
+*    RFC 7235, while the secret itself is case-sensitive. A bare value with no
+*    scheme prefix is tolerated and returned verbatim.
+*  - `x-api-key` (Issue 02): the Anthropic-native header. Taken verbatim — no
+*    scheme stripping (a value that happens to start with `Bearer ` is kept
+*    as-is).
+*
+* Order is `[Authorization, x-api-key]` for any present header; absent headers
+* contribute nothing.
+*/
+function extractCredentials(headers) {
+	const candidates = [];
+	const authorization = headers.get("authorization");
+	if (authorization !== null) candidates.push(authorization.replace(/^Bearer\s+/i, ""));
+	const apiKey = headers.get("x-api-key");
+	if (apiKey !== null) candidates.push(apiKey);
+	return candidates;
+}
+/**
+* Hard-coded exemption set: the liveness (`/`) and readiness (`/health`)
+* endpoints are reachable without a key so container orchestration probes are
+* never blocked. Everything else is protected (fail-closed) — unknown / future
+* routes default to protected.
+*
+* Matching is by **exact path**, with a trailing slash tolerated (so `/health/`
+* is exempt too) and `/` itself handled explicitly. Prefix matching is
+* deliberately avoided: `/healthz` or `/health/extra` must NOT be exempt. The
+* server registers a matching `/health/` route, so an exempt `/health/` request
+* resolves to the readiness handler rather than 404ing.
+*/
+function isExemptPath(path) {
+	if (path === "/") return true;
+	return (path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path) === "/health";
+}
+/**
+* Compute the fixed-length sha256 digest (32 bytes) of the configured key.
+* The configured key is trimmed before hashing (config-side trim).
+*/
+function digestConfiguredKey(configuredKey) {
+	return createHash("sha256").update(configuredKey.trim()).digest();
+}
+/**
+* Constant-time membership test: does any presented candidate match the
+* configured key?
+*
+* Each candidate is sha256'd to a fixed 32-byte digest and compared against the
+* configured digest. Hashing to a fixed length sidesteps the `RangeError` that
+* `crypto.timingSafeEqual` throws on length-mismatched buffers, so a
+* wrong-length presented value yields `false` rather than throwing.
+*/
+function matchesConfiguredKey(configuredDigest, candidates) {
+	return candidates.some((candidate) => {
+		return timingSafeEqual(createHash("sha256").update(candidate).digest(), configuredDigest);
+	});
+}
+/**
+* Resolve the inbound Proxy API key from its two operator-facing sources,
+* applying the precedence + normalization contract (Issue 03):
+*
+*  - `--api-key` flag (`flag`) and `COPILOT_API_KEY` env (`env`) are each
+*    **trimmed first**; a trimmed-empty source (`""`, whitespace, or
+*    `undefined`) counts as **not provided**.
+*  - When both provide a non-empty value, the **flag wins** (env ignored).
+*  - When only one provides a non-empty value, that one is used.
+*  - When neither does, `key` is `undefined` and `source` is `"none"` → auth
+*    stays disabled (same as the no-`--api-key` default).
+*
+* Pure: it reads nothing from `process.env` itself (the caller passes the env
+* value in), so it is fully unit-testable and the precedence logic is decoupled
+* from how the values are sourced.
+*/
+function resolveProxyApiKey(sources) {
+	const flag = sources.flag?.trim() ?? "";
+	if (flag !== "") return {
+		key: flag,
+		source: "flag"
+	};
+	const env = sources.env?.trim() ?? "";
+	if (env !== "") return {
+		key: env,
+		source: "env"
+	};
+	return {
+		key: void 0,
+		source: "none"
+	};
+}
+/**
+* Resolve the address the server will *actually* bind to for the startup banner
+* (Issue 04).
+*
+* Mirrors srvx's own host resolution EXACTLY so the banner reports the TRUE bind
+* rather than a guess that could diverge from what srvx passes to the runtime.
+* srvx computes `hostname = opts.hostname ?? process.env.HOST` (a raw nullish
+* coalesce — no trimming, no empty-string special-casing), and start.ts passes
+* `hostname: options.host`. So:
+*   - an explicit `--host` (even `""` / whitespace) is what srvx uses verbatim —
+*     it does NOT fall back to HOST once `opts.hostname` is a non-null string;
+*   - only an absent (`undefined`) `--host` lets srvx fall back to `HOST`;
+*   - when the coalesced value is `undefined` or empty, the runtime binds all
+*     interfaces, which we report as the explicit `0.0.0.0` so a wide-open bind
+*     is unmistakable (srvx renders the same bind as "localhost (all
+*     interfaces)").
+*
+* Critically, the resolved non-empty value is returned VERBATIM (not trimmed):
+* srvx hands the runtime exactly that string, so the banner must report exactly
+* that string — trimming here would make the banner claim a different address
+* than the one actually bound. `env` is passed in (not read) to keep the
+* function pure and unit-testable.
+*/
+function resolveBindAddress(host, env) {
+	const resolved = host ?? env;
+	if (resolved === void 0 || resolved === "") return "0.0.0.0";
+	return resolved;
+}
+/**
+* Resolve the CLIENT-FACING host for generated configs and viewer links
+* (Issue 04), derived from the SAME srvx host resolution as the banner so the
+* two never disagree about what was bound — and formatted as a valid URL
+* authority so the links actually parse.
+*
+* Two differences from {@link resolveBindAddress}:
+*  - All-interfaces rendering: a wildcard bind (`0.0.0.0` / `::` / `[::]` /
+*    empty) is not a connectable target, so it maps to `localhost` for URLs a
+*    client will actually dial (matching srvx's "localhost (all interfaces)"
+*    presentation). A narrowed bind (e.g. `127.0.0.1`, `192.168.1.10`, an IPv6
+*    address) is kept so generated links point at the real interface — fixing
+*    the prior bug where setting `HOST` (with `--host` omitted) yielded
+*    `http://localhost:<port>` links the narrowed bind wasn't listening on.
+*  - IPv6 bracketing: a literal IPv6 host (contains `:`) is wrapped in `[...]`,
+*    exactly as srvx's own `fmtURL` does, so `http://[2001:db8::1]:<port>` is a
+*    valid authority rather than the unparseable `http://2001:db8::1:<port>`.
+*
+* Returns a host token ready to drop into `http://<token>:<port>`.
+*/
+function resolveClientHost(host, env) {
+	const bind = resolveBindAddress(host, env);
+	if (bind === "0.0.0.0" || bind === "::" || bind === "[::]") return "localhost";
+	if (bind.includes(":") && !bind.startsWith("[")) return `[${bind}]`;
+	return bind;
+}
+/**
+* Build the inbound-auth startup banner lines (Issue 04).
+*
+* Returns the human-readable lines the proxy prints at boot so operators can see,
+* at a glance, the security posture of *this* instance:
+*  - auth ON  → `认证开启`, plus the key's origin (`flag` / `env`), plus the real
+*    bind address.
+*  - auth OFF → `认证关闭`, plus the real bind address (so a careless all-
+*    interfaces bind without auth is visible).
+*
+* The configured key value is **never** an input here, so it can never leak into
+* the banner — the function only knows the *source* tag, not the secret. Pure
+* (string in → strings out) so the banner copy is pinned by unit tests.
+*/
+function buildStartupAuthLines(params) {
+	const { source, bindAddress } = params;
+	return [source === "none" ? `Inbound auth: 认证关闭 (no proxy API key configured)` : `Inbound auth: 认证开启 (source: ${source})`, `Binding to: ${bindAddress}`];
+}
+/**
+* The env var Claude Code reads for its inbound credential, and the placeholder
+* value the `--claude-code` setup always embeds for it. Exported so the
+* generated env script (src/start.ts) and the auth hint below reference the SAME
+* literals — changing the placeholder or the var name in one place can't silently
+* desync the other (the hint would otherwise keep naming a string the generated
+* command no longer contains).
+*/
+const CLAUDE_CODE_AUTH_TOKEN_ENV = "ANTHROPIC_AUTH_TOKEN";
+const CLAUDE_CODE_AUTH_TOKEN_PLACEHOLDER = "dummy";
+/**
+* Build the auth-aware hint lines for the `--claude-code` setup (Issue 05).
+*
+* The generated env script ALWAYS sets `ANTHROPIC_AUTH_TOKEN="dummy"` — a real
+* key is deliberately never embedded, so the secret can't land in the clipboard
+* or shell history. When inbound auth is ON, that placeholder won't authenticate
+* against this proxy, so the operator must replace it. This builder returns the
+* visible hint that tells them which variable to change:
+*  - auth OFF (`source === "none"`) → no hint (today's behavior, unchanged).
+*  - auth ON  (`flag` / `env`)      → a one-line hint naming
+*    `ANTHROPIC_AUTH_TOKEN` as the field to set to the proxy API key value.
+*
+* Like {@link buildStartupAuthLines}, the key value is **never** an input here —
+* the builder only knows the `source` tag — so it is structurally impossible for
+* the secret to leak into the hint. Pure (tag in → strings out) so the copy is
+* pinned by unit tests.
+*/
+function buildClaudeCodeAuthHint(source) {
+	if (source === "none") return [];
+	return [`Inbound auth is ON: replace ${CLAUDE_CODE_AUTH_TOKEN_ENV}="${CLAUDE_CODE_AUTH_TOKEN_PLACEHOLDER}" with your proxy API key value before using Claude Code.`];
+}
+/**
+* Configure the proxy API key on global state from a raw configured value.
+*
+* The value is trimmed; a trimmed-empty value (or `undefined`) is treated as
+* "not provided" → auth stays disabled. Otherwise the precomputed digest is
+* stored on state (presence === enabled). Returns whether auth is enabled.
+*
+* The `--api-key` flag and `COPILOT_API_KEY` env source are reconciled upstream
+* by `resolveProxyApiKey` (flag-over-env precedence, Issue 03); this function
+* receives only the already-resolved value.
+*/
+function configureProxyApiKey(rawKey) {
+	const trimmed = rawKey?.trim() ?? "";
+	if (trimmed === "") {
+		state.proxyApiKeyDigest = void 0;
+		return false;
+	}
+	state.proxyApiKeyDigest = digestConfiguredKey(trimmed);
+	return true;
+}
+/**
+* Path → auth-family selector (Issue 02).
+*
+* The Anthropic-native surface is `/v1/messages` and its `count_tokens`
+* subpath; both map to the Anthropic family so a native Anthropic client gets
+* the `authentication_error` body. Everything else — including every other
+* `/v1/…` endpoint and any unknown / future route — defaults to the OpenAI
+* family.
+*
+* Matching is by **exact path** (a trailing slash tolerated), deliberately not
+* a prefix test: the shared `/v1/` prefix must not sweep OpenAI-style endpoints
+* into the Anthropic family, and `/v1/messages-extra` or a deeper unexpected
+* subpath must not be misclassified either. This mirrors `isExemptPath`'s
+* exact-with-trailing-slash convention.
+*/
+function selectFamily(path) {
+	const normalized = path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+	if (normalized === "/v1/messages" || normalized === "/v1/messages/count_tokens") return "anthropic";
+	return "openai";
+}
+/**
+* OpenAI-family 401 response body. The literal field values are pinned by the
+* ADR so OpenAI-compatible SDKs recognize the failure as an auth error. The
+* same body is returned whether credentials were missing or wrong (no oracle).
+*/
+function unauthorizedOpenAIBody() {
+	return { error: {
+		message: "Invalid API key provided.",
+		type: "invalid_request_error",
+		code: "invalid_api_key",
+		param: null
+	} };
+}
+/**
+* Anthropic-family 401 response body (Issue 02). Shape is pinned so Anthropic
+* SDKs (and Claude Code via `/v1/messages`) recognize the failure as an auth
+* error: a top-level `{type:"error", error:{type:"authentication_error",
+* message}}`. As with the OpenAI body, missing and wrong credentials return the
+* identical body (no oracle).
+*/
+function unauthorizedAnthropicBody() {
+	return {
+		type: "error",
+		error: {
+			type: "authentication_error",
+			message: "Invalid API key provided."
+		}
+	};
+}
+/**
+* Global fail-closed authentication middleware.
+*
+* Registered after the request logger and CORS but before route dispatch.
+* Behavior:
+*  - Disabled (no configured digest) → pass through unchanged (default).
+*  - Exempt path (`/`, `/health`) → pass through.
+*  - CORS preflight `OPTIONS` on a protected path → pass through so browser
+*    preflight isn't mistaken for a 401 (blocking it surfaces as an opaque CORS
+*    error, very hard to diagnose). Scoped to *actual* preflights — an
+*    `OPTIONS` carrying `Access-Control-Request-Method` — rather than any
+*    `OPTIONS`, so the bypass surface can't silently widen. Preflights carry no
+*    protected payload, so this doesn't weaken fail-closed.
+*  - Otherwise require a valid Proxy API key; on failure return 401 with a
+*    `WWW-Authenticate: Bearer` header and a **family-appropriate** body —
+*    Anthropic-family (`/v1/messages*`) gets the `authentication_error` shape,
+*    everything else the OpenAI `invalid_api_key` shape (Issue 02). The family
+*    only selects the body shape; it does not change what is protected. Missing
+*    and wrong credentials return the field-identical body for that family.
+*/
+function authGate() {
+	return async (c, next) => {
+		const configuredDigest = state.proxyApiKeyDigest;
+		if (!configuredDigest) return next();
+		if (isExemptPath(c.req.path)) return next();
+		if (c.req.method === "OPTIONS" && c.req.raw.headers.get("access-control-request-method") !== null) return next();
+		if (matchesConfiguredKey(configuredDigest, extractCredentials(c.req.raw.headers))) return next();
+		c.header("WWW-Authenticate", "Bearer");
+		if (selectFamily(c.req.path) === "anthropic") return c.json(unauthorizedAnthropicBody(), 401);
+		return c.json(unauthorizedOpenAIBody(), 401);
+	};
+}
+
 //#endregion
 //#region src/lib/context/request.ts
 let idCounter = 0;
@@ -1933,6 +2242,18 @@ function isHiddenModel(id, showAll) {
 * Enables real-time updates when new requests are recorded.
 */
 const clients = /* @__PURE__ */ new Set();
+function addClient(ws) {
+	clients.add(ws);
+	const msg = {
+		type: "connected",
+		data: { clientCount: clients.size },
+		timestamp: Date.now()
+	};
+	ws.send(JSON.stringify(msg));
+}
+function removeClient(ws) {
+	clients.delete(ws);
+}
 function getClientCount() {
 	return clients.size;
 }
@@ -4743,6 +5064,12 @@ eventLoggingRoutes.post("/batch", (c) => {
 	return c.text("OK", 200);
 });
 
+//#endregion
+//#region src/lib/srvx-bun.ts
+function getBunServerFromRequest(req) {
+	return req.runtime?.bun?.server;
+}
+
 //#endregion
 //#region src/routes/history/api.ts
 function handleGetEntries(c) {
@@ -6240,7 +6567,7 @@ historyRoutes.get("/api/sessions/:id", handleGetSession);
 historyRoutes.delete("/api/sessions/:id", handleDeleteSession);
 historyRoutes.get("/ws", (c) => {
 	if (c.req.header("Upgrade") !== "websocket") return c.text("Expected WebSocket upgrade", 426);
-	if (c.env?.server?.upgrade(c.req.raw)) return new Response(null, { status: 101 });
+	if (getBunServerFromRequest(c.req.raw)?.upgrade(c.req.raw, { data: { kind: "history" } })) return new Response(null, { status: 101 });
 	return c.text("WebSocket upgrade failed", 500);
 });
 historyRoutes.get("/", (c) => {
@@ -8610,7 +8937,7 @@ const handleResponses = async (c) => {
 		normalizePayload: (p) => {
 			const np = state.normalizeResponsesCallIds ? normalizeCallIds(p) : p;
 			useFunctionApplyPatch(np);
-			removeWebSearchTool(np);
+			filterUnsupportedBuiltins(np);
 			return np;
 		},
 		buildHistoryRequest: (p) => {
@@ -8767,11 +9094,10 @@ const useFunctionApplyPatch = (payload) => {
 		}
 	}
 };
-const removeWebSearchTool = (payload) => {
+const UNSUPPORTED_BUILTIN_TOOL_TYPES = new Set(["web_search", "image_generation"]);
+const filterUnsupportedBuiltins = (payload) => {
 	if (!Array.isArray(payload.tools) || payload.tools.length === 0) return;
-	payload.tools = payload.tools.filter((t) => {
-		return t.type !== "web_search";
-	});
+	payload.tools = payload.tools.filter((t) => typeof t.type !== "string" || !UNSUPPORTED_BUILTIN_TOOL_TYPES.has(t.type));
 };
 /** Record a ResponsesResult to history */
 function recordResponseResult(result, fallbackModel, historyId, startTime) {
@@ -8830,8 +9156,9 @@ usageRoute.get("/", async (c) => {
 const server = new Hono();
 server.use(tuiLogger());
 server.use(cors());
+server.use(authGate());
 server.get("/", (c) => c.text("Server running"));
-server.get("/health", (c) => {
+const healthHandler = (c) => {
 	const healthy = Boolean(state.copilotToken && state.githubToken);
 	return c.json({
 		status: healthy ? "healthy" : "unhealthy",
@@ -8841,7 +9168,9 @@ server.get("/health", (c) => {
 			models: Boolean(state.models)
 		}
 	}, healthy ? 200 : 503);
-});
+};
+server.get("/health", healthHandler);
+server.get("/health/", healthHandler);
 server.route("/chat/completions", completionRoutes);
 server.route("/models", modelRoutes);
 server.route("/usage", usageRoute);
@@ -8883,6 +9212,7 @@ function formatModelInfo(model) {
 }
 async function runServer(options) {
 	consola.info(`copilot-api v${version}`);
+	configureProxyApiKey(options.apiKey);
 	if (options.proxyEnv) initProxyFromEnv();
 	if (options.verbose) {
 		consola.level = 5;
@@ -8953,7 +9283,7 @@ async function runServer(options) {
 	const visibleModels = allModels.filter((m) => !isHiddenModel(m.id, state.showAllModels));
 	if (visibleModels.length === 0) consola.warn("All upstream models are filtered by the hardcoded blacklist. /v1/models will return an empty list, but explicit POSTs with a hidden id still pass through to upstream. Restart with --show-all-models to see the full catalogue.");
 	else consola.info(`Available models:\n${visibleModels.map((m) => formatModelInfo(m)).join("\n")}`);
-	const serverUrl = `http://${options.host ?? "localhost"}:${options.port}`;
+	const serverUrl = `http://${resolveClientHost(options.host, process.env.HOST)}:${options.port}`;
 	if (options.claudeCode) {
 		if (visibleModels.length === 0) {
 			consola.error("--claude-code interactive setup needs at least one visible model. Restart with --show-all-models or update src/lib/hidden-models.ts.");
@@ -8969,7 +9299,7 @@ async function runServer(options) {
 		});
 		const command = generateEnvScript({
 			ANTHROPIC_BASE_URL: serverUrl,
-			ANTHROPIC_AUTH_TOKEN: "dummy",
+			[CLAUDE_CODE_AUTH_TOKEN_ENV]: CLAUDE_CODE_AUTH_TOKEN_PLACEHOLDER,
 			ANTHROPIC_MODEL: selectedModel,
 			ANTHROPIC_DEFAULT_SONNET_MODEL: selectedModel,
 			ANTHROPIC_SMALL_FAST_MODEL: selectedSmallModel,
@@ -8984,13 +9314,27 @@ async function runServer(options) {
 			consola.warn("Failed to copy to clipboard. Here is the Claude Code command:");
 			consola.log(command);
 		}
+		for (const line of buildClaudeCodeAuthHint(options.apiKeySource)) consola.warn(line);
 	}
 	consola.box(`🌐 Usage Viewer: https://ericc-ch.github.io/copilot-api?endpoint=${serverUrl}/usage${options.history ? `\n📜 History UI: ${serverUrl}/history` : ""}`);
+	for (const line of buildStartupAuthLines({
+		source: options.apiKeySource,
+		bindAddress: resolveBindAddress(options.host, process.env.HOST)
+	})) process.stdout.write(`${line}\n`);
 	setupShutdownHandlers();
 	setServerInstance(serve({
 		fetch: server.fetch,
 		port: options.port,
-		hostname: options.host
+		hostname: options.host,
+		bun: { websocket: {
+			open(ws) {
+				if (ws.data?.kind === "history") addClient(ws);
+			},
+			close(ws) {
+				if (ws.data?.kind === "history") removeClient(ws);
+			},
+			message() {}
+		} }
 	}));
 }
 function parseTimezoneOffset(value) {
@@ -9072,7 +9416,7 @@ const start = defineCommand({
 		"github-token": {
 			alias: "g",
 			type: "string",
-			description: "Provide GitHub token directly (must be generated using the `auth` subcommand)"
+			description: "Provide GitHub token directly (must be generated using the `auth` subcommand). Falls back to the GH_TOKEN env var if the flag is omitted — prefer the env for automation since argv is visible via /proc/<pid>/cmdline."
 		},
 		"claude-code": {
 			alias: "c",
@@ -9138,9 +9482,17 @@ const start = defineCommand({
 		"posthog-key": {
 			type: "string",
 			description: "PostHog API key for token usage analytics (opt-in, no key = disabled)"
+		},
+		"api-key": {
+			type: "string",
+			description: "Proxy API key for inbound authentication. When set (non-empty after trimming), all endpoints except / and /health require this key via 'Authorization: Bearer <key>'. Omitted or empty = auth disabled (default, all requests pass through)."
 		}
 	},
 	run({ args }) {
+		const resolvedApiKey = resolveProxyApiKey({
+			flag: args["api-key"],
+			env: process.env.COPILOT_API_KEY
+		});
 		return runServer({
 			port: Number.parseInt(args.port, 10),
 			host: args.host,
@@ -9152,7 +9504,7 @@ const start = defineCommand({
 			requestInterval: Number.parseInt(args["request-interval"], 10),
 			recoveryTimeout: Number.parseInt(args["recovery-timeout"], 10),
 			consecutiveSuccesses: Number.parseInt(args["consecutive-successes"], 10),
-			githubToken: args["github-token"],
+			githubToken: args["github-token"] || process.env.GH_TOKEN,
 			claudeCode: args["claude-code"],
 			showToken: args["show-token"],
 			showAllModels: args["show-all-models"],
@@ -9165,7 +9517,9 @@ const start = defineCommand({
 			stripServerTools: args["strip-server-tools"],
 			contextEditing: parseContextEditing(args["context-editing"]),
 			timezoneOffset: parseTimezoneOffset(args["timezone-offset"]),
-			posthogKey: args["posthog-key"]
+			posthogKey: args["posthog-key"],
+			apiKey: resolvedApiKey.key,
+			apiKeySource: resolvedApiKey.source
 		});
 	}
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dianshuv/copilot-api",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Turn GitHub Copilot into OpenAI/Anthropic API compatible server. Usable with Claude Code!",
   "author": "dianshuv",
   "type": "module",
@@ -22,8 +22,9 @@
     "release": "npm publish --access public --//registry.npmjs.org/:_authToken=$NPM_TOKEN",
     "start": "NODE_ENV=production bun run ./src/main.ts start",
     "test": "bun test tests/*.test.ts",
-    "test:all": "bun test tests/*.test.ts && bun test tests/integration/",
-    "test:integration": "bun test tests/integration/",
+    "test:all": "bun test tests/*.test.ts && bun test tests/integration/ --max-concurrency=1 --parallel=2 && bun test tests/e2e/ --max-concurrency=1 --parallel=2",
+    "test:e2e": "bun test tests/e2e/ --max-concurrency=1 --parallel=2",
+    "test:integration": "bun test tests/integration/ --max-concurrency=1 --parallel=2",
     "typecheck": "tsc"
   },
   "simple-git-hooks": {