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 +252 -496
- package/bin/passcontrol.mjs +85 -9
- package/cli/instance-key.mjs +18 -0
- package/cli/mcp/README.md +9 -1
- package/cli/menu.mjs +55 -3
- package/cli/passport-key-store.mjs +24 -2
- package/package.json +1 -1
- package/sdk/README.md +28 -4
package/README.md
CHANGED
|
@@ -1,541 +1,297 @@
|
|
|
1
1
|
# PassControl
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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
|
-

|
|
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
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
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
|
-
|
|
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
|
-
|
|
150
|
-
|
|
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
|
-
|
|
154
|
-
|
|
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
|
-
|
|
157
|
-
|
|
158
|
-
|
|
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
|
-
|
|
153
|
+

|
|
161
154
|
|
|
162
|
-
|
|
163
|
-
|
|
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
|
-
|
|
168
|
-
credentials, leaving your provider and model settings alone.
|
|
158
|
+
## Try Cloud
|
|
169
159
|
|
|
170
|
-
|
|
171
|
-
|
|
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
|
-
|
|
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
|
-
|
|
189
|
-
passcontrol
|
|
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
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
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
|
-
|
|
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
|
-
|
|
232
|
-
|
|
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
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
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
|
-
|
|
269
|
-
passcontrol keygen instance # generates INSTANCE_SIGNING_KEY; set PASSCONTROL_ISSUER too
|
|
270
|
-
```
|
|
197
|
+
## Connect a real agent
|
|
271
198
|
|
|
272
|
-
|
|
199
|
+
For example, the direct OpenAI configuration has this shape:
|
|
273
200
|
|
|
274
201
|
```bash
|
|
275
|
-
|
|
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
|
-
|
|
289
|
-
|
|
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
|
-
|
|
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
|
-
|
|
310
|
-
|
|
311
|
-
| Need | Command |
|
|
213
|
+
| Client | Integration |
|
|
312
214
|
|---|---|
|
|
313
|
-
|
|
|
314
|
-
|
|
|
315
|
-
|
|
|
316
|
-
|
|
|
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
|
-
|
|
449
|
-
|
|
450
|
-
|
|
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
|
-
|
|
460
|
-
|
|
461
|
-
|
|
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
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
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
|
-
|
|
489
|
-
|
|
490
|
-
-
|
|
491
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
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.
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -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
|
-
|
|
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?
|
|
2374
|
-
step("
|
|
2375
|
-
step("
|
|
2376
|
-
step("
|
|
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
|
|
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);
|
package/cli/instance-key.mjs
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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(
|
|
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
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
|
|
12
|
-
# or: npm install passcontrol
|
|
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
|
|
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.
|