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 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 Vertias.
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. Give each agent a cryptographic **passport**; it signs a challenge to
5
- mint a short-lived **work-visa**; the gateway injects your *real* provider key from a vault
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 use the managed version when it's available.
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. **Passport** — each agent holds only an Ed25519 private key; it *only ever signs*, never travels.
26
- 2. **Work-visa** — the agent signs a challenge (timestamp + single-use nonce) → mints a
27
- short-lived (5 min) HS256 token carrying its identity, scope, and budget.
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
- - 🖥️ Control Tower dashboard + a developer control-plane API + TOTP MFA
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 or any Node host (`next start`). No Vercel-proprietary
55
- services are required — the kill switch is Redis-backed.
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/<you>/passcontrol && cd passcontrol
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/<you>/passcontrol && cd passcontrol
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, issue a passport, and run:
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/<you>/passcontrol && cd passcontrol
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
- The client SDK hides the visa dance — point your provider SDK at the gateway:
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 "./sdk";
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 SDK is vendored in this repo under `./sdk`; it is not a separately published npm package
161
- yet.
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
- Full API reference: [`openapi.yaml`](./openapi.yaml) and [`DOCUMENTATION.md`](./DOCUMENTATION.md).
173
- Runnable example agents in [`examples/`](./examples).
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 (≤5 minutes). Keep it out
197
- of logs and prompts; use suspend/kill switches to block future requests.
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