@dianshuv/copilot-api 0.9.0 → 0.10.0

package/README.md

@@ -15,7 +15,6 @@
 - **Graceful shutdown**: 4-phase shutdown sequence — stops accepting requests, waits for in-flight requests to complete, sends abort signal, then force-closes. Configurable via `--shutdown-graceful-wait` and `--shutdown-abort-wait`.
 - **Stream repetition detection**: Detects when models get stuck in repetitive output loops using KMP-based pattern matching and logs a warning.
 - **Stale request reaping**: Automatically force-fails requests that exceed a configurable maximum age (default 600s) to prevent resource leaks.
-- **Gemini API compatibility**: `/v1beta/models` endpoints translate Gemini API requests to OpenAI format for Copilot. Enables Google Gemini CLI to use Copilot models via `GOOGLE_GEMINI_BASE_URL` environment variable.
 - **PostHog analytics**: Optional PostHog Cloud integration (`--posthog-key`) sends per-request token usage events for long-term trend analysis. Free tier (1M events/month) is more than sufficient for individual use.
 
 ## Quick Start
@@ -70,6 +69,7 @@ make down
 | `--github-token`, `-g` | Provide GitHub token directly | none |
 | `--claude-code`, `-c` | Generate Claude Code launch command | false |
 | `--show-token` | Show tokens on fetch/refresh | false |
+| `--show-all-models` | Show all upstream models including the hardcoded blacklist (see "Hidden Models" below) | false |
 | `--proxy-env` | Use proxy from environment | false |
 | `--no-history` | Disable request history UI at `/history` | false |
 | `--history-limit` | Max history entries in memory | 1000 |
@@ -80,6 +80,36 @@ 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
+
+By default the proxy hides 30 stale / duplicate / unused upstream model ids from
+its **listing surfaces** (`/v1/models`, the startup banner, and the
+`--claude-code` interactive prompts). Pass `--show-all-models` to see the full
+upstream catalogue.
+
+**Important**: this is a *display* filter only. The remaining POST endpoints
+(`/v1/chat/completions`, `/v1/messages`, `/v1/responses`) do **not** reject
+hidden ids — an explicit `POST` with a hidden id is still forwarded to
+upstream verbatim, even without `--show-all-models`. (The embedding and
+Gemini ids in the list have no callable endpoint in this proxy at all;
+they're hidden purely to denoise the `/v1/models` listing — the upstream
+`/models` catalogue still returns them.)
+
+To change the blacklist, edit `src/lib/hidden-models.ts` and re-publish (this
+fork uses `/publish`).
+
+Currently hidden (grouped):
+
+- **Legacy GPT** — `gpt-3.5-turbo`, `gpt-3.5-turbo-0613`, `gpt-4`, `gpt-4-0613`, `gpt-4-0125-preview`
+- **GPT-4o family** — `gpt-4o`, `gpt-4o-mini`, `gpt-4-o-preview`, `gpt-4o-2024-05-13`, `gpt-4o-2024-08-06`, `gpt-4o-2024-11-20`, `gpt-4o-mini-2024-07-18`
+- **GPT-4.1 family** — `gpt-4.1`, `gpt-4.1-2025-04-14`, `gpt-41-copilot`
+- **Older / smaller GPT-5** — `gpt-5-mini`, `gpt-5.3-codex`, `gpt-5.4`
+- **All embeddings** — `text-embedding-ada-002`, `text-embedding-3-small`, `text-embedding-3-small-inference`
+- **Older Gemini** — `gemini-2.5-pro`, `gemini-3-flash-preview`
+- **Older / variant Claude** — `claude-opus-4.5`, `claude-opus-4.6`, `claude-opus-4.7-high`, `claude-opus-4.7-xhigh`, `claude-sonnet-4.5`
+- **Special-purpose** — `mai-code-1-flash-internal`, `trajectory-compaction`
 
 ### Patch-Claude Command Options
 
@@ -98,7 +128,6 @@ make down
 |----------|--------|-------------|
 | `/v1/chat/completions` | POST | Chat completions |
 | `/v1/models` | GET | List available models |
-| `/v1/embeddings` | POST | Text embeddings |
 | `/v1/responses` | POST | Responses API (for codex models) |
 
 ### Anthropic Compatible
@@ -109,14 +138,6 @@ make down
 | `/v1/messages/count_tokens` | POST | Token counting |
 | `/v1/event_logging/batch` | POST | Event logging (no-op) |
 
-### Gemini Compatible
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/v1beta/models/{model}:generateContent` | POST | Non-streaming generation |
-| `/v1beta/models/{model}:streamGenerateContent` | POST | Streaming generation (SSE) |
-| `/v1beta/models/{model}:countTokens` | POST | Token counting |
-
 ### Utility
 
 | Endpoint | Method | Description |
@@ -137,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:
@@ -146,8 +291,8 @@ Create `.claude/settings.json` in your project:
   "env": {
     "ANTHROPIC_BASE_URL": "http://localhost:4141",
     "ANTHROPIC_AUTH_TOKEN": "dummy",
-    "ANTHROPIC_MODEL": "gpt-4.1",
-    "ANTHROPIC_SMALL_FAST_MODEL": "gpt-4.1",
+    "ANTHROPIC_MODEL": "claude-opus-4.8",
+    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4.5",
     "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1",
     "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
   },
@@ -163,23 +308,6 @@ Or use the interactive setup:
 bun run start --claude-code
 ```
 
-## Using with Gemini CLI
-
-```bash
-# Start the proxy
-copilot-api start
-
-# Configure Gemini CLI to use the proxy
-export GEMINI_API_KEY="placeholder"
-export GOOGLE_GEMINI_BASE_URL="http://localhost:4141"
-
-# Basic conversation
-gemini -p "Explain this code"
-
-# Pipe review
-git diff HEAD~1 | gemini -p "Review this diff for bugs"
-```
-
 ## Upstream Project
 
 For the original project documentation, features, and updates, see: [ericc-ch/copilot-api](https://github.com/ericc-ch/copilot-api)