passcontrol 0.1.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 ADDED
@@ -0,0 +1,92 @@
1
+ Business Source License 1.1
2
+
3
+ License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
4
+ "Business Source License" is a trademark of MariaDB Corporation Ab.
5
+
6
+ -----------------------------------------------------------------------------
7
+
8
+ Parameters
9
+
10
+ Licensor: Vertias
11
+ Licensed Work: PassControl
12
+ The Licensed Work is © 2026 Vertias.
13
+ Additional Use Grant: You may make production use of the Licensed Work, provided
14
+ that you do not offer the Licensed Work to third parties as
15
+ a hosted or managed service that provides, in whole or in
16
+ substantial part, the features or functionality of the
17
+ Licensed Work, and that competes with any paid product or
18
+ service offered by the Licensor.
19
+ Change Date: 2030-06-22
20
+ Change License: Apache License, Version 2.0
21
+
22
+ For information about alternative licensing arrangements for the Licensed Work,
23
+ please contact licensing@vertias.eu.
24
+
25
+ -----------------------------------------------------------------------------
26
+
27
+ Terms
28
+
29
+ The Licensor hereby grants you the right to copy, modify, create derivative
30
+ works, redistribute, and make non-production use of the Licensed Work. The
31
+ Licensor may make an Additional Use Grant, above, permitting limited
32
+ production use.
33
+
34
+ Effective on the Change Date, or the fourth anniversary of the first publicly
35
+ available distribution of a specific version of the Licensed Work under this
36
+ License, whichever comes first, the Licensor hereby grants you rights under
37
+ the terms of the Change License, and the rights granted in the paragraph
38
+ above terminate.
39
+
40
+ If your use of the Licensed Work does not comply with the requirements
41
+ currently in effect as described in this License, you must purchase a
42
+ commercial license from the Licensor, its affiliated entities, or authorized
43
+ resellers, or you must refrain from using the Licensed Work.
44
+
45
+ All copies of the original and modified Licensed Work, and derivative works
46
+ of the Licensed Work, are subject to this License. This License applies
47
+ separately for each version of the Licensed Work and the Change Date may vary
48
+ for each version of the Licensed Work released by Licensor.
49
+
50
+ You must conspicuously display this License on each original or modified copy
51
+ of the Licensed Work. If you receive the Licensed Work in original or
52
+ modified form from a third party, the terms and conditions set forth in this
53
+ License apply to your use of that work.
54
+
55
+ Any use of the Licensed Work in violation of this License will automatically
56
+ terminate your rights under this License for the current and all other
57
+ versions of the Licensed Work.
58
+
59
+ This License does not grant you any right in any trademark or logo of
60
+ Licensor or its affiliates (provided that you may use a trademark or logo of
61
+ Licensor as expressly required by this License).
62
+
63
+ TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
64
+ AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
65
+ EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
66
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
67
+ TITLE.
68
+
69
+ MariaDB hereby grants you permission to use this License’s text to license
70
+ your works, and to refer to it using the trademark “Business Source License”,
71
+ as long as you comply with the Covenants of Licensor below.
72
+
73
+ Covenants of Licensor
74
+
75
+ In consideration of the right to use this License’s text and the “Business
76
+ Source License” name and trademark, Licensor covenants to MariaDB, and to all
77
+ other recipients of the licensed work to be provided by Licensor:
78
+
79
+ 1. To specify as the Change License the GPL Version 2.0 or any later version,
80
+ or a license that is compatible with GPL Version 2.0 or a later version,
81
+ where “compatible” means that software provided under the Change License can
82
+ be included in a program with software provided under GPL Version 2.0 or a
83
+ later version. Licensor may specify additional Change Licenses without
84
+ limitation.
85
+
86
+ 2. To either: (a) specify an additional grant of rights to use that does not
87
+ impose any additional restriction on the right granted in this License, as
88
+ the Additional Use Grant; or (b) insert the text “None”.
89
+
90
+ 3. To specify a Change Date.
91
+
92
+ 4. Not to modify this License in any other way.
package/README.md ADDED
@@ -0,0 +1,281 @@
1
+ # PassControl
2
+
3
+ **An identity & credential gateway for AI agents.** Stop pasting your OpenAI / Anthropic /
4
+ Groq / Mistral / Together / DeepSeek keys 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
6
+ and proxies the call — so the agent never holds the key. You get per-agent budgets, scopes,
7
+ an instant kill switch, and a per-agent audit trail.
8
+
9
+ 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
+
12
+ > ⚠️ **Status: early.** Built by a small team, **not yet independently audited.** It's
13
+ > security-focused and test-covered, but treat it as beta — run it on a non-critical key
14
+ > first, and see [Security](#security) for responsible disclosure. We'd rather you know than
15
+ > find out.
16
+
17
+ **New here? Start with the [Getting Started tutorial](./TUTORIAL.md)** — clone to a real
18
+ governed agent in ~15 minutes.
19
+
20
+ ---
21
+
22
+ ## The `passcontrol` CLI
23
+
24
+ PassControl pairs the browser-based **Control Tower** (where you add a provider key and issue a
25
+ passport) with a terminal **CLI** (where you configure agents, make governed calls, run a
26
+ sidecar, inspect spend/logs, and control a fleet).
27
+
28
+ ## Install
29
+
30
+ **Fastest — install the CLI globally:**
31
+
32
+ ```bash
33
+ npm install -g passcontrol
34
+ passcontrol setup # offers to fetch the local stack, then boots it and opens the dashboard
35
+ ```
36
+
37
+ The published package is just the CLI (a few files, no provider keys). `passcontrol setup`
38
+ detects it's installed globally and offers to clone the self-hostable stack (Supabase + Redis +
39
+ dashboard) into `~/passcontrol`, install its dependencies, and start it — so a single command
40
+ takes you from nothing to a running Control Tower. Override the location with `--app-dir <path>`
41
+ or the `PASSCONTROL_APP_ROOT` environment variable, and pass `--yes` for non-interactive setups.
42
+
43
+ **From a source checkout** (if you'd rather clone yourself), run the CLI with `npm run cli -- <command>`.
44
+ The short `passcontrol <command>` form also works inside a clone after `npm link`:
45
+
46
+ ```bash
47
+ git clone https://github.com/Vertias3u/PassControl.git
48
+ cd PassControl && npm install
49
+ npm run cli -- --help # every command
50
+ npm run cli -- setup # boots the local stack from this checkout
51
+ ```
52
+
53
+ ## Why
54
+ A raw provider key handed to an autonomous agent leaks (logs, repos, prompts), never rotates,
55
+ has no per-agent spend cap, no off-switch, and no record of *which* agent did *what*.
56
+ PassControl removes the key from the agent entirely and puts a governed gateway in front.
57
+
58
+ ## How it works
59
+ 1. **Passport** — each agent holds only an Ed25519 private key; it *only ever signs*, never travels.
60
+ 2. **Work-visa** — the agent signs a challenge (timestamp + single-use nonce) → mints a
61
+ short-lived (5 min) HS256 token carrying its identity, scope, and budget.
62
+ 3. **Inject & proxy** — a request arrives with a visa; the gateway verifies it → checks the
63
+ kill switch → checks scope (provider + model **and** endpoint) → reserves budget → pulls
64
+ your provider key from Supabase Vault → injects it → forwards to the provider and streams
65
+ back. The agent never sees the key.
66
+ 4. **Govern** — per-agent token **and dollar** budgets (enforced pre-flight), a layered kill
67
+ switch (platform / tenant / per-agent), and an append-only audit log of every call.
68
+
69
+ ## Features
70
+ - 🔑 Agents never hold your provider key (BYOK; key stays in the vault, injected in-flight)
71
+ - 🪪 Per-agent cryptographic identity (Ed25519), short-lived revocable visas
72
+ - 💸 Enforced per-agent **token + cost (USD)** budgets — reserved pre-flight, reconciled after
73
+ - 🎯 **Capability scoping** — a visa is scoped to specific models *and* endpoints, so a
74
+ chat-scoped agent can't reach files, fine-tuning, batches, responses, embeddings, etc.
75
+ with your key
76
+ - ⛔ Layered, per-tenant kill switch + per-agent suspend — revoke a running agent mid-task
77
+ - 📒 Per-agent / per-passport audit trail (append-only; direct `UPDATE` / `DELETE` /
78
+ `TRUNCATE` rejected by the database)
79
+ - 🧰 Drop-in for your SDK (OpenAI, Anthropic, + OpenAI-compatible **Groq / Mistral / Together
80
+ / DeepSeek**), **or any agent** via the visa sidecar — point OpenHands / Aider / Cline /
81
+ Continue at a local proxy and it just works
82
+ - 🖥️ Control Tower dashboard (fleet, spend, budgets, audit, kill switch) + a developer
83
+ control-plane API + TOTP MFA
84
+
85
+ ## Quickstart (self-host)
86
+ Stack: **Next.js** (App Router, edge routes) · **Supabase** (Postgres + Vault + Auth) ·
87
+ **Upstash Redis**. Deploy on Vercel or any Node host (`next start`). No Vercel-proprietary
88
+ services are required — the kill switch is Redis-backed.
89
+
90
+ ### Local (Docker) quickstart
91
+ For the fastest local run, use the bundled Docker stack. It starts Supabase locally
92
+ (Postgres + Vault + Auth), Redis-over-REST, applies migrations inside the DB container, and
93
+ seeds a confirmed dev user. Prereqs: Docker Desktop, the Supabase CLI, and Node 18+. No host
94
+ `psql` is required.
95
+
96
+ ```bash
97
+ git clone https://github.com/Vertias3u/PassControl && cd PassControl
98
+ npm install
99
+ npm run cli -- setup # starts local services, migrates, seeds a dev user, opens dashboard
100
+ ```
101
+
102
+ Use `npm run cli -- setup --no-open` to suppress browser launch. If another local
103
+ Supabase/Redis project owns the default service ports, use:
104
+
105
+ ```bash
106
+ npm run cli -- setup --no-open --port-offset 100
107
+ ```
108
+
109
+ This offsets the local Supabase and Redis-over-REST ports together (for example, API `54421`
110
+ and database `54422`). The dashboard still uses the configured gateway port, which defaults to 3000.
111
+
112
+ Open `http://localhost:3000` and log in with:
113
+
114
+ ```text
115
+ dev@passcontrol.local
116
+ passcontrol-dev
117
+ ```
118
+
119
+ > ⚠️ This seeded dev user exists **only for the local Docker stack** and is created by
120
+ > `scripts/seed.mjs`. It is a convenience for local development — **never deploy it or reuse
121
+ > these credentials** in a hosted/production instance. Real deployments create accounts
122
+ > through normal signup (gated by `INVITE_CODE`); no default credentials ship.
123
+
124
+ Then add a **non-critical** provider key in the Control Tower, issue a passport, and copy the
125
+ one-time `PASSPORT_ID` / `PASSPORT_SECRET` values. In the second terminal, run:
126
+
127
+ ```bash
128
+ npm run cli -- init # gateway + passport + provider/model → .passcontrol
129
+ npm run cli -- doctor --deep # verifies the configuration and mints a visa
130
+ npm run cli -- call "Say hello in 3 words"
131
+ npm run cli -- spend # confirms governed spend
132
+ ```
133
+
134
+ You should see a streamed response in the terminal and an `ok` row in the dashboard Audit Log.
135
+ That is the complete governed loop: passport → visa → vault key injection → proxied call → audit.
136
+
137
+ To expose the short form locally, run this once from the repository root:
138
+
139
+ ```bash
140
+ npm link
141
+ passcontrol --help
142
+ passcontrol status
143
+ ```
144
+
145
+ Use `passcontrol start`, `passcontrol stop`, and `passcontrol restart` to manage only a dashboard
146
+ process started by the CLI. Use `passcontrol local-logs --follow` for its output.
147
+ `passcontrol reset --local --confirm RESET` destroys and recreates local data—use it only for a clean slate.
148
+
149
+ The final agent call uses your real Anthropic/OpenAI key from the local Vault, so start
150
+ with a non-critical key.
151
+
152
+ ### Manual self-host quickstart
153
+
154
+ > **Supabase specifically** (not vanilla Postgres): the credential vault uses the
155
+ > `supabase_vault` extension, so you need a Supabase project (hosted or the self-hosted
156
+ > Supabase stack), not a plain Postgres database.
157
+
158
+ ```bash
159
+ git clone https://github.com/Vertias3u/PassControl && cd PassControl
160
+ npm install
161
+ cp .env.example .env.local # fill in Supabase / Upstash / secrets
162
+ DATABASE_URL='postgresql://…' npm run migrate # applies db/migrations/*.sql in order, once each
163
+ npm run dev # or build + `next start` on any Node host
164
+ ```
165
+ See `.env.example` for the full config (Supabase URL/keys, `VISA_SECRET`, `CACHE_ENC_KEY`,
166
+ Upstash, `CRON_SECRET`, `INVITE_CODE`). Apply migrations `0001 → …` in order;
167
+ `db/tests/rls_invariants.sql` checks tenant isolation on your database.
168
+
169
+ **Background reconcile job (required on non-Vercel hosts):** a periodic call to
170
+ `GET /api/cron/reconcile` (with header `Authorization: Bearer $CRON_SECRET`) corrects budget
171
+ drift and flushes last-seen. On Vercel it's wired via `vercel.json`. Self-hosting, schedule it
172
+ yourself (system `cron`, a GitHub Action, etc.) every few minutes — it's a correction layer,
173
+ not the hot path, so an occasional missed run is harmless.
174
+
175
+ ## CLI command center
176
+
177
+ The CLI is the terminal operator interface. `npm run cli -- …` works from a clone; replace it
178
+ with `passcontrol …` after `npm link`.
179
+
180
+ | Need | Command |
181
+ |---|---|
182
+ | See config, gateway status, and suggested next steps | `npm run cli -- status` |
183
+ | Check local setup / mint a test visa | `npm run cli -- doctor --deep` |
184
+ | Make a governed model call | `npm run cli -- call "Summarize this"` |
185
+ | Start a bridge for an existing agent | `npm run cli -- sidecar` |
186
+ | Print settings for OpenHands, Aider, Cline, Continue, or LiteLLM | `npm run cli -- env openhands` |
187
+ | List or create agents | `npm run cli -- agent list` · `npm run cli -- agent create billing-bot` |
188
+ | Suspend, resume, or revoke an agent | `npm run cli -- agent suspend <id>` |
189
+ | Inspect spend, logs, and audit history | `npm run cli -- spend` · `npm run cli -- logs` · `npm run cli -- audit` |
190
+ | Arm or release the tenant kill switch | `npm run cli -- kill on` · `npm run cli -- kill off` |
191
+ | Open the Control Tower | `npm run cli -- open` |
192
+ | Prepare or repair local services | `npm run cli -- setup` · `npm run cli -- doctor --fix` |
193
+ | Manage the local dashboard | `npm run cli -- start` · `npm run cli -- stop` · `npm run cli -- restart` |
194
+ | Follow local dashboard logs | `npm run cli -- local-logs --follow` |
195
+ | Preview/write an Aider config | `npm run cli -- configure aider` · `npm run cli -- configure aider --write` |
196
+
197
+ The CLI reads environment variables first, then a project-local `.passcontrol`, then
198
+ `~/.config/passcontrol/config`. `.passcontrol` contains a passport secret, is gitignored, and
199
+ is written with owner-only permissions—never commit or share it.
200
+
201
+ ## Using it from an agent
202
+ The client SDK hides the visa dance — point your provider SDK at the gateway:
203
+
204
+ ```ts
205
+ import OpenAI from "openai";
206
+ import { PassControl } from "./sdk";
207
+
208
+ const pc = new PassControl({ gateway, passportId, passportSecret });
209
+ const openai = new OpenAI(pc.clientOptions("openai")); // baseURL + auth wired; visas auto-refresh
210
+ ```
211
+
212
+ The SDK is vendored in this repo under `./sdk`; it is not a separately published npm package
213
+ yet.
214
+
215
+ **Using an agent you don't control (OpenHands, Aider, Cline, Continue…)?** They expect a
216
+ static API key, but a visa expires in minutes. Run the **visa sidecar** — a local proxy that
217
+ mints/refreshes the visa for you — and point the agent at it like any other endpoint:
218
+
219
+ ```bash
220
+ npm run cli -- sidecar # http://127.0.0.1:8788
221
+ npm run cli -- env openhands
222
+ # then set the agent's base URL to http://127.0.0.1:8788/api/v1/anthropic (or /openai),
223
+ # API key = anything. The agent never holds a real key or a long-lived token.
224
+ ```
225
+
226
+ Presets are available for `openhands`, `aider`, `cline`, `continue`, and `litellm`.
227
+ If a client defaults to OpenAI `/responses` (notably Continue for some o-series/gpt-5
228
+ configs), disable that mode and force `/chat/completions`; PassControl intentionally proxies
229
+ only chat/messages and model-listing endpoints.
230
+
231
+ Manage the fleet programmatically with the control-plane SDK + API key:
232
+
233
+ ```ts
234
+ import { ControlClient } from "./sdk";
235
+ const cp = new ControlClient({ gateway, apiKey: process.env.PASSCONTROL_API_KEY! });
236
+ await cp.agents.list();
237
+ await cp.killSwitch.set(true);
238
+ ```
239
+
240
+ The CLI also exposes the common read/control paths:
241
+
242
+ ```bash
243
+ npm run cli -- agent list
244
+ npm run cli -- spend
245
+ npm run cli -- logs --limit 20
246
+ npm run cli -- audit --limit 20
247
+ npm run cli -- kill on
248
+ ```
249
+
250
+ Full API reference: [`openapi.yaml`](./openapi.yaml) and [`DOCUMENTATION.md`](./DOCUMENTATION.md).
251
+ Runnable example agents in [`examples/`](./examples).
252
+
253
+ ## Limitations
254
+ - A work-visa is a bearer token and is reusable until it expires (≤5 minutes). Keep it out
255
+ of logs and prompts; use suspend/kill switches to block future requests.
256
+ - The gateway proxies only chat and model-listing endpoints: OpenAI/Groq/Mistral/Together
257
+ chat completions and models, Anthropic messages and models, and DeepSeek chat
258
+ completions. It does **not** proxy embeddings, files, fine-tuning, batches, responses, or
259
+ token-counting endpoints.
260
+ - Pricing is a best-effort in-code table and can lag provider price changes. Use it for
261
+ budgets and monitoring, not as billing reconciliation against provider invoices.
262
+ - Instant revocation assumes Redis is configured for persistence/no-eviction behavior. If
263
+ Redis evicts suspend/kill keys, enforcement falls back to short visa TTLs and durable agent
264
+ status checks at the next mint.
265
+
266
+ ## Security
267
+ Security is the point of this project, so please report issues privately rather than opening
268
+ a public issue: **security@vertias.eu**. We'll acknowledge and work with you on a fix +
269
+ disclosure timeline. Notes:
270
+ - It's **BYOK** — your provider key lives encrypted in your own Supabase Vault; it's
271
+ decrypted only in-flight and cached briefly (encrypted) in your own Redis.
272
+ - It is **not yet independently audited.** If you find a hole, you're doing us a favor.
273
+
274
+ ## License
275
+ Source-available under the **Business Source License (BSL 1.1)** — read it, run it, modify it,
276
+ self-host it. The one restriction: you may not offer it as a competing hosted/managed service.
277
+ Converts to Apache 2.0 after the change date. See [`LICENSE`](./LICENSE).
278
+
279
+ ## Contributing
280
+ Issues and PRs welcome. Run `npm run typecheck && npm test && npm run build` before a PR (CI
281
+ enforces it). Be kind; this is early.