@coder/ai-sdk-provider 0.3.1 → 0.3.3

package/README.md

@@ -115,6 +115,133 @@ createCoder({
 | `providers`     | `{ openai?, anthropic? }` | `openai` / `anthropic` | Override the admin-configured provider path segments.                                                 |
 | `fetch`         | `typeof fetch`            | global `fetch`         | Custom fetch (testing / middleware).                                                                  |
 
+## Enterprise governance & security
+
+Reference for security reviewers evaluating this package. The boundary between
+the two kinds of claims below matters: **client behavior** (what this package
+puts on the wire) is verifiable in [`src/provider.ts`](./src/provider.ts) —
+~175 lines with no dependencies beyond the official AI SDK provider packages —
+while **gateway behavior** (key custody, audit capture, retention) is a
+property of your Coder deployment, enforced server-side regardless of what any
+client does, and documented in the
+[AI Gateway docs](https://coder.com/docs/ai-coder/ai-gateway).
+
+### Data flow
+
+```text
+your app ──HTTP(S)──▶ your Coder deployment ──▶ upstream provider
+ (this package)       (AI Gateway intercepts    (Anthropic, OpenAI,
+                       /api/v2/aibridge/…)       Bedrock, Copilot, …)
+```
+
+**What leaves your app.** This package's only network destination is the
+`baseURL` you configure. It never contacts upstream vendors directly and adds
+no telemetry of its own; each request is exactly what the AI SDK builds for a
+normal provider call:
+
+- **URL** — `POST <baseURL>/api/v2/aibridge/<provider>/v1/chat/completions`
+  (OpenAI surface; `…/v1/embeddings` for `textEmbeddingModel`) or
+  `…/v1/messages` (Anthropic surface). `/api/v2/aibridge` is this package's
+  default; deployments also serve the post-rename alias `/api/v2/ai-gateway`
+  (see `aiGatewayPath`).
+- **Auth headers** — per the mode matrix below.
+- **Body** — standard OpenAI-/Anthropic-format JSON: the model id (passed
+  through unchanged), your full prompt/message content, tool definitions, and
+  sampling parameters. Prompt content is visible to the Gateway — that is what
+  enables auditing.
+- Anything you add via the `headers` option.
+
+Transport security follows the scheme of your `baseURL` — the client does not
+enforce `https://` (an `http://` URL sends tokens, keys, and prompts in
+plaintext). Always use an HTTPS deployment URL outside trusted local
+environments.
+
+**What the Gateway does before forwarding** _(server-side —
+[authentication docs](https://coder.com/docs/ai-coder/ai-gateway/auth))_: it
+authenticates the token as an active Coder user and rejects the request
+outright when it is missing or invalid (nothing is forwarded upstream), strips
+all Coder credentials from the outbound request, and attaches the upstream
+credential for the mode in use.
+
+### Credential isolation: centralized vs. BYOK
+
+|                                 | **Centralized (default)**                                             | **BYOK**                                                                                                                                 |
+| ------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Your app holds                  | Coder API token only                                                  | Coder API token **+** the user's own upstream key                                                                                        |
+| On the wire                     | `Authorization: Bearer <Coder token>` (both surfaces)                 | `X-Coder-AI-Governance-Token: <Coder token>`; upstream key in `Authorization: Bearer` (OpenAI surface) / `x-api-key` (Anthropic surface) |
+| Upstream provider keys live     | On the deployment, admin-configured — never distributed to developers | With the individual user; forwarded per request, bypassing the deployment's central key pool                                             |
+| Coder token forwarded upstream? | **No** — stripped and replaced by the deployment's provider key       | **No** — the governance header is stripped before forwarding                                                                             |
+| Admin control                   | Provider and key configuration, rotation, failover                    | Can be disabled deployment-wide (`CODER_AI_GATEWAY_ALLOW_BYOK=false` rejects requests carrying the governance header with `403`)         |
+
+Both modes are audited identically: audit records store _which credential
+kind_ was used (`centralized` / `byok`), not the credential itself.
+
+### Audit capture
+
+Every request is attributed to the Coder user whose token authenticated it —
+per user, per request, in both modes. Per intercepted request the Gateway
+records _(server-side —
+[audit docs](https://coder.com/docs/ai-coder/ai-gateway/audit))_:
+
+- **Identity & metadata** — initiating user, provider, model, client,
+  credential kind, timestamps.
+- **Last user prompt** — earlier turns and system prompts are not stored.
+- **Token usage** — input / output / cache counts.
+- **Tool calls** — tool name and arguments; tool _results_ are not stored.
+- **Model reasoning** — extended-thinking / reasoning-summary content when
+  present.
+
+Model-generated response text is **discarded**, not stored. Retention defaults
+to **60 days** and is configurable (`CODER_AI_GATEWAY_RETENTION`; `0` keeps
+data indefinitely). Auditors browse sessions and causal tool-call chains in
+the deployment dashboard under `/ai-gateway/sessions`.
+
+### Required Coder permissions
+
+| To…                                          | You need                                                                                                                                                      |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Send requests through the Gateway            | An active Coder user with a valid API token — no extra role. (RBAC: members hold create/update on `aibridge_interception`, i.e. recording their own traffic.) |
+| Read audit data (prompts, tool calls, usage) | The **Owner** or **Auditor** role. Regular members cannot read interceptions back — not even their own.                                                       |
+| Configure providers / keys, toggle BYOK      | Deployment administrator (server flags / deployment configuration).                                                                                           |
+| Use the feature at all                       | A deployment licensed for [AI Governance](https://coder.com/docs/ai-coder/ai-governance) — the Gateway is license-gated server-side.                          |
+
+### Security FAQ
+
+- **Does prompt data ever go anywhere other than my deployment?** This package
+  only ever _initiates_ requests to `baseURL`; onward traffic to the upstream
+  vendor originates from your deployment (or its standalone gateway replicas),
+  using the providers your admins configured. One standard-`fetch` caveat:
+  redirects are followed by default, so a cross-origin redirect issued by your
+  deployment or an intermediary would resend the request — prompt body and
+  non-`Authorization` headers (in BYOK mode that includes `x-api-key` and the
+  governance token) — to the redirect target. To forbid this, supply a custom
+  fetch: `fetch: (url, init) => fetch(url, { ...init, redirect: "error" })`.
+- **Do developers ever handle raw provider keys?** Centralized mode: no —
+  developers only ever hold a Coder token. BYOK mode: they supply their own
+  personal key, which is forwarded per request without entering central custody.
+- **What is the blast radius of a leaked Coder token?** A Coder API token is
+  not an AI-only credential — it grants the bearer the user's **full Coder API
+  permissions** (workspaces, templates, and anything else that user's roles
+  allow), and, until revoked or expired, AI usage through your Gateway (fully
+  attributed to that user). What it can _not_ do is authenticate to upstream
+  vendors: under normal Gateway forwarding it is stripped and does not leave
+  your deployment (the cross-origin-redirect caveat above is the exception —
+  a redirect can resend non-`Authorization` headers, including the governance
+  header, before the Gateway ever sees them). Treat a leak as a Coder account
+  compromise — revoke the token — and prefer short-lived, dedicated tokens
+  for AI workloads.
+- **Is model-generated content stored?** Partially. Assistant _response text_
+  is discarded, but two model-generated artifacts are retained for auditing:
+  reasoning content (extended thinking / reasoning summaries) and tool-call
+  arguments — alongside the last user prompt and token counts.
+- **Can I verify the client claims myself?** Yes: [`src/provider.ts`](./src/provider.ts)
+  is the entire wire-facing surface — it only selects base URLs and auth
+  headers, then delegates request construction to the official AI SDK provider
+  packages. [`test/provider.test.ts`](./test/provider.test.ts) asserts the
+  request URL, auth headers, and model pass-through for the chat/messages
+  routes in both auth modes; the underlying AI SDK packages add their own
+  protocol headers (e.g. `anthropic-version`) and are not re-tested here.
+
 ## Examples
 
 Runnable scripts live in [`examples/`](./examples) (run against a real deployment via `tsx`):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coder/ai-sdk-provider",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Vercel AI SDK provider for Coder AI Gateway. Point the AI SDK at your Coder deployment with a Coder API token and use any model your deployment proxies — across AI Gateway's OpenAI- and Anthropic-compatible surfaces.",
   "keywords": [
     "ai",