passcontrol 0.9.0 → 0.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,541 +1,297 @@
1
1
  # PassControl
2
2
 
3
- **An identity & credential gateway for AI agents.** Stop pasting your OpenAI / Anthropic /
4
- Groq / Mistral / Together / DeepSeek keys into agent runtimes. Start with a named,
5
- revocable **Direct Agent Key**, or give the agent a higher-assurance cryptographic
6
- **passport** that signs challenges for short-lived **work-visas**. The gateway injects your
7
- *real* provider key from a vault and proxies the call — so **the agent never holds the key**.
8
- You get per-agent budgets, capability scopes, an instant kill switch, and a per-agent audit trail.
9
-
10
- A [Vertias](https://vertias.eu) project. **Bring-your-own-key** — your provider key stays in your
11
- own vault when self-hosted, or in the managed server-side Vault in PassControl Cloud. Cloud is
12
- currently a free private beta; [request access](https://passcontrol.vertias.eu/beta).
13
-
14
- ### ▶ [See it work in 60 seconds →](https://passcontrol.vertias.eu)
15
-
16
- No signup, no provider key, nothing to install. Run a governed AI call, arm the kill switch,
17
- run the same call again, and watch it get blocked at the gateway. The demo runs the **real**
18
- pipeline — passport → work-visa → scope + budget checks → kill switch — and only the model
19
- response is synthesized, by a keyless provider that never touches a vault.
20
-
21
- The hosted demo includes the public **signed-receipt verifier** at
22
- [`/verify/receipt`](https://passcontrol.vertias.eu/verify/receipt). Verification runs in your
23
- browser; the receipt is never uploaded to PassControl. Release-by-release changes are collected
24
- in the public [PassControl updates](https://passcontrol.vertias.eu/updates) archive. The
25
- [AI agent security learning center](https://passcontrol.vertias.eu/learn) explains identity,
26
- credential isolation, least privilege, budgets, revocation and audit evidence without treating
27
- one product layer as the whole security stack.
28
-
29
- **Hermes Agent:** the dashboard prints Hermes's current custom-provider YAML for a reveal-once
30
- Direct Agent Key — the simplest path. For passport identity in Hermes, run the connector and
31
- print its form with `passcontrol env hermes`; that works against Cloud too.
32
- See [`docs/integrations/hermes.md`](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
33
-
34
- **Never paste a passport private key into a client's `api_key` field.** A passport is a signing
35
- key, not a bearer token — a client that only stores a static string cannot sign a challenge, so
36
- the call is refused and the key is exposed. Static-key clients take a Direct Agent Key or the
37
- connector.
38
-
39
- ![PassControl kill switch — a live agent's calls flip from 200 OK to 403 BLOCKED the instant the kill switch is armed, then back when it's released](https://raw.githubusercontent.com/Vertias3u/PassControl/main/docs/demo/kill-switch.gif)
40
-
41
- *Instant, per-agent revocation — the kill switch cuts off a live agent mid-run (`200 OK` → `403 BLOCKED`) and restores it, with no key rotation and no redeploy. Real traffic through the gateway; the status codes and timestamps are live.*
42
-
43
- > ⚠️ **Status: early.** Built by a small team, **not yet independently audited.** It's
44
- > security-focused and test-covered, but treat it as beta — run it against a **non-critical key
45
- > first**, and see [Security](#security) for responsible disclosure. We'd rather you know than
46
- > find out.
47
-
48
- **New here?** The [Getting Started tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md) takes you from install to a real
49
- governed agent in ~15 minutes.
50
-
51
- ```bash
52
- npm install -g passcontrol
53
- passcontrol login # approve once in your browser — this machine is set up
3
+ PassControl is an identity and credential gateway for AI agents. It keeps
4
+ provider API keys out of agent configuration and applies per-agent scopes, policies,
5
+ budgets, and stop controls before forwarding model requests.
6
+
7
+ Bring your own provider key. In **Cloud**, it is stored in the managed server-side
8
+ Supabase Vault. When **self-hosted**, you operate the gateway, Vault, database, and
9
+ Redis. In both cases the gateway decrypts and injects the provider key; the agent
10
+ receives the provider response, not that key. The gateway operator remains trusted:
11
+ this is credential isolation, not end-to-end encryption from the agent to the provider.
12
+
13
+ Built by one developer under [Vertias](https://vertias.eu). Early software, **not yet
14
+ independently audited**. Start with a non-critical provider key. Source-available
15
+ under [BSL 1.1](./LICENSE).
16
+
17
+ ## Request and authentication flow
18
+
19
+ ```text
20
+ Direct Agent Key ───────────────────────────────────────────────┐
21
+ v
22
+ Passport private key ── signs challenge ──> short-lived visa ──> gateway
23
+ stays client-side + request proof |
24
+ when required |
25
+ authentication → kill/suspend → scope/policy → budget hold
26
+ |
27
+ Vault key → provider → response
28
+ |
29
+ settlement + best-effort log/receipt
54
30
  ```
55
31
 
56
- Nothing else to install: the npm package is the CLI, not the stack. `login` ends by making one
57
- governed call and verifying its **signed receipt** against our published key, so you watch the
58
- thing work rather than being told it does. Want a look first? The
59
- [hosted demo](https://passcontrol.vertias.eu) runs the same pipeline in your browser, keyless.
60
-
61
- Prefer to run the whole gateway yourself? `passcontrol setup` does that, and needs **Docker
62
- Desktop, the Supabase CLI, and Node 18+** — see [Self-host](#self-host).
63
-
64
- ---
65
-
66
- ## Why
67
-
68
- A raw provider key handed to an autonomous agent **leaks** (logs, repos, prompts), **never
69
- rotates**, has **no per-agent spend cap**, **no off-switch**, and leaves **no record** of which
70
- agent did what. PassControl takes the key out of the agent entirely and puts a governed gateway
71
- in front of it.
72
-
73
- ## How it works
74
-
75
- 1. **Identity** — use a reveal-once Direct Agent Key in the provider-native SDK or compatible client, or a
76
- passport whose Ed25519 private key only signs and never travels over the wire.
77
- 2. **Work-visa (passport mode)** — the agent signs a challenge (timestamp + single-use nonce) and mints a
78
- short-lived (~5 min) token carrying its identity, scope, and budget snapshot.
79
- 3. **Inject & proxy** — a request arrives bearing a visa. The gateway verifies it → checks the
80
- kill switch → checks scope (provider + model **and** endpoint) → reserves budget atomically →
81
- pulls your provider key from the vault → injects it → forwards to the provider and streams
82
- back. The agent never sees the key.
83
- 4. **Govern** — per-agent **token + dollar** budgets (enforced *before* the call), a layered kill
84
- switch (platform / tenant / per-agent), and an append-only audit log of every call.
85
-
86
- ```
87
- agent ──sign──▶ challenge ──visa──▶ ┌─────────── PassControl gateway ───────────┐
88
- │ verify · kill/scope/budget · inject key │ ──▶ provider
89
- (holds only a passport key) │ (real key from vault, never returned) │ ◀── stream
90
- └────────────────────────────────────────────┘
91
- ```
92
-
93
- ## Features
94
-
95
- - 🔑 **Agents never hold your provider key** — BYOK; the key stays vaulted, injected in-flight only
96
- - 🪪 **Per-agent cryptographic identity** (Ed25519) with short-lived, revocable visas
97
- - 🔌 **Direct Agent Keys** — named, independently revocable installation credentials for a
98
- fast provider-native on-ramp, with receipts that never mislabel them as passports
99
- - 💸 **Enforced per-agent token + cost (USD) budgets** — reserved pre-flight, reconciled after
100
- - 🎯 **Capability scoping** — a visa is scoped to specific models *and* endpoints, so a
101
- chat-scoped agent can't reach files, fine-tuning, batches, embeddings, etc. with your key
102
- - ⛔ **Instant, layered kill switch** + per-agent suspend/revoke — stop a running agent mid-task
103
- - 📒 **Append-only audit trail** per agent/passport (direct `UPDATE`/`DELETE`/`TRUNCATE` rejected
104
- by the database)
105
- - 🧾 **Signed call receipts** — a governed call, allowed *or* blocked, is recorded in an
106
- Ed25519-signed artifact a counterparty can check without an account, your database, or your
107
- permission ([details below](#signed-call-receipts))
108
- - 🌐 **Paste-and-check verification page** at `/verify/receipt` — runs entirely in the visitor's
109
- browser; the receipt is never uploaded
110
- - 👤 **Owner binding** — declare who your agents are operated by, so a receipt can say *whose*
111
- agent made the call. Self-declared by default; provable by domain control or an identity
112
- check, and the two are stored and rendered separately so a claim never passes as a fact
113
- - 🧰 **Drop-in for your SDK** (OpenAI, Anthropic, and OpenAI-compatible Groq / Mistral / Together /
114
- DeepSeek) — **or any agent or desktop chat app** that takes a base URL and a key (OpenHands,
115
- Aider, Cline, Continue, Chatbox, Jan, Msty, Cherry Studio, Open WebUI, LibreChat…): a Cloud
116
- Direct Agent Key on the hosted service, or the passport connector. None of them has native
117
- passport support; the connector is what supplies passport identity to a static-key tool —
118
- against Cloud or a self-hosted gateway
119
- - 🔌 **Local MCP server** for Claude Desktop, Cursor, and Claude Code — governed `chat` and
120
- `list_models` tools with no provider key or passport secret in the client config
121
- - 🪪 **Agent passport page** — a per-agent identity document: a sigil derived from the
122
- agent's public key, its visas (allowed scopes), the providers it has actually reached,
123
- budget state, and a redacted PNG you can export
124
- - 🖥️ **Control Tower** dashboard (fleet, spend, budgets, audit, kill switch) + a developer
125
- control-plane API + TOTP MFA
126
-
127
- ## Install & first run
128
-
129
- **Cloud — one command, and nothing else installed.** The published npm package is the CLI
130
- only: no dashboard, no database, no Docker, no Supabase.
32
+ A Passport private key never reaches Cloud or the gateway. It signs challenge bytes
33
+ locally to mint a work-visa; the sidecar also signs request proofs. Visas are
34
+ HS256 tokens, normally valid for five minutes (`VISA_TTL_SECONDS`: 300–900 seconds).
35
+
36
+ | Credential | What the client does | Boundary |
37
+ |---|---|---|
38
+ | **Direct Agent Key (DAK)** | Sends a named, reveal-once `pc_agent_…` bearer key | Bound to one agent; hash stored server-side, optional expiry, independently revocable. Works with static-key clients. Does not mint visas or authorize control-plane operations. |
39
+ | **Passport** | Holds an Ed25519 keypair and signs challenges for visas | Proves possession at mint. Private key stays in the SDK runtime, CLI, sidecar, or MCP process. |
40
+ | **Passport with required sender proof** | Sends a fresh signed proof with each visa-authenticated request | A stolen visa alone is insufficient. The proof binds method, gateway origin/path, time, nonce, and visa hash. |
41
+ | **Control key** | Sends `pc_…` to `/api/control/v1` | Manages the workspace; separate from either agent credential. Keep it out of agent integrations. |
42
+
43
+ Passport sender-proof modes are **off**, **observe**, and **required**. Off ignores
44
+ proofs; observe records what would pass without enforcing it; required rejects missing,
45
+ invalid, stale, or replayed proofs. Only enforced success is recorded as
46
+ `passport_proof_per_request`; observing a valid proof does not upgrade authentication.
47
+ The sidecar supplies proofs; the direct CLI call, MCP chat, and TypeScript SDK
48
+ do not attach them and cannot use required mode without an additional proof implementation.
49
+ Proofs do **not** bind the request body or query string and do not attest hardware or
50
+ key storage. See [authentication and lifecycle](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md).
51
+
52
+ Passport expiry and rotation grace are checked at mint, not on every existing visa.
53
+ Use suspend/revoke or a kill switch to stop subsequent requests using issued visas;
54
+ these controls do not cancel an upstream request already in flight. Public lifecycle
55
+ checks and the signed [revocation list](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md)
56
+ are separate from signature verification.
57
+
58
+ ## What the gateway enforces
59
+
60
+ - An allowlist of provider endpoints, plus the agent's provider/model scope.
61
+ - Live policy rules: model/endpoint denials, time windows, request limits; optional
62
+ shadow evaluation records candidate decisions without enforcing them.
63
+ - Token and cost admission limits through atomic reservations and settlement.
64
+ - Platform/tenant kill switches and per-agent suspension/revocation.
65
+ - Provider failover within supported request families and each attempt's authorization
66
+ and budget checks; it is not arbitrary API translation.
67
+
68
+ Passport scopes are snapshots in visas; scope edits can take up to the configured visa
69
+ TTL to replace those snapshots. Other live controls have their own cache/invalidation
70
+ behavior. Kill-state reads default to fail-open; `KILL_SWITCH_FAIL_CLOSED=true` blocks
71
+ on kill/suspend read failure. Required sender-proof replay checks and DAK credential
72
+ validation fail closed. Redis persistence and no-eviction configuration matter.
73
+
74
+ ### Budgets under uncertainty
75
+
76
+ Admission reserves an **estimate**, not a provider invoice or a guaranteed upper bound.
77
+ Concurrent attempts consume reserved headroom. Complete usage settles measured tokens
78
+ and table-priced cost; actual usage can exceed the estimate and cap. Anthropic cache
79
+ reads/writes count toward token usage as well as their applicable price.
80
+
81
+ A broken stream, missing usage, or ambiguous dispatch is not assumed free. An uncertain
82
+ settlement retains at least the estimate (or higher observed usage); an attempt whose
83
+ ending never runs leaves an open hold that does not expire. `may_have_dispatched`
84
+ means dispatch permission was claimed, not that billing is proven. Such a hold cannot
85
+ be released as `not_spent` through recovery.
86
+
87
+ Lost or mismatched established budget generations cause `503 blocked_budget_state`,
88
+ not a fresh allowance. Recovery is an explicit operator action over retained logs and
89
+ adjustments; it cannot reconstruct missing evidence. See [Budget recovery](https://github.com/Vertias3u/PassControl/blob/main/docs/budget-recovery.md).
90
+
91
+ Prices are an in-code estimate table. Unknown models on built-in endpoints use a
92
+ provider fallback rate. **Custom endpoints are unpriced**, even when the model name
93
+ matches: logs mark cost unknown, receipts carry `unp`, and token accounting continues.
94
+ The cost budget retains a proxy estimate; it does not become knowledge of actual dollars.
95
+ Known/table-priced cost, conservative enforced spend, and open holds are different figures.
96
+
97
+ ## Supported providers and endpoints
98
+
99
+ All paths below are relative to `/api/v1/<provider>`. SDK base URLs and aliases are in
100
+ [the endpoint reference](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md).
101
+
102
+ | Provider ID | Inference | Discovery |
103
+ |---|---|---|
104
+ | `openai` | Chat Completions and **POST Responses** | Models list/detail |
105
+ | `anthropic` | Messages | Models list/detail |
106
+ | `groq`, `mistral`, `together` | OpenAI-compatible Chat Completions | Models list/detail |
107
+ | `deepseek` | OpenAI-compatible Chat Completions | Not proxied |
108
+ | `gemini` | Google's **OpenAI-compatible** Chat Completions | Models list/detail |
109
+
110
+ Gemini's native `generateContent` API is not supported. Responses support is OpenAI-only;
111
+ response retrieval/deletion, embeddings, files, fine-tuning, batches, and token-counting
112
+ endpoints are not proxied. Model availability still depends on your provider account.
113
+
114
+ Custom provider base URLs support compatible deployments such as Ollama, vLLM, or
115
+ LiteLLM without adding provider IDs. They require operator opt-in:
116
+ `PROVIDER_ENDPOINT_MODE=selfhost` permits HTTP, private addresses, and custom ports;
117
+ a comma-separated hostname list permits only listed HTTPS hosts on port 443. Unset/off
118
+ refuses custom endpoints. Shape validation is **not full SSRF prevention**: it does not
119
+ resolve or pin DNS. Operators must control egress and trust the destination receiving
120
+ the provider credential. Upstream redirects are refused, never followed.
121
+
122
+ ## Receipts, statements, and identity evidence
123
+
124
+ A signed call receipt records the issuer's decision, authentication method, reported
125
+ usage/cost, and (when read) a digest of client request bytes. It does not include the
126
+ provider response body. Verify it with an explicitly trusted issuer:
131
127
 
132
128
  ```bash
133
- npm install -g passcontrol
134
- passcontrol login # opens your browser, you approve once, this machine is set up
135
- ```
136
-
137
- `login` prints an 8-character code, copies it to your clipboard, and opens the approval page.
138
- Paste it, press **Approve**, and the CLI generates an Ed25519 keypair *on your machine* — only
139
- the public half is ever sent — creates your agent, and writes a working config. No 43-character
140
- secrets travel between a browser and a terminal.
141
-
142
- Then it proves it worked, before handing the terminal back:
143
-
129
+ passcontrol verify receipt "<jws>" --issuer https://your-gateway.example
144
130
  ```
145
- ✓ minted a visa with the passport this machine just created
146
- ✓ governed call ok — demo/demo-1, 12 tokens
147
- ✓ receipt verified against https://passcontrol.vertias.eu/.well-known/jwks.json
148
131
 
149
- Your agent is live. Anyone can check that call for themselves:
150
- passcontrol verify receipt eyJhbGc… --issuer https://passcontrol.vertias.eu
151
- ```
132
+ The public `/.well-known/jwks.json` publishes instance verification keys;
133
+ [the hosted receipt verifier](https://passcontrol.vertias.eu/verify/receipt) and
134
+ `/verify/receipt` on your deployment check in the visitor's browser. A valid signature proves that key
135
+ signed those bytes. It does not prove the issuer is honest, the provider billed that
136
+ amount, or all calls were recorded. Logging/signing is best-effort; absent receipts
137
+ prove nothing. Retain old public keys for historical verification when rotating the
138
+ instance signer.
152
139
 
153
- That last line is the part nobody else has. It is a signed record of one governed call that a
154
- stranger can verify offline against a public key, with no account and no access to your logs.
140
+ **Cloud signed spend statements** commit to a fixed set of receipts using a Merkle root
141
+ and link to a preceding statement. Inclusion proofs establish membership in that signed
142
+ set. They do not independently audit totals, completeness, or provider invoices. A chain
143
+ check needs the relevant earlier statements or a trusted checkpoint. The public self-host
144
+ tree ships the format and verification code/page, **not statement production, scheduling,
145
+ or statement/proof-serving routes**. See [statement format and limits](https://github.com/Vertias3u/PassControl/blob/main/docs/statement-format.md).
155
146
 
156
- You type the code in yourself on purpose. **We will never send you an approval link with the
157
- code already filled in**; if you receive one, it is not from us, and approving it would hand
158
- whoever sent it a key to your workspace.
147
+ Owner binding is per workspace. A typed owner is a declaration; GitHub verification
148
+ checks publication of a token in a particular account's repository, and domain
149
+ verification checks a well-known HTTPS token. Neither proves a person's legal identity
150
+ or trustworthiness. Company registry evidence is also distinct from authority to represent
151
+ that company. Only published bindings are attached to public evidence.
159
152
 
160
- Now point an agent at it:
153
+ ![Recorded kill-switch demonstration: subsequent requests are refused](https://raw.githubusercontent.com/Vertias3u/PassControl/main/docs/demo/kill-switch.gif)
161
154
 
162
- ```bash
163
- passcontrol sidecar # holds the passport, mints visas, forwards to Cloud
164
- passcontrol env openhands # ready-to-paste settings for your agent
165
- ```
155
+ The recording illustrates a stop control on successive calls; it does not show cancellation
156
+ of an already-dispatched stream.
166
157
 
167
- Finished with a machine? `passcontrol logout` revokes its control key and clears its
168
- credentials, leaving your provider and model settings alone.
158
+ ## Try Cloud
169
159
 
170
- **Configuring by hand, or wiring up CI?** `passcontrol init` walks through gateway + passport +
171
- provider/model with no browser, and plain environment variables work everywhere the config file
172
- does.
160
+ [Request access to the free private beta](https://passcontrol.vertias.eu/beta), or try
161
+ [the keyless browser demo](https://passcontrol.vertias.eu). The demo synthesizes model
162
+ output; it does not exercise a billed provider.
173
163
 
174
- **Want to run the whole thing yourself?** That is [Self-host](#self-host) below. `passcontrol
175
- setup` is the self-host command, and it is the one that wants Docker and the Supabase CLI —
176
- neither `login` nor the sidecar wants either.
177
-
178
- > Working from a **source clone** instead of the global install? Everything below works as
179
- > `npm run cli -- <command>`; after `npm link` in the clone, the short `passcontrol <command>` form
180
- > works too.
181
-
182
- ## Claude Desktop, Cursor, and Claude Code via MCP
183
-
184
- PassControl ships a local stdio MCP server. Store the passport once in the owner-only global
185
- profile, then let the CLI merge a secret-free entry into your client config:
164
+ With Node installed:
186
165
 
187
166
  ```bash
188
- passcontrol login # or `passcontrol init --global` to do it by hand
189
- passcontrol configure claude-desktop --write # or: cursor
190
- # Claude Code: passcontrol configure claude-code prints its `claude mcp add` command
167
+ npm install -g passcontrol
168
+ passcontrol login
191
169
  ```
192
170
 
193
- Restart the client, then use the governed `chat` and `list_models` tools. The generated config
194
- contains only absolute Node/CLI paths—no passport or provider key. `chat` still goes through the
195
- gateway's identity, scope, budget, endpoint, and kill-switch checks. Preview without writing via
196
- `passcontrol configure claude-desktop`, or print the JSON with `passcontrol env claude-desktop`.
197
-
198
- ## Real agents & the passport connector
199
-
200
- > **The connector is not self-hosting.** It is a small local signer — one foreground process,
201
- > no Docker, no database — that holds your passport and talks to whichever gateway you configure,
202
- > **including PassControl Cloud**. Running it is the same shape as running a cloud provider's
203
- > local auth proxy: the control plane stays hosted, only the signing key stays yours.
204
- >
205
- > Pick by what your client can do, not by where the gateway lives:
206
- >
207
- > | Your client | Credential | Local process? |
208
- > |---|---|---|
209
- > | You control its JS/TS | **Passport** via [the SDK](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) | none |
210
- > | Claude Desktop / Cursor / Claude Code | **Passport** via `passcontrol mcp` | the MCP server |
211
- > | Takes only a base URL + API key | **Passport** via this connector | the connector |
212
- > | Takes only a base URL + API key | **Direct Agent Key** — simplest | none |
213
- >
214
- > A Direct Agent Key is lower-assurance bearer possession, issued reveal-once from the dashboard
215
- > and bound to one agent. It is the right default for a static-key tool. The connector is what you
216
- > reach for when you want passport identity in that same tool — on Cloud or self-hosted alike.
217
-
218
- A visa is deliberately short-lived so it's revocable — but a real coding agent runs a **long,
219
- multi-call session** that would outlive a single visa. The **sidecar** solves this: a tiny local
220
- proxy that mints, caches, and auto-refreshes the visa (and re-mints instantly on expiry), so your
221
- agent points at one stable endpoint and **never times out mid-task**.
222
-
223
- ```bash
224
- passcontrol sidecar # http://127.0.0.1:8788
225
- passcontrol env openhands # prints ready-to-paste settings for your agent
226
- ```
171
+ Login prints a device code and opens browser approval. Enter only the code from your
172
+ own terminal: approval grants this machine a workspace control key. The CLI creates a
173
+ Passport locally, registers its public key, saves configuration, and attempts a keyless
174
+ governed call and receipt verification. That proof requires a gateway with demo and
175
+ signing enabled; it is not a real-provider test. See [the tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md).
227
176
 
228
- Point any OpenAI/Anthropic-compatible agent at the sidecar with a **dummy** key:
177
+ Run **`passcontrol`** with no arguments in an interactive terminal to open the command
178
+ browser: searchable grouped commands, recent actions, and configuration-aware options.
179
+ Use `passcontrol --help` or explicit commands in scripts.
229
180
 
230
181
  ```bash
231
- export ANTHROPIC_BASE_URL="http://127.0.0.1:8788/api/v1/anthropic" # or /api/v1/openai, /deepseek…
232
- export ANTHROPIC_API_KEY="passcontrol" # ignored — the sidecar injects a live visa
182
+ passcontrol status
183
+ passcontrol call "Say hello" # off/observe mode; real provider calls require a stored key
184
+ passcontrol doctor --deep
185
+ passcontrol key status
186
+ passcontrol key migrate # move an existing file key to the OS store
187
+ passcontrol logout
233
188
  ```
234
189
 
235
- **Why not `HTTPS_PROXY`?** Because governing a `CONNECT` tunnel means terminating its TLS,
236
- which means installing a certificate authority on your machine that can impersonate any
237
- site to any program trusting it. PassControl exists to get a one-provider secret *off* your
238
- machine; installing a broader one to save an environment variable is the wrong trade. So
239
- the sidecar answers `HTTPS_PROXY` honestly instead of silently: a `CONNECT` to a provider
240
- is **refused** with the base URL to use, never quietly tunnelled into a call that looks
241
- governed and is not. It also refuses every other host — it is not an open proxy — and
242
- `--allow-connect <host>` names exceptions, which can never be a provider.
243
-
244
- The agent never holds a real key or a long-lived token. Presets ship for coding agents
245
- (**openhands, aider, cline, continue, litellm**), for the desktop chat apps you would otherwise
246
- paste a raw provider key into (**chatbox, jan, msty, cherry-studio, open-webui, librechat**), and
247
- a catch-all **generic** (`passcontrol env <preset>`). `passcontrol env` with an unknown name
248
- prints the current list, which is generated — it cannot drift from what the CLI accepts. Also,
249
- **[Hermes Agent](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md)** works through the generic settings with no custom
250
- code. A single long streaming completion also works
251
- directly — it's verified once at the start, so it finishes even if it runs past the visa TTL; only
252
- *multi-call* sessions need the sidecar's refresh. Raise `VISA_TTL_SECONDS` (300–900) to widen the
253
- window, but the sidecar is the real answer for long sessions.
254
-
255
- > If a client defaults to OpenAI `/responses` (some Continue configs for o-series/gpt-5), force
256
- > `/chat/completions` — PassControl intentionally proxies only chat/messages and model-listing
257
- > endpoints.
258
-
259
- ## Signed call receipts
260
-
261
- Your audit log convinces **you**. It convinces nobody else — you control that database.
262
-
263
- A **receipt** is one call's record, signed with your deployment's Ed25519 key. Anyone can
264
- check it with no account, no access to your database, and no cooperation from you. Approvals
265
- and refusals are both signed; *"the gateway stopped this agent from touching that model,
266
- here's the proof"* is often the more useful document.
190
+ The CLI supports macOS Keychain, Linux Secret Service (`secret-tool`), and Windows
191
+ DPAPI-backed storage. File configuration may contain a storage marker instead of the
192
+ Passport secret; explicit environment secrets take precedence. An unavailable OS store
193
+ can use an existing file fallback with a warning. Custody shown by the gateway is
194
+ **DECLARED evidence**, not proof of storage. The signer still reads key material into
195
+ process memory; this is not a non-exportable hardware key.
267
196
 
268
- ```bash
269
- passcontrol keygen instance # generates INSTANCE_SIGNING_KEY; set PASSCONTROL_ISSUER too
270
- ```
197
+ ## Connect a real agent
271
198
 
272
- Then anyone you hand a receipt to runs:
199
+ For example, the direct OpenAI configuration has this shape:
273
200
 
274
201
  ```bash
275
- passcontrol verify receipt "<receipt>" --issuer https://passcontrol.example.com
276
- ```
277
-
278
- ```
279
- ✓ Receipt is valid.
280
- → Issuer: http://localhost:3000
281
- → Passport: kZCFp7d2x4VDruiulJ21gogYbczBDAGZa-OuwR3qgh8
282
- → Call: POST chat/completions → demo/demo-1
283
- → Verdict: ok (HTTP 200)
284
- → Usage: 15 in / 46 out · 61 µ¢
285
- → Request: sha-256 VizsbKJwhtYoTNBv_XkJSf4ihWpdQWQfpXVvuDA6usM (105 bytes)
202
+ export OPENAI_BASE_URL=https://YOUR-PASSCONTROL-HOST/api/v1/openai/v1
203
+ export OPENAI_API_KEY=pc_agent_REVEAL_ONCE_VALUE
204
+ export OPENAI_MODEL=gpt-4o-mini
286
205
  ```
287
206
 
288
- Change one character and it fails. No terminal? Your deployment serves a paste-and-check page
289
- at **`/verify/receipt`** (including on the hosted demo) — verification runs in the visitor's browser, the receipt is never
290
- uploaded, and the shareable link carries it in the URL fragment, which browsers never send to
291
- a server.
292
-
293
- **What it does and doesn't prove.** A valid signature means the named issuer signed this
294
- record and nothing in it has changed. It does *not* vouch for the issuer — anyone can run
295
- PassControl, so trusting it is the reader's call. It covers the **request and the gateway's
296
- decision**, never the provider's reply. And the absence of a receipt proves nothing: receipt
297
- writing is best-effort, so this is evidence, not a complete ledger.
298
-
299
- > **Rotating the signing key is the one dangerous operation.** Receipts never expire, so
300
- > replacing the key retroactively invalidates every receipt you have ever signed. Move the old
301
- > seed to `INSTANCE_SIGNING_KEY_PREV` **first** — nothing is ever signed with it; it exists so
302
- > its public half stays published. This is inverted relative to `VISA_SECRET_PREV`.
303
-
304
- Full claim reference and the JWKS endpoint: [`DOCUMENTATION.md`](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md) ·
305
- walkthrough: [`TUTORIAL.md`](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md).
207
+ Use your dashboard's actual values; Anthropic uses its native base URL and key variables.
208
+ Never paste a Passport private key into an API-key field.
306
209
 
307
- ## CLI command center
210
+ Add a provider credential in the dashboard and give the agent a concrete model within
211
+ its scope and suitable budgets. Choose by what your client supports:
308
212
 
309
- The primary interface is `passcontrol <command>`. Highlights:
310
-
311
- | Need | Command |
213
+ | Client | Integration |
312
214
  |---|---|
313
- | Set this machine up through the browser | `passcontrol login` |
314
- | Revoke this machine's key and clear its credentials | `passcontrol logout` |
315
- | Config, gateway status, suggested next steps | `passcontrol status` |
316
- | Check local setup / mint a test visa | `passcontrol doctor --deep` |
317
- | Compare CLI, gateway and database versions | `passcontrol version` |
318
- | Make a governed model call | `passcontrol call "Summarize this"` |
319
- | Run the local MCP server | `passcontrol mcp` |
320
- | Run the auto-refreshing bridge for an agent | `passcontrol sidecar` |
321
- | Print agent/MCP settings without writing | `passcontrol env openhands` · `passcontrol env claude-desktop` |
322
- | List / create agents | `passcontrol agent list` · `passcontrol agent create billing-bot` |
323
- | Suspend, resume, or revoke an agent | `passcontrol agent suspend <id>` |
324
- | Inspect spend, logs, and audit history | `passcontrol spend` · `passcontrol logs` · `passcontrol audit` |
325
- | Save / restore a workspace configuration snapshot | `passcontrol export --out workspace.json` · `passcontrol import workspace.json` (previews first; never overwrites an existing agent) |
326
- | Generate this deployment's receipt signing key | `passcontrol keygen instance` |
327
- | Check a receipt or agent token (no account needed) | `passcontrol verify receipt <jws> --issuer <origin>` |
328
- | Arm / release the tenant kill switch | `passcontrol kill on` · `passcontrol kill off` |
329
- | Prepare or repair local services | `passcontrol setup` · `passcontrol doctor --fix` |
330
- | Start / stop the whole local stack | `passcontrol start` · `passcontrol stop` · `passcontrol restart` (add `--dashboard-only` to leave Supabase and Redis alone) |
331
- | Follow local dashboard logs | `passcontrol local-logs --follow` |
332
- | Point the CLI at a different checkout | `passcontrol setup --app-dir <path>` |
333
- | Forget the remembered checkout | `passcontrol unlink` |
334
- | Open the Control Tower | `passcontrol open` |
335
- | Set up an integration (preview, or `--write`) | `passcontrol configure aider` · `passcontrol configure claude-desktop --write` |
336
-
337
- `passcontrol stop` brings down the **whole** local stack — dashboard, Supabase, and Redis.
338
- Use `--dashboard-only` to leave the services running. It never removes volumes, so your
339
- Vault, passports, and audit log survive; wiping data stays with `reset` below.
340
-
341
- Config resolves in order: **environment variables → project-local `.passcontrol` →
342
- `~/.config/passcontrol/config`**. `.passcontrol` holds a passport secret, is gitignored, and is
343
- written owner-only — never commit or share it.
344
-
345
- The local stack itself lives in a checkout of this repo, not in the installed npm package.
346
- The CLI resolves it in order: **`--app-dir <path>` → `PASSCONTROL_APP_ROOT` → the
347
- surrounding checkout → the one it remembers** in `~/.config/passcontrol/app.json`.
348
- `passcontrol status` shows which of those the current path came from. That remembered path
349
- outlives `npm uninstall -g`, so if a fresh install keeps pointing at an old directory, clear
350
- it with `passcontrol unlink` (or repoint with `--app-dir`).
351
-
352
- `passcontrol reset --local --confirm RESET` destroys and recreates local data — use it only for a
353
- clean slate.
354
-
355
- ## Using it from your own code
356
-
357
- The client SDK exported at `passcontrol/sdk` hides the visa dance — point your provider SDK at the
358
- gateway and visas auto-refresh:
359
-
360
- ```ts
361
- import OpenAI from "openai";
362
- import { PassControl } from "passcontrol/sdk";
363
-
364
- const pc = new PassControl({ gateway, passportId, passportSecret });
365
- const openai = new OpenAI(pc.clientOptions("openai")); // baseURL + auth wired; visas auto-refresh
366
- ```
367
-
368
- Manage the fleet programmatically with the control-plane SDK + an API key:
369
-
370
- ```ts
371
- import { ControlClient } from "passcontrol/sdk";
372
- const cp = new ControlClient({ gateway, apiKey: process.env.PASSCONTROL_API_KEY! });
373
- await cp.agents.list();
374
- await cp.killSwitch.set(true);
375
- ```
376
-
377
- Both credential-bearing clients enforce the same `gateway` boundary — a bare HTTPS origin, plain
378
- HTTP only on loopback — and refuse anything else at construction, before any request.
379
-
380
- The compiled ESM SDK ships with the current CLI release. Keep Passport secrets **and `pc_` control keys**
381
- in trusted server runtimes, never browser-exposed variables. See the
382
- [Cloud Passport SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md).
383
- Full API reference: [`openapi.yaml`](https://github.com/Vertias3u/PassControl/blob/main/openapi.yaml) and [`DOCUMENTATION.md`](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md). Runnable example
384
- agents live in [`examples/`](https://github.com/Vertias3u/PassControl/tree/main/examples).
385
-
386
- ## Self-host
387
-
388
- Stack: **Next.js** (App Router, edge routes) · **Supabase** (Postgres + Vault + Auth) · **Upstash /
389
- any Redis**. Deploy on Vercel, Cloudflare Workers through the tested OpenNext path, or any Node host
390
- (`next start`). No Vercel-proprietary services are required — the kill switch is Redis-backed. See
391
- [`docs/deployment/cloudflare.md`](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md) for the Cloud build, production
392
- Auth/SMTP checklist, five-minute Cron Trigger, local `workerd` preview, and owner-only deploy handoff.
393
-
394
- ### Local (Docker) — the fastest path
395
-
396
- ```bash
397
- npm install -g passcontrol
398
- passcontrol setup # prereq checks → fetches the stack → boots it → opens the dashboard
399
- ```
400
-
401
- `passcontrol setup` detects the global install and offers to clone the self-hostable stack (Supabase + Redis +
402
- dashboard) into `~/passcontrol`, install its dependencies, and start it — one command from nothing
403
- to a running Control Tower. It first checks your prerequisites (Docker running, Supabase CLI, Node
404
- version, free ports) and tells you exactly what to fix if something's missing.
405
-
406
- - Change the checkout location: `--app-dir <path>` or `PASSCONTROL_APP_ROOT=<path>`
407
- - Non-interactive: `--yes`
408
- - Skip opening the browser: `--no-open`
409
- - Ports already taken by another local Supabase? `passcontrol setup --port-offset 100`
410
- (offsets Supabase + Redis together, e.g. API `54421`, DB `54422`; the dashboard stays on `:3000`)
411
-
412
- During `dev:stack` the seed step (`scripts/seed.mjs`) asks you to **choose an account email
413
- and password**. Then log in to the Control Tower at **http://localhost:3000** with those.
414
-
415
- > ⚠️ **No shared default credentials ship**, on any install. The account you create guards the
416
- > real provider keys in your local Vault — and the stack stops being localhost-only the moment
417
- > you reach it from another device (Tailscale, LAN), so choose a real password. Non-interactive
418
- > runs (CI, piped output) get a generated password printed once. Deployed installs create
419
- > accounts through normal signup, gated by `INVITE_CODE`.
420
-
421
- Add a **non-critical** provider key in the Control Tower, issue a passport, and copy the one-time
422
- `PASSPORT_ID` / `PASSPORT_SECRET`. Then, in your project directory:
423
-
424
- ```bash
425
- passcontrol init # gateway + passport + provider/model → writes .passcontrol
426
- passcontrol doctor --deep # verifies config, prerequisites, and mints a test visa
427
- passcontrol version # CLI vs gateway vs database schema, in one table
428
- passcontrol call "Say hello in 3 words"
429
- passcontrol spend # confirms governed spend
430
- ```
431
-
432
- You'll see a streamed response and an `ok` row in the dashboard Audit Log — the complete governed
433
- loop: **passport → visa → vault key injection → proxied call → audit**. That last call uses your
434
- real key from the local Vault, so start with a throwaway one.
435
-
436
- > Working from a **source clone** instead of the global install? Everything below works as
437
- > `npm run cli -- <command>`; after `npm link` in the clone, the short `passcontrol <command>` form
438
- > works too.
439
-
440
- `passcontrol setup` (above) is the one-command route. Under the hood it runs the bundled Docker
441
- stack: local Supabase (Postgres + Vault + Auth), Redis-over-REST, migrations applied inside the DB
442
- container, and a seeded dev user. Prereqs: **Docker Desktop, the Supabase CLI, Node 18+** — no host
443
- `psql` required.
444
-
445
- From a source checkout you can drive the same thing directly:
215
+ | Static base URL + API key | Dashboard **Connect an agent**: copy its provider-native URL and DAK |
216
+ | Your JS/TS code | `PassControl` from `passcontrol/sdk`; [SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) |
217
+ | Static-key client needing Passport | `passcontrol sidecar`, then `passcontrol env <integration>` |
218
+ | MCP client | `passcontrol mcp`; configure as below |
446
219
 
447
220
  ```bash
448
- git clone https://github.com/Vertias3u/PassControl && cd PassControl
449
- npm install
450
- npm run cli -- setup # or: passcontrol setup after `npm link`
451
- ```
452
-
453
- ### Manual self-host
454
-
455
- > **Supabase specifically** (not vanilla Postgres): the credential vault uses the `supabase_vault`
456
- > extension, so you need a Supabase project — hosted or the self-hosted Supabase stack — not a
457
- > plain Postgres database.
221
+ # Passport bridge: talks to Cloud or your self-hosted gateway
222
+ passcontrol sidecar
223
+ passcontrol env hermes
458
224
 
459
- ```bash
460
- git clone https://github.com/Vertias3u/PassControl && cd PassControl
461
- npm install
462
- cp .env.example .env.local # fill in Supabase / Redis / secrets
463
- DATABASE_URL='postgresql://…' npm run migrate # applies db/migrations/*.sql in order, once each
464
- npm run dev # or build + `next start` on any Node host
225
+ # MCP: global Passport configuration, no secret in generated client config
226
+ passcontrol configure claude-desktop --write
227
+ # Also: cursor; claude-code prints its client-managed add command
465
228
  ```
466
229
 
467
- See [`.env.example`](https://github.com/Vertias3u/PassControl/blob/main/.env.example) for the full config (Supabase URL/keys, `VISA_SECRET`,
468
- `CACHE_ENC_KEY`, Redis, `CRON_SECRET`, `PASSCONTROL_SIGNUP_MODE`, `INVITE_CODE`). Apply migrations `0001 → …` in order;
469
- [`db/tests/rls_invariants.sql`](https://github.com/Vertias3u/PassControl/blob/main/db/tests/rls_invariants.sql) checks tenant isolation and the
470
- privileged-column locks on your database.
471
-
472
- **Background reconcile job (required on non-Vercel hosts):** a periodic `GET /api/cron/reconcile`
473
- (header `Authorization: Bearer $CRON_SECRET`) corrects budget drift and flushes last-seen. On
474
- Vercel it's wired via `vercel.json`; elsewhere schedule it yourself (system `cron`, a GitHub
475
- Action…) every few minutes. It's a correction layer, not the hot path — an occasional missed run is
476
- harmless.
477
-
478
- ## Providers & endpoints
479
-
480
- Supported providers: **OpenAI, Anthropic, Groq, Mistral, Together, DeepSeek**. The gateway proxies
481
- **only chat and model-listing endpoints** — OpenAI-shaped chat completions + models, Anthropic
482
- messages + models, DeepSeek chat completions. It does **not** proxy embeddings, files, fine-tuning,
483
- batches, `/responses`, or token-counting endpoints (that's the point — a leaked visa can't reach
484
- your full provider surface).
485
-
486
- ## Limitations
230
+ The sidecar listens on loopback by default and substitutes a visa for the client's dummy
231
+ API key. Treat access to that local listener as access to the configured agent. It is
232
+ not a sandbox against other processes running as you. Its provider CONNECT requests are
233
+ refused; use base URLs rather than TLS interception.
487
234
 
488
- - A work-visa is a **bearer token**, reusable until it expires (≤5 min). Keep it out of logs and
489
- prompts; use suspend/kill to block future requests immediately.
490
- - **Pricing** is a best-effort in-code table and can lag provider price changes. Use it for budgets
491
- and monitoring, not billing reconciliation against provider invoices.
492
- - **Instant revocation** assumes Redis is configured for persistence / no-eviction. If Redis evicts
493
- suspend/kill keys, enforcement falls back to short visa TTLs and the durable agent-status check at
494
- the next mint.
235
+ Presets: `openhands`, `aider`, `cline`, `continue`, `litellm`, `hermes`, `chatbox`, `jan`,
236
+ `msty`, `cherry-studio`, `open-webui`, `librechat`, `generic`; MCP presets:
237
+ `claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
238
+ supported paths. [Hermes configuration](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
495
239
 
496
- ## What the CLI sends, and where
497
-
498
- No telemetry, no analytics, no usage reporting — none of this tool's operation is
499
- reported anywhere. There is exactly **one** outbound request PassControl makes that
500
- you did not ask for, and it is worth naming precisely rather than leaving you to
501
- find it in a packet capture:
502
-
503
- Once every 24 hours, `passcontrol` asks `registry.npmjs.org` for the latest published
504
- version number so it can tell you when your install is old. It sends nothing but the
505
- HTTP request itself — no identifiers, no configuration, no workspace or agent data.
506
- It is skipped entirely when stdout is not a terminal (so it never fires inside an
507
- agent run, a CI job, or a piped command), skipped under `--json`, and skipped when
508
- `CI` is set.
240
+ ## Self-host
509
241
 
510
- To turn it off completely:
242
+ The npm package contains the CLI and compiled SDK, not the application/database stack.
243
+ `passcontrol setup` obtains the public source and starts a local development stack.
244
+ It needs Git, Docker, the Supabase CLI, and Node/npm. The CLI package declares Node ≥18, but use **Node 22+ for the full stack**:
245
+ locked Supabase dependencies need ≥20 and Wrangler needs ≥22.
511
246
 
512
247
  ```bash
513
- export PASSCONTROL_NO_UPDATE_CHECK=1 # or the conventional NO_UPDATE_NOTIFIER=1
248
+ passcontrol setup --no-open
249
+ # Or from a source checkout:
250
+ git clone https://github.com/Vertias3u/PassControl.git
251
+ cd PassControl
252
+ npm ci
253
+ npm run dev:stack
254
+ npm run dev:docker
514
255
  ```
515
256
 
516
- It never downloads or installs anything. Upgrading stays a command you type.
517
-
518
- ## Security
519
-
520
- Security is the whole point, so please report issues privately rather than opening a public
521
- issue — use GitHub's
522
- **[private vulnerability reporting](https://github.com/Vertias3u/PassControl/security/advisories/new)**
523
- (Security tab → "Report a vulnerability"). You'll get an acknowledgement and a fix +
524
- disclosure timeline worked out with you.
525
-
526
- - It's **BYOK** — your provider key lives encrypted in your own Supabase Vault, decrypted only
527
- in-flight and cached briefly (encrypted) in your own Redis. It is never logged or returned.
528
- - Tenant isolation is enforced by Postgres **RLS on every table**; the sole decrypt path is a
529
- `SECURITY DEFINER`, service-role-only function.
530
- - It is **not yet independently audited.** If you find a hole, you're doing us a favor.
531
-
532
- ## License
533
-
534
- Source-available under the **Business Source License (BSL 1.1)** — read it, run it, modify it,
535
- self-host it. The one restriction: you may not offer it as a competing hosted/managed service.
536
- Converts to Apache 2.0 after the change date. See [`LICENSE`](./LICENSE).
537
-
538
- ## Contributing
539
-
540
- Issues and PRs welcome. Run `npm run typecheck && npm test && npm run build` before a PR (CI
541
- enforces it). Be kind — this is early.
257
+ Local setup starts Supabase (Postgres + Auth + Vault) and Redis with a REST adapter,
258
+ applies migrations, and seeds a local account. It writes `.env.docker`; use
259
+ `npm run dev:docker` to load it. This is development setup, not a production deployment.
260
+ There are no shared default credentials. `passcontrol setup --app-dir <path>` selects a
261
+ checkout; `passcontrol unlink` forgets a remembered one.
262
+
263
+ For production, configure [`.env.example`](https://github.com/Vertias3u/PassControl/blob/main/.env.example), use Supabase (plain Postgres
264
+ is insufficient), apply the public migrations with `DATABASE_URL=… npm run migrate`,
265
+ and build/run the app. Supported paths are Next.js on Vercel, `npm run build` then
266
+ `npm start` on a Node host behind a trusted reverse proxy, and the
267
+ [Cloudflare/OpenNext build](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md). Configure Auth/SMTP,
268
+ secrets, backups, Redis persistence/no-eviction, and periodic authenticated
269
+ `GET /api/cron/reconcile`. A local successful boot does not validate production operations.
270
+
271
+ | Boundary | Cloud | Public self-host tree |
272
+ |---|---|---|
273
+ | Gateway, dashboard, auth, budgets, receipts, SDK | Managed deployment | Included; you operate them |
274
+ | Provider credentials and request processing | Managed infrastructure | Your infrastructure and chosen upstreams |
275
+ | Passport private key | Client-side | Client-side |
276
+ | Signed spend statement issuance/proof service | Hosted capability | Verification and format only |
277
+ | Invite workflow, hosted quotas and hosted-site operations | Cloud-specific | Not the hosted service |
278
+
279
+ Workspace portability: `passcontrol export --out workspace.json` saves configuration;
280
+ `passcontrol import workspace.json` previews it before an explicit import. The CLI path
281
+ does not migrate provider secrets or manufacture verified owner identity. Treat exports
282
+ as sensitive configuration and inspect the result for partial/refused items.
283
+
284
+ [Release updates](https://passcontrol.vertias.eu/updates) and the
285
+ [learning center](https://passcontrol.vertias.eu/learn) are hosted-site resources.
286
+
287
+ ## Limits and security status
288
+
289
+ PassControl governs requests routed through it. It cannot prevent an agent from using
290
+ another credential or network path, secure a compromised signer, guarantee a provider's
291
+ usage report, or make an issuer's assertions independently true. Short visas, stop controls,
292
+ pricing tables, and best-effort logs each have the limits described above.
293
+
294
+ Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/Vertias3u/PassControl/security/advisories/new).
295
+ See [SECURITY.md](https://github.com/Vertias3u/PassControl/blob/main/SECURITY.md), [API documentation](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md), and
296
+ [contributing](https://github.com/Vertias3u/PassControl/blob/main/CONTRIBUTING.md). No independent audit or production assurance is implied
297
+ by the test suite. Read [LICENSE](./LICENSE) for the actual usage terms.
@@ -77,6 +77,7 @@ import {
77
77
  checkIssuerPublishesKey,
78
78
  generateInstanceKey,
79
79
  instanceKidFromSeed,
80
+ retiredKeyEntry,
80
81
  } from "../cli/instance-key.mjs";
81
82
  import { FAILURE_REASONS, verifyAgentToken, verifyReceipt, verifyStatement } from "../cli/verify.mjs";
82
83
  import { compareProtocolSets } from "../cli/protocols.mjs";
@@ -216,6 +217,9 @@ ${heading("Trust")}
216
217
  ${cmd} key status show the local passport key storage tier
217
218
  ${cmd} key migrate move a tier 0 file key into the OS credential store
218
219
  ${cmd} keygen instance create the receipt-signing key
220
+ ${cmd} keygen instance --retire <seed>
221
+ print the public entry that keeps a rotated-out
222
+ key's receipts verifiable
219
223
  ${cmd} verify receipt <jws> --issuer <origin>
220
224
  verify a signed call receipt
221
225
  ${cmd} verify token <jwt> --audience <aud> --issuer <origin>
@@ -1039,7 +1043,18 @@ async function startDashboard(opts = {}) {
1039
1043
  const logPath = dashboardLogPath();
1040
1044
  fs.mkdirSync(path.dirname(statePath), { recursive: true, mode: 0o700 });
1041
1045
  const logFd = fs.openSync(logPath, "a", 0o600);
1042
- const child = spawn(process.platform === "win32" ? "npm.cmd" : "npm", ["run", "dev:docker"], {
1046
+ // `node scripts/dev-docker.mjs` rather than `npm run dev:docker`: identical
1047
+ // work (that is all the npm script is now), minus two wrapper processes. The
1048
+ // pid recorded below is then the dev server itself, which matters because
1049
+ // stopDashboard signals a single pid on Windows rather than a process group —
1050
+ // through npm.cmd it would kill the wrapper and leave the server holding the
1051
+ // port. It also keeps the one path that runs daily clear of the Windows
1052
+ // batch-file spawn restriction that batchFileShell exists to work around.
1053
+ const devServer = path.join(appRoot, "scripts", "dev-docker.mjs");
1054
+ if (!fs.existsSync(devServer)) {
1055
+ throw new Error(`${devServer} is missing — this checkout is incomplete or predates the local-stack launcher. Re-clone, or run \`npm run dev:docker\` from ${appRoot} by hand.`);
1056
+ }
1057
+ const child = spawn(process.execPath, [devServer], {
1043
1058
  cwd: appRoot,
1044
1059
  detached: process.platform !== "win32",
1045
1060
  env: { ...process.env, PORT: String(dashboard.port) },
@@ -1185,9 +1200,22 @@ async function localLogsCommand(opts = {}) {
1185
1200
  });
1186
1201
  }
1187
1202
 
1203
+ // Windows will not spawn a `.cmd`/`.bat` without a shell. Since Node 18.20.2 /
1204
+ // 20.12.2 (the CVE-2024-27980 hardening) it refuses outright with EINVAL rather
1205
+ // than executing it, which is how `passcontrol setup` died on the very first
1206
+ // step with nothing but `✗ spawn EINVAL` to go on.
1207
+ //
1208
+ // Scoped to batch files ON PURPOSE, not applied to every spawn. `runCommand`
1209
+ // also carries `docker compose -f docker/compose.yml` and `supabase start`;
1210
+ // routing those through cmd.exe would re-introduce shell quoting to arguments
1211
+ // that today are passed as an array and are safe in a path containing spaces.
1212
+ function batchFileShell(command) {
1213
+ return process.platform === "win32" && /\.(cmd|bat)$/i.test(command) ? { shell: true } : {};
1214
+ }
1215
+
1188
1216
  async function runCommand(command, args, { cwd = appRoot, env = process.env } = {}) {
1189
1217
  await new Promise((resolve, reject) => {
1190
- const child = spawn(command, args, { cwd, env, stdio: "inherit" });
1218
+ const child = spawn(command, args, { cwd, env, stdio: "inherit", ...batchFileShell(command) });
1191
1219
  child.once("error", reject);
1192
1220
  child.once("exit", (code) => code === 0 ? resolve() : reject(new Error(`${command} exited with code ${code}.`)));
1193
1221
  });
@@ -2355,12 +2383,35 @@ async function statementsCommand(opts) {
2355
2383
  );
2356
2384
  }
2357
2385
 
2358
- async function keygenCommand(rest) {
2386
+ async function keygenCommand(rest, opts = {}) {
2359
2387
  const target = rest[0];
2360
2388
  if (target !== "instance") {
2361
2389
  throw new Error(`Usage: ${cliCommand("keygen instance")}`);
2362
2390
  }
2363
2391
 
2392
+ // `--retire <seed>` prints the public pair for a key being taken out of
2393
+ // service. Nothing about it is secret, and that is the point: the operator
2394
+ // has no other way to derive a public half, and the alternative they reach
2395
+ // for — pasting the seed — is 32 base64url bytes too.
2396
+ // From `opts`, not `rest`: parseArgv consumes every `--flag` and its value
2397
+ // before the command ever sees the array, so scanning `rest` for "--retire"
2398
+ // finds nothing and silently generates a NEW key instead — which, run against
2399
+ // a live deployment's seed, looks like it worked.
2400
+ if (opts.retire !== undefined) {
2401
+ const seed = typeof opts.retire === "string" ? opts.retire : "";
2402
+ if (!seed) throw new Error(`Usage: ${cliCommand("keygen instance --retire <seed>")}`);
2403
+ const { entry, kid } = retiredKeyEntry(seed);
2404
+ ok(`Retired key ${kid}.`);
2405
+ step("Append this to INSTANCE_SIGNING_KEY_HISTORY (comma-separated) and leave it there");
2406
+ step("forever — receipts carry no expiry, so this is what keeps old ones checkable:");
2407
+ console.log(` ${entry}`);
2408
+ console.log("");
2409
+ step("It is a PUBLIC key. It cannot sign, which is why history takes this and not the");
2410
+ step("seed: a retired seed left in configuration can mint new receipts under the old kid.");
2411
+ step("Delete the seed once this is in place.");
2412
+ return;
2413
+ }
2414
+
2364
2415
  const { seed, kid } = generateInstanceKey();
2365
2416
  ok("Generated an Ed25519 instance signing key.");
2366
2417
  step("This key signs call receipts and agent-to-agent tokens. Store the seed like a password:");
@@ -2370,10 +2421,14 @@ async function keygenCommand(rest) {
2370
2421
  step("Also set PASSCONTROL_ISSUER to this deployment's https origin — it becomes the");
2371
2422
  step("`iss` claim, and the origin other deployments use to find this one's JWKS.");
2372
2423
  step("");
2373
- step("Rotating? Move the current value to INSTANCE_SIGNING_KEY_PREV and keep it there.");
2374
- step("Unlike VISA_SECRET_PREV we never sign with it — its public key stays published so");
2375
- step("receipts signed before the rotation still verify. Publish the new key, wait one");
2376
- step("JWKS max-age window, then start signing with it.");
2424
+ step("Rotating? Two steps, and the FIRST is the one that lasts:");
2425
+ step(` 1. ${cliCommand("keygen instance --retire <the old seed>")} — append the pair it prints`);
2426
+ step(" to INSTANCE_SIGNING_KEY_HISTORY. That list is permanent and public-only.");
2427
+ step(" 2. Move the old seed to INSTANCE_SIGNING_KEY_PREV for the changeover, then delete it.");
2428
+ step("Unlike VISA_SECRET_PREV we never sign with either — their public keys stay published");
2429
+ step("so receipts signed before the rotation still verify. _PREV holds ONE generation, so");
2430
+ step("history is what keeps the receipts from the rotation before this one checkable.");
2431
+ step("Publish the new key, wait one JWKS max-age window, then start signing with it.");
2377
2432
  }
2378
2433
 
2379
2434
  function passportFileForMigration() {
@@ -2546,11 +2601,32 @@ async function importCommand(rest = [], opts = {}) {
2546
2601
  );
2547
2602
  }
2548
2603
 
2604
+ // The envelope, before anything is planned or sent.
2605
+ //
2606
+ // This used to be `snapshot.workspace?.agents ?? []`, which turns a truncated
2607
+ // file into an empty fleet: the API plans nothing, `every()` over an empty
2608
+ // plan is true, the report says `complete: true`, and the CLI prints "Nothing
2609
+ // to create." and exits 0. A damaged snapshot restored no fleet at all and
2610
+ // every surface reported success (T4-03). A MISSING agents collection is
2611
+ // corruption; an EMPTY one is a workspace that genuinely has no agents and
2612
+ // still imports fine.
2613
+ //
2614
+ // The server validates this independently — it has to, since anyone can curl
2615
+ // it — but the operator holding the damaged file is here, so this is where the
2616
+ // message can name the file and say what is wrong with it.
2617
+ if (!Array.isArray(snapshot.workspace?.agents)) {
2618
+ throw new Error(
2619
+ `${file} has no "workspace.agents" array. That is a truncated or damaged export, ` +
2620
+ `not an empty workspace — importing it would restore nothing and report success. ` +
2621
+ `Re-export from the source deployment.`
2622
+ );
2623
+ }
2624
+
2549
2625
  // Only what the import writes goes on the wire. Provider mappings, break-glass
2550
2626
  // grants, the exclusions prose and the display settings stay on disk — they
2551
2627
  // are not importable, so sending them would spend the size budget on bytes the
2552
2628
  // server ignores.
2553
- const agents = snapshot.workspace?.agents ?? [];
2629
+ const agents = snapshot.workspace.agents;
2554
2630
  const payload = { agents, ownership: snapshot.workspace?.ownership ?? null };
2555
2631
  const size = Buffer.byteLength(JSON.stringify(payload));
2556
2632
  if (size > IMPORT_BODY_LIMIT) {
@@ -3141,7 +3217,7 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
3141
3217
  await openDashboard(opts);
3142
3218
  break;
3143
3219
  case "keygen":
3144
- await keygenCommand(commandRest);
3220
+ await keygenCommand(commandRest, opts);
3145
3221
  break;
3146
3222
  case "key":
3147
3223
  await keyCommand(commandRest, opts);
@@ -27,6 +27,24 @@ export function generateInstanceKey() {
27
27
  return { seed, kid: instanceKidFromSeed(seed) };
28
28
  }
29
29
 
30
+ /**
31
+ * Turn a retiring SEED into the `<kid>:<x>` pair that goes in
32
+ * INSTANCE_SIGNING_KEY_HISTORY — public half only, so a retired key can never
33
+ * sign again.
34
+ *
35
+ * This exists because the operator cannot derive a public key by hand. Without
36
+ * it they would paste the seed, which is also 32 base64url bytes and would sail
37
+ * through any length check; the app rejects that pair because the kid does not
38
+ * recompute, but "rejected" only helps if there is a right value to type
39
+ * instead. Throws on anything that is not a 32-byte seed.
40
+ */
41
+ export function retiredKeyEntry(seed) {
42
+ const bytes = fromB64url(seed);
43
+ if (bytes.length !== 32) throw new Error("A signing seed is 32 bytes, base64url-encoded.");
44
+ const x = b64url(ed25519.getPublicKey(bytes));
45
+ return { entry: `${instanceKidFromSeed(seed)}:${x}`, kid: instanceKidFromSeed(seed) };
46
+ }
47
+
30
48
  /**
31
49
  * Verify that PASSCONTROL_ISSUER resolves to a deployment publishing OUR key.
32
50
  *
package/cli/mcp/README.md CHANGED
@@ -11,7 +11,7 @@ passcontrol init --global
11
11
  ```
12
12
 
13
13
  The client receives neither the provider key nor the short-lived work visa. The
14
- server mints the visa locally and sends every model call through the configured
14
+ server signs locally and obtains the visa from the gateway and sends every model call through the configured
15
15
  PassControl gateway.
16
16
 
17
17
  ## Claude Desktop
@@ -52,3 +52,11 @@ Desktop/Cursor entries use absolute Node and `bin/passcontrol.mjs` paths because
52
52
  may not inherit shell `PATH`. Existing `mcpServers` entries are preserved, an existing file is
53
53
  backed up to `.bak`, and a different PassControl entry requires `--force`. No generated client
54
54
  config contains a passport secret or provider key.
55
+
56
+
57
+ In 0.9.0 `chat` sends a bearer visa, without a sender proof. Required sender-proof mode
58
+ therefore refuses it; use off/observe for this client. `list_models` reads model patterns
59
+ from the visa scope, not a live upstream model catalog; a wildcard is not a callable model.
60
+ Providers: OpenAI, Anthropic, Groq, Mistral, Together, DeepSeek, and Gemini (OpenAI-compatible).
61
+ The global profile can use the CLI OS credential store (`passcontrol key status`) rather
62
+ than containing the Passport secret. Custody declarations do not prove storage.
package/cli/menu.mjs CHANGED
@@ -97,6 +97,56 @@ export const GROUPS = [
97
97
  command({ id: "unlink", label: "Forget the remembered checkout", run: ["unlink"], detail: "unlink", description: "Remove the saved local app-checkout pointer.", effect: "local_write", current: currentFrom("app") }),
98
98
  ],
99
99
  },
100
+ {
101
+ section: "CONTROL",
102
+ title: "Connect an agent",
103
+ hint: "servers that carry agent traffic",
104
+ // Neither row here runs from the menu. Both carry `needsArgs`, so selecting
105
+ // one prints its command line and returns — the menu must never hand the
106
+ // terminal to a process that holds it until killed, and that invariant is
107
+ // what `menu.test.mjs` enforces, not their absence.
108
+ //
109
+ // Both were hidden outright before 0.9.1. The invariant was right; the cost
110
+ // was discoverability. The sidecar is the only 0.9 path that attaches sender
111
+ // proofs, so under `required` mode the one mandatory command was the one
112
+ // missing from the front door — which is how an owner hit it in a manual
113
+ // Cloud E2E. Listing them needed a line that did not exist: every group
114
+ // already rendered at the 23-line ceiling and the top level sat at 23 with
115
+ // eight groups, so this group is paid for by the "Choose a group" heading.
116
+ items: [
117
+ // Listed, but deliberately NOT runnable from a bare selection. The sidecar
118
+ // is a foreground server that owns the terminal until it is killed, so the
119
+ // menu prints its command line and returns instead of exec'ing it — the
120
+ // `needsArgs` branch in `bin/passcontrol.mjs`. It was hidden outright until
121
+ // 0.9.1, which kept the invariant but cost discoverability: the sidecar is
122
+ // the only 0.9.0 path that attaches sender proofs, so under `required` mode
123
+ // the one mandatory command was the one missing from the front door. Found
124
+ // in a manual Cloud E2E, by someone who went looking for it here.
125
+ //
126
+ // The description is terse because `render` neither wraps nor truncates:
127
+ // a line over 80 columns wraps in the terminal and adds rows the height
128
+ // sweep cannot count, which is the torn frame that sweep exists to stop.
129
+ // The base-URL shape is the one lesson worth the width — pointing a client
130
+ // at the bare host fails with what looks like an empty provider response.
131
+ //
132
+ // Those keywords are bare words on purpose: this file ships in the npm
133
+ // artifact, and `scripts/build-cli-package.mjs` scans shipped sources for
134
+ // imports with a regex that does not know about comments. Prose that puts
135
+ // the import keyword immediately before a quoted word is read as a bare
136
+ // import of that word and fails the build with "imports packages the root
137
+ // manifest does not declare". The scanner erring that way is the safe
138
+ // direction, since the alternative is shipping an undeclared dependency;
139
+ // just never write that shape in a comment in a file the npm artifact
140
+ // carries.
141
+ command({ id: "sidecar", label: "Run the local sidecar proxy", run: ["sidecar"], detail: "sidecar", description: "Local proxy signing a sender proof per call; agents use /api/v1/<provider>.", effect: "long_running", network: "provider", keywords: ["proxy", "visa", "proof", "passport"], needsArgs: true, returnToMenu: true }),
142
+ // The other long-lived server, on identical terms. Its own gotcha earns
143
+ // the description's width: MCP `chat` sends a bearer visa and attaches no
144
+ // sender proof in 0.9, so a workspace in required mode refuses this client
145
+ // while the sidecar keeps working. Most people never run it by hand —
146
+ // `configure <client> --write` wires it into the client's own config.
147
+ command({ id: "mcp", label: "Serve MCP to desktop agent clients", run: ["mcp"], detail: "mcp", description: "Stdio server for MCP clients. Its chat sends no sender proof in 0.9.", effect: "long_running", network: "provider", keywords: ["stdio", "claude", "cursor", "desktop"], needsArgs: true, returnToMenu: true }),
148
+ ],
149
+ },
100
150
  {
101
151
  section: "CONTROL",
102
152
  title: "Fleet",
@@ -197,8 +247,6 @@ export const HIDDEN = {
197
247
  help: "the menu replaces it in this mode",
198
248
  settings: "this is the menu itself",
199
249
  menu: "an alias of settings",
200
- mcp: "a long-lived stdio server — it owns the terminal and would never return to the menu",
201
- sidecar: "a long-lived foreground server, same reason as mcp",
202
250
  fleet: "an alias of `agent`, already listed once under Fleet",
203
251
  agent: "reached through its subcommands under Fleet",
204
252
  key: "reached through its subcommands under Trust",
@@ -550,7 +598,11 @@ export function render(state, { colour = true, header = "", groups = GROUPS, con
550
598
  }
551
599
 
552
600
  if (state.group === null) {
553
- lines.push(bold(" Choose a group"));
601
+ // No "Choose a group" heading. It was one line telling the reader what the
602
+ // list under it plainly is, and this frame is measured to the row: dropping
603
+ // it is what made room for a ninth group, so the two long-lived servers
604
+ // could be listed at all. The footer already says what the keys do.
605
+ //
554
606
  // Section headings are drawn, never navigated. They are not entries in
555
607
  // `groups`, so `moveCursor` and `reduce` keep counting rows exactly as they
556
608
  // did — the arrow-key arithmetic is untouched by this grouping, which is
@@ -22,7 +22,11 @@ const MACOS_PASSWORD_PROMPT = /password data for new item/iu;
22
22
  * exists for the same reason — so that check costs under a second instead of the
23
23
  * full helper timeout.
24
24
  */
25
- export function runProcess(command, args, { input = "", env = {}, timeoutMs = COMMAND_TIMEOUT_MS } = {}) {
25
+ export function runProcess(
26
+ command,
27
+ args,
28
+ { input = "", env = {}, timeoutMs = COMMAND_TIMEOUT_MS, detached = false } = {}
29
+ ) {
26
30
  const result = spawnSync(command, args, {
27
31
  input,
28
32
  encoding: "utf8",
@@ -31,6 +35,11 @@ export function runProcess(command, args, { input = "", env = {}, timeoutMs = CO
31
35
  maxBuffer: 64 * 1024,
32
36
  env: { ...process.env, ...env },
33
37
  stdio: ["pipe", "pipe", "pipe"],
38
+ // `detached` puts the child in its own session (setsid), which leaves it with
39
+ // NO controlling terminal. Only one caller wants that and it is documented at
40
+ // that call site; it is off by default because on Windows the same flag opens
41
+ // a new console window, which no adapter here has any use for.
42
+ detached,
34
43
  });
35
44
  // Deliberately omit stderr and the native Error object. Helpers sometimes
36
45
  // repeat their input in diagnostics, and no caller may log that raw text.
@@ -159,10 +168,23 @@ export function createPassportCredentialStore({
159
168
  if (/[\r\n]/u.test(secret)) {
160
169
  return fixedFailure("macOS Keychain cannot store a key containing a newline");
161
170
  }
171
+ // `detached` is what makes the stdin above reachable, and without it none
172
+ // of the reasoning in the comment above holds. Given a controlling
173
+ // terminal, security(1) does not read the prompt from stdin at all — it
174
+ // opens /dev/tty and asks the human, so the pipe is ignored, the write
175
+ // stalls until the helper timeout, and the key never lands. Detaching the
176
+ // child into its own session removes the terminal it would have reached
177
+ // for, and it falls back to stdin, which is where the secret already is.
178
+ //
179
+ // The consequence of getting this wrong is not a flaky test: it is that
180
+ // the feature works in every context that has no tty — CI, an agent shell,
181
+ // a piped script — and fails in the ONLY context that has one, which is a
182
+ // person at a terminal. tests/passport-key-store-os.test.ts owns a pty for
183
+ // exactly this reason.
162
184
  const result = invoke(run,
163
185
  "security",
164
186
  ["add-generic-password", "-U", "-a", passportId, "-s", SERVICE, "-w"],
165
- { input: `${secret}\n${secret}\n` }
187
+ { input: `${secret}\n${secret}\n`, detached: true }
166
188
  );
167
189
  if (result.timedOut) {
168
190
  // The one place the prompt bit earns its keep: `security` stalling
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "0.9.0",
3
+ "version": "0.9.2",
4
4
  "description": "Identity, scope and budget controls for AI agents while provider keys stay server-side.",
5
5
  "license": "BUSL-1.1",
6
6
  "homepage": "https://passcontrol.vertias.eu",
package/sdk/README.md CHANGED
@@ -8,8 +8,8 @@ your existing OpenAI/Anthropic SDK, **not rewriting the agent**.
8
8
  Install it beside the provider SDK used by your agent:
9
9
 
10
10
  ```bash
11
- npm install passcontrol@^0.6.0 openai
12
- # or: npm install passcontrol@^0.6.0 @anthropic-ai/sdk
11
+ npm install passcontrol@0.9.1 openai
12
+ # or: npm install passcontrol@0.9.1 @anthropic-ai/sdk
13
13
  ```
14
14
 
15
15
  Dependencies: only [`@noble/curves`](https://github.com/paulmillr/noble-curves) and the
@@ -39,7 +39,7 @@ That rejects two self-host shapes worth knowing about up front:
39
39
  - **A gateway served under a sub-path** (`https://example.com/passcontrol`). Give it its own
40
40
  origin or subdomain.
41
41
 
42
- The rule exists because the visa is a bearer credential: the SDK pins it to exactly this origin
42
+ The rule limits the initial credential destination: the SDK pins it to exactly this origin
43
43
  and refuses to attach it anywhere else, so a gateway value that is loose about scheme or path
44
44
  would weaken the pin it is used to define.
45
45
 
@@ -145,9 +145,33 @@ The full reference lives in [the public OpenAPI document](https://github.com/Ver
145
145
  `refreshSkewSeconds` (default 30s) of expiry, then re-minted automatically.
146
146
  - **Single-flight.** Concurrent `getVisa()` calls share one challenge request.
147
147
  - **401 retry.** If a proxied call returns `401` (visa rejected/expired), the SDK
148
- invalidates the cache, re-mints once, and retries.
148
+ invalidates the cache, re-mints once, and retries if the effective request body is replayable. Single-use init streams are not retried.
149
149
  - **Origin pinning.** A visa is attached only to `/api/v1/*` on the configured gateway origin.
150
150
  Any other origin, scheme, port or path — including the challenge endpoint and the control
151
151
  plane — is refused before the request leaves the process.
152
152
  - **No secret on the wire.** The passport private key only signs the challenge locally;
153
153
  the gateway only ever sees the public key and the signature.
154
+
155
+
156
+ ## 0.9.0 compatibility and assurance
157
+
158
+ `clientOptions` accepts `openai`, `anthropic`, `groq`, `mistral`, `together`, `deepseek`,
159
+ and `gemini`. OpenAI POST Responses works through `pc.fetch`/the OpenAI SDK as well as
160
+ Chat Completions. Gemini uses Google's OpenAI-compatible endpoint; native
161
+ `generateContent` is not supported. See [accepted paths](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md#data-plane--proxy-a-model-call).
162
+
163
+ The TypeScript SDK **does not attach sender proofs in 0.9.0**. Its provider requests use
164
+ bearer visas: they work with sender-proof mode off/observe, but required mode refuses
165
+ them without an additional correct proof implementation. The current sidecar attaches
166
+ proofs. A valid mint signature is not a signature over each provider request.
167
+
168
+ The wrapper validates the initial gateway origin/path. It does not override fetch's
169
+ redirect policy, so it is not a complete redirect-chain credential boundary. Gateway
170
+ upstream forwarding separately refuses provider redirects. Keep custom transports and
171
+ the configured gateway trusted.
172
+
173
+ The SDK takes a raw secret supplied by your application; it does not automatically read
174
+ the CLI's OS credential store. The CLI's storage declarations are not storage attestation.
175
+ Signed receipts are issuer assertions and best-effort, not proof of complete logging or
176
+ provider billing. The SDK exports statement/inclusion verification; statement retrieval
177
+ methods target Cloud's service and do not add it to a self-hosted installation.