passcontrol 0.9.5 → 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 +275 -11
- package/cli/config.mjs +86 -3
- 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).
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -36,6 +36,7 @@ import {
|
|
|
36
36
|
formatProxyError,
|
|
37
37
|
globalConfigPath,
|
|
38
38
|
mergeConfigFile,
|
|
39
|
+
localActivationPatch,
|
|
39
40
|
mergeConfigFileAtomic,
|
|
40
41
|
muted,
|
|
41
42
|
heading,
|
|
@@ -69,7 +70,19 @@ import {
|
|
|
69
70
|
supportsWrite,
|
|
70
71
|
} from "../cli/presets.mjs";
|
|
71
72
|
import { importCompletionMessage, noAgentCreateMessage } from "../cli/workspace-import-report.mjs";
|
|
72
|
-
import { checkForUpdate } from "../cli/update-check.mjs";
|
|
73
|
+
import { checkForUpdate, fetchLatest, REGISTRY_URL } from "../cli/update-check.mjs";
|
|
74
|
+
import {
|
|
75
|
+
clearMarker,
|
|
76
|
+
detectInstall,
|
|
77
|
+
dirtyBlockers,
|
|
78
|
+
expectedProjectId,
|
|
79
|
+
formatPlan,
|
|
80
|
+
isPublicRepoUrl,
|
|
81
|
+
planUpdate,
|
|
82
|
+
readMarker,
|
|
83
|
+
stackFromConfig,
|
|
84
|
+
writeMarker,
|
|
85
|
+
} from "../cli/update.mjs";
|
|
73
86
|
import { startSidecar } from "../cli/sidecar.mjs";
|
|
74
87
|
import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
|
|
75
88
|
import { loginCommand } from "../cli/login.mjs";
|
|
@@ -186,6 +199,7 @@ ${heading("Operate")}
|
|
|
186
199
|
${cmd} status [--no-network] [--json]
|
|
187
200
|
show active config and instance state
|
|
188
201
|
${cmd} version [--json] CLI, gateway and database schema versions
|
|
202
|
+
${cmd} update [--check] [--yes] update this CLI and the local self-host app (code, dependencies, migrations)
|
|
189
203
|
${cmd} doctor [--deep] [--fix] diagnose setup and repair a stopped dashboard
|
|
190
204
|
${cmd} open open the Control Tower in a browser
|
|
191
205
|
${cmd} logout [--revoke-agent] revoke this machine's key and clear its credentials
|
|
@@ -791,6 +805,7 @@ async function prepareLocalActivation(target, opts = {}) {
|
|
|
791
805
|
storageMarker,
|
|
792
806
|
previousGateway: config.gateway,
|
|
793
807
|
globalPath: globalConfigPath(),
|
|
808
|
+
globalValues: values,
|
|
794
809
|
};
|
|
795
810
|
}
|
|
796
811
|
|
|
@@ -807,16 +822,21 @@ function restoreFileAtomically(file, contents) {
|
|
|
807
822
|
}
|
|
808
823
|
|
|
809
824
|
function commitLocalActivation(prepared) {
|
|
810
|
-
|
|
825
|
+
const patch = localActivationPatch({
|
|
826
|
+
switching: prepared.switching,
|
|
827
|
+
globalValues: prepared.globalValues,
|
|
828
|
+
targetUrl: prepared.target.url,
|
|
829
|
+
});
|
|
830
|
+
if (!patch) return;
|
|
811
831
|
const existed = fs.existsSync(prepared.globalPath);
|
|
812
832
|
const previous = existed ? fs.readFileSync(prepared.globalPath, "utf8") : null;
|
|
813
|
-
mergeConfigFileAtomic(prepared.globalPath,
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
}
|
|
833
|
+
mergeConfigFileAtomic(prepared.globalPath, patch);
|
|
834
|
+
if (!prepared.switching) {
|
|
835
|
+
// A fresh machine: nothing to forget, only the gateway to record so that
|
|
836
|
+
// `login` targets this stack instead of Cloud.
|
|
837
|
+
ok(`active gateway set to ${prepared.target.url}`);
|
|
838
|
+
return;
|
|
839
|
+
}
|
|
820
840
|
|
|
821
841
|
if (prepared.storageMarker === PASSPORT_KEY_STORAGE_OS && prepared.passportId) {
|
|
822
842
|
const removed = createPassportCredentialStore().delete(prepared.passportId);
|
|
@@ -1073,16 +1093,65 @@ function removeDashboardState() {
|
|
|
1073
1093
|
fs.rmSync(dashboardStatePath(), { force: true });
|
|
1074
1094
|
}
|
|
1075
1095
|
|
|
1096
|
+
/**
|
|
1097
|
+
* The command line of a live process, or null when it cannot be read.
|
|
1098
|
+
*
|
|
1099
|
+
* `ps -o command=` on macOS and Linux; on Windows, the CIM process record via
|
|
1100
|
+
* PowerShell (present on every supported Windows). Bounded, never throws.
|
|
1101
|
+
*/
|
|
1102
|
+
function processCommandLine(pid) {
|
|
1103
|
+
try {
|
|
1104
|
+
if (process.platform === "win32") {
|
|
1105
|
+
const out = execFileSync(
|
|
1106
|
+
"powershell.exe",
|
|
1107
|
+
["-NoProfile", "-NonInteractive", "-Command", `(Get-CimInstance Win32_Process -Filter "ProcessId=${Number(pid)}").CommandLine`],
|
|
1108
|
+
{ encoding: "utf8", timeout: 10_000, windowsHide: true }
|
|
1109
|
+
);
|
|
1110
|
+
return out.trim() || null;
|
|
1111
|
+
}
|
|
1112
|
+
const out = execFileSync("ps", ["-o", "command=", "-p", String(Number(pid))], { encoding: "utf8", timeout: 5_000 });
|
|
1113
|
+
return out.trim() || null;
|
|
1114
|
+
} catch {
|
|
1115
|
+
return null;
|
|
1116
|
+
}
|
|
1117
|
+
}
|
|
1118
|
+
|
|
1119
|
+
/**
|
|
1120
|
+
* Whether the recorded PID is still the supervisor this CLI spawned (C7).
|
|
1121
|
+
*
|
|
1122
|
+
* A live PID alone is not proof: after a crash or reboot the state file
|
|
1123
|
+
* survives and the OS reuses the number, and `stop` then signalled the new
|
|
1124
|
+
* owner's whole process group — or, on Windows, `taskkill /T` its tree. The
|
|
1125
|
+
* state records the script the supervisor runs; the PID is ours only while its
|
|
1126
|
+
* command line still names it. Older state files without `script` fall back to
|
|
1127
|
+
* the launcher's file name.
|
|
1128
|
+
*
|
|
1129
|
+
* "unknown" (the command line could not be read) is not "ours": status still
|
|
1130
|
+
* reports it, but nothing is killed on an unverified PID.
|
|
1131
|
+
*/
|
|
1132
|
+
function managedDashboardIdentity(state) {
|
|
1133
|
+
const command = processCommandLine(state.pid);
|
|
1134
|
+
if (command === null) return "unknown";
|
|
1135
|
+
const expected = typeof state.script === "string" && state.script ? state.script : "dev-docker.mjs";
|
|
1136
|
+
return command.includes(expected) ? "ours" : "other";
|
|
1137
|
+
}
|
|
1138
|
+
|
|
1076
1139
|
function runningManagedDashboard() {
|
|
1077
1140
|
const state = readDashboardState();
|
|
1078
1141
|
if (!state) return null;
|
|
1079
1142
|
try {
|
|
1080
1143
|
process.kill(state.pid, 0);
|
|
1081
|
-
return state;
|
|
1082
1144
|
} catch (error) {
|
|
1083
1145
|
if (error.code === "ESRCH") removeDashboardState();
|
|
1084
1146
|
return null;
|
|
1085
1147
|
}
|
|
1148
|
+
const identity = managedDashboardIdentity(state);
|
|
1149
|
+
if (identity === "other") {
|
|
1150
|
+
// The PID now belongs to something else. The dashboard we started is gone.
|
|
1151
|
+
removeDashboardState();
|
|
1152
|
+
return null;
|
|
1153
|
+
}
|
|
1154
|
+
return { ...state, verified: identity === "ours" };
|
|
1086
1155
|
}
|
|
1087
1156
|
|
|
1088
1157
|
function dashboardStatusLabel(gateway, noNetwork, target = managedDashboardTarget()) {
|
|
@@ -1278,7 +1347,8 @@ async function startDashboard(opts = {}) {
|
|
|
1278
1347
|
child.unref();
|
|
1279
1348
|
fs.writeFileSync(
|
|
1280
1349
|
statePath,
|
|
1281
|
-
|
|
1350
|
+
// `script` is the identity check's anchor — see managedDashboardIdentity.
|
|
1351
|
+
`${JSON.stringify({ pid: child.pid, script: devServer, gateway: dashboard.url, port: dashboard.port, logPath, startedAt: new Date().toISOString() })}\n`,
|
|
1282
1352
|
{ mode: 0o600 }
|
|
1283
1353
|
);
|
|
1284
1354
|
|
|
@@ -1326,6 +1396,14 @@ async function stopDashboard() {
|
|
|
1326
1396
|
ok("No CLI-managed local dashboard is running.");
|
|
1327
1397
|
return;
|
|
1328
1398
|
}
|
|
1399
|
+
if (!state.verified) {
|
|
1400
|
+
// Refuse rather than guess: signalling a process group we cannot identify
|
|
1401
|
+
// is exactly the failure this check exists to prevent.
|
|
1402
|
+
throw new Error(
|
|
1403
|
+
`Could not confirm that PID ${state.pid} is the dashboard this CLI started, so it was not stopped. ` +
|
|
1404
|
+
`Stop it yourself if it is, then delete ${dashboardStatePath()}.`
|
|
1405
|
+
);
|
|
1406
|
+
}
|
|
1329
1407
|
|
|
1330
1408
|
if (process.platform === "win32") {
|
|
1331
1409
|
// Politely first — it lets Next flush if anything is listening for it — but
|
|
@@ -1547,6 +1625,188 @@ async function resetLocalStack(opts = {}) {
|
|
|
1547
1625
|
ok("Local stack recreated. Run `passcontrol start` to launch the dashboard.");
|
|
1548
1626
|
}
|
|
1549
1627
|
|
|
1628
|
+
// ── passcontrol update ───────────────────────────────────────────────────────
|
|
1629
|
+
//
|
|
1630
|
+
// The decisions live in cli/update.mjs (pure, tested); this is the half that
|
|
1631
|
+
// runs git, npm and the stack. Order matters and is the whole design: read
|
|
1632
|
+
// everything, show the plan, ask once, update the CLI, then hand the app phase
|
|
1633
|
+
// to the NEW CLI so the version doing the work is the one that knows the steps.
|
|
1634
|
+
|
|
1635
|
+
function gitIn(root, args, timeout = 60_000, { raw = false } = {}) {
|
|
1636
|
+
const out = execFileSync("git", args, { cwd: root, encoding: "utf8", timeout, stdio: ["ignore", "pipe", "pipe"] });
|
|
1637
|
+
// `raw` for porcelain output, whose leading space is a status column.
|
|
1638
|
+
return raw ? out : out.trim();
|
|
1639
|
+
}
|
|
1640
|
+
|
|
1641
|
+
/** The self-host checkout's state, or why it is left alone. Fetches origin/main. */
|
|
1642
|
+
function analyzeAppForUpdate({ fetchRemote = true } = {}) {
|
|
1643
|
+
let source;
|
|
1644
|
+
try {
|
|
1645
|
+
source = resolveAppRootSource();
|
|
1646
|
+
} catch (error) {
|
|
1647
|
+
return { status: "refuse", reason: error.message };
|
|
1648
|
+
}
|
|
1649
|
+
if (!source) return { status: "none" };
|
|
1650
|
+
const root = source.path;
|
|
1651
|
+
const marker = readMarker();
|
|
1652
|
+
const resume = marker && path.resolve(marker.appRoot) === root ? marker : null;
|
|
1653
|
+
const refuse = (reason) => ({ status: "refuse", root, reason, resume });
|
|
1654
|
+
|
|
1655
|
+
if (!fs.existsSync(path.join(root, ".git"))) {
|
|
1656
|
+
return refuse(`${root} is not a git checkout (a downloaded archive?), so it cannot be fast-forwarded. Update it by hand, or replace it with a fresh \`${cliCommand("setup")}\` clone.`);
|
|
1657
|
+
}
|
|
1658
|
+
let origin = "";
|
|
1659
|
+
try {
|
|
1660
|
+
origin = gitIn(root, ["config", "--get", "remote.origin.url"]);
|
|
1661
|
+
} catch {
|
|
1662
|
+
// No origin: refused just below.
|
|
1663
|
+
}
|
|
1664
|
+
if (!isPublicRepoUrl(origin, PUBLIC_REPO_URL)) {
|
|
1665
|
+
return refuse(`${root} is not a clone of the public PassControl repo (origin: ${origin || "none"}), so it is its owner's to update.`);
|
|
1666
|
+
}
|
|
1667
|
+
let branch = "";
|
|
1668
|
+
try {
|
|
1669
|
+
branch = gitIn(root, ["symbolic-ref", "--short", "HEAD"]);
|
|
1670
|
+
} catch {
|
|
1671
|
+
// Detached HEAD: refused just below.
|
|
1672
|
+
}
|
|
1673
|
+
if (branch !== "main") return refuse(`${root} is on ${branch || "a detached HEAD"}, not main.`);
|
|
1674
|
+
const blockers = dirtyBlockers(gitIn(root, ["status", "--porcelain", "--untracked-files=no"], 60_000, { raw: true }));
|
|
1675
|
+
if (blockers.length) {
|
|
1676
|
+
return refuse(`${root} has local changes (${blockers.join(", ")}). Commit or discard them, then rerun.`);
|
|
1677
|
+
}
|
|
1678
|
+
const configPath = path.join(root, "supabase", "config.toml");
|
|
1679
|
+
const stack = fs.existsSync(configPath) ? stackFromConfig(fs.readFileSync(configPath, "utf8")) : null;
|
|
1680
|
+
if (!stack) return refuse(`the local stack was never set up in ${root}; run \`${cliCommand("setup")}\` first.`);
|
|
1681
|
+
const expected = expectedProjectId(path.basename(root), stack.offset);
|
|
1682
|
+
if (stack.projectId !== expected) {
|
|
1683
|
+
return refuse(
|
|
1684
|
+
`supabase/config.toml names the project "${stack.projectId}", but this directory would now run as "${expected}". ` +
|
|
1685
|
+
"Was the checkout moved or renamed? Re-running the stack here would start an EMPTY database, so it is left alone. Move it back, then rerun."
|
|
1686
|
+
);
|
|
1687
|
+
}
|
|
1688
|
+
if (fetchRemote) {
|
|
1689
|
+
try {
|
|
1690
|
+
gitIn(root, ["fetch", "--quiet", "origin", "main"], 120_000);
|
|
1691
|
+
} catch (error) {
|
|
1692
|
+
return refuse(`could not fetch the public repo (${String(error.message).split("\n")[0]}).`);
|
|
1693
|
+
}
|
|
1694
|
+
}
|
|
1695
|
+
const head = gitIn(root, ["rev-parse", "HEAD"]);
|
|
1696
|
+
const target = gitIn(root, ["rev-parse", "origin/main"]);
|
|
1697
|
+
const ahead = Number(gitIn(root, ["rev-list", "--count", "origin/main..HEAD"]));
|
|
1698
|
+
if (ahead > 0) return refuse(`${root} has ${ahead} commit(s) that are not in the public repo, so it cannot be fast-forwarded.`);
|
|
1699
|
+
const behind = Number(gitIn(root, ["rev-list", "--count", "HEAD..origin/main"]));
|
|
1700
|
+
const base = { root, offset: stack.offset, head, target, resume, lockfileDirty: gitIn(root, ["status", "--porcelain", "--untracked-files=no", "--", "package-lock.json"]) !== "" };
|
|
1701
|
+
if (behind === 0) return { status: "current", ...base };
|
|
1702
|
+
const migrations = gitIn(root, ["diff", "--name-only", "--diff-filter=A", head, target, "--", "db/migrations"]).split("\n").filter(Boolean);
|
|
1703
|
+
return { status: "behind", behind, from: head.slice(0, 7), to: target.slice(0, 7), migrations, ...base };
|
|
1704
|
+
}
|
|
1705
|
+
|
|
1706
|
+
async function applyAppUpdate(app) {
|
|
1707
|
+
appRoot = app.root;
|
|
1708
|
+
const npm = process.platform === "win32" ? "npm.cmd" : "npm";
|
|
1709
|
+
const dashboard = managedDashboardTarget();
|
|
1710
|
+
const managed = runningManagedDashboard();
|
|
1711
|
+
// A dashboard the CLI did not start (\`npm run dev\` by hand) would have its
|
|
1712
|
+
// dependencies and env rewritten underneath it — the same trap as building
|
|
1713
|
+
// while dev runs. Refuse rather than break it.
|
|
1714
|
+
if (!managed && await portIsListening(dashboard.port)) {
|
|
1715
|
+
throw new Error(
|
|
1716
|
+
`Port ${dashboard.port} is served by something this CLI did not start (a dashboard run by hand?). Stop it, then rerun \`${cliCommand("update")}\`. Nothing was changed.`
|
|
1717
|
+
);
|
|
1718
|
+
}
|
|
1719
|
+
const restart = app.resume?.wasRunning ?? Boolean(managed);
|
|
1720
|
+
const from = app.resume?.from ?? app.head;
|
|
1721
|
+
writeMarker({ appRoot: app.root, from, to: app.target, wasRunning: restart, startedAt: new Date().toISOString() });
|
|
1722
|
+
try {
|
|
1723
|
+
if (managed) {
|
|
1724
|
+
step("Stopping the dashboard…");
|
|
1725
|
+
await stopDashboard();
|
|
1726
|
+
}
|
|
1727
|
+
if (app.status === "behind") {
|
|
1728
|
+
// npm's own rewrite of the lockfile (see dirtyBlockers); \`npm ci\` below
|
|
1729
|
+
// installs exactly what the new lockfile says.
|
|
1730
|
+
if (app.lockfileDirty) gitIn(app.root, ["checkout", "--", "package-lock.json"]);
|
|
1731
|
+
step(`Fast-forwarding ${app.from} → ${app.to}…`);
|
|
1732
|
+
await runCommand("git", ["merge", "--ff-only", "origin/main"], { cwd: app.root });
|
|
1733
|
+
}
|
|
1734
|
+
step("Installing dependencies (npm ci)…");
|
|
1735
|
+
await runCommand(npm, ["ci"], { cwd: app.root });
|
|
1736
|
+
step("Applying migrations and refreshing the local stack…");
|
|
1737
|
+
await runCommand(npm, ["run", "dev:stack"], {
|
|
1738
|
+
cwd: app.root,
|
|
1739
|
+
env: { ...process.env, PASSCONTROL_PORT_OFFSET: String(app.offset), PASSCONTROL_SKIP_SEED: "1", PASSCONTROL_VIA_CLI: "1" },
|
|
1740
|
+
});
|
|
1741
|
+
if (restart) await startDashboard({ dashboardOnly: true });
|
|
1742
|
+
} catch (error) {
|
|
1743
|
+
throw new Error(
|
|
1744
|
+
`The update stopped part way: ${error.message}\n` +
|
|
1745
|
+
`Fix the cause, then run \`${cliCommand("update --app-only")}\` to finish (install, migrations${restart ? ", restart" : ""}). ` +
|
|
1746
|
+
"The dashboard is stopped until then."
|
|
1747
|
+
);
|
|
1748
|
+
}
|
|
1749
|
+
clearMarker();
|
|
1750
|
+
ok(`App updated to ${String(app.target).slice(0, 7)}.`);
|
|
1751
|
+
step(`To roll back the code: git -C ${app.root} checkout ${from}. Database migrations only go forward.`);
|
|
1752
|
+
}
|
|
1753
|
+
|
|
1754
|
+
async function updateCommand(opts = {}) {
|
|
1755
|
+
const appOnly = Boolean(opts.appOnly);
|
|
1756
|
+
if (appOnly && opts.expectVersion && String(opts.expectVersion) !== CLI_VERSION) {
|
|
1757
|
+
throw new Error(
|
|
1758
|
+
`Expected the updated CLI ${opts.expectVersion}, but this is ${CLI_VERSION}. The CLI update did not land where this command runs from; nothing in the app was changed.`
|
|
1759
|
+
);
|
|
1760
|
+
}
|
|
1761
|
+
const latest = appOnly ? CLI_VERSION : await fetchLatest(REGISTRY_URL, 10_000);
|
|
1762
|
+
const install = detectInstall({
|
|
1763
|
+
scriptPath: fs.realpathSync(CLI_ENTRY),
|
|
1764
|
+
isSourceCheckout: isRepoCheckout(PACKAGE_ROOT) && process.env.PASSCONTROL_FORCE_INSTALLED !== "1",
|
|
1765
|
+
version: latest ?? CLI_VERSION,
|
|
1766
|
+
});
|
|
1767
|
+
const app = analyzeAppForUpdate();
|
|
1768
|
+
const plan = planUpdate({ current: CLI_VERSION, latest, install, app });
|
|
1769
|
+
if (opts.json) {
|
|
1770
|
+
console.log(JSON.stringify(plan, null, 2));
|
|
1771
|
+
return;
|
|
1772
|
+
}
|
|
1773
|
+
for (const line of formatPlan(plan)) console.log(line);
|
|
1774
|
+
if (opts.check) return;
|
|
1775
|
+
if (plan.nothingToDo) {
|
|
1776
|
+
ok("Nothing to update.");
|
|
1777
|
+
return;
|
|
1778
|
+
}
|
|
1779
|
+
if (!opts.yes) {
|
|
1780
|
+
if (!(process.stdin.isTTY && process.stdout.isTTY)) {
|
|
1781
|
+
throw new Error("Refusing to update without a terminal to confirm. Rerun with --yes, or --check to only see the plan.");
|
|
1782
|
+
}
|
|
1783
|
+
if (!await confirmYes("\nProceed? [Y/n] ")) {
|
|
1784
|
+
step("Nothing was changed.");
|
|
1785
|
+
return;
|
|
1786
|
+
}
|
|
1787
|
+
}
|
|
1788
|
+
const appWork = plan.app.status === "behind" || Boolean(plan.app.resume);
|
|
1789
|
+
if (plan.cli.needed && plan.cli.command) {
|
|
1790
|
+
step(`Updating the CLI: ${plan.cli.command.join(" ")}`);
|
|
1791
|
+
try {
|
|
1792
|
+
await runCommand(plan.cli.command[0], plan.cli.command.slice(1), { cwd: os.homedir() });
|
|
1793
|
+
} catch (error) {
|
|
1794
|
+
throw new Error(
|
|
1795
|
+
`The CLI update failed (${error.message}). If npm reported EACCES, run it yourself with the permissions your install needs:\n ${plan.cli.manual}\nNothing else was changed.`
|
|
1796
|
+
);
|
|
1797
|
+
}
|
|
1798
|
+
ok(`CLI updated to ${plan.cli.to}.`);
|
|
1799
|
+
if (!appWork) return;
|
|
1800
|
+
// Hand the app phase to the NEW CLI and do nothing else here: any lazy import
|
|
1801
|
+
// after npm replaced these files would load the new code into the old process.
|
|
1802
|
+
const child = spawn(process.execPath, [CLI_ENTRY, "update", "--app-only", "--yes", "--expect-version", String(plan.cli.to)], { stdio: "inherit" });
|
|
1803
|
+
process.exitCode = await new Promise((resolve) => child.once("exit", (code) => resolve(code ?? 1)));
|
|
1804
|
+
return;
|
|
1805
|
+
}
|
|
1806
|
+
if (plan.cli.needed) step(`Update the CLI yourself: ${plan.cli.manual}`);
|
|
1807
|
+
if (appWork) await applyAppUpdate(plan.app);
|
|
1808
|
+
}
|
|
1809
|
+
|
|
1550
1810
|
async function setupLocal(opts = {}) {
|
|
1551
1811
|
const dashboard = canonicalLocalDashboard();
|
|
1552
1812
|
const activation = await prepareLocalActivation(dashboard, opts);
|
|
@@ -1560,6 +1820,7 @@ async function setupLocal(opts = {}) {
|
|
|
1560
1820
|
await runLocalCommand(process.platform === "win32" ? "npm.cmd" : "npm", ["run", "dev:stack"], {
|
|
1561
1821
|
...process.env,
|
|
1562
1822
|
PASSCONTROL_PORT_OFFSET: String(offset),
|
|
1823
|
+
PASSCONTROL_VIA_CLI: "1",
|
|
1563
1824
|
});
|
|
1564
1825
|
// dev:stack has just brought Supabase and Redis up (and would have exited
|
|
1565
1826
|
// non-zero if it hadn't), so skip start's own service pass rather than print
|
|
@@ -3512,6 +3773,9 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
|
|
|
3512
3773
|
case "reset":
|
|
3513
3774
|
await resetLocalStack(opts);
|
|
3514
3775
|
break;
|
|
3776
|
+
case "update":
|
|
3777
|
+
await updateCommand(opts);
|
|
3778
|
+
break;
|
|
3515
3779
|
case "setup":
|
|
3516
3780
|
await setupLocal(opts);
|
|
3517
3781
|
break;
|
package/cli/config.mjs
CHANGED
|
@@ -205,7 +205,46 @@ export function assertConfigLoaded() {
|
|
|
205
205
|
}
|
|
206
206
|
|
|
207
207
|
export function resolveModel(provider) {
|
|
208
|
-
|
|
208
|
+
// `||`, not `??`: the config writer emits every key, so a fresh login left
|
|
209
|
+
// `MODEL=` in the file, and an empty string is not a model.
|
|
210
|
+
return process.env.MODEL || defaultModelForProvider(provider);
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* Provider and gateway, with an EMPTY value treated as unset. The config writer
|
|
215
|
+
* emits every key, so a fresh `login` wrote `PROVIDER=` — and `??` kept the empty
|
|
216
|
+
* string, so bare `call` and `agent create` failed with `Unknown provider ""`
|
|
217
|
+
* (1.0.0 self-host E2E). Reading empty as unset also repairs the configs 0.9.x
|
|
218
|
+
* logins already wrote.
|
|
219
|
+
*/
|
|
220
|
+
export function resolveConfigDefaults(env = process.env) {
|
|
221
|
+
return {
|
|
222
|
+
provider: env.PROVIDER || DEFAULT_PROVIDER,
|
|
223
|
+
gateway: trimSlash(env.PASSCONTROL_GATEWAY || DEFAULT_GATEWAY),
|
|
224
|
+
};
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/**
|
|
228
|
+
* What `setup` writes to the global config when it activates a local stack.
|
|
229
|
+
*
|
|
230
|
+
* Switching away from another gateway also forgets that gateway's credentials.
|
|
231
|
+
* Otherwise it still RECORDS the local gateway when the file names none: with no
|
|
232
|
+
* config the CLI's built-in default is already localhost, so setup used to think
|
|
233
|
+
* nothing needed writing — while `login`, which deliberately ignores that
|
|
234
|
+
* default, then went to Cloud. Null when the file already names a gateway.
|
|
235
|
+
*/
|
|
236
|
+
export function localActivationPatch({ switching, globalValues = {}, targetUrl }) {
|
|
237
|
+
if (switching) {
|
|
238
|
+
return {
|
|
239
|
+
PASSCONTROL_GATEWAY: targetUrl,
|
|
240
|
+
PASSPORT_ID: "",
|
|
241
|
+
PASSPORT_SECRET: "",
|
|
242
|
+
PASSPORT_KEY_STORAGE: "",
|
|
243
|
+
PASSCONTROL_API_KEY: "",
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
if (!String(globalValues.PASSCONTROL_GATEWAY ?? "").trim()) return { PASSCONTROL_GATEWAY: targetUrl };
|
|
247
|
+
return null;
|
|
209
248
|
}
|
|
210
249
|
|
|
211
250
|
export function resolvedConfig() {
|
|
@@ -214,7 +253,7 @@ export function resolvedConfig() {
|
|
|
214
253
|
}
|
|
215
254
|
|
|
216
255
|
function currentConfig() {
|
|
217
|
-
const provider = process.env
|
|
256
|
+
const { provider, gateway } = resolveConfigDefaults(process.env);
|
|
218
257
|
const passportId = process.env.PASSPORT_ID ?? "";
|
|
219
258
|
const fileSecret = process.env.PASSPORT_SECRET ?? "";
|
|
220
259
|
const passportStorageMarker = process.env.PASSPORT_KEY_STORAGE ?? "";
|
|
@@ -234,7 +273,7 @@ function currentConfig() {
|
|
|
234
273
|
return passport;
|
|
235
274
|
};
|
|
236
275
|
return {
|
|
237
|
-
gateway
|
|
276
|
+
gateway,
|
|
238
277
|
passportId,
|
|
239
278
|
get passportSecret() {
|
|
240
279
|
return resolvedPassport().secret;
|
|
@@ -598,8 +637,52 @@ export function formatChallengeError(status, body) {
|
|
|
598
637
|
return `Challenge failed: ${status} ${detail}`;
|
|
599
638
|
}
|
|
600
639
|
|
|
640
|
+
/** The gateway's JSON error body, or {} when it is not one. */
|
|
641
|
+
function errorBody(detail) {
|
|
642
|
+
try {
|
|
643
|
+
const parsed = JSON.parse(detail);
|
|
644
|
+
return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
|
|
645
|
+
} catch {
|
|
646
|
+
return {};
|
|
647
|
+
}
|
|
648
|
+
}
|
|
649
|
+
|
|
601
650
|
export function formatProxyError(status, body) {
|
|
602
651
|
const detail = String(body ?? "").trim();
|
|
652
|
+
const { error, rule, reason, limit } = errorBody(detail);
|
|
653
|
+
const blocked = `Proxy blocked the call with ${status}: ${detail}`;
|
|
654
|
+
if (status === 402 && error === "blocked_budget_period") {
|
|
655
|
+
return `${blocked}\n→ The agent's daily or monthly limit is spent; it resets at the next UTC day or month (see the retry-after header).\n→ Fix: wait for the reset, or raise the limit in the dashboard.`;
|
|
656
|
+
}
|
|
657
|
+
if (status === 403 && error === "blocked_policy" && rule === "max_output_tokens") {
|
|
658
|
+
const ceiling = Number.isSafeInteger(limit) ? ` (${limit})` : "";
|
|
659
|
+
return reason === "missing"
|
|
660
|
+
? `${blocked}\n→ The agent's policy has an output ceiling${ceiling}, and this request did not state an output limit.\n→ Fix: state an output limit — max_tokens (or max_completion_tokens / max_output_tokens) no higher than the ceiling.`
|
|
661
|
+
: `${blocked}\n→ The request asked for more output than the agent's output ceiling${ceiling}.\n→ Fix: send a smaller max_tokens, or raise the ceiling in the agent's policy.`;
|
|
662
|
+
}
|
|
663
|
+
if (status === 403 && error === "blocked_policy") {
|
|
664
|
+
return `${blocked}\n→ A rule in the agent's live policy refused this call (a deny rule, time window or hourly cap).\n→ Fix: review the policy on the agent's page, or use its decision trace to see which rule.`;
|
|
665
|
+
}
|
|
666
|
+
if (status === 403 && error === "blocked_scope") {
|
|
667
|
+
return `${blocked}\n→ This provider and model are outside the agent's allowed models.\n→ Fix: call an allowed model, or widen the agent's scope in the dashboard.`;
|
|
668
|
+
}
|
|
669
|
+
if (status === 409 && error === "no_provider_key") {
|
|
670
|
+
return `${blocked}\n→ The workspace has no provider key stored for this provider.\n→ Fix: add one under Settings → Provider credentials in the dashboard.`;
|
|
671
|
+
}
|
|
672
|
+
if (status === 400 && error === "server_side_tools_unsupported") {
|
|
673
|
+
return `${blocked}\n→ The request uses a hosted tool (such as web search) that the provider bills outside tokens, which no budget here can hold.\n→ Fix: remove the hosted tool, or call that feature outside PassControl.`;
|
|
674
|
+
}
|
|
675
|
+
// 402 is also how the gateway refuses a call it cannot price under a dollar
|
|
676
|
+
// limit; a bigger budget fixes none of those, so each gets its own advice.
|
|
677
|
+
if (status === 402 && error === "unpriced_model") {
|
|
678
|
+
return `${blocked}\n→ PassControl has no price for this model, so the agent's dollar limit cannot be enforced against it.\n→ Fix: use a model PassControl prices, or remove the dollar limit (a token cap still works).`;
|
|
679
|
+
}
|
|
680
|
+
if (status === 402 && error === "unpriced_option") {
|
|
681
|
+
return `${blocked}\n→ The named request field bills above the model's listed price, so the agent's dollar limit cannot hold it.\n→ Fix: drop that field (e.g. service_tier), or remove the dollar limit.`;
|
|
682
|
+
}
|
|
683
|
+
if (status === 402 && error === "unpriced_endpoint") {
|
|
684
|
+
return `${blocked}\n→ This agent's provider goes through a custom endpoint PassControl cannot price, so its dollar limit cannot be enforced.\n→ Fix: remove the dollar limit (a token cap still works), or use the provider's own endpoint.`;
|
|
685
|
+
}
|
|
603
686
|
if (status === 402) {
|
|
604
687
|
return `Proxy blocked the call with 402: ${detail}\n→ Fix: raise or clear the agent budget in the dashboard, then retry.`;
|
|
605
688
|
}
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
export const DEFAULT_ALLOWED_MODELS = Object.freeze({
|
|
8
8
|
anthropic: "claude-*",
|
|
9
9
|
openai: "gpt-*",
|
|
10
|
-
groq: "
|
|
10
|
+
groq: "openai/gpt-oss-*",
|
|
11
11
|
mistral: "mistral-*",
|
|
12
12
|
together: "openai/gpt-oss-*",
|
|
13
13
|
deepseek: "deepseek-*",
|
|
@@ -17,11 +17,11 @@ export const DEFAULT_ALLOWED_MODELS = Object.freeze({
|
|
|
17
17
|
export const DEFAULT_CLIENT_MODELS = Object.freeze({
|
|
18
18
|
anthropic: "claude-haiku-4-5",
|
|
19
19
|
openai: "gpt-5-mini",
|
|
20
|
-
groq: "
|
|
20
|
+
groq: "openai/gpt-oss-20b",
|
|
21
21
|
mistral: "mistral-small-latest",
|
|
22
|
-
together: "openai/gpt-oss-
|
|
23
|
-
deepseek: "deepseek-
|
|
24
|
-
gemini: "gemini-
|
|
22
|
+
together: "openai/gpt-oss-120b",
|
|
23
|
+
deepseek: "deepseek-flash",
|
|
24
|
+
gemini: "gemini-3.8-flash",
|
|
25
25
|
});
|
|
26
26
|
|
|
27
27
|
export function defaultAllowedModelForProvider(provider) {
|
package/cli/mcp/README.md
CHANGED
|
@@ -6,6 +6,8 @@ It reads the same environment, nearest `.passcontrol`, and global
|
|
|
6
6
|
passport in the global profile so clients can launch from any working directory without
|
|
7
7
|
embedding a secret:
|
|
8
8
|
|
|
9
|
+
On Windows, run these shell commands in PowerShell. Replace placeholders before running.
|
|
10
|
+
|
|
9
11
|
```sh
|
|
10
12
|
passcontrol passport import --global --gateway https://YOUR-PASSCONTROL-HOST --id PUBLIC_PASSPORT_ID
|
|
11
13
|
# paste the one-time secret at the hidden prompt
|
package/cli/menu.mjs
CHANGED
|
@@ -226,6 +226,7 @@ export const GROUPS = [
|
|
|
226
226
|
command({ id: "doctor", label: "Diagnose setup", run: ["doctor"], detail: "doctor", description: "Inspect the local stack, gateway, credentials, and protocol compatibility.", network: "gateway", current: currentFrom("gateway") }),
|
|
227
227
|
command({ id: "status", label: "Show cockpit status", run: ["status"], detail: "status", description: "Show local configuration, gateway health, and the next useful action.", network: "gateway", current: currentFrom("gateway") }),
|
|
228
228
|
command({ id: "version", label: "CLI, gateway and schema versions", run: ["version"], detail: "version", description: "Compare CLI, gateway build, schema, and protocol versions.", network: "gateway" }),
|
|
229
|
+
command({ id: "update", label: "Update PassControl", run: ["update"], detail: "update [--check]", description: "Update the CLI and the local app: code, dependencies, migrations.", effect: "irreversible", network: "provider", keywords: ["upgrade", "new version", "migrate"] }),
|
|
229
230
|
command({ id: "open", label: "Open the Control Tower", run: ["open"], detail: "open", description: "Open the configured dashboard in the system browser.", effect: "launch", network: "browser" }),
|
|
230
231
|
command({ id: "call", label: "Make a governed model call", run: ["call"], detail: "call \"<prompt>\"", description: "Mint a visa and make a billable governed provider call.", effect: "tenant_write", network: "provider", needsArgs: true, current: currentFrom("provider") }),
|
|
231
232
|
],
|
package/cli/update-check.mjs
CHANGED
|
@@ -16,7 +16,8 @@
|
|
|
16
16
|
// wall-clock time rather than by how often the CLI is run.
|
|
17
17
|
//
|
|
18
18
|
// It reports only that a newer version exists. It never downloads, installs or
|
|
19
|
-
// runs anything — upgrading stays a thing the operator types
|
|
19
|
+
// runs anything — upgrading stays a thing the operator types (`passcontrol update`,
|
|
20
|
+
// cli/update.mjs, which asks before it changes anything).
|
|
20
21
|
import fs from "node:fs";
|
|
21
22
|
import os from "node:os";
|
|
22
23
|
import path from "node:path";
|
|
@@ -110,7 +111,7 @@ export function writeCache(file, data) {
|
|
|
110
111
|
/** The notice itself, or null when there is nothing worth saying. */
|
|
111
112
|
export function updateNotice(current, latest) {
|
|
112
113
|
if (!isNewer(latest, current)) return null;
|
|
113
|
-
return `Update available ${current} → ${latest}
|
|
114
|
+
return `Update available ${current} → ${latest} passcontrol update`;
|
|
114
115
|
}
|
|
115
116
|
|
|
116
117
|
/**
|
|
@@ -124,7 +125,10 @@ export async function fetchLatest(url = REGISTRY_URL, timeoutMs = 1500, fetchImp
|
|
|
124
125
|
try {
|
|
125
126
|
const res = await fetchImpl(url, {
|
|
126
127
|
signal: controller.signal,
|
|
127
|
-
|
|
128
|
+
// Plain JSON. The abbreviated-metadata type is for the full packument; on
|
|
129
|
+
// /latest the registry answers 406 to it, which made every check return
|
|
130
|
+
// null and no notice was ever shown (found 2026-09-27).
|
|
131
|
+
headers: { accept: "application/json" },
|
|
128
132
|
});
|
|
129
133
|
if (!res.ok) return null;
|
|
130
134
|
const body = await res.json();
|
package/cli/update.mjs
ADDED
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
// `passcontrol update` — the decisions, kept pure so every one of them is tested
|
|
2
|
+
// before it touches someone's install. bin/passcontrol.mjs does the mutating
|
|
3
|
+
// half (npm, git, the local stack) and asks this module what to do.
|
|
4
|
+
//
|
|
5
|
+
// Two things get updated, and they fail differently:
|
|
6
|
+
//
|
|
7
|
+
// * The CLI. Only an npm global install is updated in place, pinned to the
|
|
8
|
+
// exact version just read from the registry (not `@latest`, so a release
|
|
9
|
+
// published mid-update cannot slip in). npx, pnpm, yarn, bun, volta and a
|
|
10
|
+
// source checkout each get the right command PRINTED: guessing another
|
|
11
|
+
// package manager's layout is how a tool ends up installed twice.
|
|
12
|
+
// * The self-host app checkout `setup` made — a clone of the PUBLIC repo only.
|
|
13
|
+
// Fast-forward, never merge; refuse on local edits, a diverged branch, or a
|
|
14
|
+
// checkout that is not the public repo (a private or forked checkout is its
|
|
15
|
+
// owner's to update). Migrations only go forward, so the plan names them.
|
|
16
|
+
import fs from "node:fs";
|
|
17
|
+
import os from "node:os";
|
|
18
|
+
import path from "node:path";
|
|
19
|
+
|
|
20
|
+
import { isNewer } from "./update-check.mjs";
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* How this CLI was installed, and how to update it.
|
|
24
|
+
*
|
|
25
|
+
* `command` is non-null only when running it is safe: an npm global install
|
|
26
|
+
* whose prefix can be read off the script's own path. Everything else gets a
|
|
27
|
+
* `manual` line to print.
|
|
28
|
+
*/
|
|
29
|
+
export function detectInstall({ scriptPath, platform = process.platform, isSourceCheckout = false, version }) {
|
|
30
|
+
const spec = `passcontrol@${version}`;
|
|
31
|
+
const p = String(scriptPath ?? "");
|
|
32
|
+
const has = (fragment) => p.replace(/\\/gu, "/").includes(fragment);
|
|
33
|
+
if (isSourceCheckout) {
|
|
34
|
+
return { method: "source", command: null, manual: "This CLI runs from a source checkout: update it with `git pull` there." };
|
|
35
|
+
}
|
|
36
|
+
if (has("/_npx/")) return { method: "npx", command: null, manual: `npx passcontrol@${version} (npx runs a fresh copy; nothing to install)` };
|
|
37
|
+
if (has("/pnpm/") || has("/.pnpm/")) return { method: "pnpm", command: null, manual: `pnpm add -g ${spec}` };
|
|
38
|
+
if (has("/yarn/global/") || has("/.yarn/")) return { method: "yarn", command: null, manual: `yarn global add ${spec}` };
|
|
39
|
+
if (has("/.bun/")) return { method: "bun", command: null, manual: `bun add -g ${spec}` };
|
|
40
|
+
if (has("/.volta/")) return { method: "volta", command: null, manual: `volta install ${spec}` };
|
|
41
|
+
|
|
42
|
+
const windows = platform === "win32";
|
|
43
|
+
const match = windows
|
|
44
|
+
? /^(.*)\\node_modules\\passcontrol\\bin\\passcontrol\.mjs$/iu.exec(p)
|
|
45
|
+
: /^(.*)\/lib\/node_modules\/passcontrol\/bin\/passcontrol\.mjs$/u.exec(p);
|
|
46
|
+
if (match && match[1]) {
|
|
47
|
+
const prefix = match[1];
|
|
48
|
+
return {
|
|
49
|
+
method: "npm-global",
|
|
50
|
+
prefix,
|
|
51
|
+
command: [windows ? "npm.cmd" : "npm", "install", "-g", "--prefix", prefix, spec],
|
|
52
|
+
manual: `npm install -g --prefix ${prefix} ${spec}`,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
return { method: "unknown", command: null, manual: `npm install -g ${spec}` };
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** `github.com/owner/repo`, lowercased, from any of the forms git accepts. */
|
|
59
|
+
function normalizeRepoUrl(url) {
|
|
60
|
+
let s = String(url ?? "").trim().toLowerCase();
|
|
61
|
+
s = s.replace(/^git@([^:]+):/u, "$1/");
|
|
62
|
+
s = s.replace(/^[a-z+]+:\/\//u, "");
|
|
63
|
+
s = s.replace(/^[^@/]+@/u, "");
|
|
64
|
+
s = s.replace(/\/+$/u, "").replace(/\.git$/u, "");
|
|
65
|
+
return s;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Exact host, owner and repo — never a prefix or substring match. */
|
|
69
|
+
export function isPublicRepoUrl(url, publicUrl) {
|
|
70
|
+
const a = normalizeRepoUrl(url);
|
|
71
|
+
return a !== "" && a === normalizeRepoUrl(publicUrl);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Tracked files with local changes that must stop an update.
|
|
76
|
+
*
|
|
77
|
+
* `package-lock.json` is tolerated: `npm install` rewrites it (the 0.9.5 mirror
|
|
78
|
+
* shipped a stale root version, so every setup checkout shows it modified), it
|
|
79
|
+
* is npm's output rather than anyone's work, and the update restores it and
|
|
80
|
+
* then runs `npm ci`. Untracked files are left to the fast-forward, which names
|
|
81
|
+
* any real collision itself.
|
|
82
|
+
*/
|
|
83
|
+
export function dirtyBlockers(porcelain) {
|
|
84
|
+
const files = [];
|
|
85
|
+
for (const raw of String(porcelain ?? "").split("\n")) {
|
|
86
|
+
const line = raw.replace(/\r$/u, "");
|
|
87
|
+
if (!line.trim()) continue;
|
|
88
|
+
// Two status columns, a space, the path. A caller that trimmed git's output
|
|
89
|
+
// leaves the FIRST line with one column (" M x" → "M x"), so accept that
|
|
90
|
+
// too rather than reading columns by position (which once saw "ackage-lock.json").
|
|
91
|
+
const match = /^([ MADRCUT?!]{2}) (.+)$/u.exec(line) ?? /^([MADRCUT?!]) (.+)$/u.exec(line);
|
|
92
|
+
if (!match) continue;
|
|
93
|
+
const status = match[1].trim();
|
|
94
|
+
if (status === "??" || status === "!!") continue;
|
|
95
|
+
if (match[2] !== "package-lock.json") files.push(match[2]);
|
|
96
|
+
}
|
|
97
|
+
return files;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The project id and port offset `setup` baked into supabase/config.toml, or
|
|
102
|
+
* null. Read back rather than re-derived, because re-running the stack with a
|
|
103
|
+
* different offset or id brings up a FRESH, EMPTY Supabase project — which
|
|
104
|
+
* looks exactly like data loss.
|
|
105
|
+
*/
|
|
106
|
+
export function stackFromConfig(configText) {
|
|
107
|
+
const text = String(configText ?? "");
|
|
108
|
+
const projectId = /^project_id\s*=\s*"([^"]+)"\s*$/mu.exec(text)?.[1];
|
|
109
|
+
const api = /^\[api\]\s*\n(?:[^[]*?\n)?port\s*=\s*(\d+)/mu.exec(text)?.[1];
|
|
110
|
+
if (!projectId || !api) return null;
|
|
111
|
+
const offset = Number(api) - 54321;
|
|
112
|
+
if (!Number.isInteger(offset) || offset < 0 || offset > 10000) return null;
|
|
113
|
+
return { projectId, offset };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** The id scripts/dev-stack.sh will compute for this directory and offset. */
|
|
117
|
+
export function expectedProjectId(dirName, offset) {
|
|
118
|
+
return offset === 0 ? dirName : `${dirName}-${offset}`;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* What an update would do. `app.status` is one of:
|
|
123
|
+
* none — no self-host checkout on this machine (a Cloud user)
|
|
124
|
+
* current — at the public repo's tip
|
|
125
|
+
* behind — fast-forwardable; `behind`, `from`, `to`, `migrations`
|
|
126
|
+
* refuse — `reason` says why this checkout is left alone
|
|
127
|
+
* `app.resume` is set when an earlier update stopped part way.
|
|
128
|
+
*/
|
|
129
|
+
export function planUpdate({ current, latest, install, app }) {
|
|
130
|
+
const cli = {
|
|
131
|
+
reachable: typeof latest === "string",
|
|
132
|
+
needed: typeof latest === "string" && isNewer(latest, current),
|
|
133
|
+
from: current,
|
|
134
|
+
to: latest ?? null,
|
|
135
|
+
command: install?.command ?? null,
|
|
136
|
+
manual: install?.manual ?? "",
|
|
137
|
+
method: install?.method ?? "unknown",
|
|
138
|
+
};
|
|
139
|
+
const appWork = app?.status === "behind" || Boolean(app?.resume);
|
|
140
|
+
return { cli, app: app ?? { status: "none" }, nothingToDo: !cli.needed && !appWork };
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** The plan as lines for a terminal. */
|
|
144
|
+
export function formatPlan(plan) {
|
|
145
|
+
const lines = [];
|
|
146
|
+
const { cli, app } = plan;
|
|
147
|
+
if (!cli.reachable) {
|
|
148
|
+
lines.push("CLI: could not reach the npm registry, so it is not known whether a newer version exists.");
|
|
149
|
+
} else if (cli.needed) {
|
|
150
|
+
lines.push(`CLI: ${cli.from} → ${cli.to}`);
|
|
151
|
+
lines.push(cli.command ? ` runs: ${cli.command.join(" ")}` : ` run it yourself: ${cli.manual}`);
|
|
152
|
+
} else {
|
|
153
|
+
lines.push(`CLI: ${cli.from}, nothing newer on npm (latest published: ${cli.to}).`);
|
|
154
|
+
}
|
|
155
|
+
switch (app.status) {
|
|
156
|
+
case "none":
|
|
157
|
+
lines.push("App: no self-host checkout on this machine.");
|
|
158
|
+
break;
|
|
159
|
+
case "refuse":
|
|
160
|
+
lines.push(`App: left alone — ${app.reason}`);
|
|
161
|
+
break;
|
|
162
|
+
case "current":
|
|
163
|
+
lines.push(app.resume ? "App: at the latest commit, but an earlier update was interrupted; it will finish install, migrations and restart." : "App: up to date.");
|
|
164
|
+
break;
|
|
165
|
+
case "behind": {
|
|
166
|
+
lines.push(`App: ${app.behind} new commit(s), ${app.from} → ${app.to}`);
|
|
167
|
+
const migrations = app.migrations ?? [];
|
|
168
|
+
lines.push(
|
|
169
|
+
migrations.length
|
|
170
|
+
? ` new database migrations (they only go forward): ${migrations.map((m) => path.basename(m)).join(", ")}`
|
|
171
|
+
: " no new database migrations"
|
|
172
|
+
);
|
|
173
|
+
lines.push(" steps: stop the dashboard, fast-forward, npm ci, apply migrations, start the dashboard again if it was running");
|
|
174
|
+
break;
|
|
175
|
+
}
|
|
176
|
+
default:
|
|
177
|
+
break;
|
|
178
|
+
}
|
|
179
|
+
return lines;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
// ── Resume marker ─────────────────────────────────────────────────────────────
|
|
183
|
+
//
|
|
184
|
+
// Written before the first change to the checkout and cleared on success. After
|
|
185
|
+
// a fast-forward HEAD already equals the target, so without it a failed
|
|
186
|
+
// `npm ci` or migration would read as "up to date" on the next run.
|
|
187
|
+
|
|
188
|
+
export function markerPath(env = process.env) {
|
|
189
|
+
const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
|
|
190
|
+
return path.join(base, "passcontrol", "update-in-progress.json");
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
export function readMarker(env = process.env) {
|
|
194
|
+
try {
|
|
195
|
+
const value = JSON.parse(fs.readFileSync(markerPath(env), "utf8"));
|
|
196
|
+
return value && typeof value.appRoot === "string" ? value : null;
|
|
197
|
+
} catch {
|
|
198
|
+
return null;
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
export function writeMarker(marker, env = process.env) {
|
|
203
|
+
const file = markerPath(env);
|
|
204
|
+
fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
|
|
205
|
+
fs.writeFileSync(file, `${JSON.stringify(marker)}\n`, { mode: 0o600 });
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
export function clearMarker(env = process.env) {
|
|
209
|
+
try {
|
|
210
|
+
fs.rmSync(markerPath(env), { force: true });
|
|
211
|
+
} catch {
|
|
212
|
+
// Nothing to clear.
|
|
213
|
+
}
|
|
214
|
+
}
|
package/package.json
CHANGED
package/sdk/README.md
CHANGED
|
@@ -7,12 +7,14 @@ your existing OpenAI/Anthropic SDK, **not rewriting the agent**.
|
|
|
7
7
|
|
|
8
8
|
Install it beside the provider SDK used by your agent:
|
|
9
9
|
|
|
10
|
+
On Windows, run these shell commands in PowerShell. Replace placeholders before running.
|
|
11
|
+
|
|
10
12
|
```bash
|
|
11
|
-
npm install passcontrol
|
|
12
|
-
# or: npm install passcontrol
|
|
13
|
+
npm install passcontrol openai
|
|
14
|
+
# or: npm install passcontrol @anthropic-ai/sdk
|
|
13
15
|
```
|
|
14
16
|
|
|
15
|
-
Dependencies:
|
|
17
|
+
Dependencies: [`@noble/curves`](https://github.com/paulmillr/noble-curves), `@noble/hashes`, and the
|
|
16
18
|
platform `fetch`/`crypto`. Runs on Node 18+ and edge/server runtimes.
|
|
17
19
|
|
|
18
20
|
> Keep `passportSecret` in the trusted agent runtime and out of source control, logs,
|
|
@@ -105,7 +107,7 @@ const res = await pc.fetch(`${gateway}/api/v1/anthropic/v1/messages`, {
|
|
|
105
107
|
## Control-plane SDK (manage your fleet)
|
|
106
108
|
|
|
107
109
|
Separate from the data-plane client above: `ControlClient` (in `./control`) is a typed
|
|
108
|
-
wrapper over the
|
|
110
|
+
wrapper over the workspace control API (`/api/control/v1`), authenticated with a `pc_` API key.
|
|
109
111
|
It mirrors the REST resources, unwraps the `{ data }` envelope, and throws
|
|
110
112
|
`ControlApiError` (with `status`, `code`, `requestId`) on failure.
|
|
111
113
|
|
|
@@ -153,14 +155,14 @@ The full reference lives in [the public OpenAPI document](https://github.com/Ver
|
|
|
153
155
|
the gateway only ever sees the public key and the signature.
|
|
154
156
|
|
|
155
157
|
|
|
156
|
-
##
|
|
158
|
+
## Compatibility and assurance
|
|
157
159
|
|
|
158
160
|
`clientOptions` accepts `openai`, `anthropic`, `groq`, `mistral`, `together`, `deepseek`,
|
|
159
161
|
and `gemini`. OpenAI POST Responses works through `pc.fetch`/the OpenAI SDK as well as
|
|
160
162
|
Chat Completions. Gemini uses Google's OpenAI-compatible endpoint; native
|
|
161
163
|
`generateContent` is not supported. See [accepted paths](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md#data-plane--proxy-a-model-call).
|
|
162
164
|
|
|
163
|
-
The TypeScript SDK **does not attach sender proofs
|
|
165
|
+
The TypeScript SDK **does not attach sender proofs**. Its provider requests use
|
|
164
166
|
bearer visas: they work with sender-proof mode off/observe, but required mode refuses
|
|
165
167
|
them without an additional correct proof implementation. The current sidecar attaches
|
|
166
168
|
proofs. A valid mint signature is not a signature over each provider request.
|
package/sdk/control.d.ts
CHANGED
|
@@ -95,6 +95,9 @@ export declare class ControlClient {
|
|
|
95
95
|
}[];
|
|
96
96
|
budget_tokens?: number | null;
|
|
97
97
|
budget_cents?: number | null;
|
|
98
|
+
/** Periodic spend limit: send both, or both null to remove it. */
|
|
99
|
+
budget_period?: "day" | "month" | null;
|
|
100
|
+
budget_period_cents?: number | null;
|
|
98
101
|
}, opts?: WriteOpts) => Promise<{
|
|
99
102
|
id: string;
|
|
100
103
|
}>;
|