passcontrol 0.8.0 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +252 -493
- package/bin/passcontrol.mjs +672 -30
- package/cli/config.mjs +71 -9
- package/cli/gateway-wait.mjs +79 -0
- package/cli/login.mjs +5 -0
- package/cli/logout.mjs +48 -4
- package/cli/mcp/README.md +9 -1
- package/cli/mcp/gateway.mjs +2 -0
- package/cli/menu-session.mjs +64 -0
- package/cli/menu.mjs +785 -0
- package/cli/passport-key-store.mjs +413 -0
- package/cli/protocols.d.mts +3 -0
- package/cli/protocols.mjs +23 -0
- package/cli/selftest.mjs +63 -13
- package/cli/sidecar.mjs +4 -0
- package/cli/verify.mjs +78 -3
- package/cli/visa-client.mjs +30 -2
- package/package.json +1 -1
- package/sdk/README.md +30 -5
- package/sdk/control.d.ts +38 -0
- package/sdk/control.js +32 -0
- package/sdk/index.d.ts +2 -2
- package/sdk/index.js +1 -1
- package/sdk/verify.d.ts +90 -1
- package/sdk/verify.js +83 -5
package/README.md
CHANGED
|
@@ -1,538 +1,297 @@
|
|
|
1
1
|
# PassControl
|
|
2
2
|
|
|
3
|
-
**
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
**Never paste a passport private key into a client's `api_key` field.** A passport is a signing
|
|
32
|
-
key, not a bearer token — a client that only stores a static string cannot sign a challenge, so
|
|
33
|
-
the call is refused and the key is exposed. Static-key clients take a Direct Agent Key or the
|
|
34
|
-
connector.
|
|
35
|
-
|
|
36
|
-

