passcontrol 0.1.0 → 0.1.2
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 +195 -189
- package/bin/passcontrol.mjs +85 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,205 +1,183 @@
|
|
|
1
1
|
# PassControl
|
|
2
2
|
|
|
3
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
|
|
5
|
-
mint a short-lived **work-visa**; the gateway injects your
|
|
6
|
-
and proxies the call — so the agent never holds the key
|
|
7
|
-
an instant kill switch, and a per-agent audit trail.
|
|
4
|
+
Groq / Mistral / Together / DeepSeek keys into agent runtimes. Give each agent a cryptographic
|
|
5
|
+
**passport**; it signs a challenge to mint a short-lived **work-visa**; the gateway injects your
|
|
6
|
+
*real* provider key from a vault and proxies the call — so **the agent never holds the key**.
|
|
7
|
+
You get per-agent budgets, capability scopes, an instant kill switch, and a per-agent audit trail.
|
|
8
8
|
|
|
9
|
-
A [Vertias](https://vertias.eu) project. **Bring-your-own-key**
|
|
10
|
-
|
|
9
|
+
A [Vertias](https://vertias.eu) project. **Bring-your-own-key** — your provider key stays in your
|
|
10
|
+
own vault. Self-host it today; a managed version comes later.
|
|
11
11
|
|
|
12
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
|
|
14
|
-
> first
|
|
13
|
+
> security-focused and test-covered, but treat it as beta — run it against a **non-critical key
|
|
14
|
+
> first**, and see [Security](#security) for responsible disclosure. We'd rather you know than
|
|
15
15
|
> find out.
|
|
16
16
|
|
|
17
|
-
**New here
|
|
17
|
+
**New here?** The [Getting Started tutorial](./TUTORIAL.md) takes you from install to a real
|
|
18
18
|
governed agent in ~15 minutes.
|
|
19
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
20
|
```bash
|
|
33
21
|
npm install -g passcontrol
|
|
34
|
-
passcontrol setup #
|
|
22
|
+
passcontrol setup # boots the self-hostable stack + opens the Control Tower
|
|
35
23
|
```
|
|
36
24
|
|
|
37
|
-
|
|
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
|
-
```
|
|
25
|
+
---
|
|
52
26
|
|
|
53
27
|
## Why
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
28
|
+
|
|
29
|
+
A raw provider key handed to an autonomous agent **leaks** (logs, repos, prompts), **never
|
|
30
|
+
rotates**, has **no per-agent spend cap**, **no off-switch**, and leaves **no record** of which
|
|
31
|
+
agent did what. PassControl takes the key out of the agent entirely and puts a governed gateway
|
|
32
|
+
in front of it.
|
|
57
33
|
|
|
58
34
|
## How it works
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
35
|
+
|
|
36
|
+
1. **Passport** — each agent holds only an Ed25519 private key. It *only ever signs*; the key
|
|
37
|
+
never travels over the wire.
|
|
38
|
+
2. **Work-visa** — the agent signs a challenge (timestamp + single-use nonce) and mints a
|
|
39
|
+
short-lived (~5 min) token carrying its identity, scope, and budget snapshot.
|
|
40
|
+
3. **Inject & proxy** — a request arrives bearing a visa. The gateway verifies it → checks the
|
|
41
|
+
kill switch → checks scope (provider + model **and** endpoint) → reserves budget atomically →
|
|
42
|
+
pulls your provider key from the vault → injects it → forwards to the provider and streams
|
|
65
43
|
back. The agent never sees the key.
|
|
66
|
-
4. **Govern** — per-agent token
|
|
44
|
+
4. **Govern** — per-agent **token + dollar** budgets (enforced *before* the call), a layered kill
|
|
67
45
|
switch (platform / tenant / per-agent), and an append-only audit log of every call.
|
|
68
46
|
|
|
47
|
+
```
|
|
48
|
+
agent ──sign──▶ challenge ──visa──▶ ┌─────────── PassControl gateway ───────────┐
|
|
49
|
+
│ verify · kill/scope/budget · inject key │ ──▶ provider
|
|
50
|
+
(holds only a passport key) │ (real key from vault, never returned) │ ◀── stream
|
|
51
|
+
└────────────────────────────────────────────┘
|
|
52
|
+
```
|
|
53
|
+
|
|
69
54
|
## Features
|
|
70
|
-
|
|
71
|
-
-
|
|
72
|
-
-
|
|
55
|
+
|
|
56
|
+
- 🔑 **Agents never hold your provider key** — BYOK; the key stays vaulted, injected in-flight only
|
|
57
|
+
- 🪪 **Per-agent cryptographic identity** (Ed25519) with short-lived, revocable visas
|
|
58
|
+
- 💸 **Enforced per-agent token + cost (USD) budgets** — reserved pre-flight, reconciled after
|
|
73
59
|
- 🎯 **Capability scoping** — a visa is scoped to specific models *and* endpoints, so a
|
|
74
|
-
chat-scoped agent can't reach files, fine-tuning, batches,
|
|
75
|
-
|
|
76
|
-
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
Continue at a local proxy and it just works
|
|
82
|
-
- 🖥️ Control Tower dashboard (fleet, spend, budgets, audit, kill switch) + a developer
|
|
60
|
+
chat-scoped agent can't reach files, fine-tuning, batches, embeddings, etc. with your key
|
|
61
|
+
- ⛔ **Instant, layered kill switch** + per-agent suspend/revoke — stop a running agent mid-task
|
|
62
|
+
- 📒 **Append-only audit trail** per agent/passport (direct `UPDATE`/`DELETE`/`TRUNCATE` rejected
|
|
63
|
+
by the database)
|
|
64
|
+
- 🧰 **Drop-in for your SDK** (OpenAI, Anthropic, and OpenAI-compatible Groq / Mistral / Together /
|
|
65
|
+
DeepSeek) — **or any agent** via the visa sidecar (OpenHands, Aider, Cline, Continue…)
|
|
66
|
+
- 🖥️ **Control Tower** dashboard (fleet, spend, budgets, audit, kill switch) + a developer
|
|
83
67
|
control-plane API + TOTP MFA
|
|
84
68
|
|
|
85
|
-
##
|
|
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.
|
|
69
|
+
## Install & first run
|
|
89
70
|
|
|
90
|
-
|
|
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.
|
|
71
|
+
**Global CLI (recommended):**
|
|
95
72
|
|
|
96
73
|
```bash
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
74
|
+
npm install -g passcontrol
|
|
75
|
+
passcontrol --version # 0.1.1
|
|
76
|
+
passcontrol setup # prereq checks → fetches the stack → boots it → opens the dashboard
|
|
100
77
|
```
|
|
101
78
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
```
|
|
79
|
+
The published npm package is **just the CLI** (a handful of files, no provider keys). `passcontrol
|
|
80
|
+
setup` detects the global install and offers to clone the self-hostable stack (Supabase + Redis +
|
|
81
|
+
dashboard) into `~/passcontrol`, install its dependencies, and start it — one command from nothing
|
|
82
|
+
to a running Control Tower. It first checks your prerequisites (Docker running, Supabase CLI, Node
|
|
83
|
+
version, free ports) and tells you exactly what to fix if something's missing.
|
|
108
84
|
|
|
109
|
-
|
|
110
|
-
|
|
85
|
+
- Change the checkout location: `--app-dir <path>` or `PASSCONTROL_APP_ROOT=<path>`
|
|
86
|
+
- Non-interactive: `--yes`
|
|
87
|
+
- Skip opening the browser: `--no-open`
|
|
88
|
+
- Ports already taken by another local Supabase? `passcontrol setup --port-offset 100`
|
|
89
|
+
(offsets Supabase + Redis together, e.g. API `54421`, DB `54422`; the dashboard stays on `:3000`)
|
|
111
90
|
|
|
112
|
-
|
|
91
|
+
Then log in to the Control Tower at **http://localhost:3000** with the seeded local dev user:
|
|
113
92
|
|
|
114
93
|
```text
|
|
115
94
|
dev@passcontrol.local
|
|
116
95
|
passcontrol-dev
|
|
117
96
|
```
|
|
118
97
|
|
|
119
|
-
> ⚠️ This seeded
|
|
120
|
-
>
|
|
121
|
-
>
|
|
122
|
-
> through normal signup (gated by `INVITE_CODE`); no default credentials ship.
|
|
98
|
+
> ⚠️ This seeded user exists **only for the local Docker stack** (created by `scripts/seed.mjs`).
|
|
99
|
+
> **Never deploy it or reuse these credentials.** Real deployments create accounts through normal
|
|
100
|
+
> signup, gated by `INVITE_CODE`; no default credentials ship.
|
|
123
101
|
|
|
124
|
-
|
|
125
|
-
|
|
102
|
+
Add a **non-critical** provider key in the Control Tower, issue a passport, and copy the one-time
|
|
103
|
+
`PASSPORT_ID` / `PASSPORT_SECRET`. Then, in your project directory:
|
|
126
104
|
|
|
127
105
|
```bash
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
106
|
+
passcontrol init # gateway + passport + provider/model → writes .passcontrol
|
|
107
|
+
passcontrol doctor --deep # verifies config, prerequisites, and mints a test visa
|
|
108
|
+
passcontrol call "Say hello in 3 words"
|
|
109
|
+
passcontrol spend # confirms governed spend
|
|
132
110
|
```
|
|
133
111
|
|
|
134
|
-
You
|
|
135
|
-
|
|
112
|
+
You'll see a streamed response and an `ok` row in the dashboard Audit Log — the complete governed
|
|
113
|
+
loop: **passport → visa → vault key injection → proxied call → audit**. That last call uses your
|
|
114
|
+
real key from the local Vault, so start with a throwaway one.
|
|
136
115
|
|
|
137
|
-
|
|
116
|
+
> Working from a **source clone** instead of the global install? Everything below works as
|
|
117
|
+
> `npm run cli -- <command>`; after `npm link` in the clone, the short `passcontrol <command>` form
|
|
118
|
+
> works too.
|
|
138
119
|
|
|
139
|
-
|
|
140
|
-
npm link
|
|
141
|
-
passcontrol --help
|
|
142
|
-
passcontrol status
|
|
143
|
-
```
|
|
120
|
+
## Real agents & the visa sidecar
|
|
144
121
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
122
|
+
A visa is deliberately short-lived so it's revocable — but a real coding agent runs a **long,
|
|
123
|
+
multi-call session** that would outlive a single visa. The **sidecar** solves this: a tiny local
|
|
124
|
+
proxy that mints, caches, and auto-refreshes the visa (and re-mints instantly on expiry), so your
|
|
125
|
+
agent points at one stable endpoint and **never times out mid-task**.
|
|
148
126
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
127
|
+
```bash
|
|
128
|
+
passcontrol sidecar # http://127.0.0.1:8788
|
|
129
|
+
passcontrol env openhands # prints ready-to-paste settings for your agent
|
|
130
|
+
```
|
|
153
131
|
|
|
154
|
-
|
|
155
|
-
> `supabase_vault` extension, so you need a Supabase project (hosted or the self-hosted
|
|
156
|
-
> Supabase stack), not a plain Postgres database.
|
|
132
|
+
Point any OpenAI/Anthropic-compatible agent at the sidecar with a **dummy** key:
|
|
157
133
|
|
|
158
134
|
```bash
|
|
159
|
-
|
|
160
|
-
|
|
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
|
|
135
|
+
export ANTHROPIC_BASE_URL="http://127.0.0.1:8788/api/v1/anthropic" # or /api/v1/openai, /deepseek…
|
|
136
|
+
export ANTHROPIC_API_KEY="passcontrol" # ignored — the sidecar injects a live visa
|
|
164
137
|
```
|
|
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
138
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
139
|
+
The agent never holds a real key or a long-lived token. Presets ship for **openhands, aider, cline,
|
|
140
|
+
continue, litellm** (`passcontrol env <preset>`). A single long streaming completion also works
|
|
141
|
+
directly — it's verified once at the start, so it finishes even if it runs past the visa TTL; only
|
|
142
|
+
*multi-call* sessions need the sidecar's refresh. Raise `VISA_TTL_SECONDS` (300–900) to widen the
|
|
143
|
+
window, but the sidecar is the real answer for long sessions.
|
|
144
|
+
|
|
145
|
+
> If a client defaults to OpenAI `/responses` (some Continue configs for o-series/gpt-5), force
|
|
146
|
+
> `/chat/completions` — PassControl intentionally proxies only chat/messages and model-listing
|
|
147
|
+
> endpoints.
|
|
174
148
|
|
|
175
149
|
## CLI command center
|
|
176
150
|
|
|
177
|
-
The
|
|
178
|
-
with `passcontrol …` after `npm link`.
|
|
151
|
+
The primary interface is `passcontrol <command>`. Highlights:
|
|
179
152
|
|
|
180
153
|
| Need | Command |
|
|
181
154
|
|---|---|
|
|
182
|
-
|
|
|
183
|
-
| Check local setup / mint a test visa | `
|
|
184
|
-
| Make a governed model call | `
|
|
185
|
-
|
|
|
186
|
-
| Print settings
|
|
187
|
-
| List
|
|
188
|
-
| Suspend, resume, or revoke an agent | `
|
|
189
|
-
| Inspect spend, logs, and audit history | `
|
|
190
|
-
| Arm
|
|
191
|
-
|
|
|
192
|
-
|
|
|
193
|
-
|
|
|
194
|
-
|
|
|
195
|
-
| Preview/write an
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
`~/.config/passcontrol/config
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
155
|
+
| Config, gateway status, suggested next steps | `passcontrol status` |
|
|
156
|
+
| Check local setup / mint a test visa | `passcontrol doctor --deep` |
|
|
157
|
+
| Make a governed model call | `passcontrol call "Summarize this"` |
|
|
158
|
+
| Run the auto-refreshing bridge for an agent | `passcontrol sidecar` |
|
|
159
|
+
| Print agent settings (OpenHands, Aider, Cline, Continue, LiteLLM) | `passcontrol env openhands` |
|
|
160
|
+
| List / create agents | `passcontrol agent list` · `passcontrol agent create billing-bot` |
|
|
161
|
+
| Suspend, resume, or revoke an agent | `passcontrol agent suspend <id>` |
|
|
162
|
+
| Inspect spend, logs, and audit history | `passcontrol spend` · `passcontrol logs` · `passcontrol audit` |
|
|
163
|
+
| Arm / release the tenant kill switch | `passcontrol kill on` · `passcontrol kill off` |
|
|
164
|
+
| Prepare or repair local services | `passcontrol setup` · `passcontrol doctor --fix` |
|
|
165
|
+
| Manage the local dashboard | `passcontrol start` · `passcontrol stop` · `passcontrol restart` |
|
|
166
|
+
| Follow local dashboard logs | `passcontrol local-logs --follow` |
|
|
167
|
+
| Open the Control Tower | `passcontrol open` |
|
|
168
|
+
| Preview/write an agent config | `passcontrol configure aider` · `passcontrol configure aider --write` |
|
|
169
|
+
|
|
170
|
+
Config resolves in order: **environment variables → project-local `.passcontrol` →
|
|
171
|
+
`~/.config/passcontrol/config`**. `.passcontrol` holds a passport secret, is gitignored, and is
|
|
172
|
+
written owner-only — never commit or share it.
|
|
173
|
+
|
|
174
|
+
`passcontrol reset --local --confirm RESET` destroys and recreates local data — use it only for a
|
|
175
|
+
clean slate.
|
|
176
|
+
|
|
177
|
+
## Using it from your own code
|
|
178
|
+
|
|
179
|
+
The client SDK (vendored in [`./sdk`](./sdk)) hides the visa dance — point your provider SDK at the
|
|
180
|
+
gateway and visas auto-refresh:
|
|
203
181
|
|
|
204
182
|
```ts
|
|
205
183
|
import OpenAI from "openai";
|
|
@@ -209,26 +187,7 @@ const pc = new PassControl({ gateway, passportId, passportSecret });
|
|
|
209
187
|
const openai = new OpenAI(pc.clientOptions("openai")); // baseURL + auth wired; visas auto-refresh
|
|
210
188
|
```
|
|
211
189
|
|
|
212
|
-
|
|
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:
|
|
190
|
+
Manage the fleet programmatically with the control-plane SDK + an API key:
|
|
232
191
|
|
|
233
192
|
```ts
|
|
234
193
|
import { ControlClient } from "./sdk";
|
|
@@ -237,45 +196,92 @@ await cp.agents.list();
|
|
|
237
196
|
await cp.killSwitch.set(true);
|
|
238
197
|
```
|
|
239
198
|
|
|
240
|
-
The
|
|
199
|
+
The SDK is not a separately published npm package yet. Full API reference:
|
|
200
|
+
[`openapi.yaml`](./openapi.yaml) and [`DOCUMENTATION.md`](./DOCUMENTATION.md). Runnable example
|
|
201
|
+
agents live in [`examples/`](./examples).
|
|
202
|
+
|
|
203
|
+
## Self-host
|
|
204
|
+
|
|
205
|
+
Stack: **Next.js** (App Router, edge routes) · **Supabase** (Postgres + Vault + Auth) · **Upstash /
|
|
206
|
+
any Redis**. Deploy on Vercel or any Node host (`next start`). No Vercel-proprietary services are
|
|
207
|
+
required — the kill switch is Redis-backed.
|
|
208
|
+
|
|
209
|
+
### Local (Docker) — the fastest path
|
|
210
|
+
|
|
211
|
+
`passcontrol setup` (above) is the one-command route. Under the hood it runs the bundled Docker
|
|
212
|
+
stack: local Supabase (Postgres + Vault + Auth), Redis-over-REST, migrations applied inside the DB
|
|
213
|
+
container, and a seeded dev user. Prereqs: **Docker Desktop, the Supabase CLI, Node 18+** — no host
|
|
214
|
+
`psql` required.
|
|
215
|
+
|
|
216
|
+
From a source checkout you can drive the same thing directly:
|
|
241
217
|
|
|
242
218
|
```bash
|
|
243
|
-
|
|
244
|
-
npm
|
|
245
|
-
npm run cli --
|
|
246
|
-
npm run cli -- audit --limit 20
|
|
247
|
-
npm run cli -- kill on
|
|
219
|
+
git clone https://github.com/Vertias3u/PassControl && cd PassControl
|
|
220
|
+
npm install
|
|
221
|
+
npm run cli -- setup # or: passcontrol setup after `npm link`
|
|
248
222
|
```
|
|
249
223
|
|
|
250
|
-
|
|
251
|
-
|
|
224
|
+
### Manual self-host
|
|
225
|
+
|
|
226
|
+
> **Supabase specifically** (not vanilla Postgres): the credential vault uses the `supabase_vault`
|
|
227
|
+
> extension, so you need a Supabase project — hosted or the self-hosted Supabase stack — not a
|
|
228
|
+
> plain Postgres database.
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
git clone https://github.com/Vertias3u/PassControl && cd PassControl
|
|
232
|
+
npm install
|
|
233
|
+
cp .env.example .env.local # fill in Supabase / Redis / secrets
|
|
234
|
+
DATABASE_URL='postgresql://…' npm run migrate # applies db/migrations/*.sql in order, once each
|
|
235
|
+
npm run dev # or build + `next start` on any Node host
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
See [`.env.example`](./.env.example) for the full config (Supabase URL/keys, `VISA_SECRET`,
|
|
239
|
+
`CACHE_ENC_KEY`, Redis, `CRON_SECRET`, `INVITE_CODE`). Apply migrations `0001 → …` in order;
|
|
240
|
+
[`db/tests/rls_invariants.sql`](./db/tests/rls_invariants.sql) checks tenant isolation and the
|
|
241
|
+
privileged-column locks on your database.
|
|
242
|
+
|
|
243
|
+
**Background reconcile job (required on non-Vercel hosts):** a periodic `GET /api/cron/reconcile`
|
|
244
|
+
(header `Authorization: Bearer $CRON_SECRET`) corrects budget drift and flushes last-seen. On
|
|
245
|
+
Vercel it's wired via `vercel.json`; elsewhere schedule it yourself (system `cron`, a GitHub
|
|
246
|
+
Action…) every few minutes. It's a correction layer, not the hot path — an occasional missed run is
|
|
247
|
+
harmless.
|
|
248
|
+
|
|
249
|
+
## Providers & endpoints
|
|
250
|
+
|
|
251
|
+
Supported providers: **OpenAI, Anthropic, Groq, Mistral, Together, DeepSeek**. The gateway proxies
|
|
252
|
+
**only chat and model-listing endpoints** — OpenAI-shaped chat completions + models, Anthropic
|
|
253
|
+
messages + models, DeepSeek chat completions. It does **not** proxy embeddings, files, fine-tuning,
|
|
254
|
+
batches, `/responses`, or token-counting endpoints (that's the point — a leaked visa can't reach
|
|
255
|
+
your full provider surface).
|
|
252
256
|
|
|
253
257
|
## Limitations
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
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.
|
|
258
|
+
|
|
259
|
+
- A work-visa is a **bearer token**, reusable until it expires (≤5 min). Keep it out of logs and
|
|
260
|
+
prompts; use suspend/kill to block future requests immediately.
|
|
261
|
+
- **Pricing** is a best-effort in-code table and can lag provider price changes. Use it for budgets
|
|
262
|
+
and monitoring, not billing reconciliation against provider invoices.
|
|
263
|
+
- **Instant revocation** assumes Redis is configured for persistence / no-eviction. If Redis evicts
|
|
264
|
+
suspend/kill keys, enforcement falls back to short visa TTLs and the durable agent-status check at
|
|
265
|
+
the next mint.
|
|
265
266
|
|
|
266
267
|
## Security
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
disclosure timeline.
|
|
270
|
-
|
|
271
|
-
|
|
268
|
+
|
|
269
|
+
Security is the whole point, so please report issues privately rather than opening a public issue:
|
|
270
|
+
**security@vertias.eu**. We'll acknowledge and work with you on a fix + disclosure timeline.
|
|
271
|
+
|
|
272
|
+
- It's **BYOK** — your provider key lives encrypted in your own Supabase Vault, decrypted only
|
|
273
|
+
in-flight and cached briefly (encrypted) in your own Redis. It is never logged or returned.
|
|
274
|
+
- Tenant isolation is enforced by Postgres **RLS on every table**; the sole decrypt path is a
|
|
275
|
+
`SECURITY DEFINER`, service-role-only function.
|
|
272
276
|
- It is **not yet independently audited.** If you find a hole, you're doing us a favor.
|
|
273
277
|
|
|
274
278
|
## License
|
|
279
|
+
|
|
275
280
|
Source-available under the **Business Source License (BSL 1.1)** — read it, run it, modify it,
|
|
276
281
|
self-host it. The one restriction: you may not offer it as a competing hosted/managed service.
|
|
277
282
|
Converts to Apache 2.0 after the change date. See [`LICENSE`](./LICENSE).
|
|
278
283
|
|
|
279
284
|
## Contributing
|
|
285
|
+
|
|
280
286
|
Issues and PRs welcome. Run `npm run typecheck && npm test && npm run build` before a PR (CI
|
|
281
|
-
enforces it). Be kind
|
|
287
|
+
enforces it). Be kind — this is early.
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -265,6 +265,53 @@ function commandExists(command) {
|
|
|
265
265
|
}
|
|
266
266
|
}
|
|
267
267
|
|
|
268
|
+
function checkDockerInstalled() {
|
|
269
|
+
return commandExists("docker")
|
|
270
|
+
? { ok: true, message: "Docker CLI: installed." }
|
|
271
|
+
: {
|
|
272
|
+
ok: false,
|
|
273
|
+
message: "Docker CLI: not installed. Fix: install Docker Desktop from https://docs.docker.com/desktop/.",
|
|
274
|
+
};
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
function checkDockerDaemon() {
|
|
278
|
+
if (!commandExists("docker")) {
|
|
279
|
+
return {
|
|
280
|
+
ok: false,
|
|
281
|
+
message: "Docker daemon: unavailable. Fix: install Docker Desktop, start it, and wait for the engine to become ready.",
|
|
282
|
+
};
|
|
283
|
+
}
|
|
284
|
+
try {
|
|
285
|
+
execFileSync("docker", ["info"], { stdio: "ignore" });
|
|
286
|
+
return { ok: true, message: "Docker daemon: running." };
|
|
287
|
+
} catch {
|
|
288
|
+
return {
|
|
289
|
+
ok: false,
|
|
290
|
+
message: "Docker daemon: not running. Fix: start Docker Desktop and wait for the engine to become ready.",
|
|
291
|
+
};
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
function checkSupabaseInstalled() {
|
|
296
|
+
return commandExists("supabase")
|
|
297
|
+
? { ok: true, message: "Supabase CLI: installed." }
|
|
298
|
+
: {
|
|
299
|
+
ok: false,
|
|
300
|
+
message: "Supabase CLI: not installed. Fix: install it from https://supabase.com/docs/guides/local-development/cli/getting-started.",
|
|
301
|
+
};
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
function checkNodeVersion() {
|
|
305
|
+
const version = process.versions.node;
|
|
306
|
+
const major = Number(version.split(".")[0]);
|
|
307
|
+
return major >= 18
|
|
308
|
+
? { ok: true, message: `Node.js: v${version} (supported).` }
|
|
309
|
+
: {
|
|
310
|
+
ok: false,
|
|
311
|
+
message: `Node.js: v${version} is unsupported. Fix: install Node.js 18 or newer from https://nodejs.org/.`,
|
|
312
|
+
};
|
|
313
|
+
}
|
|
314
|
+
|
|
268
315
|
async function promptLine(question, fallback) {
|
|
269
316
|
const rl = createInterface({ input: process.stdin, output: process.stdout });
|
|
270
317
|
try {
|
|
@@ -435,8 +482,10 @@ async function waitForGateway(timeoutMs = 30000) {
|
|
|
435
482
|
}
|
|
436
483
|
|
|
437
484
|
function ownSupabaseDatabaseIsRunning(offset = 0) {
|
|
438
|
-
const project = `${path.basename(appRoot)}${offset ? `-${offset}` : ""}`;
|
|
439
485
|
try {
|
|
486
|
+
const root = appRoot ?? resolveAppRoot();
|
|
487
|
+
if (!root) return false;
|
|
488
|
+
const project = `${path.basename(root)}${offset ? `-${offset}` : ""}`;
|
|
440
489
|
return Boolean(
|
|
441
490
|
execFileSync("docker", ["ps", "-q", "--filter", `name=^/supabase_db_${project}$`], { encoding: "utf8" }).trim()
|
|
442
491
|
);
|
|
@@ -458,6 +507,39 @@ async function assertLocalStackPortsAvailable(offset = 0) {
|
|
|
458
507
|
}
|
|
459
508
|
}
|
|
460
509
|
|
|
510
|
+
async function checkLocalStackPorts(offset = 0) {
|
|
511
|
+
try {
|
|
512
|
+
await assertLocalStackPortsAvailable(offset);
|
|
513
|
+
return { ok: true, message: "Local stack ports: available." };
|
|
514
|
+
} catch (error) {
|
|
515
|
+
return {
|
|
516
|
+
ok: false,
|
|
517
|
+
message: `Local stack ports: unavailable. Fix: stop the conflicting project or rerun setup with --port-offset N. Details: ${error.message}`,
|
|
518
|
+
};
|
|
519
|
+
}
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
async function runLocalPrerequisiteChecks({ offset = 0, report = false, enforce = false } = {}) {
|
|
523
|
+
const results = [
|
|
524
|
+
checkDockerInstalled(),
|
|
525
|
+
checkDockerDaemon(),
|
|
526
|
+
checkSupabaseInstalled(),
|
|
527
|
+
checkNodeVersion(),
|
|
528
|
+
await checkLocalStackPorts(offset),
|
|
529
|
+
];
|
|
530
|
+
|
|
531
|
+
if (report) {
|
|
532
|
+
step("Local prerequisites");
|
|
533
|
+
for (const result of results) (result.ok ? ok : fail)(result.message);
|
|
534
|
+
}
|
|
535
|
+
|
|
536
|
+
if (enforce) {
|
|
537
|
+
const failure = results.find((result) => !result.ok);
|
|
538
|
+
if (failure) throw new Error(failure.message);
|
|
539
|
+
}
|
|
540
|
+
return results;
|
|
541
|
+
}
|
|
542
|
+
|
|
461
543
|
async function startDashboard(opts = {}) {
|
|
462
544
|
await ensureAppRoot({ clone: true, appDir: opts.appDir, yes: opts.yes });
|
|
463
545
|
const dashboard = localDashboard();
|
|
@@ -609,8 +691,8 @@ async function setupLocal(opts = {}) {
|
|
|
609
691
|
if (!Number.isInteger(offset) || offset < 0 || offset > 10000) {
|
|
610
692
|
throw new Error("--port-offset must be an integer from 0 to 10000.");
|
|
611
693
|
}
|
|
694
|
+
await runLocalPrerequisiteChecks({ offset, enforce: true });
|
|
612
695
|
await ensureAppRoot({ clone: true, appDir: opts.appDir, yes: opts.yes });
|
|
613
|
-
await assertLocalStackPortsAvailable(offset);
|
|
614
696
|
step("Preparing the local Supabase, Redis, migrations, and dev user…");
|
|
615
697
|
await runLocalCommand(process.platform === "win32" ? "npm.cmd" : "npm", ["run", "dev:stack"], {
|
|
616
698
|
...process.env,
|
|
@@ -1082,6 +1164,7 @@ async function doctorCommand(opts = {}) {
|
|
|
1082
1164
|
|
|
1083
1165
|
console.log("");
|
|
1084
1166
|
step("Deep checks");
|
|
1167
|
+
await runLocalPrerequisiteChecks({ report: true });
|
|
1085
1168
|
if (config.passportId && config.passportSecret) {
|
|
1086
1169
|
try {
|
|
1087
1170
|
const visa = await mintVisa(config);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "passcontrol",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "Secure Agent Control Plane & Passport Vault — identity-aware reverse proxy for AI agent credentials.",
|
|
5
5
|
"license": "BUSL-1.1",
|
|
6
6
|
"homepage": "https://github.com/Vertias3u/PassControl#readme",
|