passcontrol 0.9.4 → 1.0.0
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 +242 -135
- package/bin/passcontrol.mjs +348 -35
- package/cli/config.mjs +129 -4
- package/cli/integration-defaults.mjs +5 -5
- package/cli/mcp/README.md +2 -0
- package/cli/menu.mjs +1 -0
- package/cli/update-check.mjs +7 -3
- package/cli/update.mjs +214 -0
- package/package.json +1 -1
- package/sdk/README.md +8 -6
- package/sdk/control.d.ts +3 -0
package/README.md
CHANGED
|
@@ -1,20 +1,216 @@
|
|
|
1
1
|
# PassControl
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
provider
|
|
5
|
-
|
|
3
|
+
**An identity and credential gateway for AI agents.** The agent never holds the real
|
|
4
|
+
provider key: PassControl authenticates it, checks scope, policy and budget, then injects
|
|
5
|
+
the key and forwards the request. Call logs and signed receipts let you inspect what
|
|
6
|
+
happened, with [explicit limits on that evidence](#limits-and-security-status).
|
|
6
7
|
|
|
7
|
-
|
|
8
|
-
|
|
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.
|
|
8
|
+
Use it when you want to give each agent its own permissions, spending allowance and
|
|
9
|
+
stop control without copying provider secrets into every tool. Bring your own provider key.
|
|
12
10
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
11
|
+
| Start here | Choose it when | You operate |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| [Cloud](#cloud) — free private beta, access by request | You want a managed gateway without running a database or Docker | Your agents and provider account |
|
|
14
|
+
| [Self-host](#self-host) — full working core | You want the gateway and provider credentials on infrastructure you control | Gateway, dashboard, Supabase Auth + Vault + database, and Redis |
|
|
15
|
+
|
|
16
|
+
A **Passport** is an Ed25519 signing key used to obtain a short-lived visa. A **Direct
|
|
17
|
+
Agent Key** is a lower-assurance bearer credential bound to one agent; its calls are
|
|
18
|
+
not passport-signed. Both go through gateway controls.
|
|
19
|
+
|
|
20
|
+
Built by one developer under [Vertias](https://vertias.eu). Early software, **not
|
|
21
|
+
independently audited**. Start with a non-critical provider key. Source-available under
|
|
22
|
+
[BSL 1.1](./LICENSE).
|
|
23
|
+
|
|
24
|
+
## Cloud
|
|
25
|
+
|
|
26
|
+
[Request beta access](https://passcontrol.vertias.eu/beta). To look around first, try
|
|
27
|
+
[the keyless browser demo](https://passcontrol.vertias.eu): it synthesizes output and
|
|
28
|
+
does not call a billed provider.
|
|
29
|
+
|
|
30
|
+
Once you have access, install the CLI with Node/npm and sign in:
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
npm install -g passcontrol
|
|
34
|
+
passcontrol login
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Approve only the device code from your own terminal: this grants the machine a workspace
|
|
38
|
+
control key. Login creates a Passport locally, registers its public key, and attempts a
|
|
39
|
+
keyless governed call and receipt verification. That check needs demo and signing enabled;
|
|
40
|
+
it is not a real-provider test.
|
|
41
|
+
|
|
42
|
+
For a real call, add a provider key in the dashboard, give the agent a matching
|
|
43
|
+
provider/model scope and budgets, and follow [the first-call tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md).
|
|
44
|
+
For a static-key client, use **Connect an agent** and copy its generated gateway URL,
|
|
45
|
+
Direct Agent Key and concrete model into your client. The provider key stays in Vault.
|
|
46
|
+
|
|
47
|
+
## Self-host
|
|
48
|
+
|
|
49
|
+
Already stuck? See [self-host troubleshooting and operations](https://github.com/Vertias3u/PassControl/blob/main/docs/self-host.md).
|
|
50
|
+
|
|
51
|
+
Use **Node 22+**, npm, Git, Docker and the Supabase CLI. The npm package contains the CLI
|
|
52
|
+
and compiled SDK; setup obtains the public application source and starts the local stack.
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
npm install -g passcontrol
|
|
56
|
+
passcontrol setup
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Setup starts Supabase (Postgres + Auth + Vault) and Redis with a REST adapter, applies
|
|
60
|
+
migrations, seeds a local account and opens the dashboard. There are no shared default
|
|
61
|
+
credentials. This is a **local development setup**, not a production deployment.
|
|
62
|
+
|
|
63
|
+
**Updating.** `passcontrol update` updates the CLI and the checkout `setup` made. It shows the
|
|
64
|
+
plan first (`--check` stops there), asks once (`--yes` for scripts), then updates an npm global
|
|
65
|
+
install of the CLI to the exact version it found and lets the new CLI finish. For the app it
|
|
66
|
+
fast-forwards to the public repo's `main`, runs `npm ci`, applies new migrations (listed in the
|
|
67
|
+
plan; they only go forward), and restarts the dashboard if it was running. It leaves a checkout
|
|
68
|
+
alone, and says why, if it has local changes, has diverged, is not a clone of the public repo,
|
|
69
|
+
or was moved since setup (re-running the stack there would start an empty database). npx, pnpm,
|
|
70
|
+
yarn, bun and volta installs get the right command printed instead. If an update stops part way,
|
|
71
|
+
`passcontrol update --app-only` finishes it.
|
|
72
|
+
|
|
73
|
+
1. **Make a Passport call.** Add a non-critical provider key in **Provider Keys**. Issue a
|
|
74
|
+
Passport with a matching provider/model scope and budgets. Choose the dashboard's
|
|
75
|
+
Sidecar or MCP configuration flow, copy its generated Passport import command into
|
|
76
|
+
your terminal, then paste the one-time secret at the hidden prompt. The command itself
|
|
77
|
+
contains no secret. Follow the generated client configuration and send a small prompt.
|
|
78
|
+
Check the call and budget charge in the dashboard.
|
|
79
|
+
2. **Try a Direct Agent Key.** Use **Connect an agent**, select a concrete model within
|
|
80
|
+
scope, and copy the generated gateway URL and reveal-once key into your static-key
|
|
81
|
+
client. Send another prompt and check its authentication method in the call log.
|
|
82
|
+
3. **Check the budget.** Lower the test agent's token budget below the next request's
|
|
83
|
+
reservation estimate and retry; expect a budget refusal. Restore the budget afterward.
|
|
84
|
+
4. **Check the kill switch.** Arm it in the dashboard and retry; subsequent requests
|
|
85
|
+
should be refused. Disarm it when finished. It cannot cancel a request already upstream.
|
|
86
|
+
|
|
87
|
+
The Passport import hands browser-issued configuration to the CLI without putting its
|
|
88
|
+
secret in shell history. Keep the one-time secret until import succeeds.
|
|
89
|
+
[The tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md) explains the manual
|
|
90
|
+
CLI path; [client options](#connect-a-real-agent) cover SDK, Sidecar and MCP.
|
|
91
|
+
|
|
92
|
+
## Limits and security status
|
|
93
|
+
|
|
94
|
+
PassControl is **not independently audited**. The public developer API has **not shipped**;
|
|
95
|
+
the source includes a control-plane API, but that is not a launched public developer service.
|
|
96
|
+
No independent audit or production assurance is implied by the test suite.
|
|
16
97
|
|
|
17
|
-
|
|
98
|
+
PassControl governs requests routed through it. It cannot prevent an agent from using
|
|
99
|
+
another credential or network path, secure a compromised signer, guarantee a provider's
|
|
100
|
+
usage report, or make an issuer's assertions independently true. Budget admission reserves
|
|
101
|
+
an estimate, not a guaranteed invoice ceiling. Logging and receipt signing are best-effort;
|
|
102
|
+
a valid receipt does not prove every call was recorded.
|
|
103
|
+
|
|
104
|
+
The gateway operator remains trusted: Cloud uses managed server-side Supabase Vault;
|
|
105
|
+
self-hosting uses your Vault. The gateway decrypts and injects the provider key. This is
|
|
106
|
+
credential isolation, not end-to-end encryption from agent to provider.
|
|
107
|
+
|
|
108
|
+
Short visas, stop controls, pricing tables and evidence each have further limits below.
|
|
109
|
+
Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/Vertias3u/PassControl/security/advisories/new).
|
|
110
|
+
See [SECURITY.md](https://github.com/Vertias3u/PassControl/blob/main/SECURITY.md) and [LICENSE](./LICENSE) for security guidance and usage terms.
|
|
111
|
+
|
|
112
|
+
## Connect a real agent
|
|
113
|
+
|
|
114
|
+
Use the dashboard's generated provider-native configuration: gateway base URL, Direct
|
|
115
|
+
Agent Key and model. Anthropic uses its native base URL and key variables. Never paste
|
|
116
|
+
a Passport private key into an API-key field.
|
|
117
|
+
|
|
118
|
+
To see the whole integration run once, [`examples/direct-key-worker.mjs`](https://github.com/Vertias3u/PassControl/blob/main/examples/direct-key-worker.mjs)
|
|
119
|
+
is an ordinary OpenAI-SDK worker configured only by the agent's Setup file
|
|
120
|
+
(`passcontrol.env`). It makes one governed call and prints its receipt ID, then asks for a
|
|
121
|
+
model outside the agent's access and shows PassControl refusing it before the provider.
|
|
122
|
+
|
|
123
|
+
Add a provider credential in the dashboard and give the agent a concrete model within
|
|
124
|
+
its scope and suitable budgets. Choose by what your client supports:
|
|
125
|
+
|
|
126
|
+
| Client | Integration |
|
|
127
|
+
|---|---|
|
|
128
|
+
| Static base URL + API key | Dashboard **Connect an agent**: copy its provider-native URL and DAK |
|
|
129
|
+
| Your JS/TS code | `PassControl` from `passcontrol/sdk`; [SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) |
|
|
130
|
+
| Static-key client needing Passport | `passcontrol sidecar`, then `passcontrol env <integration>` |
|
|
131
|
+
| MCP client | `passcontrol mcp`; configure as below |
|
|
132
|
+
|
|
133
|
+
Direct Agent Keys point the client at the PassControl gateway origin. Passport Sidecar clients
|
|
134
|
+
point at loopback with a provider path (for example `http://127.0.0.1:8788/api/v1/anthropic`) and the sidecar forwards to the gateway.
|
|
135
|
+
The sidecar adds per-request sender proof; the current SDK and MCP paths use bearer visas and are
|
|
136
|
+
refused when sender proof is required.
|
|
137
|
+
|
|
138
|
+
For a Passport bridge to Cloud or self-host, start this in one terminal:
|
|
139
|
+
|
|
140
|
+
```sh
|
|
141
|
+
passcontrol sidecar
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
In another terminal, print the client settings:
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
passcontrol env hermes
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
For MCP, write client configuration using the global Passport profile, with no secret
|
|
151
|
+
in the generated configuration:
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
passcontrol configure claude-desktop --write
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
The cursor preset also writes configuration; claude-code prints its client-managed add command.
|
|
158
|
+
|
|
159
|
+
The sidecar listens on loopback by default and substitutes a visa for the client's dummy
|
|
160
|
+
API key. Treat access to that local listener as access to the configured agent. It is
|
|
161
|
+
not a sandbox against other processes running as you. Its provider CONNECT requests are
|
|
162
|
+
refused; use base URLs rather than TLS interception.
|
|
163
|
+
|
|
164
|
+
Presets (from `cli/presets.mjs`): `generic`, `openhands`, `litellm`, `aider`, `hermes`, `cline`, `continue`, `chatbox`, `jan`, `msty`, `cherry-studio`, `open-webui`, `librechat`; MCP presets: `claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
|
|
165
|
+
supported paths. [Hermes configuration](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
|
|
166
|
+
|
|
167
|
+
## CLI configuration and key storage
|
|
168
|
+
|
|
169
|
+
<details>
|
|
170
|
+
<summary>Command browser, key custody and Passport import</summary>
|
|
171
|
+
|
|
172
|
+
Run **`passcontrol`** with no arguments in an interactive terminal to open the command
|
|
173
|
+
browser: searchable grouped commands, recent actions, and configuration-aware options.
|
|
174
|
+
Use `passcontrol --help` or explicit commands in scripts.
|
|
175
|
+
|
|
176
|
+
The direct CLI call uses off/observe sender-proof mode; real provider calls need a stored
|
|
177
|
+
key and matching scope. Key migration moves an existing file key to the OS store.
|
|
178
|
+
|
|
179
|
+
```sh
|
|
180
|
+
passcontrol status
|
|
181
|
+
passcontrol call "Say hello"
|
|
182
|
+
passcontrol doctor --deep
|
|
183
|
+
passcontrol key status
|
|
184
|
+
passcontrol key migrate
|
|
185
|
+
passcontrol logout
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The CLI supports macOS Keychain, Linux Secret Service (`secret-tool`), and Windows
|
|
189
|
+
DPAPI-backed storage. File configuration may contain a storage marker instead of the
|
|
190
|
+
Passport secret; explicit environment secrets take precedence. An unavailable OS store
|
|
191
|
+
can use an existing file fallback with a warning. Custody shown by the gateway is
|
|
192
|
+
**DECLARED evidence**, not proof of storage. The signer still reads key material into
|
|
193
|
+
process memory; this is not a non-exportable hardware key.
|
|
194
|
+
|
|
195
|
+
For a Passport issued in the dashboard for Sidecar or MCP, import it without putting the
|
|
196
|
+
one-time secret in shell history:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
passcontrol passport import --global --gateway https://YOUR-PASSCONTROL-HOST --id PUBLIC_PASSPORT_ID
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The CLI proves the 32-byte Ed25519 secret matches the public ID, stores it in macOS Keychain,
|
|
203
|
+
Linux Secret Service, or Windows DPAPI, verifies readback, and only then atomically updates the
|
|
204
|
+
global profile. Replacement requires `--replace`. The public command contains no secret.
|
|
205
|
+
|
|
206
|
+
</details>
|
|
207
|
+
|
|
208
|
+
## Security and protocol reference
|
|
209
|
+
|
|
210
|
+
<details>
|
|
211
|
+
<summary>Authentication, enforcement, budget uncertainty, providers and evidence</summary>
|
|
212
|
+
|
|
213
|
+
### Request and authentication flow
|
|
18
214
|
|
|
19
215
|
```text
|
|
20
216
|
Direct Agent Key ───────────────────────────────────────────────┐
|
|
@@ -55,7 +251,7 @@ these controls do not cancel an upstream request already in flight. Public lifec
|
|
|
55
251
|
checks and the signed [revocation list](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md)
|
|
56
252
|
are separate from signature verification.
|
|
57
253
|
|
|
58
|
-
|
|
254
|
+
### What the gateway enforces
|
|
59
255
|
|
|
60
256
|
- An allowlist of provider endpoints, plus the agent's provider/model scope.
|
|
61
257
|
- Live policy rules: model/endpoint denials, time windows, request limits; optional
|
|
@@ -64,6 +260,10 @@ are separate from signature verification.
|
|
|
64
260
|
- Platform/tenant kill switches and per-agent suspension/revocation.
|
|
65
261
|
- Provider failover within supported request families and each attempt's authorization
|
|
66
262
|
and budget checks; it is not arbitrary API translation.
|
|
263
|
+
- The injected provider key is removed from what comes back: if an upstream echoes it in
|
|
264
|
+
an error body, a JSON answer or an event stream (even split across chunks), the agent
|
|
265
|
+
receives `[REDACTED_PROVIDER_KEY]` instead. This covers the exact key, not a key an
|
|
266
|
+
upstream has transformed.
|
|
67
267
|
|
|
68
268
|
Passport scopes are snapshots in visas; scope edits can take up to the configured visa
|
|
69
269
|
TTL to replace those snapshots. Other live controls have their own cache/invalidation
|
|
@@ -71,7 +271,7 @@ behavior. Kill-state reads default to fail-open; `KILL_SWITCH_FAIL_CLOSED=true`
|
|
|
71
271
|
on kill/suspend read failure. Required sender-proof replay checks and DAK credential
|
|
72
272
|
validation fail closed. Redis persistence and no-eviction configuration matter.
|
|
73
273
|
|
|
74
|
-
|
|
274
|
+
#### Budgets under uncertainty
|
|
75
275
|
|
|
76
276
|
Admission reserves an **estimate**, not a provider invoice or a guaranteed upper bound.
|
|
77
277
|
Concurrent attempts consume reserved headroom. Complete usage settles measured tokens
|
|
@@ -84,12 +284,21 @@ ending never runs leaves an open hold that does not expire. `may_have_dispatched
|
|
|
84
284
|
means dispatch permission was claimed, not that billing is proven. Such a hold cannot
|
|
85
285
|
be released as `not_spent` through recovery.
|
|
86
286
|
|
|
287
|
+
An agent can also have a **daily or monthly spend limit** (calendar UTC), checked in the
|
|
288
|
+
same reservation as its cumulative caps and refused with `402 blocked_budget_period` and a
|
|
289
|
+
`retry-after` to the next reset. A call counts toward the period it finishes in; spend
|
|
290
|
+
earlier in the period counts when the limit is set; an attempt that never settles keeps
|
|
291
|
+
counting until an operator resolves it. An **output ceiling** (`max_output_tokens` in the
|
|
292
|
+
agent's policy) refuses any request whose stated output limit is missing or larger — it is
|
|
293
|
+
never rewritten to fit.
|
|
294
|
+
|
|
87
295
|
Lost or mismatched established budget generations cause `503 blocked_budget_state`,
|
|
88
296
|
not a fresh allowance. Recovery is an explicit operator action over retained logs and
|
|
89
297
|
adjustments; it cannot reconstruct missing evidence. See [Budget recovery](https://github.com/Vertias3u/PassControl/blob/main/docs/budget-recovery.md).
|
|
90
298
|
|
|
91
|
-
Prices are an in-code estimate table
|
|
92
|
-
|
|
299
|
+
Prices are an in-code estimate table, one row per model, read from each provider's pricing
|
|
300
|
+
page. Under a dollar limit, a model with no row is refused `402 unpriced_model`; without one it
|
|
301
|
+
is estimated at the provider's highest listed rate. **Custom endpoints are unpriced**, even when the model name
|
|
93
302
|
matches: logs mark cost unknown, receipts carry `unp`, and token accounting continues.
|
|
94
303
|
The cost budget retains a proxy estimate; it does not become knowledge of actual dollars.
|
|
95
304
|
Known/table-priced cost, conservative enforced spend, and open holds are different figures.
|
|
@@ -99,7 +308,7 @@ live open reservations marked **not yet charged**. The call table keeps observed
|
|
|
99
308
|
charge in separate columns and can load older durable rows on demand. An unavailable database or
|
|
100
309
|
Redis explanation is shown as unavailable, never as zero.
|
|
101
310
|
|
|
102
|
-
|
|
311
|
+
### Supported providers and endpoints
|
|
103
312
|
|
|
104
313
|
All paths below are relative to `/api/v1/<provider>`. SDK base URLs and aliases are in
|
|
105
314
|
[the endpoint reference](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md).
|
|
@@ -114,7 +323,9 @@ All paths below are relative to `/api/v1/<provider>`. SDK base URLs and aliases
|
|
|
114
323
|
|
|
115
324
|
Gemini's native `generateContent` API is not supported. Responses support is OpenAI-only;
|
|
116
325
|
response retrieval/deletion, embeddings, files, fine-tuning, batches, and token-counting
|
|
117
|
-
endpoints are not proxied.
|
|
326
|
+
endpoints are not proxied. OpenAI's hosted tools (web search, file search, code interpreter
|
|
327
|
+
and others billed outside tokens) and its search models are refused, because no token budget can
|
|
328
|
+
hold their fees. Model availability still depends on your provider account.
|
|
118
329
|
|
|
119
330
|
Custom provider base URLs support compatible deployments such as Ollama, vLLM, or
|
|
120
331
|
LiteLLM without adding provider IDs. They require operator opt-in:
|
|
@@ -124,7 +335,7 @@ refuses custom endpoints. Shape validation is **not full SSRF prevention**: it d
|
|
|
124
335
|
resolve or pin DNS. Operators must control egress and trust the destination receiving
|
|
125
336
|
the provider credential. Upstream redirects are refused, never followed.
|
|
126
337
|
|
|
127
|
-
|
|
338
|
+
### Receipts, statements, and identity evidence
|
|
128
339
|
|
|
129
340
|
A signed call receipt records the issuer's decision, authentication method, reported
|
|
130
341
|
usage/cost, and (when read) a digest of client request bytes. It does not include the
|
|
@@ -160,116 +371,18 @@ that company. Only published bindings are attached to public evidence.
|
|
|
160
371
|
The recording illustrates a stop control on successive calls; it does not show cancellation
|
|
161
372
|
of an already-dispatched stream.
|
|
162
373
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
[Request access to the free private beta](https://passcontrol.vertias.eu/beta), or try
|
|
166
|
-
[the keyless browser demo](https://passcontrol.vertias.eu). The demo synthesizes model
|
|
167
|
-
output; it does not exercise a billed provider.
|
|
168
|
-
|
|
169
|
-
With Node installed:
|
|
170
|
-
|
|
171
|
-
```bash
|
|
172
|
-
npm install -g passcontrol
|
|
173
|
-
passcontrol login
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
Login prints a device code and opens browser approval. Enter only the code from your
|
|
177
|
-
own terminal: approval grants this machine a workspace control key. The CLI creates a
|
|
178
|
-
Passport locally, registers its public key, saves configuration, and attempts a keyless
|
|
179
|
-
governed call and receipt verification. That proof requires a gateway with demo and
|
|
180
|
-
signing enabled; it is not a real-provider test. See [the tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md).
|
|
181
|
-
|
|
182
|
-
Run **`passcontrol`** with no arguments in an interactive terminal to open the command
|
|
183
|
-
browser: searchable grouped commands, recent actions, and configuration-aware options.
|
|
184
|
-
Use `passcontrol --help` or explicit commands in scripts.
|
|
185
|
-
|
|
186
|
-
```bash
|
|
187
|
-
passcontrol status
|
|
188
|
-
passcontrol call "Say hello" # off/observe mode; real provider calls require a stored key
|
|
189
|
-
passcontrol doctor --deep
|
|
190
|
-
passcontrol key status
|
|
191
|
-
passcontrol key migrate # move an existing file key to the OS store
|
|
192
|
-
passcontrol logout
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
The CLI supports macOS Keychain, Linux Secret Service (`secret-tool`), and Windows
|
|
196
|
-
DPAPI-backed storage. File configuration may contain a storage marker instead of the
|
|
197
|
-
Passport secret; explicit environment secrets take precedence. An unavailable OS store
|
|
198
|
-
can use an existing file fallback with a warning. Custody shown by the gateway is
|
|
199
|
-
**DECLARED evidence**, not proof of storage. The signer still reads key material into
|
|
200
|
-
process memory; this is not a non-exportable hardware key.
|
|
201
|
-
|
|
202
|
-
For a Passport issued in the dashboard for Sidecar or MCP, import it without putting the
|
|
203
|
-
one-time secret in shell history:
|
|
204
|
-
|
|
205
|
-
```bash
|
|
206
|
-
passcontrol passport import --global --gateway https://YOUR-PASSCONTROL-HOST \
|
|
207
|
-
--id PUBLIC_PASSPORT_ID
|
|
208
|
-
# paste the secret at the hidden prompt, or provide it on raw stdin
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
The CLI proves the 32-byte Ed25519 secret matches the public ID, stores it in macOS Keychain,
|
|
212
|
-
Linux Secret Service, or Windows DPAPI, verifies readback, and only then atomically updates the
|
|
213
|
-
global profile. Replacement requires `--replace`. The public command contains no secret.
|
|
214
|
-
|
|
215
|
-
## Connect a real agent
|
|
216
|
-
|
|
217
|
-
For example, the direct OpenAI configuration has this shape:
|
|
218
|
-
|
|
219
|
-
```bash
|
|
220
|
-
export OPENAI_BASE_URL=https://YOUR-PASSCONTROL-HOST/api/v1/openai/v1
|
|
221
|
-
export OPENAI_API_KEY=pc_agent_REVEAL_ONCE_VALUE
|
|
222
|
-
export OPENAI_MODEL=gpt-4o-mini
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
Use your dashboard's actual values; Anthropic uses its native base URL and key variables.
|
|
226
|
-
Never paste a Passport private key into an API-key field.
|
|
227
|
-
|
|
228
|
-
Add a provider credential in the dashboard and give the agent a concrete model within
|
|
229
|
-
its scope and suitable budgets. Choose by what your client supports:
|
|
230
|
-
|
|
231
|
-
| Client | Integration |
|
|
232
|
-
|---|---|
|
|
233
|
-
| Static base URL + API key | Dashboard **Connect an agent**: copy its provider-native URL and DAK |
|
|
234
|
-
| Your JS/TS code | `PassControl` from `passcontrol/sdk`; [SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) |
|
|
235
|
-
| Static-key client needing Passport | `passcontrol sidecar`, then `passcontrol env <integration>` |
|
|
236
|
-
| MCP client | `passcontrol mcp`; configure as below |
|
|
237
|
-
|
|
238
|
-
Direct Agent Keys point the client at the PassControl gateway origin. Passport Sidecar clients
|
|
239
|
-
point at loopback (default `http://127.0.0.1:8788`) and the sidecar forwards to the gateway.
|
|
240
|
-
The sidecar adds per-request sender proof; the current SDK and MCP paths use bearer visas and are
|
|
241
|
-
refused when sender proof is required.
|
|
242
|
-
|
|
243
|
-
```bash
|
|
244
|
-
# Passport bridge: talks to Cloud or your self-hosted gateway
|
|
245
|
-
passcontrol sidecar
|
|
246
|
-
passcontrol env hermes
|
|
247
|
-
|
|
248
|
-
# MCP: global Passport configuration, no secret in generated client config
|
|
249
|
-
passcontrol configure claude-desktop --write
|
|
250
|
-
# Also: cursor; claude-code prints its client-managed add command
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
The sidecar listens on loopback by default and substitutes a visa for the client's dummy
|
|
254
|
-
API key. Treat access to that local listener as access to the configured agent. It is
|
|
255
|
-
not a sandbox against other processes running as you. Its provider CONNECT requests are
|
|
256
|
-
refused; use base URLs rather than TLS interception.
|
|
374
|
+
</details>
|
|
257
375
|
|
|
258
|
-
|
|
259
|
-
`msty`, `cherry-studio`, `open-webui`, `librechat`, `generic`; MCP presets:
|
|
260
|
-
`claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
|
|
261
|
-
supported paths. [Hermes configuration](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
|
|
376
|
+
## Self-host operations reference
|
|
262
377
|
|
|
263
|
-
|
|
378
|
+
<details>
|
|
379
|
+
<summary>Source setup, lifecycle, credential switching, production and portability</summary>
|
|
264
380
|
|
|
265
|
-
The
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
locked Supabase dependencies need ≥20 and Wrangler needs ≥22.
|
|
381
|
+
The CLI package declares Node ≥18, but the full stack needs Node 22+: locked Supabase
|
|
382
|
+
dependencies need ≥20 and Wrangler needs ≥22. Use `passcontrol setup --no-open` to
|
|
383
|
+
suppress browser launch. From a source checkout, the equivalent development path is:
|
|
269
384
|
|
|
270
385
|
```bash
|
|
271
|
-
passcontrol setup --no-open
|
|
272
|
-
# Or from a source checkout:
|
|
273
386
|
git clone https://github.com/Vertias3u/PassControl.git
|
|
274
387
|
cd PassControl
|
|
275
388
|
npm ci
|
|
@@ -298,7 +411,8 @@ global write could not override them safely. Clean up any still-active remote id
|
|
|
298
411
|
original gateway.
|
|
299
412
|
|
|
300
413
|
For production, configure [`.env.example`](https://github.com/Vertias3u/PassControl/blob/main/.env.example), use Supabase (plain Postgres
|
|
301
|
-
is insufficient), apply the public migrations with
|
|
414
|
+
is insufficient), set `DATABASE_URL` in your shell environment and apply the public migrations with
|
|
415
|
+
`npm run migrate`,
|
|
302
416
|
and build/run the app. Supported paths are Next.js on Vercel, `npm run build` then
|
|
303
417
|
`npm start` on a Node host behind a trusted reverse proxy, and the
|
|
304
418
|
[Cloudflare/OpenNext build](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md). Configure Auth/SMTP,
|
|
@@ -321,14 +435,7 @@ as sensitive configuration and inspect the result for partial/refused items.
|
|
|
321
435
|
[Release updates](https://passcontrol.vertias.eu/updates) and the
|
|
322
436
|
[learning center](https://passcontrol.vertias.eu/learn) are hosted-site resources.
|
|
323
437
|
|
|
324
|
-
|
|
438
|
+
</details>
|
|
325
439
|
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
usage report, or make an issuer's assertions independently true. Short visas, stop controls,
|
|
329
|
-
pricing tables, and best-effort logs each have the limits described above.
|
|
330
|
-
|
|
331
|
-
Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/Vertias3u/PassControl/security/advisories/new).
|
|
332
|
-
See [SECURITY.md](https://github.com/Vertias3u/PassControl/blob/main/SECURITY.md), [API documentation](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md), and
|
|
333
|
-
[contributing](https://github.com/Vertias3u/PassControl/blob/main/CONTRIBUTING.md). No independent audit or production assurance is implied
|
|
334
|
-
by the test suite. Read [LICENSE](./LICENSE) for the actual usage terms.
|
|
440
|
+
For the full reference, see [API documentation](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md).
|
|
441
|
+
Contributions: [CONTRIBUTING.md](https://github.com/Vertias3u/PassControl/blob/main/CONTRIBUTING.md).
|