ghc-proxy 0.10.2 → 0.10.3

package/README.md

@@ -110,6 +110,7 @@ ghc-proxy uses a subcommand structure:
 ```bash
 bunx --bun ghc-proxy@latest start          # Start the proxy server
 bunx --bun ghc-proxy@latest auth           # Run GitHub auth flow without starting the server
+bunx --bun ghc-proxy@latest auth --account work # Create or replace a named account
 bunx --bun ghc-proxy@latest check-usage    # Show your Copilot usage/quota in the terminal
 bunx --bun ghc-proxy@latest debug          # Print diagnostic info (version, paths, token status)
 bunx --bun ghc-proxy@latest selfcheck      # Probe tokenizer chunks and Bun/Node runtime contracts in the packaged bundle
@@ -191,17 +192,114 @@ The proxy normalizes and persists the GHE domain automatically after a successfu
 
 ## Configuration
 
-The proxy reads an optional JSON config file at:
+The proxy reads an optional JSON config file at:
 
 ```
-~/.local/share/ghc-proxy/config.json
-```
-
-All fields are optional. The full schema:
+~/.local/share/ghc-proxy/config.json
+```
+
+GitHub credentials are stored separately at
+`~/.local/share/ghc-proxy/credentials.json`. The credential file is versioned,
+selects one active account for legacy single-account mode, and can retain
+multiple named accounts:
+
+```json
+{
+  "version": 1,
+  "activeAccount": "default",
+  "accounts": {
+    "default": {
+      "githubToken": "<base64>",
+      "gheDomain": "company.ghe.com"
+    }
+  }
+}
+```
+
+Base64 is low-cost obfuscation, not encryption; anyone who can read the file can
+decode it. On first startup after upgrading, a legacy `config.json` token is
+copied into this store only after a complete temporary config backup is created.
+The legacy field and backup are removed after the stored credential succeeds at
+both GitHub identity validation and Copilot token acquisition. A failed or
+interrupted migration keeps the backup and reports its recovery path.
+
+### Named Account Routing
+
+Authenticate each account under a stable name:
+
+```bash
+bunx --bun ghc-proxy@latest auth --account default
+bunx --bun ghc-proxy@latest auth --account account1
+
+# A named GHE.com account keeps its own tenant beside its credential.
+bunx --bun ghc-proxy@latest auth --account work --ghe-domain company.ghe.com
+```
+
+Account names are case-sensitive, 1-64 characters, and may contain ASCII
+letters, numbers, `.`, `_`, and `-`; the first character must be alphanumeric.
+
+For an existing single-account installation, open the local Dashboard Accounts
+view. The current legacy account remains the default, and the bootstrap form
+suggests `defaultaccount.localhost` as its dedicated hostname. Edit that value
+if needed, then enable routing. The change is persisted transactionally and
+takes effect without restarting the process.
+
+You can also configure hostname routing directly in `config.json`:
+
+```json
+{
+  "accountRouting": {
+    "baseHostname": "localhost",
+    "defaultAccount": "default",
+    "hostnames": {
+      "default.localhost": "default",
+      "account1.localhost": "account1"
+    }
+  }
+}
+```
+
+With that configuration, `http://localhost:4141`, `http://127.0.0.1:4141`, and
+the stable dedicated hostname `http://default.localhost:4141` use `default`, while
+`http://account1.localhost:4141` uses `account1`. Every routed account must have
+exactly one dedicated hostname. The base hostname is an additional alias for
+the currently selected default; `127.0.0.1` is a fixed loopback alias for that
+same default. Switching the default never changes any dedicated hostname. DNS
+hostname matching is case-insensitive, ignores the request port, and accepts a
+trailing root dot. Any other hostname is rejected with HTTP `421` before a route handler or
+upstream request runs. `Forwarded` and `X-Forwarded-Host` are not trusted for
+account selection.
+
+Each account has independent GitHub/Copilot tokens, refresh scheduling, model
+cache, Responses emulator state, local rate limiter, and upstream queue/cooldown
+state. A failure or capacity response on one account never switches, falls back,
+rotates, or load-balances the request to another account. Process-wide policy
+configuration remains shared.
+
+`accountRouting` is opt-in so existing single-account installations retain their
+current Host behavior until the local Dashboard bootstrap is explicitly
+confirmed. The active legacy credential becomes the explicit default account;
+the suggested `defaultaccount.localhost` hostname is editable before commit. In
+routing mode every referenced account must already exist, and `defaultAccount`
+must be explicit. Invalid or ambiguous routing config fails startup. Dashboard
+bootstrap is unavailable while process-wide `start --github-token` or
+`start --ghe-domain` overrides are active, and those overrides are rejected once
+routing is enabled because they cannot identify one named account. Hostname
+routing is a deterministic selector, not an authorization boundary: callers
+that can reach the listener and choose a configured `Host` can select that
+account unless access is enforced separately.
+
+For Docker deployments, leave `GH_TOKEN` unset in routing mode and mount the
+populated credential/config directory. The image healthcheck reads
+`accountRouting.baseHostname`, applies the same DNS ASCII/case/root-dot
+normalization, and sends it as `Host` while connecting over loopback, so health
+checks continue to exercise the configured base hostname rather than the
+`127.0.0.1` default alias.
+
+All fields are optional. The full schema:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `githubToken` | `string` | unset | Persisted GitHub token. The device-code flow (`auth` or first startup) writes it automatically; `start --github-token` is runtime-only and does not write this field |
 | `modelRewrites` | `{ from, to }[]` | `[]` | Glob-pattern model substitution rules (see [Model Rewrites](#model-rewrites)) |
 | `modelFallback` | `object` | built-in family defaults | Override default model fallbacks (see [Customizing Fallbacks](#customizing-fallbacks)) |
 | `modelFallback.claudeOpus` | `string` | `claude-opus-5` | Fallback for `claude-opus-*` models |
@@ -224,8 +322,9 @@ All fields are optional. The full schema:
 | `upstreamRecoveryBudgetSeconds` | `number` | `60` | Shared recovery deadline after the first retryable outcome or active-cooldown encounter (`1..120` seconds) |
 | `overloadFallbacks` | `Record<string, string>` | `{}` (disabled) | Exact effective-model mappings for one opt-in fallback dispatch after terminal model `529` |
 | `upstreamQueueBaseDelaySeconds` | `number` | `2` | Base delay (seconds) for upstream retry backoff when `Retry-After` is absent |
-| `upstreamQueueMaxDelaySeconds` | `number` | `60` | Maximum computed backoff (seconds); does not clamp `Retry-After` |
+| `upstreamQueueMaxDelaySeconds` | `number` | `60` | Maximum computed backoff (seconds); does not clamp `Retry-After` |
 | `gheDomain` | `string` | unset | GitHub Enterprise Cloud company domain (persisted automatically after GHE.com auth) |
+| `accountRouting` | `{ baseHostname, defaultAccount, hostnames }` | unset | Opt-in exact DNS hostname to named-account routing; unknown hostnames are rejected |
 
 Example:
 
@@ -375,7 +474,7 @@ When the Copilot token response includes `endpoints.api`, `ghc-proxy` now prefer
 
 Incoming requests hit an [Elysia](https://elysiajs.com/) server. `chat/completions` requests are validated, normalized into the shared planning pipeline, and then forwarded to Copilot. `responses` requests use a native Responses path with explicit compatibility policies. `messages` requests are routed per-model and can use native Anthropic passthrough, the Responses translation path, or the existing chat-completions fallback. The translator tracks exact vs lossy vs unsupported behavior explicitly; see the [Messages Routing and Translation Guide](./docs/messages-routing-and-translation.md) and the [Anthropic Translation Matrix](./docs/anthropic-translation-matrix.md) for the current support surface.
 
-The built-in, read-only Dashboard projects process health, model routing, behavior, and recent request lifecycle metadata without storing request or response content. See [Dashboard Observability](./docs/design/dashboard-observability.md).
+The built-in Dashboard projects process health, named account status, model routing, behavior, and recent request lifecycle metadata without storing request or response content. Its protected Accounts view can explicitly bootstrap a legacy account into named routing, authenticate a new account with a dedicated hostname, and switch the default account. See [Dashboard Observability](./docs/design/dashboard-observability.md).
 
 For Anthropic `search_result` blocks, an April 17, 2026 probe against `claude-opus-4.6` on Copilot native `/v1/messages` accepted top-level search results and pure search-result tool outputs, but rejected top-level `citations` and mixed text/search-result tool output arrays. The native path sanitizes those observed rejection cases, while translated paths flatten search results to text; re-run the probe before treating that dated upstream result as universal.
 
@@ -426,7 +525,7 @@ This keeps the existing chat pipeline stable while allowing newer Copilot models
 | `GET`  | `/usage` | Copilot quota / usage monitoring |
 | `GET`  | `/token` | Inspect the current Copilot token |
 
-**Local Dashboard (read-only):**
+**Local Dashboard:**
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -437,8 +536,13 @@ This keeps the existing chat pipeline stable while allowing newer Copilot models
 | `GET` | `/dashboard/api/models` | Upstream model metadata and effective proxy capabilities |
 | `GET` | `/dashboard/api/behavior` | Active routing, compatibility policies, strategies, and effect counters |
 | `GET` | `/dashboard/api/requests` | Active requests and the most recent 256 completed request summaries |
+| `GET` | `/dashboard/api/accounts` | Safe per-account identity, tenant, authentication, Copilot status, quota, hostname, and default marker |
+| `POST` | `/dashboard/api/accounts/bootstrap` | Persist and enable named routing for the current legacy default account |
+| `POST` | `/dashboard/api/accounts` | Start device authentication for a new named account and its dedicated hostname |
+| `GET` | `/dashboard/api/account-auth/:id` | Read the safe state of an in-progress account authentication |
+| `POST` | `/dashboard/api/accounts/default` | Persist and activate an explicit default account |
 
-Dashboard routes are restricted to local access and return `403` when the peer, request host, or supplied `Origin` fails the loopback/same-origin checks. They are excluded from request history and access logging. See [Dashboard Observability](./docs/design/dashboard-observability.md) for the projection and security contract.
+Dashboard routes are restricted to local access and return `403` when the peer, request host, or supplied `Origin` fails the loopback/same-origin checks. A normal legacy single-account process exposes an explicit bootstrap action; adding accounts and changing the default remain unavailable until bootstrap succeeds. Processes using `start --github-token` or `start --ghe-domain` retain legacy behavior and return `409` for account management because those overrides cannot be assigned safely. Dashboard requests are excluded from request history and access logging. See [Dashboard Observability](./docs/design/dashboard-observability.md) for the projection, transaction, and security contract.
 
 > **Note:** The `/v1/` prefix is optional for OpenAI-compatible endpoints (`/chat/completions`, `/responses` and its resource routes, `/models`, `/embeddings`). Anthropic endpoints (`/v1/messages`, `/v1/messages/count_tokens`) require the `/v1` prefix. The utility and Dashboard endpoints are root-only and not exposed under `/v1`.
 
@@ -568,6 +672,9 @@ volumes:
 ## Running from Source
 
 Repository development uses Bun >= 1.4 even if you run the published package with Node.js.
+Install dev dependencies when building from source: `gpt-tokenizer` is a
+build-time dependency whose five encodings are still bundled into the published
+runtime for the local count endpoints and packaged `selfcheck`.
 
 ```bash
 git clone https://github.com/wxxb789/ghc-proxy.git
@@ -580,8 +687,8 @@ bun run start
 
 ## Development
 
-```bash
-bun install              # Install dependencies
+```bash
+bun install              # Install dependencies, including build-time tokenizer sources
 bun run dev              # Start with --watch
 bun run start            # Start without --watch
 bun run build            # Build with tsdown

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,27 @@
+# Third-Party Notices
+
+ghc-proxy bundles portions of `gpt-tokenizer` in its published JavaScript.
+
+## gpt-tokenizer
+
+MIT License
+
+Copyright (c) 2023-2024 Bazyli Brzoska
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.