passcontrol 0.1.1 → 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.
Files changed (2) hide show
  1. package/README.md +195 -189
  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 **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.
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** (you keep your provider key);
10
- self-host it, or use the managed version when it's available.
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 on a non-critical key
14
- > first, and see [Security](#security) for responsible disclosure. We'd rather you know than
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? Start with the [Getting Started tutorial](./TUTORIAL.md)** — clone to a real
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 # offers to fetch the local stack, then boots it and opens the dashboard
22
+ passcontrol setup # boots the self-hostable stack + opens the Control Tower
35
23
  ```
36
24
 
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
- ```
25
+ ---
52
26
 
53
27
  ## 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.
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
- 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
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 **and dollar** budgets (enforced pre-flight), a layered kill
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
- - 🔑 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
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, 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
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
- ## 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.
69
+ ## Install & first run
89
70
 
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.
71
+ **Global CLI (recommended):**
95
72
 
96
73
  ```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
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
- 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
- ```
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
- 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.
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
- Open `http://localhost:3000` and log in with:
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 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.
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
- 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:
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
- 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
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 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.
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
- To expose the short form locally, run this once from the repository root:
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
- ```bash
140
- npm link
141
- passcontrol --help
142
- passcontrol status
143
- ```
120
+ ## Real agents & the visa sidecar
144
121
 
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.
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
- 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
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
- > **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.
132
+ Point any OpenAI/Anthropic-compatible agent at the sidecar with a **dummy** key:
157
133
 
158
134
  ```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
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
- **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.
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 CLI is the terminal operator interface. `npm run cli -- …` works from a clone; replace it
178
- with `passcontrol …` after `npm link`.
151
+ The primary interface is `passcontrol <command>`. Highlights:
179
152
 
180
153
  | Need | Command |
181
154
  |---|---|
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:
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
- 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:
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 CLI also exposes the common read/control paths:
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
- 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
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
- Full API reference: [`openapi.yaml`](./openapi.yaml) and [`DOCUMENTATION.md`](./DOCUMENTATION.md).
251
- Runnable example agents in [`examples/`](./examples).
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
- - 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.
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
- 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.
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; this is early.
287
+ enforces it). Be kind — this is early.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "0.1.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",