|
|
37
|
-
|
|
38
|
-
*Instant, per-agent revocation — the kill switch cuts off a live agent mid-run (`200 OK` → `403 BLOCKED`) and restores it, with no key rotation and no redeploy. Real traffic through the gateway; the status codes and timestamps are live.*
|
|
39
|
-
|
|
40
|
-
> ⚠️ **Status: early.** Built by a small team, **not yet independently audited.** It's
|
|
41
|
-
> security-focused and test-covered, but treat it as beta — run it against a **non-critical key
|
|
42
|
-
> first**, and see [Security](#security) for responsible disclosure. We'd rather you know than
|
|
43
|
-
> find out.
|
|
44
|
-
|
|
45
|
-
**New here?** The [Getting Started tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md) takes you from install to a real
|
|
46
|
-
governed agent in ~15 minutes.
|
|
47
|
-
|
|
48
|
-
```bash
|
|
49
|
-
npm install -g passcontrol
|
|
50
|
-
passcontrol login # approve once in your browser — this machine is set up
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
Nothing else to install: the npm package is the CLI, not the stack. `login` ends by making one
|
|
54
|
-
governed call and verifying its **signed receipt** against our published key, so you watch the
|
|
55
|
-
thing work rather than being told it does. Want a look first? The
|
|
56
|
-
[hosted demo](https://passcontrol.vertias.eu) runs the same pipeline in your browser, keyless.
|
|
57
|
-
|
|
58
|
-
Prefer to run the whole gateway yourself? `passcontrol setup` does that, and needs **Docker
|
|
59
|
-
Desktop, the Supabase CLI, and Node 18+** — see [Self-host](#self-host).
|
|
60
|
-
|
|
61
|
-
---
|
|
62
|
-
|
|
63
|
-
## Why
|
|
64
|
-
|
|
65
|
-
A raw provider key handed to an autonomous agent **leaks** (logs, repos, prompts), **never
|
|
66
|
-
rotates**, has **no per-agent spend cap**, **no off-switch**, and leaves **no record** of which
|
|
67
|
-
agent did what. PassControl takes the key out of the agent entirely and puts a governed gateway
|
|
68
|
-
in front of it.
|
|
69
|
-
|
|
70
|
-
## How it works
|
|
71
|
-
|
|
72
|
-
1. **Identity** — use a reveal-once Direct Agent Key in the provider-native SDK or compatible client, or a
|
|
73
|
-
passport whose Ed25519 private key only signs and never travels over the wire.
|
|
74
|
-
2. **Work-visa (passport mode)** — the agent signs a challenge (timestamp + single-use nonce) and mints a
|
|
75
|
-
short-lived (~5 min) token carrying its identity, scope, and budget snapshot.
|
|
76
|
-
3. **Inject & proxy** — a request arrives bearing a visa. The gateway verifies it → checks the
|
|
77
|
-
kill switch → checks scope (provider + model **and** endpoint) → reserves budget atomically →
|
|
78
|
-
pulls your provider key from the vault → injects it → forwards to the provider and streams
|
|
79
|
-
back. The agent never sees the key.
|
|
80
|
-
4. **Govern** — per-agent **token + dollar** budgets (enforced *before* the call), a layered kill
|
|
81
|
-
switch (platform / tenant / per-agent), and an append-only audit log of every call.
|
|
82
|
-
|
|
83
|
-
```
|
|
84
|
-
agent ──sign──▶ challenge ──visa──▶ ┌─────────── PassControl gateway ───────────┐
|
|
85
|
-
│ verify · kill/scope/budget · inject key │ ──▶ provider
|
|
86
|
-
(holds only a passport key) │ (real key from vault, never returned) │ ◀── stream
|
|
87
|
-
└────────────────────────────────────────────┘
|
|
3
|
+
PassControl **0.9.0** is an identity and credential gateway for AI agents. It keeps
|
|
4
|
+
provider API keys out of agent configuration and applies per-agent scopes, policies,
|
|
5
|
+
budgets, and stop controls before forwarding model requests.
|
|
6
|
+
|
|
7
|
+
Bring your own provider key. In **Cloud**, it is stored in the managed server-side
|
|
8
|
+
Supabase Vault. When **self-hosted**, you operate the gateway, Vault, database, and
|
|
9
|
+
Redis. In both cases the gateway decrypts and injects the provider key; the agent
|
|
10
|
+
receives the provider response, not that key. The gateway operator remains trusted:
|
|
11
|
+
this is credential isolation, not end-to-end encryption from the agent to the provider.
|
|
12
|
+
|
|
13
|
+
Built by one developer under [Vertias](https://vertias.eu). Early software, **not yet
|
|
14
|
+
independently audited**. Start with a non-critical provider key. Source-available
|
|
15
|
+
under [BSL 1.1](./LICENSE).
|
|
16
|
+
|
|
17
|
+
## Request and authentication flow
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
Direct Agent Key ───────────────────────────────────────────────┐
|
|
21
|
+
v
|
|
22
|
+
Passport private key ── signs challenge ──> short-lived visa ──> gateway
|
|
23
|
+
stays client-side + request proof |
|
|
24
|
+
when required |
|
|
25
|
+
authentication → kill/suspend → scope/policy → budget hold
|
|
26
|
+
|
|
|
27
|
+
Vault key → provider → response
|
|
28
|
+
|
|
|
29
|
+
settlement + best-effort log/receipt
|
|
88
30
|
```
|
|
89
31
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
32
|
+
A Passport private key never reaches Cloud or the gateway. It signs challenge bytes
|
|
33
|
+
locally to mint a work-visa; the sidecar also signs request proofs. Visas are
|
|
34
|
+
HS256 tokens, normally valid for five minutes (`VISA_TTL_SECONDS`: 300–900 seconds).
|
|
35
|
+
|
|
36
|
+
| Credential | What the client does | Boundary |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| **Direct Agent Key (DAK)** | Sends a named, reveal-once `pc_agent_…` bearer key | Bound to one agent; hash stored server-side, optional expiry, independently revocable. Works with static-key clients. Does not mint visas or authorize control-plane operations. |
|
|
39
|
+
| **Passport** | Holds an Ed25519 keypair and signs challenges for visas | Proves possession at mint. Private key stays in the SDK runtime, CLI, sidecar, or MCP process. |
|
|
40
|
+
| **Passport with required sender proof** | Sends a fresh signed proof with each visa-authenticated request | A stolen visa alone is insufficient. The proof binds method, gateway origin/path, time, nonce, and visa hash. |
|
|
41
|
+
| **Control key** | Sends `pc_…` to `/api/control/v1` | Manages the workspace; separate from either agent credential. Keep it out of agent integrations. |
|
|
42
|
+
|
|
43
|
+
Passport sender-proof modes are **off**, **observe**, and **required**. Off ignores
|
|
44
|
+
proofs; observe records what would pass without enforcing it; required rejects missing,
|
|
45
|
+
invalid, stale, or replayed proofs. Only enforced success is recorded as
|
|
46
|
+
`passport_proof_per_request`; observing a valid proof does not upgrade authentication.
|
|
47
|
+
The 0.9.0 sidecar supplies proofs; the direct CLI call, MCP chat, and TypeScript SDK
|
|
48
|
+
do not attach them and cannot use required mode without an additional proof implementation.
|
|
49
|
+
Proofs do **not** bind the request body or query string and do not attest hardware or
|
|
50
|
+
key storage. See [authentication and lifecycle](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md).
|
|
51
|
+
|
|
52
|
+
Passport expiry and rotation grace are checked at mint, not on every existing visa.
|
|
53
|
+
Use suspend/revoke or a kill switch to stop subsequent requests using issued visas;
|
|
54
|
+
these controls do not cancel an upstream request already in flight. Public lifecycle
|
|
55
|
+
checks and the signed [revocation list](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md)
|
|
56
|
+
are separate from signature verification.
|
|
57
|
+
|
|
58
|
+
## What the gateway enforces
|
|
59
|
+
|
|
60
|
+
- An allowlist of provider endpoints, plus the agent's provider/model scope.
|
|
61
|
+
- Live policy rules: model/endpoint denials, time windows, request limits; optional
|
|
62
|
+
shadow evaluation records candidate decisions without enforcing them.
|
|
63
|
+
- Token and cost admission limits through atomic reservations and settlement.
|
|
64
|
+
- Platform/tenant kill switches and per-agent suspension/revocation.
|
|
65
|
+
- Provider failover within supported request families and each attempt's authorization
|
|
66
|
+
and budget checks; it is not arbitrary API translation.
|
|
67
|
+
|
|
68
|
+
Passport scopes are snapshots in visas; scope edits can take up to the configured visa
|
|
69
|
+
TTL to replace those snapshots. Other live controls have their own cache/invalidation
|
|
70
|
+
behavior. Kill-state reads default to fail-open; `KILL_SWITCH_FAIL_CLOSED=true` blocks
|
|
71
|
+
on kill/suspend read failure. Required sender-proof replay checks and DAK credential
|
|
72
|
+
validation fail closed. Redis persistence and no-eviction configuration matter.
|
|
73
|
+
|
|
74
|
+
### Budgets under uncertainty
|
|
75
|
+
|
|
76
|
+
Admission reserves an **estimate**, not a provider invoice or a guaranteed upper bound.
|
|
77
|
+
Concurrent attempts consume reserved headroom. Complete usage settles measured tokens
|
|
78
|
+
and table-priced cost; actual usage can exceed the estimate and cap. Anthropic cache
|
|
79
|
+
reads/writes count toward token usage as well as their applicable price.
|
|
80
|
+
|
|
81
|
+
A broken stream, missing usage, or ambiguous dispatch is not assumed free. An uncertain
|
|
82
|
+
settlement retains at least the estimate (or higher observed usage); an attempt whose
|
|
83
|
+
ending never runs leaves an open hold that does not expire. `may_have_dispatched`
|
|
84
|
+
means dispatch permission was claimed, not that billing is proven. Such a hold cannot
|
|
85
|
+
be released as `not_spent` through recovery.
|
|
86
|
+
|
|
87
|
+
Lost or mismatched established budget generations cause `503 blocked_budget_state`,
|
|
88
|
+
not a fresh allowance. Recovery is an explicit operator action over retained logs and
|
|
89
|
+
adjustments; it cannot reconstruct missing evidence. See [Budget recovery](https://github.com/Vertias3u/PassControl/blob/main/docs/budget-recovery.md).
|
|
90
|
+
|
|
91
|
+
Prices are an in-code estimate table. Unknown models on built-in endpoints use a
|
|
92
|
+
provider fallback rate. **Custom endpoints are unpriced**, even when the model name
|
|
93
|
+
matches: logs mark cost unknown, receipts carry `unp`, and token accounting continues.
|
|
94
|
+
The cost budget retains a proxy estimate; it does not become knowledge of actual dollars.
|
|
95
|
+
Known/table-priced cost, conservative enforced spend, and open holds are different figures.
|
|
96
|
+
|
|
97
|
+
## Supported providers and endpoints
|
|
98
|
+
|
|
99
|
+
All paths below are relative to `/api/v1/<provider>`. SDK base URLs and aliases are in
|
|
100
|
+
[the endpoint reference](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md).
|
|
101
|
+
|
|
102
|
+
| Provider ID | Inference | Discovery |
|
|
103
|
+
|---|---|---|
|
|
104
|
+
| `openai` | Chat Completions and **POST Responses** | Models list/detail |
|
|
105
|
+
| `anthropic` | Messages | Models list/detail |
|
|
106
|
+
| `groq`, `mistral`, `together` | OpenAI-compatible Chat Completions | Models list/detail |
|
|
107
|
+
| `deepseek` | OpenAI-compatible Chat Completions | Not proxied |
|
|
108
|
+
| `gemini` | Google's **OpenAI-compatible** Chat Completions | Models list/detail |
|
|
109
|
+
|
|
110
|
+
Gemini's native `generateContent` API is not supported. Responses support is OpenAI-only;
|
|
111
|
+
response retrieval/deletion, embeddings, files, fine-tuning, batches, and token-counting
|
|
112
|
+
endpoints are not proxied. Model availability still depends on your provider account.
|
|
113
|
+
|
|
114
|
+
Custom provider base URLs support compatible deployments such as Ollama, vLLM, or
|
|
115
|
+
LiteLLM without adding provider IDs. They require operator opt-in:
|
|
116
|
+
`PROVIDER_ENDPOINT_MODE=selfhost` permits HTTP, private addresses, and custom ports;
|
|
117
|
+
a comma-separated hostname list permits only listed HTTPS hosts on port 443. Unset/off
|
|
118
|
+
refuses custom endpoints. Shape validation is **not full SSRF prevention**: it does not
|
|
119
|
+
resolve or pin DNS. Operators must control egress and trust the destination receiving
|
|
120
|
+
the provider credential. Upstream redirects are refused, never followed.
|
|
121
|
+
|
|
122
|
+
## Receipts, statements, and identity evidence
|
|
123
|
+
|
|
124
|
+
A signed call receipt records the issuer's decision, authentication method, reported
|
|
125
|
+
usage/cost, and (when read) a digest of client request bytes. It does not include the
|
|
126
|
+
provider response body. Verify it with an explicitly trusted issuer:
|
|
128
127
|
|
|
129
128
|
```bash
|
|
130
|
-
|
|
131
|
-
passcontrol login # opens your browser, you approve once, this machine is set up
|
|
129
|
+
passcontrol verify receipt "<jws>" --issuer https://your-gateway.example
|
|
132
130
|
```
|
|
133
131
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
132
|
+
The public `/.well-known/jwks.json` publishes instance verification keys;
|
|
133
|
+
[the hosted receipt verifier](https://passcontrol.vertias.eu/verify/receipt) and
|
|
134
|
+
`/verify/receipt` on your deployment check in the visitor's browser. A valid signature proves that key
|
|
135
|
+
signed those bytes. It does not prove the issuer is honest, the provider billed that
|
|
136
|
+
amount, or all calls were recorded. Logging/signing is best-effort; absent receipts
|
|
137
|
+
prove nothing. Retain old public keys for historical verification when rotating the
|
|
138
|
+
instance signer.
|
|
138
139
|
|
|
139
|
-
|
|
140
|
+
**Cloud signed spend statements** commit to a fixed set of receipts using a Merkle root
|
|
141
|
+
and link to a preceding statement. Inclusion proofs establish membership in that signed
|
|
142
|
+
set. They do not independently audit totals, completeness, or provider invoices. A chain
|
|
143
|
+
check needs the relevant earlier statements or a trusted checkpoint. The public self-host
|
|
144
|
+
tree ships the format and verification code/page, **not statement production, scheduling,
|
|
145
|
+
or statement/proof-serving routes**. See [statement format and limits](https://github.com/Vertias3u/PassControl/blob/main/docs/statement-format.md).
|
|
140
146
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
Your agent is live. Anyone can check that call for themselves:
|
|
147
|
-
passcontrol verify receipt eyJhbGc… --issuer https://passcontrol.vertias.eu
|
|
148
|
-
```
|
|
147
|
+
Owner binding is per workspace. A typed owner is a declaration; GitHub verification
|
|
148
|
+
checks publication of a token in a particular account's repository, and domain
|
|
149
|
+
verification checks a well-known HTTPS token. Neither proves a person's legal identity
|
|
150
|
+
or trustworthiness. Company registry evidence is also distinct from authority to represent
|
|
151
|
+
that company. Only published bindings are attached to public evidence.
|
|
149
152
|
|
|
150
|
-
|
|
151
|
-
stranger can verify offline against a public key, with no account and no access to your logs.
|
|
153
|
+

|
|
152
154
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
whoever sent it a key to your workspace.
|
|
155
|
+
The recording illustrates a stop control on successive calls; it does not show cancellation
|
|
156
|
+
of an already-dispatched stream.
|
|
156
157
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
```bash
|
|
160
|
-
passcontrol sidecar # holds the passport, mints visas, forwards to Cloud
|
|
161
|
-
passcontrol env openhands # ready-to-paste settings for your agent
|
|
162
|
-
```
|
|
158
|
+
## Try Cloud
|
|
163
159
|
|
|
164
|
-
|
|
165
|
-
|
|
160
|
+
[Request access to the free private beta](https://passcontrol.vertias.eu/beta), or try
|
|
161
|
+
[the keyless browser demo](https://passcontrol.vertias.eu). The demo synthesizes model
|
|
162
|
+
output; it does not exercise a billed provider.
|
|
166
163
|
|
|
167
|
-
|
|
168
|
-
provider/model with no browser, and plain environment variables work everywhere the config file
|
|
169
|
-
does.
|
|
170
|
-
|
|
171
|
-
**Want to run the whole thing yourself?** That is [Self-host](#self-host) below. `passcontrol
|
|
172
|
-
setup` is the self-host command, and it is the one that wants Docker and the Supabase CLI —
|
|
173
|
-
neither `login` nor the sidecar wants either.
|
|
174
|
-
|
|
175
|
-
> Working from a **source clone** instead of the global install? Everything below works as
|
|
176
|
-
> `npm run cli -- <command>`; after `npm link` in the clone, the short `passcontrol <command>` form
|
|
177
|
-
> works too.
|
|
178
|
-
|
|
179
|
-
## Claude Desktop, Cursor, and Claude Code via MCP
|
|
180
|
-
|
|
181
|
-
PassControl ships a local stdio MCP server. Store the passport once in the owner-only global
|
|
182
|
-
profile, then let the CLI merge a secret-free entry into your client config:
|
|
164
|
+
With Node installed:
|
|
183
165
|
|
|
184
166
|
```bash
|
|
185
|
-
|
|
186
|
-
passcontrol
|
|
187
|
-
# Claude Code: passcontrol configure claude-code prints its `claude mcp add` command
|
|
167
|
+
npm install -g passcontrol@0.9.0
|
|
168
|
+
passcontrol login
|
|
188
169
|
```
|
|
189
170
|
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
## Real agents & the passport connector
|
|
196
|
-
|
|
197
|
-
> **The connector is not self-hosting.** It is a small local signer — one foreground process,
|
|
198
|
-
> no Docker, no database — that holds your passport and talks to whichever gateway you configure,
|
|
199
|
-
> **including PassControl Cloud**. Running it is the same shape as running a cloud provider's
|
|
200
|
-
> local auth proxy: the control plane stays hosted, only the signing key stays yours.
|
|
201
|
-
>
|
|
202
|
-
> Pick by what your client can do, not by where the gateway lives:
|
|
203
|
-
>
|
|
204
|
-
> | Your client | Credential | Local process? |
|
|
205
|
-
> |---|---|---|
|
|
206
|
-
> | You control its JS/TS | **Passport** via [the SDK](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) | none |
|
|
207
|
-
> | Claude Desktop / Cursor / Claude Code | **Passport** via `passcontrol mcp` | the MCP server |
|
|
208
|
-
> | Takes only a base URL + API key | **Passport** via this connector | the connector |
|
|
209
|
-
> | Takes only a base URL + API key | **Direct Agent Key** — simplest | none |
|
|
210
|
-
>
|
|
211
|
-
> A Direct Agent Key is lower-assurance bearer possession, issued reveal-once from the dashboard
|
|
212
|
-
> and bound to one agent. It is the right default for a static-key tool. The connector is what you
|
|
213
|
-
> reach for when you want passport identity in that same tool — on Cloud or self-hosted alike.
|
|
214
|
-
|
|
215
|
-
A visa is deliberately short-lived so it's revocable — but a real coding agent runs a **long,
|
|
216
|
-
multi-call session** that would outlive a single visa. The **sidecar** solves this: a tiny local
|
|
217
|
-
proxy that mints, caches, and auto-refreshes the visa (and re-mints instantly on expiry), so your
|
|
218
|
-
agent points at one stable endpoint and **never times out mid-task**.
|
|
219
|
-
|
|
220
|
-
```bash
|
|
221
|
-
passcontrol sidecar # http://127.0.0.1:8788
|
|
222
|
-
passcontrol env openhands # prints ready-to-paste settings for your agent
|
|
223
|
-
```
|
|
171
|
+
Login prints a device code and opens browser approval. Enter only the code from your
|
|
172
|
+
own terminal: approval grants this machine a workspace control key. The CLI creates a
|
|
173
|
+
Passport locally, registers its public key, saves configuration, and attempts a keyless
|
|
174
|
+
governed call and receipt verification. That proof requires a gateway with demo and
|
|
175
|
+
signing enabled; it is not a real-provider test. See [the tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md).
|
|
224
176
|
|
|
225
|
-
|
|
177
|
+
Run **`passcontrol`** with no arguments in an interactive terminal to open the command
|
|
178
|
+
browser: searchable grouped commands, recent actions, and configuration-aware options.
|
|
179
|
+
Use `passcontrol --help` or explicit commands in scripts.
|
|
226
180
|
|
|
227
181
|
```bash
|
|
228
|
-
|
|
229
|
-
|
|
182
|
+
passcontrol status
|
|
183
|
+
passcontrol call "Say hello" # off/observe mode; real provider calls require a stored key
|
|
184
|
+
passcontrol doctor --deep
|
|
185
|
+
passcontrol key status
|
|
186
|
+
passcontrol key migrate # move an existing file key to the OS store
|
|
187
|
+
passcontrol logout
|
|
230
188
|
```
|
|
231
189
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
governed and is not. It also refuses every other host — it is not an open proxy — and
|
|
239
|
-
`--allow-connect <host>` names exceptions, which can never be a provider.
|
|
240
|
-
|
|
241
|
-
The agent never holds a real key or a long-lived token. Presets ship for coding agents
|
|
242
|
-
(**openhands, aider, cline, continue, litellm**), for the desktop chat apps you would otherwise
|
|
243
|
-
paste a raw provider key into (**chatbox, jan, msty, cherry-studio, open-webui, librechat**), and
|
|
244
|
-
a catch-all **generic** (`passcontrol env <preset>`). `passcontrol env` with an unknown name
|
|
245
|
-
prints the current list, which is generated — it cannot drift from what the CLI accepts. Also,
|
|
246
|
-
**[Hermes Agent](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md)** works through the generic settings with no custom
|
|
247
|
-
code. A single long streaming completion also works
|
|
248
|
-
directly — it's verified once at the start, so it finishes even if it runs past the visa TTL; only
|
|
249
|
-
*multi-call* sessions need the sidecar's refresh. Raise `VISA_TTL_SECONDS` (300–900) to widen the
|
|
250
|
-
window, but the sidecar is the real answer for long sessions.
|
|
251
|
-
|
|
252
|
-
> If a client defaults to OpenAI `/responses` (some Continue configs for o-series/gpt-5), force
|
|
253
|
-
> `/chat/completions` — PassControl intentionally proxies only chat/messages and model-listing
|
|
254
|
-
> endpoints.
|
|
255
|
-
|
|
256
|
-
## Signed call receipts
|
|
257
|
-
|
|
258
|
-
Your audit log convinces **you**. It convinces nobody else — you control that database.
|
|
259
|
-
|
|
260
|
-
A **receipt** is one call's record, signed with your deployment's Ed25519 key. Anyone can
|
|
261
|
-
check it with no account, no access to your database, and no cooperation from you. Approvals
|
|
262
|
-
and refusals are both signed; *"the gateway stopped this agent from touching that model,
|
|
263
|
-
here's the proof"* is often the more useful document.
|
|
190
|
+
The CLI supports macOS Keychain, Linux Secret Service (`secret-tool`), and Windows
|
|
191
|
+
DPAPI-backed storage. File configuration may contain a storage marker instead of the
|
|
192
|
+
Passport secret; explicit environment secrets take precedence. An unavailable OS store
|
|
193
|
+
can use an existing file fallback with a warning. Custody shown by the gateway is
|
|
194
|
+
**DECLARED evidence**, not proof of storage. The signer still reads key material into
|
|
195
|
+
process memory; this is not a non-exportable hardware key.
|
|
264
196
|
|
|
265
|
-
|
|
266
|
-
passcontrol keygen instance # generates INSTANCE_SIGNING_KEY; set PASSCONTROL_ISSUER too
|
|
267
|
-
```
|
|
197
|
+
## Connect a real agent
|
|
268
198
|
|
|
269
|
-
|
|
199
|
+
For example, the direct OpenAI configuration has this shape:
|
|
270
200
|
|
|
271
201
|
```bash
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
202
|
+
export OPENAI_BASE_URL=https://YOUR-PASSCONTROL-HOST/api/v1/openai/v1
|
|
203
|
+
export OPENAI_API_KEY=pc_agent_REVEAL_ONCE_VALUE
|
|
204
|
+
export OPENAI_MODEL=gpt-4o-mini
|
|
275
205
|
```
|
|
276
|
-
✓ Receipt is valid.
|
|
277
|
-
→ Issuer: http://localhost:3000
|
|
278
|
-
→ Passport: kZCFp7d2x4VDruiulJ21gogYbczBDAGZa-OuwR3qgh8
|
|
279
|
-
→ Call: POST chat/completions → demo/demo-1
|
|
280
|
-
→ Verdict: ok (HTTP 200)
|
|
281
|
-
→ Usage: 15 in / 46 out · 61 µ¢
|
|
282
|
-
→ Request: sha-256 VizsbKJwhtYoTNBv_XkJSf4ihWpdQWQfpXVvuDA6usM (105 bytes)
|
|
283
|
-
```
|
|
284
|
-
|
|
285
|
-
Change one character and it fails. No terminal? Your deployment serves a paste-and-check page
|
|
286
|
-
at **`/verify/receipt`** (including on the hosted demo) — verification runs in the visitor's browser, the receipt is never
|
|
287
|
-
uploaded, and the shareable link carries it in the URL fragment, which browsers never send to
|
|
288
|
-
a server.
|
|
289
|
-
|
|
290
|
-
**What it does and doesn't prove.** A valid signature means the named issuer signed this
|
|
291
|
-
record and nothing in it has changed. It does *not* vouch for the issuer — anyone can run
|
|
292
|
-
PassControl, so trusting it is the reader's call. It covers the **request and the gateway's
|
|
293
|
-
decision**, never the provider's reply. And the absence of a receipt proves nothing: receipt
|
|
294
|
-
writing is best-effort, so this is evidence, not a complete ledger.
|
|
295
|
-
|
|
296
|
-
> **Rotating the signing key is the one dangerous operation.** Receipts never expire, so
|
|
297
|
-
> replacing the key retroactively invalidates every receipt you have ever signed. Move the old
|
|
298
|
-
> seed to `INSTANCE_SIGNING_KEY_PREV` **first** — nothing is ever signed with it; it exists so
|
|
299
|
-
> its public half stays published. This is inverted relative to `VISA_SECRET_PREV`.
|
|
300
|
-
|
|
301
|
-
Full claim reference and the JWKS endpoint: [`DOCUMENTATION.md`](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md) ·
|
|
302
|
-
walkthrough: [`TUTORIAL.md`](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md).
|
|
303
206
|
|
|
304
|
-
|
|
207
|
+
Use your dashboard's actual values; Anthropic uses its native base URL and key variables.
|
|
208
|
+
Never paste a Passport private key into an API-key field.
|
|
305
209
|
|
|
306
|
-
|
|
210
|
+
Add a provider credential in the dashboard and give the agent a concrete model within
|
|
211
|
+
its scope and suitable budgets. Choose by what your client supports:
|
|
307
212
|
|
|
308
|
-
|
|
|
213
|
+
| Client | Integration |
|
|
309
214
|
|---|---|
|
|
310
|
-
|
|
|
311
|
-
|
|
|
312
|
-
|
|
|
313
|
-
|
|
|
314
|
-
| Compare CLI, gateway and database versions | `passcontrol version` |
|
|
315
|
-
| Make a governed model call | `passcontrol call "Summarize this"` |
|
|
316
|
-
| Run the local MCP server | `passcontrol mcp` |
|
|
317
|
-
| Run the auto-refreshing bridge for an agent | `passcontrol sidecar` |
|
|
318
|
-
| Print agent/MCP settings without writing | `passcontrol env openhands` · `passcontrol env claude-desktop` |
|
|
319
|
-
| List / create agents | `passcontrol agent list` · `passcontrol agent create billing-bot` |
|
|
320
|
-
| Suspend, resume, or revoke an agent | `passcontrol agent suspend <id>` |
|
|
321
|
-
| Inspect spend, logs, and audit history | `passcontrol spend` · `passcontrol logs` · `passcontrol audit` |
|
|
322
|
-
| Save / restore a workspace configuration snapshot | `passcontrol export --out workspace.json` · `passcontrol import workspace.json` (previews first; never overwrites an existing agent) |
|
|
323
|
-
| Generate this deployment's receipt signing key | `passcontrol keygen instance` |
|
|
324
|
-
| Check a receipt or agent token (no account needed) | `passcontrol verify receipt <jws> --issuer <origin>` |
|
|
325
|
-
| Arm / release the tenant kill switch | `passcontrol kill on` · `passcontrol kill off` |
|
|
326
|
-
| Prepare or repair local services | `passcontrol setup` · `passcontrol doctor --fix` |
|
|
327
|
-
| Start / stop the whole local stack | `passcontrol start` · `passcontrol stop` · `passcontrol restart` (add `--dashboard-only` to leave Supabase and Redis alone) |
|
|
328
|
-
| Follow local dashboard logs | `passcontrol local-logs --follow` |
|
|
329
|
-
| Point the CLI at a different checkout | `passcontrol setup --app-dir <path>` |
|
|
330
|
-
| Forget the remembered checkout | `passcontrol unlink` |
|
|
331
|
-
| Open the Control Tower | `passcontrol open` |
|
|
332
|
-
| Set up an integration (preview, or `--write`) | `passcontrol configure aider` · `passcontrol configure claude-desktop --write` |
|
|
333
|
-
|
|
334
|
-
`passcontrol stop` brings down the **whole** local stack — dashboard, Supabase, and Redis.
|
|
335
|
-
Use `--dashboard-only` to leave the services running. It never removes volumes, so your
|
|
336
|
-
Vault, passports, and audit log survive; wiping data stays with `reset` below.
|
|
337
|
-
|
|
338
|
-
Config resolves in order: **environment variables → project-local `.passcontrol` →
|
|
339
|
-
`~/.config/passcontrol/config`**. `.passcontrol` holds a passport secret, is gitignored, and is
|
|
340
|
-
written owner-only — never commit or share it.
|
|
341
|
-
|
|
342
|
-
The local stack itself lives in a checkout of this repo, not in the installed npm package.
|
|
343
|
-
The CLI resolves it in order: **`--app-dir <path>` → `PASSCONTROL_APP_ROOT` → the
|
|
344
|
-
surrounding checkout → the one it remembers** in `~/.config/passcontrol/app.json`.
|
|
345
|
-
`passcontrol status` shows which of those the current path came from. That remembered path
|
|
346
|
-
outlives `npm uninstall -g`, so if a fresh install keeps pointing at an old directory, clear
|
|
347
|
-
it with `passcontrol unlink` (or repoint with `--app-dir`).
|
|
348
|
-
|
|
349
|
-
`passcontrol reset --local --confirm RESET` destroys and recreates local data — use it only for a
|
|
350
|
-
clean slate.
|
|
351
|
-
|
|
352
|
-
## Using it from your own code
|
|
353
|
-
|
|
354
|
-
The client SDK exported at `passcontrol/sdk` hides the visa dance — point your provider SDK at the
|
|
355
|
-
gateway and visas auto-refresh:
|
|
356
|
-
|
|
357
|
-
```ts
|
|
358
|
-
import OpenAI from "openai";
|
|
359
|
-
import { PassControl } from "passcontrol/sdk";
|
|
360
|
-
|
|
361
|
-
const pc = new PassControl({ gateway, passportId, passportSecret });
|
|
362
|
-
const openai = new OpenAI(pc.clientOptions("openai")); // baseURL + auth wired; visas auto-refresh
|
|
363
|
-
```
|
|
364
|
-
|
|
365
|
-
Manage the fleet programmatically with the control-plane SDK + an API key:
|
|
366
|
-
|
|
367
|
-
```ts
|
|
368
|
-
import { ControlClient } from "passcontrol/sdk";
|
|
369
|
-
const cp = new ControlClient({ gateway, apiKey: process.env.PASSCONTROL_API_KEY! });
|
|
370
|
-
await cp.agents.list();
|
|
371
|
-
await cp.killSwitch.set(true);
|
|
372
|
-
```
|
|
373
|
-
|
|
374
|
-
Both credential-bearing clients enforce the same `gateway` boundary — a bare HTTPS origin, plain
|
|
375
|
-
HTTP only on loopback — and refuse anything else at construction, before any request.
|
|
376
|
-
|
|
377
|
-
The compiled ESM SDK ships with the current CLI release. Keep Passport secrets **and `pc_` control keys**
|
|
378
|
-
in trusted server runtimes, never browser-exposed variables. See the
|
|
379
|
-
[Cloud Passport SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md).
|
|
380
|
-
Full API reference: [`openapi.yaml`](https://github.com/Vertias3u/PassControl/blob/main/openapi.yaml) and [`DOCUMENTATION.md`](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md). Runnable example
|
|
381
|
-
agents live in [`examples/`](https://github.com/Vertias3u/PassControl/tree/main/examples).
|
|
382
|
-
|
|
383
|
-
## Self-host
|
|
384
|
-
|
|
385
|
-
Stack: **Next.js** (App Router, edge routes) · **Supabase** (Postgres + Vault + Auth) · **Upstash /
|
|
386
|
-
any Redis**. Deploy on Vercel, Cloudflare Workers through the tested OpenNext path, or any Node host
|
|
387
|
-
(`next start`). No Vercel-proprietary services are required — the kill switch is Redis-backed. See
|
|
388
|
-
[`docs/deployment/cloudflare.md`](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md) for the Cloud build, production
|
|
389
|
-
Auth/SMTP checklist, five-minute Cron Trigger, local `workerd` preview, and owner-only deploy handoff.
|
|
390
|
-
|
|
391
|
-
### Local (Docker) — the fastest path
|
|
215
|
+
| Static base URL + API key | Dashboard **Connect an agent**: copy its provider-native URL and DAK |
|
|
216
|
+
| Your JS/TS code | `PassControl` from `passcontrol/sdk`; [SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) |
|
|
217
|
+
| Static-key client needing Passport | `passcontrol sidecar`, then `passcontrol env <integration>` |
|
|
218
|
+
| MCP client | `passcontrol mcp`; configure as below |
|
|
392
219
|
|
|
393
220
|
```bash
|
|
394
|
-
|
|
395
|
-
passcontrol
|
|
396
|
-
|
|
221
|
+
# Passport bridge: talks to Cloud or your self-hosted gateway
|
|
222
|
+
passcontrol sidecar
|
|
223
|
+
passcontrol env hermes
|
|
397
224
|
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
version, free ports) and tells you exactly what to fix if something's missing.
|
|
402
|
-
|
|
403
|
-
- Change the checkout location: `--app-dir <path>` or `PASSCONTROL_APP_ROOT=<path>`
|
|
404
|
-
- Non-interactive: `--yes`
|
|
405
|
-
- Skip opening the browser: `--no-open`
|
|
406
|
-
- Ports already taken by another local Supabase? `passcontrol setup --port-offset 100`
|
|
407
|
-
(offsets Supabase + Redis together, e.g. API `54421`, DB `54422`; the dashboard stays on `:3000`)
|
|
408
|
-
|
|
409
|
-
During `dev:stack` the seed step (`scripts/seed.mjs`) asks you to **choose an account email
|
|
410
|
-
and password**. Then log in to the Control Tower at **http://localhost:3000** with those.
|
|
411
|
-
|
|
412
|
-
> ⚠️ **No shared default credentials ship**, on any install. The account you create guards the
|
|
413
|
-
> real provider keys in your local Vault — and the stack stops being localhost-only the moment
|
|
414
|
-
> you reach it from another device (Tailscale, LAN), so choose a real password. Non-interactive
|
|
415
|
-
> runs (CI, piped output) get a generated password printed once. Deployed installs create
|
|
416
|
-
> accounts through normal signup, gated by `INVITE_CODE`.
|
|
417
|
-
|
|
418
|
-
Add a **non-critical** provider key in the Control Tower, issue a passport, and copy the one-time
|
|
419
|
-
`PASSPORT_ID` / `PASSPORT_SECRET`. Then, in your project directory:
|
|
420
|
-
|
|
421
|
-
```bash
|
|
422
|
-
passcontrol init # gateway + passport + provider/model → writes .passcontrol
|
|
423
|
-
passcontrol doctor --deep # verifies config, prerequisites, and mints a test visa
|
|
424
|
-
passcontrol version # CLI vs gateway vs database schema, in one table
|
|
425
|
-
passcontrol call "Say hello in 3 words"
|
|
426
|
-
passcontrol spend # confirms governed spend
|
|
225
|
+
# MCP: global Passport configuration, no secret in generated client config
|
|
226
|
+
passcontrol configure claude-desktop --write
|
|
227
|
+
# Also: cursor; claude-code prints its client-managed add command
|
|
427
228
|
```
|
|
428
229
|
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
230
|
+
The sidecar listens on loopback by default and substitutes a visa for the client's dummy
|
|
231
|
+
API key. Treat access to that local listener as access to the configured agent. It is
|
|
232
|
+
not a sandbox against other processes running as you. Its provider CONNECT requests are
|
|
233
|
+
refused; use base URLs rather than TLS interception.
|
|
432
234
|
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
`passcontrol setup` (above) is the one-command route. Under the hood it runs the bundled Docker
|
|
438
|
-
stack: local Supabase (Postgres + Vault + Auth), Redis-over-REST, migrations applied inside the DB
|
|
439
|
-
container, and a seeded dev user. Prereqs: **Docker Desktop, the Supabase CLI, Node 18+** — no host
|
|
440
|
-
`psql` required.
|
|
441
|
-
|
|
442
|
-
From a source checkout you can drive the same thing directly:
|
|
443
|
-
|
|
444
|
-
```bash
|
|
445
|
-
git clone https://github.com/Vertias3u/PassControl && cd PassControl
|
|
446
|
-
npm install
|
|
447
|
-
npm run cli -- setup # or: passcontrol setup after `npm link`
|
|
448
|
-
```
|
|
235
|
+
Presets: `openhands`, `aider`, `cline`, `continue`, `litellm`, `hermes`, `chatbox`, `jan`,
|
|
236
|
+
`msty`, `cherry-studio`, `open-webui`, `librechat`, `generic`; MCP presets:
|
|
237
|
+
`claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
|
|
238
|
+
supported paths. [Hermes configuration](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
|
|
449
239
|
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
> **Supabase specifically** (not vanilla Postgres): the credential vault uses the `supabase_vault`
|
|
453
|
-
> extension, so you need a Supabase project — hosted or the self-hosted Supabase stack — not a
|
|
454
|
-
> plain Postgres database.
|
|
455
|
-
|
|
456
|
-
```bash
|
|
457
|
-
git clone https://github.com/Vertias3u/PassControl && cd PassControl
|
|
458
|
-
npm install
|
|
459
|
-
cp .env.example .env.local # fill in Supabase / Redis / secrets
|
|
460
|
-
DATABASE_URL='postgresql://…' npm run migrate # applies db/migrations/*.sql in order, once each
|
|
461
|
-
npm run dev # or build + `next start` on any Node host
|
|
462
|
-
```
|
|
463
|
-
|
|
464
|
-
See [`.env.example`](https://github.com/Vertias3u/PassControl/blob/main/.env.example) for the full config (Supabase URL/keys, `VISA_SECRET`,
|
|
465
|
-
`CACHE_ENC_KEY`, Redis, `CRON_SECRET`, `PASSCONTROL_SIGNUP_MODE`, `INVITE_CODE`). Apply migrations `0001 → …` in order;
|
|
466
|
-
[`db/tests/rls_invariants.sql`](https://github.com/Vertias3u/PassControl/blob/main/db/tests/rls_invariants.sql) checks tenant isolation and the
|
|
467
|
-
privileged-column locks on your database.
|
|
468
|
-
|
|
469
|
-
**Background reconcile job (required on non-Vercel hosts):** a periodic `GET /api/cron/reconcile`
|
|
470
|
-
(header `Authorization: Bearer $CRON_SECRET`) corrects budget drift and flushes last-seen. On
|
|
471
|
-
Vercel it's wired via `vercel.json`; elsewhere schedule it yourself (system `cron`, a GitHub
|
|
472
|
-
Action…) every few minutes. It's a correction layer, not the hot path — an occasional missed run is
|
|
473
|
-
harmless.
|
|
474
|
-
|
|
475
|
-
## Providers & endpoints
|
|
476
|
-
|
|
477
|
-
Supported providers: **OpenAI, Anthropic, Groq, Mistral, Together, DeepSeek**. The gateway proxies
|
|
478
|
-
**only chat and model-listing endpoints** — OpenAI-shaped chat completions + models, Anthropic
|
|
479
|
-
messages + models, DeepSeek chat completions. It does **not** proxy embeddings, files, fine-tuning,
|
|
480
|
-
batches, `/responses`, or token-counting endpoints (that's the point — a leaked visa can't reach
|
|
481
|
-
your full provider surface).
|
|
482
|
-
|
|
483
|
-
## Limitations
|
|
484
|
-
|
|
485
|
-
- A work-visa is a **bearer token**, reusable until it expires (≤5 min). Keep it out of logs and
|
|
486
|
-
prompts; use suspend/kill to block future requests immediately.
|
|
487
|
-
- **Pricing** is a best-effort in-code table and can lag provider price changes. Use it for budgets
|
|
488
|
-
and monitoring, not billing reconciliation against provider invoices.
|
|
489
|
-
- **Instant revocation** assumes Redis is configured for persistence / no-eviction. If Redis evicts
|
|
490
|
-
suspend/kill keys, enforcement falls back to short visa TTLs and the durable agent-status check at
|
|
491
|
-
the next mint.
|
|
492
|
-
|
|
493
|
-
## What the CLI sends, and where
|
|
494
|
-
|
|
495
|
-
No telemetry, no analytics, no usage reporting — none of this tool's operation is
|
|
496
|
-
reported anywhere. There is exactly **one** outbound request PassControl makes that
|
|
497
|
-
you did not ask for, and it is worth naming precisely rather than leaving you to
|
|
498
|
-
find it in a packet capture:
|
|
499
|
-
|
|
500
|
-
Once every 24 hours, `passcontrol` asks `registry.npmjs.org` for the latest published
|
|
501
|
-
version number so it can tell you when your install is old. It sends nothing but the
|
|
502
|
-
HTTP request itself — no identifiers, no configuration, no workspace or agent data.
|
|
503
|
-
It is skipped entirely when stdout is not a terminal (so it never fires inside an
|
|
504
|
-
agent run, a CI job, or a piped command), skipped under `--json`, and skipped when
|
|
505
|
-
`CI` is set.
|
|
240
|
+
## Self-host
|
|
506
241
|
|
|
507
|
-
|
|
242
|
+
The npm package contains the CLI and compiled SDK, not the application/database stack.
|
|
243
|
+
`passcontrol setup` obtains the public source and starts a local development stack.
|
|
244
|
+
It needs Git, Docker, the Supabase CLI, and Node/npm. The CLI package declares Node ≥18, but use **Node 22+ for the full stack**:
|
|
245
|
+
locked Supabase dependencies need ≥20 and Wrangler needs ≥22.
|
|
508
246
|
|
|
509
247
|
```bash
|
|
510
|
-
|
|
248
|
+
passcontrol setup --no-open
|
|
249
|
+
# Or from a source checkout:
|
|
250
|
+
git clone https://github.com/Vertias3u/PassControl.git
|
|
251
|
+
cd PassControl
|
|
252
|
+
npm ci
|
|
253
|
+
npm run dev:stack
|
|
254
|
+
npm run dev:docker
|
|
511
255
|
```
|
|
512
256
|
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
257
|
+
Local setup starts Supabase (Postgres + Auth + Vault) and Redis with a REST adapter,
|
|
258
|
+
applies migrations, and seeds a local account. It writes `.env.docker`; use
|
|
259
|
+
`npm run dev:docker` to load it. This is development setup, not a production deployment.
|
|
260
|
+
There are no shared default credentials. `passcontrol setup --app-dir <path>` selects a
|
|
261
|
+
checkout; `passcontrol unlink` forgets a remembered one.
|
|
262
|
+
|
|
263
|
+
For production, configure [`.env.example`](https://github.com/Vertias3u/PassControl/blob/main/.env.example), use Supabase (plain Postgres
|
|
264
|
+
is insufficient), apply the public migrations with `DATABASE_URL=… npm run migrate`,
|
|
265
|
+
and build/run the app. Supported paths are Next.js on Vercel, `npm run build` then
|
|
266
|
+
`npm start` on a Node host behind a trusted reverse proxy, and the
|
|
267
|
+
[Cloudflare/OpenNext build](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md). Configure Auth/SMTP,
|
|
268
|
+
secrets, backups, Redis persistence/no-eviction, and periodic authenticated
|
|
269
|
+
`GET /api/cron/reconcile`. A local successful boot does not validate production operations.
|
|
270
|
+
|
|
271
|
+
| Boundary | Cloud | Public self-host tree |
|
|
272
|
+
|---|---|---|
|
|
273
|
+
| Gateway, dashboard, auth, budgets, receipts, SDK | Managed deployment | Included; you operate them |
|
|
274
|
+
| Provider credentials and request processing | Managed infrastructure | Your infrastructure and chosen upstreams |
|
|
275
|
+
| Passport private key | Client-side | Client-side |
|
|
276
|
+
| Signed spend statement issuance/proof service | Hosted capability | Verification and format only |
|
|
277
|
+
| Invite workflow, hosted quotas and hosted-site operations | Cloud-specific | Not the hosted service |
|
|
278
|
+
|
|
279
|
+
Workspace portability: `passcontrol export --out workspace.json` saves configuration;
|
|
280
|
+
`passcontrol import workspace.json` previews it before an explicit import. The CLI path
|
|
281
|
+
does not migrate provider secrets or manufacture verified owner identity. Treat exports
|
|
282
|
+
as sensitive configuration and inspect the result for partial/refused items.
|
|
283
|
+
|
|
284
|
+
[Release updates](https://passcontrol.vertias.eu/updates) and the
|
|
285
|
+
[learning center](https://passcontrol.vertias.eu/learn) are hosted-site resources.
|
|
286
|
+
|
|
287
|
+
## Limits and security status
|
|
288
|
+
|
|
289
|
+
PassControl governs requests routed through it. It cannot prevent an agent from using
|
|
290
|
+
another credential or network path, secure a compromised signer, guarantee a provider's
|
|
291
|
+
usage report, or make an issuer's assertions independently true. Short visas, stop controls,
|
|
292
|
+
pricing tables, and best-effort logs each have the limits described above.
|
|
293
|
+
|
|
294
|
+
Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/Vertias3u/PassControl/security/advisories/new).
|
|
295
|
+
See [SECURITY.md](https://github.com/Vertias3u/PassControl/blob/main/SECURITY.md), [API documentation](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md), and
|
|
296
|
+
[contributing](https://github.com/Vertias3u/PassControl/blob/main/CONTRIBUTING.md). No independent audit or production assurance is implied
|
|
297
|
+
by the test suite. Read [LICENSE](./LICENSE) for the actual usage terms.
|