passcontrol 0.5.3 → 0.6.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/LICENSE +2 -2
- package/README.md +90 -22
- package/bin/passcontrol.mjs +238 -71
- package/cli/config.mjs +95 -0
- package/cli/mcp/gateway.mjs +4 -4
- package/cli/presets.mjs +1 -0
- package/cli/sidecar.mjs +7 -3
- package/cli/visa-client.mjs +10 -2
- package/package.json +11 -3
- package/sdk/README.md +152 -0
- package/sdk/control.d.ts +103 -0
- package/sdk/control.js +102 -0
- package/sdk/gateway.d.ts +22 -0
- package/sdk/gateway.js +66 -0
- package/sdk/index.d.ts +6 -0
- package/sdk/index.js +20 -0
- package/sdk/passcontrol.d.ts +47 -0
- package/sdk/passcontrol.js +197 -0
- package/sdk/verify.d.ts +182 -0
- package/sdk/verify.js +238 -0
package/LICENSE
CHANGED
|
@@ -7,9 +7,9 @@ License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
|
|
|
7
7
|
|
|
8
8
|
Parameters
|
|
9
9
|
|
|
10
|
-
Licensor: Vertias
|
|
10
|
+
Licensor: Kristiyan Ivanov, operating under the Vertias name
|
|
11
11
|
Licensed Work: PassControl
|
|
12
|
-
The Licensed Work is © 2026
|
|
12
|
+
The Licensed Work is © 2026 Kristiyan Ivanov.
|
|
13
13
|
Additional Use Grant: You may make production use of the Licensed Work, provided
|
|
14
14
|
that you do not offer the Licensed Work to third parties as
|
|
15
15
|
a hosted or managed service that provides, in whole or in
|
package/README.md
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
# PassControl
|
|
2
2
|
|
|
3
3
|
**An identity & credential gateway for AI agents.** Stop pasting your OpenAI/Anthropic keys
|
|
4
|
-
into agent runtimes.
|
|
5
|
-
|
|
4
|
+
into agent runtimes. Start with a named, revocable **Direct Agent Key**, or give a
|
|
5
|
+
higher-assurance agent a cryptographic **passport** that signs challenges for short-lived
|
|
6
|
+
**work-visas**. The gateway injects your *real* provider key from a vault
|
|
6
7
|
and proxies the call — so the agent never holds the key. You get per-agent budgets, scopes,
|
|
7
8
|
an instant kill switch, and a per-agent audit trail.
|
|
8
9
|
|
|
9
10
|
A [Vertias](https://vertias.eu) project. **Bring-your-own-key** (you keep your provider key);
|
|
10
|
-
self-host it, or
|
|
11
|
+
self-host it, or [request access](https://passcontrol.vertias.eu/beta) to the free Cloud private beta.
|
|
11
12
|
|
|
12
13
|
> ⚠️ **Status: early.** Built by a small team, **not yet independently audited.** It's
|
|
13
14
|
> security-focused and test-covered, but treat it as beta — run it on a non-critical key
|
|
@@ -22,9 +23,10 @@ has no per-agent spend cap, no off-switch, and no record of *which* agent did *w
|
|
|
22
23
|
PassControl removes the key from the agent entirely and puts a governed gateway in front.
|
|
23
24
|
|
|
24
25
|
## How it works
|
|
25
|
-
1. **
|
|
26
|
-
|
|
27
|
-
|
|
26
|
+
1. **Identity** — paste a reveal-once Direct Agent Key into the provider-native SDK or compatible client,
|
|
27
|
+
or use an Ed25519 passport whose private key only signs and never travels.
|
|
28
|
+
2. **Work-visa (passport mode)** — the agent signs a challenge (timestamp + single-use nonce) → mints a
|
|
29
|
+
short-lived (5 minutes by default) HS256 token carrying its identity, scope, and budget.
|
|
28
30
|
3. **Inject & proxy** — a request arrives with a visa; the gateway verifies it → checks the
|
|
29
31
|
kill switch → checks scope → reserves budget → pulls your provider key from Supabase Vault
|
|
30
32
|
→ injects it → forwards to the provider and streams back. The agent never sees the key.
|
|
@@ -34,6 +36,8 @@ PassControl removes the key from the agent entirely and puts a governed gateway
|
|
|
34
36
|
## Features
|
|
35
37
|
- 🔑 Agents never hold your provider key (BYOK; key stays in the vault, injected in-flight)
|
|
36
38
|
- 🪪 Per-agent cryptographic identity (Ed25519), short-lived revocable visas
|
|
39
|
+
- 🔌 Direct Agent Keys — named, independently revocable installation credentials for a
|
|
40
|
+
90-second provider-native Cloud on-ramp; receipts label this lower-assurance mode honestly
|
|
37
41
|
- 💸 Enforced per-agent token/cost budgets (reserved pre-flight, reconciled after)
|
|
38
42
|
- ⛔ Layered, per-tenant kill switch + per-agent suspend
|
|
39
43
|
- 📒 Per-agent / per-passport audit trail (append-only; direct `UPDATE` / `DELETE` /
|
|
@@ -47,12 +51,33 @@ PassControl removes the key from the agent entirely and puts a governed gateway
|
|
|
47
51
|
Claude Code — same scope, budget, and kill switch (`passcontrol mcp`)
|
|
48
52
|
- 🪪 Agent passport page — per-agent identity document: key-derived sigil, allowed scopes,
|
|
49
53
|
providers actually reached, budget state, exportable (redacted) PNG
|
|
50
|
-
-
|
|
54
|
+
- 🧭 Policy rules — deny by model or endpoint, restrict to time windows, cap requests per
|
|
55
|
+
hour; evaluated at the gateway *before* your provider key is ever resolved
|
|
56
|
+
- 🧪 Policy shadow mode — run a candidate policy against real traffic without enforcing it,
|
|
57
|
+
see where it would have diverged from the live one, then promote the exact draft you tested
|
|
58
|
+
- 🔄 Passport rotation & expiry — rotate a key with a grace window where both keys work, or
|
|
59
|
+
with no window at all if it leaked; set an expiry that's enforced when a visa is minted
|
|
60
|
+
- 🚨 Break-glass elevation — widen an agent's scope deliberately, for a bounded window (max
|
|
61
|
+
1 hour), with a mandatory reason, an audit row, and a security alert. It widens **scope
|
|
62
|
+
only**: kill switch, suspend, policy denials and budgets all still apply
|
|
63
|
+
- 🕓 Capability-change history — what changed on an agent, what it changed *from*, and
|
|
64
|
+
whether it came from the dashboard or the API
|
|
65
|
+
- 🏷️ Owner binding — bind a fleet to a domain you prove you control (HTTPS well-known
|
|
66
|
+
challenge), and optionally publish it, so a signed receipt can say *whose* agent called
|
|
67
|
+
- 🔀 Provider failover — an ordered fallback list per agent, applied inside the same
|
|
68
|
+
governed call
|
|
69
|
+
- 🖥️ Control Tower dashboard — an attention queue ranking the fleet by budget risk, expiry,
|
|
70
|
+
refusals and inactivity; a call-detail drawer over the stored audit row; before/after
|
|
71
|
+
previews on every consequential save; and a persistent indicator while any agent is
|
|
72
|
+
elevated. Plus a developer control-plane API and TOTP MFA
|
|
51
73
|
|
|
52
74
|
## Quickstart (self-host)
|
|
53
75
|
Stack: **Next.js** (App Router, edge routes) · **Supabase** (Postgres + Vault + Auth) ·
|
|
54
|
-
**Upstash Redis**. Deploy on Vercel
|
|
55
|
-
services are required — the kill switch is
|
|
76
|
+
**Upstash Redis**. Deploy on Vercel, Cloudflare Workers through the tested OpenNext path, or any
|
|
77
|
+
Node host (`next start`). No Vercel-proprietary services are required — the kill switch is
|
|
78
|
+
Redis-backed. See [`docs/deployment/cloudflare.md`](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md) for the Cloud
|
|
79
|
+
build, production Auth/SMTP checklist, five-minute Cron Trigger, local `workerd` preview, and the
|
|
80
|
+
explicit owner-only deploy handoff.
|
|
56
81
|
|
|
57
82
|
### See it work in 60 seconds — nothing to install
|
|
58
83
|
|
|
@@ -71,7 +96,7 @@ install — **prereqs: Docker Desktop and the Supabase CLI**, and the first stac
|
|
|
71
96
|
a few minutes:
|
|
72
97
|
|
|
73
98
|
```bash
|
|
74
|
-
git clone https://github.com
|
|
99
|
+
git clone https://github.com/Vertias3u/PassControl.git && cd PassControl
|
|
75
100
|
npm install
|
|
76
101
|
PASSCONTROL_DEMO=1 npm run dev:stack # local stack + a keyless demo passport
|
|
77
102
|
PASSCONTROL_DEMO=1 npm run dev:docker & # run the gateway with demo mode on
|
|
@@ -91,7 +116,7 @@ prompts you to create your Control Tower account. Prereqs: Docker Desktop and th
|
|
|
91
116
|
CLI. No host `psql` is required.
|
|
92
117
|
|
|
93
118
|
```bash
|
|
94
|
-
git clone https://github.com
|
|
119
|
+
git clone https://github.com/Vertias3u/PassControl.git && cd PassControl
|
|
95
120
|
npm install
|
|
96
121
|
npm run dev:stack # starts Supabase + Redis locally, migrates, creates your account
|
|
97
122
|
npm run dev:docker # runs the app against the local stack (loads .env.docker)
|
|
@@ -107,7 +132,10 @@ guards the provider keys in your local Vault, so pick a real password. Open
|
|
|
107
132
|
> No shared default credentials ship. If the stack was brought up without a terminal
|
|
108
133
|
> attached (CI, piped output), a password is generated and printed once by the seed step.
|
|
109
134
|
|
|
110
|
-
Then add a provider key in the Control Tower
|
|
135
|
+
Then add a provider key in the Control Tower. The fastest route is **Connect an agent**:
|
|
136
|
+
copy the generated provider-native base URL and reveal-once Direct Agent Key into the
|
|
137
|
+
matching SDK or compatible client. For higher-assurance challenge-response identity, issue a passport
|
|
138
|
+
and run:
|
|
111
139
|
|
|
112
140
|
```bash
|
|
113
141
|
PASSPORT_ID=<passport_id> PASSPORT_SECRET=<passport_secret> \
|
|
@@ -130,14 +158,14 @@ with a non-critical key.
|
|
|
130
158
|
> Supabase stack), not a plain Postgres database.
|
|
131
159
|
|
|
132
160
|
```bash
|
|
133
|
-
git clone https://github.com
|
|
161
|
+
git clone https://github.com/Vertias3u/PassControl.git && cd PassControl
|
|
134
162
|
npm install
|
|
135
163
|
cp .env.example .env.local # fill in Supabase / Upstash / secrets
|
|
136
164
|
DATABASE_URL='postgresql://…' npm run migrate # applies db/migrations/*.sql in order, once each
|
|
137
165
|
npm run dev # or build + `next start` on any Node host
|
|
138
166
|
```
|
|
139
167
|
See `.env.example` for the full config (Supabase URL/keys, `VISA_SECRET`, `CACHE_ENC_KEY`,
|
|
140
|
-
Upstash, `CRON_SECRET`, `INVITE_CODE`). Apply migrations `0001 → …` in order;
|
|
168
|
+
Upstash, `CRON_SECRET`, `PASSCONTROL_SIGNUP_MODE`, `INVITE_CODE`). Apply migrations `0001 → …` in order;
|
|
141
169
|
`db/tests/rls_invariants.sql` checks tenant isolation on your database.
|
|
142
170
|
|
|
143
171
|
**Background reconcile job (required on non-Vercel hosts):** a periodic call to
|
|
@@ -147,18 +175,41 @@ yourself (system `cron`, a GitHub Action, etc.) every few minutes — it's a cor
|
|
|
147
175
|
not the hot path, so an occasional missed run is harmless.
|
|
148
176
|
|
|
149
177
|
## Using it from an agent
|
|
150
|
-
|
|
178
|
+
For the generic Direct Agent Key path, use the values the dashboard shows once:
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
export OPENAI_BASE_URL=https://YOUR-PASSCONTROL-HOST/api/v1/openai/v1
|
|
182
|
+
export OPENAI_API_KEY=pc_agent_REVEAL_ONCE_VALUE
|
|
183
|
+
export OPENAI_MODEL=gpt-5
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
For Anthropic's native SDK, the same wizard instead emits
|
|
187
|
+
`ANTHROPIC_BASE_URL=https://YOUR-PASSCONTROL-HOST/api/v1/anthropic`,
|
|
188
|
+
`ANTHROPIC_API_KEY`, and a concrete `ANTHROPIC_MODEL`. Authorization wildcard patterns
|
|
189
|
+
such as `gpt-*` or `claude-*` are never copied into the SDK's model field.
|
|
190
|
+
|
|
191
|
+
That key is not a passport and never becomes one in receipts. It is still bound to the
|
|
192
|
+
agent's live scopes, policy, budgets, suspension, and kill switches. Add a signing passport
|
|
193
|
+
later without replacing the agent ID or history.
|
|
194
|
+
|
|
195
|
+
Hermes Agent uses its current `model.provider: custom` configuration, not the removed legacy
|
|
196
|
+
base-URL environment variables. Cloud users copy the exact YAML from **Connect an agent**;
|
|
197
|
+
self-hosted passport users run `passcontrol env hermes`. See
|
|
198
|
+
[`docs/integrations/hermes.md`](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
|
|
199
|
+
|
|
200
|
+
For passport mode, the client SDK hides the visa dance:
|
|
151
201
|
|
|
152
202
|
```ts
|
|
153
203
|
import OpenAI from "openai";
|
|
154
|
-
import { PassControl } from "
|
|
204
|
+
import { PassControl } from "passcontrol/sdk";
|
|
155
205
|
|
|
156
206
|
const pc = new PassControl({ gateway, passportId, passportSecret });
|
|
157
207
|
const openai = new OpenAI(pc.clientOptions("openai")); // baseURL + auth wired; visas auto-refresh
|
|
158
208
|
```
|
|
159
209
|
|
|
160
|
-
The
|
|
161
|
-
|
|
210
|
+
The compiled ESM SDK ships at `passcontrol/sdk` in npm version 0.6.0. Keep the Passport secret
|
|
211
|
+
in a trusted agent runtime; never place it in a browser-exposed environment variable. See the
|
|
212
|
+
[Cloud Passport SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md).
|
|
162
213
|
|
|
163
214
|
Manage the fleet programmatically with the control-plane SDK + API key:
|
|
164
215
|
|
|
@@ -169,8 +220,13 @@ await cp.agents.list();
|
|
|
169
220
|
await cp.killSwitch.set(true);
|
|
170
221
|
```
|
|
171
222
|
|
|
172
|
-
|
|
173
|
-
|
|
223
|
+
Both credential-bearing clients enforce the same `gateway` boundary — a bare HTTPS origin, plain
|
|
224
|
+
HTTP only on loopback — and refuse anything else at construction, before any request. The `pc_`
|
|
225
|
+
key manages the whole fleet, so like the Passport secret it stays server-side and never reaches a
|
|
226
|
+
browser bundle.
|
|
227
|
+
|
|
228
|
+
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).
|
|
229
|
+
Runnable example agents in [`examples/`](https://github.com/Vertias3u/PassControl/tree/main/examples).
|
|
174
230
|
|
|
175
231
|
## Use it from Claude Desktop, Cursor, or Claude Code (MCP)
|
|
176
232
|
`passcontrol mcp` runs a local [MCP](https://modelcontextprotocol.io) server that exposes two
|
|
@@ -193,8 +249,20 @@ tool and the call is governed end-to-end — arm the kill switch and the next to
|
|
|
193
249
|
refused. Run `passcontrol env claude-desktop` to preview the config without writing it.
|
|
194
250
|
|
|
195
251
|
## Limitations
|
|
196
|
-
- A work-visa is a bearer token and is reusable until it expires
|
|
197
|
-
of logs and prompts; use
|
|
252
|
+
- A work-visa is a bearer token and is reusable until it expires — 5 minutes by default,
|
|
253
|
+
configurable up to 15 via `VISA_TTL_SECONDS`. Keep it out of logs and prompts; use
|
|
254
|
+
suspend/kill switches to block future requests.
|
|
255
|
+
- Passport expiry is checked when a visa is **minted**, not on every proxied call, so a
|
|
256
|
+
passport that lapses mid-visa keeps working until that visa runs out. Suspend the agent
|
|
257
|
+
if you need it stopped now.
|
|
258
|
+
- Shadow-mode counts are a **floor, not a census.** The audit write is best-effort by
|
|
259
|
+
design, so a database blip loses the row and the shadow verdict with it. Calls logged
|
|
260
|
+
before the current draft was last edited are excluded rather than misattributed to it.
|
|
261
|
+
- Break-glass widens **scope and nothing else.** To get past a deny rule, change the deny
|
|
262
|
+
rule — that is a reviewable act, and break-glass deliberately isn't a way around it.
|
|
263
|
+
- An owner binding that is only a typed name is **self-attested, and the UI says so.** Only
|
|
264
|
+
the domain-verified tier means anything was actually checked, and a binding that stops
|
|
265
|
+
confirming is demoted rather than silently kept.
|
|
198
266
|
- The gateway proxies only chat and model-listing endpoints: OpenAI/Groq/Mistral/Together
|
|
199
267
|
chat completions and models, Anthropic messages and models, and DeepSeek chat
|
|
200
268
|
completions. It does **not** proxy embeddings, files, fine-tuning, batches, responses, or
|