passcontrol 0.9.0 → 0.9.1
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/cli/mcp/README.md +9 -1
- package/cli/menu.mjs +55 -3
- 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
|
|
54
|
-
```
|
|
55
|
-
|
|
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
|
-
└────────────────────────────────────────────┘
|
|
3
|
+
PassControl **0.9.0** 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
|
|
91
30
|
```
|
|
92
31
|
|
|
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 0.9.0 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
|
-
|
|
144
|
-
```
|
|
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
|
-
|
|
149
|
-
Your agent is live. Anyone can check that call for themselves:
|
|
150
|
-
passcontrol verify receipt eyJhbGc… --issuer https://passcontrol.vertias.eu
|
|
129
|
+
passcontrol verify receipt "<jws>" --issuer https://your-gateway.example
|
|
151
130
|
```
|
|
152
131
|
|
|
153
|
-
|
|
154
|
-
|
|
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.
|
|
155
139
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
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).
|
|
159
146
|
|
|
160
|
-
|
|
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.
|
|
161
152
|
|
|
162
|
-
|
|
163
|
-
passcontrol sidecar # holds the passport, mints visas, forwards to Cloud
|
|
164
|
-
passcontrol env openhands # ready-to-paste settings for your agent
|
|
165
|
-
```
|
|
153
|
+

|
|
166
154
|
|
|
167
|
-
|
|
168
|
-
|
|
155
|
+
The recording illustrates a stop control on successive calls; it does not show cancellation
|
|
156
|
+
of an already-dispatched stream.
|
|
169
157
|
|
|
170
|
-
|
|
171
|
-
provider/model with no browser, and plain environment variables work everywhere the config file
|
|
172
|
-
does.
|
|
158
|
+
## Try Cloud
|
|
173
159
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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.
|
|
177
163
|
|
|
178
|
-
|
|
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@0.9.0
|
|
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.
|
|
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.
|
|
292
209
|
|
|
293
|
-
|
|
294
|
-
|
|
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.
|
|
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:
|
|
298
212
|
|
|
299
|
-
|
|
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).
|
|
306
|
-
|
|
307
|
-
## CLI command center
|
|
308
|
-
|
|
309
|
-
The primary interface is `passcontrol <command>`. Highlights:
|
|
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
|
|
221
|
+
# Passport bridge: talks to Cloud or your self-hosted gateway
|
|
222
|
+
passcontrol sidecar
|
|
223
|
+
passcontrol env hermes
|
|
454
224
|
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
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
|
-
|
|
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
|
|
487
|
-
|
|
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.
|
|
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.
|
|
495
234
|
|
|
496
|
-
|
|
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).
|
|
497
239
|
|
|
498
|
-
|
|
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/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
|
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.
|