passcontrol 0.2.0 → 0.4.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/README.md +44 -8
- package/bin/passcontrol.mjs +295 -34
- package/cli/config.mjs +36 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -49,28 +49,58 @@ Stack: **Next.js** (App Router, edge routes) · **Supabase** (Postgres + Vault +
|
|
|
49
49
|
**Upstash Redis**. Deploy on Vercel or any Node host (`next start`). No Vercel-proprietary
|
|
50
50
|
services are required — the kill switch is Redis-backed.
|
|
51
51
|
|
|
52
|
+
### See it work in 60 seconds — nothing to install
|
|
53
|
+
|
|
54
|
+
**[passcontrol.vertias.eu](https://passcontrol.vertias.eu)** — no signup, no provider key,
|
|
55
|
+
no clone. Run a governed AI call, arm the kill switch, run the same call again, and watch
|
|
56
|
+
it get blocked at the gateway.
|
|
57
|
+
|
|
58
|
+
That demo runs the **real** pipeline — passport → work-visa → scope + budget checks → kill
|
|
59
|
+
switch. Only the model response is synthesized, by a keyless `demo` provider that never
|
|
60
|
+
touches the Vault.
|
|
61
|
+
|
|
62
|
+
### Prove it on your own machine (`passcontrol try`)
|
|
63
|
+
|
|
64
|
+
Same story, your hardware, still no provider key and no account. This one is a real local
|
|
65
|
+
install — **prereqs: Docker Desktop and the Supabase CLI**, and the first stack boot takes
|
|
66
|
+
a few minutes:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
git clone https://github.com/<you>/passcontrol && cd passcontrol
|
|
70
|
+
npm install
|
|
71
|
+
PASSCONTROL_DEMO=1 npm run dev:stack # local stack + a keyless demo passport
|
|
72
|
+
PASSCONTROL_DEMO=1 npm run dev:docker & # run the gateway with demo mode on
|
|
73
|
+
npx passcontrol try # governed call → arm kill switch → blocked → disarm
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`passcontrol try` runs the real pipeline end-to-end and shows the same call blocked after
|
|
77
|
+
the kill switch fires — the whole PassControl story in one command, verified on your own
|
|
78
|
+
stack. Demo mode is **off by default and must never be enabled in production**: the keyless
|
|
79
|
+
`demo` provider is env-gated and never touches the Vault. Ready to use it for real?
|
|
80
|
+
Continue with the full quickstart below.
|
|
81
|
+
|
|
52
82
|
### Local (Docker) quickstart
|
|
53
83
|
For the fastest local run, use the bundled Docker stack. It starts Supabase locally
|
|
54
84
|
(Postgres + Vault + Auth), Redis-over-REST, applies migrations inside the DB container, and
|
|
55
|
-
|
|
56
|
-
is required.
|
|
85
|
+
prompts you to create your Control Tower account. Prereqs: Docker Desktop and the Supabase
|
|
86
|
+
CLI. No host `psql` is required.
|
|
57
87
|
|
|
58
88
|
```bash
|
|
59
89
|
git clone https://github.com/<you>/passcontrol && cd passcontrol
|
|
60
90
|
npm install
|
|
61
|
-
npm run dev:stack # starts Supabase + Redis locally, migrates,
|
|
91
|
+
npm run dev:stack # starts Supabase + Redis locally, migrates, creates your account
|
|
62
92
|
npm run dev:docker # runs the app against the local stack (loads .env.docker)
|
|
63
93
|
```
|
|
64
94
|
|
|
65
95
|
> Use **`npm run dev:docker`**, not `npm run dev`, for the local stack — plain `npm run
|
|
66
96
|
> dev` loads `.env.local` (your hosted Supabase), not the Docker stack's `.env.docker`.
|
|
67
97
|
|
|
68
|
-
|
|
98
|
+
During `dev:stack` you're asked to choose an account email and password — that account
|
|
99
|
+
guards the provider keys in your local Vault, so pick a real password. Open
|
|
100
|
+
`http://localhost:3000` and log in with it.
|
|
69
101
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
passcontrol-dev
|
|
73
|
-
```
|
|
102
|
+
> No shared default credentials ship. If the stack was brought up without a terminal
|
|
103
|
+
> attached (CI, piped output), a password is generated and printed once by the seed step.
|
|
74
104
|
|
|
75
105
|
Then add a provider key in the Control Tower, issue a passport, and run:
|
|
76
106
|
|
|
@@ -82,6 +112,12 @@ node examples/chat-agent.mjs "Say hello in 3 words"
|
|
|
82
112
|
The final agent call uses your real Anthropic/OpenAI key from the local Vault, so start
|
|
83
113
|
with a non-critical key.
|
|
84
114
|
|
|
115
|
+
> **Installed globally?** The stack lives in a checkout of this repo, not in the npm
|
|
116
|
+
> package, and the CLI remembers which one in `~/.config/passcontrol/app.json`. That file
|
|
117
|
+
> outlives `npm uninstall -g`, so a fresh install can keep pointing at an old directory.
|
|
118
|
+
> `passcontrol status` shows where the current path came from; `passcontrol unlink` forgets
|
|
119
|
+
> it, and `passcontrol setup --app-dir <path>` repoints.
|
|
120
|
+
|
|
85
121
|
### Manual self-host quickstart
|
|
86
122
|
|
|
87
123
|
> **Supabase specifically** (not vanilla Postgres): the credential vault uses the
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -16,14 +16,17 @@ import {
|
|
|
16
16
|
configPathLabel,
|
|
17
17
|
defaultModelForProvider,
|
|
18
18
|
fail,
|
|
19
|
+
formatLabel,
|
|
19
20
|
formatChallengeError,
|
|
20
21
|
formatProxyError,
|
|
21
22
|
globalConfigPath,
|
|
23
|
+
heading,
|
|
22
24
|
ok,
|
|
23
25
|
redact,
|
|
24
26
|
requireControlApiKey,
|
|
25
27
|
requirePassport,
|
|
26
28
|
step,
|
|
29
|
+
warn,
|
|
27
30
|
writeConfigFile,
|
|
28
31
|
} from "../cli/config.mjs";
|
|
29
32
|
import {
|
|
@@ -48,6 +51,16 @@ const CLI_VERSION = (() => {
|
|
|
48
51
|
return "0.0.0";
|
|
49
52
|
}
|
|
50
53
|
})();
|
|
54
|
+
|
|
55
|
+
// Fixed demo credentials for `passcontrol try` — LOCAL demo stack ONLY. The demo
|
|
56
|
+
// passport can only ever reach the keyless `demo` provider (no real key, no cost,
|
|
57
|
+
// no real upstream); the demo provider + these seeds exist only when the stack is
|
|
58
|
+
// brought up with PASSCONTROL_DEMO=1. Hardcoding them is safe, like the seeded dev
|
|
59
|
+
// password — they grant nothing in a real deployment.
|
|
60
|
+
// App-side source of truth: lib/demo/identity.ts (duplicated here to keep the shipped plain-ESM CLI transpilation-free).
|
|
61
|
+
const DEMO_PASSPORT_ID = "kZCFp7d2x4VDruiulJ21gogYbczBDAGZa-OuwR3qgh8";
|
|
62
|
+
const DEMO_PASSPORT_SECRET = "XqsVuXtmWiu6bKEmmqov2Q2TwkOVdzlZMWR-NWubSKo";
|
|
63
|
+
const DEMO_API_KEY = "pc_demolocaltrydemolocaltrydemolocaltry0000";
|
|
51
64
|
const DASHBOARD_STATE_FILE = "local-dashboard.json";
|
|
52
65
|
const APP_STATE_FILE = "app.json";
|
|
53
66
|
const PUBLIC_REPO_URL = "https://github.com/Vertias3u/PassControl.git";
|
|
@@ -99,14 +112,14 @@ function cliCommand(args = "") {
|
|
|
99
112
|
|
|
100
113
|
function usage() {
|
|
101
114
|
const cmd = cliPrefix();
|
|
102
|
-
return
|
|
115
|
+
return `${heading("PassControl")}
|
|
103
116
|
|
|
104
|
-
Usage:
|
|
117
|
+
${heading("Usage:")}
|
|
105
118
|
${cmd} show cockpit status
|
|
106
119
|
${cmd} init [--global] create a config profile
|
|
107
120
|
${cmd} status [--no-network] show active config
|
|
108
121
|
${cmd} start start the configured local dashboard
|
|
109
|
-
${cmd} stop
|
|
122
|
+
${cmd} stop [--dashboard-only] stop the whole local stack (dashboard + Supabase + Redis)
|
|
110
123
|
${cmd} restart restart the CLI-managed local dashboard
|
|
111
124
|
${cmd} local-logs [--follow] show local dashboard logs
|
|
112
125
|
${cmd} doctor [--deep] [--fix] check local setup and repair a stopped dashboard
|
|
@@ -114,6 +127,9 @@ Usage:
|
|
|
114
127
|
destroy and recreate the local stack
|
|
115
128
|
${cmd} setup [--no-open] [--port-offset N] [--app-dir DIR]
|
|
116
129
|
clone the app (if needed), start local services, open the dashboard
|
|
130
|
+
--app-dir repoints the CLI and is remembered
|
|
131
|
+
${cmd} unlink forget the remembered app checkout
|
|
132
|
+
${cmd} try 60-second demo: governed keyless call + kill switch (no key)
|
|
117
133
|
${cmd} call "hi" mint a visa and call a model
|
|
118
134
|
${cmd} sidecar [--port 8788] start the local agent bridge
|
|
119
135
|
${cmd} mcp start the local stdio MCP server
|
|
@@ -133,10 +149,13 @@ Usage:
|
|
|
133
149
|
${cmd} kill on|off toggle tenant kill switch
|
|
134
150
|
${cmd} open start (if needed) and open the dashboard
|
|
135
151
|
|
|
136
|
-
Config:
|
|
152
|
+
${heading("Config:")}
|
|
137
153
|
Env vars win, then nearest .passcontrol, then ~/.config/passcontrol/config.
|
|
138
154
|
Installed globally, the local-stack commands (setup/start/reset) use a cloned
|
|
139
|
-
app checkout
|
|
155
|
+
app checkout, resolved in this order:
|
|
156
|
+
--app-dir DIR → PASSCONTROL_APP_ROOT → surrounding checkout → remembered
|
|
157
|
+
checkout in ~/.config/passcontrol/app.json (survives npm uninstall; clear
|
|
158
|
+
it with \`${cmd} unlink\`).
|
|
140
159
|
`;
|
|
141
160
|
}
|
|
142
161
|
|
|
@@ -178,17 +197,17 @@ async function printCockpit({ noNetwork = false } = {}) {
|
|
|
178
197
|
const passportConfigured = Boolean(config.passportId && config.passportSecret);
|
|
179
198
|
const adminConfigured = Boolean(config.apiKey);
|
|
180
199
|
|
|
181
|
-
console.log("PassControl\n
|
|
182
|
-
console.log(
|
|
183
|
-
console.log(
|
|
184
|
-
console.log(
|
|
185
|
-
console.log(
|
|
186
|
-
console.log(
|
|
187
|
-
console.log(
|
|
188
|
-
console.log(
|
|
189
|
-
console.log(
|
|
190
|
-
console.log(`
|
|
191
|
-
console.log("Next commands:");
|
|
200
|
+
console.log(`${heading("PassControl")}\n`);
|
|
201
|
+
console.log(formatLabel("Gateway", `${gateway.label} ${config.gateway}`));
|
|
202
|
+
console.log(formatLabel("Dashboard", dashboardStatusLabel(gateway, noNetwork)));
|
|
203
|
+
console.log(formatLabel("App", appRootLabel()));
|
|
204
|
+
console.log(formatLabel("Config", configPathLabel(config.sources)));
|
|
205
|
+
console.log(formatLabel("Provider", config.provider));
|
|
206
|
+
console.log(formatLabel("Model", config.model));
|
|
207
|
+
console.log(formatLabel("Passport", passportConfigured ? redact(config.passportId) : "missing"));
|
|
208
|
+
console.log(formatLabel("Admin key", adminConfigured ? redact(config.apiKey, 6) : "missing"));
|
|
209
|
+
console.log(`${formatLabel("Sidecar", `foreground command (\`${cliCommand("sidecar")}\`)`)}\n`);
|
|
210
|
+
console.log(heading("Next commands:"));
|
|
192
211
|
console.log(` ${cliCommand("start")} start the local dashboard`);
|
|
193
212
|
console.log(` ${cliCommand("stop")} stop the local dashboard`);
|
|
194
213
|
console.log(` ${cliCommand("restart")} restart the local dashboard`);
|
|
@@ -246,31 +265,50 @@ function saveAppRoot(dir) {
|
|
|
246
265
|
fs.writeFileSync(statePath, `${JSON.stringify({ path: dir, savedAt: new Date().toISOString() })}\n`, { mode: 0o600 });
|
|
247
266
|
}
|
|
248
267
|
|
|
268
|
+
function forgetAppRoot() {
|
|
269
|
+
const saved = readSavedAppRoot();
|
|
270
|
+
fs.rmSync(appRootStatePath(), { force: true });
|
|
271
|
+
return saved;
|
|
272
|
+
}
|
|
273
|
+
|
|
249
274
|
// Precedence: explicit env override → the surrounding checkout (npm run cli --) →
|
|
250
|
-
// a previously cloned/saved checkout.
|
|
251
|
-
//
|
|
252
|
-
|
|
275
|
+
// a previously cloned/saved checkout. (An explicit --app-dir outranks all three;
|
|
276
|
+
// ensureAppRoot applies it before consulting this.) Returns null when the CLI is
|
|
277
|
+
// installed globally and no stack has been set up yet. `source` exists so status
|
|
278
|
+
// can say where the path came from — a saved root that outlives the checkout it
|
|
279
|
+
// points at is invisible otherwise, which reads as the CLI ignoring the user.
|
|
280
|
+
function resolveAppRootSource() {
|
|
253
281
|
const envRoot = process.env.PASSCONTROL_APP_ROOT?.trim();
|
|
254
282
|
if (envRoot) {
|
|
255
283
|
const abs = path.resolve(envRoot);
|
|
256
284
|
if (!isRepoCheckout(abs)) {
|
|
257
285
|
throw new Error(`PASSCONTROL_APP_ROOT=${envRoot} is not a PassControl checkout (missing scripts/dev-stack.sh).`);
|
|
258
286
|
}
|
|
259
|
-
return abs;
|
|
287
|
+
return { path: abs, source: "PASSCONTROL_APP_ROOT" };
|
|
288
|
+
}
|
|
289
|
+
if (process.env.PASSCONTROL_FORCE_INSTALLED !== "1" && isRepoCheckout(PACKAGE_ROOT)) {
|
|
290
|
+
return { path: PACKAGE_ROOT, source: "surrounding checkout" };
|
|
260
291
|
}
|
|
261
|
-
if (process.env.PASSCONTROL_FORCE_INSTALLED !== "1" && isRepoCheckout(PACKAGE_ROOT)) return PACKAGE_ROOT;
|
|
262
292
|
const saved = readSavedAppRoot();
|
|
263
|
-
if (saved && isRepoCheckout(saved))
|
|
293
|
+
if (saved && isRepoCheckout(saved)) {
|
|
294
|
+
return { path: path.resolve(saved), source: `saved — \`${cliCommand("unlink")}\` to clear` };
|
|
295
|
+
}
|
|
264
296
|
return null;
|
|
265
297
|
}
|
|
266
298
|
|
|
299
|
+
function resolveAppRoot() {
|
|
300
|
+
return resolveAppRootSource()?.path ?? null;
|
|
301
|
+
}
|
|
302
|
+
|
|
267
303
|
function defaultAppDir() {
|
|
268
304
|
return path.join(os.homedir(), "passcontrol");
|
|
269
305
|
}
|
|
270
306
|
|
|
271
307
|
function appRootLabel() {
|
|
272
308
|
try {
|
|
273
|
-
|
|
309
|
+
const resolved = resolveAppRootSource();
|
|
310
|
+
if (!resolved) return `not set up (run \`${cliCommand("setup")}\`)`;
|
|
311
|
+
return `${resolved.path} (${resolved.source})`;
|
|
274
312
|
} catch (error) {
|
|
275
313
|
return error.message;
|
|
276
314
|
}
|
|
@@ -351,15 +389,35 @@ async function confirmYes(question) {
|
|
|
351
389
|
// installed globally. `clone: false` never clones — it errors with a pointer to
|
|
352
390
|
// `passcontrol setup` (used by reset/doctor, where there's nothing yet to act on).
|
|
353
391
|
async function ensureAppRoot({ clone = false, appDir, yes = false } = {}) {
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
392
|
+
// An explicit --app-dir is the strongest signal there is and must outrank a
|
|
393
|
+
// saved checkout. It used to lose: resolveAppRoot() ran first, so a stale
|
|
394
|
+
// ~/.config/passcontrol/app.json (which survives `npm uninstall -g`) meant
|
|
395
|
+
// `setup --app-dir NEW` silently kept using the old directory, with no error
|
|
396
|
+
// and no way to repoint short of deleting an undocumented state file.
|
|
397
|
+
// parseArgv yields `true` for a valueless --app-dir; path.resolve(true) would
|
|
398
|
+
// throw a raw TypeError that reads as a crash rather than a usage mistake.
|
|
399
|
+
if (appDir !== undefined && typeof appDir !== "string") {
|
|
400
|
+
throw new Error(`--app-dir needs a directory path, e.g. \`${cliCommand("setup --app-dir ~/passcontrol")}\`.`);
|
|
401
|
+
}
|
|
402
|
+
const explicit = appDir ? path.resolve(appDir) : null;
|
|
403
|
+
if (explicit && isRepoCheckout(explicit)) {
|
|
404
|
+
saveAppRoot(explicit);
|
|
405
|
+
appRoot = explicit;
|
|
358
406
|
return appRoot;
|
|
359
407
|
}
|
|
408
|
+
if (appRoot) return appRoot;
|
|
409
|
+
if (!explicit) {
|
|
410
|
+
const resolved = resolveAppRoot();
|
|
411
|
+
if (resolved) {
|
|
412
|
+
appRoot = resolved;
|
|
413
|
+
return appRoot;
|
|
414
|
+
}
|
|
415
|
+
}
|
|
360
416
|
if (!clone) {
|
|
361
417
|
throw new Error(
|
|
362
|
-
|
|
418
|
+
explicit
|
|
419
|
+
? `--app-dir ${appDir} is not a PassControl checkout (missing scripts/dev-stack.sh).`
|
|
420
|
+
: `No PassControl app checkout found. Run \`${cliCommand("setup")}\` to clone and start it, or set PASSCONTROL_APP_ROOT to an existing checkout.`
|
|
363
421
|
);
|
|
364
422
|
}
|
|
365
423
|
|
|
@@ -370,7 +428,9 @@ async function ensureAppRoot({ clone = false, appDir, yes = false } = {}) {
|
|
|
370
428
|
);
|
|
371
429
|
}
|
|
372
430
|
|
|
373
|
-
const target =
|
|
431
|
+
const target =
|
|
432
|
+
explicit ??
|
|
433
|
+
path.resolve(interactive ? await promptLine(`Where should the PassControl app be cloned? [${defaultAppDir()}] `, defaultAppDir()) : defaultAppDir());
|
|
374
434
|
if (fs.existsSync(target) && fs.readdirSync(target).length) {
|
|
375
435
|
if (isRepoCheckout(target)) {
|
|
376
436
|
saveAppRoot(target);
|
|
@@ -639,6 +699,68 @@ async function stopDashboard() {
|
|
|
639
699
|
ok(`stopped CLI-managed dashboard (PID ${state.pid})`);
|
|
640
700
|
}
|
|
641
701
|
|
|
702
|
+
// `passcontrol stop` — one command for "stop PassControl". Previously this halted
|
|
703
|
+
// only the CLI-managed dashboard, so a developer still had to remember
|
|
704
|
+
// `supabase stop` and a `docker compose` invocation in the right directory to
|
|
705
|
+
// actually free the ports and the RAM.
|
|
706
|
+
//
|
|
707
|
+
// Deliberately NON-DESTRUCTIVE: it stops containers but never removes volumes, so
|
|
708
|
+
// the Vault, passports, and audit log survive. Wiping local data stays with
|
|
709
|
+
// `passcontrol reset --local --confirm RESET`, which asks before it deletes.
|
|
710
|
+
async function stopCommand(opts = {}) {
|
|
711
|
+
await stopDashboard();
|
|
712
|
+
|
|
713
|
+
if (opts.dashboardOnly) {
|
|
714
|
+
step("Left Supabase and Redis running (--dashboard-only).");
|
|
715
|
+
return;
|
|
716
|
+
}
|
|
717
|
+
|
|
718
|
+
let root;
|
|
719
|
+
try {
|
|
720
|
+
root = resolveAppRoot();
|
|
721
|
+
} catch (error) {
|
|
722
|
+
// A bad PASSCONTROL_APP_ROOT shouldn't turn "stop" into a failure — the
|
|
723
|
+
// dashboard is already down, which is most of what was asked for.
|
|
724
|
+
step(error.message);
|
|
725
|
+
return;
|
|
726
|
+
}
|
|
727
|
+
if (!root) {
|
|
728
|
+
step(`No local stack checkout found — nothing else to stop (\`${cliCommand("setup")}\` creates one).`);
|
|
729
|
+
return;
|
|
730
|
+
}
|
|
731
|
+
// Helpers below (localComposeProjectName) read the module-level appRoot, which
|
|
732
|
+
// is only populated by ensureAppRoot() on the setup path. Stop never clones, so
|
|
733
|
+
// publish the resolved checkout here.
|
|
734
|
+
appRoot = root;
|
|
735
|
+
|
|
736
|
+
// Each service is stopped independently and tolerantly: a stack that is already
|
|
737
|
+
// down, or half down, must still end with everything down and exit 0.
|
|
738
|
+
await stopLocalService("Supabase", "supabase", ["stop"], root);
|
|
739
|
+
await stopLocalService(
|
|
740
|
+
"Redis",
|
|
741
|
+
"docker",
|
|
742
|
+
["compose", "-f", "docker/compose.yml", "down"],
|
|
743
|
+
root,
|
|
744
|
+
{ ...process.env, COMPOSE_PROJECT_NAME: localComposeProjectName() }
|
|
745
|
+
);
|
|
746
|
+
|
|
747
|
+
ok("PassControl stopped. Local data kept — `passcontrol reset --local` wipes it.");
|
|
748
|
+
}
|
|
749
|
+
|
|
750
|
+
/** Stop one local service, reporting rather than throwing when it is already down. */
|
|
751
|
+
async function stopLocalService(label, command, args, cwd, env = process.env) {
|
|
752
|
+
if (!commandExists(command)) {
|
|
753
|
+
step(`${label}: \`${command}\` not found — skipping.`);
|
|
754
|
+
return;
|
|
755
|
+
}
|
|
756
|
+
try {
|
|
757
|
+
await runCommand(command, args, { cwd, env });
|
|
758
|
+
ok(`${label} stopped`);
|
|
759
|
+
} catch {
|
|
760
|
+
step(`${label}: already stopped (or not running).`);
|
|
761
|
+
}
|
|
762
|
+
}
|
|
763
|
+
|
|
642
764
|
async function restartDashboard(opts = {}) {
|
|
643
765
|
localDashboard();
|
|
644
766
|
const managed = runningManagedDashboard();
|
|
@@ -683,6 +805,37 @@ async function runLocalCommand(command, args, env = process.env) {
|
|
|
683
805
|
await runCommand(command, args, { cwd: appRoot, env });
|
|
684
806
|
}
|
|
685
807
|
|
|
808
|
+
// The saved app root lives outside the npm package, so `npm uninstall -g` leaves
|
|
809
|
+
// it behind and a reinstall silently keeps pointing at the old checkout. `unlink`
|
|
810
|
+
// is the supported way to forget it — without this, deleting an undocumented
|
|
811
|
+
// state file by hand is the only reset.
|
|
812
|
+
function unlinkCommand() {
|
|
813
|
+
const statePath = appRootStatePath();
|
|
814
|
+
// Branch on the file, not on readSavedAppRoot(): that returns null for corrupt
|
|
815
|
+
// JSON exactly as it does for a missing file, so keying off it would report
|
|
816
|
+
// "does not exist" about a file that does — and leave the blockage in place.
|
|
817
|
+
if (!fs.existsSync(statePath)) {
|
|
818
|
+
ok(`No saved app checkout to forget (${statePath} does not exist).`);
|
|
819
|
+
return;
|
|
820
|
+
}
|
|
821
|
+
const saved = readSavedAppRoot();
|
|
822
|
+
|
|
823
|
+
// Forgetting the path while the stack is up strands it: `stop` resolves the
|
|
824
|
+
// checkout to bring Supabase and Redis down, and can't once the path is gone.
|
|
825
|
+
const running = runningManagedDashboard();
|
|
826
|
+
if (running) {
|
|
827
|
+
warn(`A CLI-managed dashboard (PID ${running.pid}) is still running from ${saved ?? "the saved checkout"}.`);
|
|
828
|
+
warn(`Run \`${cliCommand("stop")}\` first, or stop it from that checkout by hand.`);
|
|
829
|
+
}
|
|
830
|
+
|
|
831
|
+
forgetAppRoot();
|
|
832
|
+
ok(saved ? `Forgot the saved app checkout ${saved} (removed ${statePath}).` : `Removed an unreadable app checkout state file (${statePath}).`);
|
|
833
|
+
// `setup --app-dir` runs the Docker/Supabase prerequisite gate before it
|
|
834
|
+
// repoints, so it is not the zero-dependency answer; name the env override too.
|
|
835
|
+
step(`Link another with \`${cliCommand("setup --app-dir <path>")}\` (also starts the local stack),`);
|
|
836
|
+
step("or set PASSCONTROL_APP_ROOT=<path> for a one-off override.");
|
|
837
|
+
}
|
|
838
|
+
|
|
686
839
|
async function resetLocalStack(opts = {}) {
|
|
687
840
|
if (opts.local !== true) {
|
|
688
841
|
throw new Error("Usage: passcontrol reset --local --confirm RESET");
|
|
@@ -720,8 +873,8 @@ async function setupLocal(opts = {}) {
|
|
|
720
873
|
});
|
|
721
874
|
await startDashboard(opts);
|
|
722
875
|
if (!opts.noOpen) await openDashboard(opts);
|
|
723
|
-
console.log(`\
|
|
724
|
-
console.log("
|
|
876
|
+
console.log(`\n${formatLabel("Local dashboard", dashboard.url, 19)}`);
|
|
877
|
+
console.log(formatLabel("Login", "the account you created during setup", 19));
|
|
725
878
|
step("Add a non-critical provider key, issue a passport, then run `passcontrol doctor --deep`.");
|
|
726
879
|
}
|
|
727
880
|
|
|
@@ -741,7 +894,7 @@ async function initCommand(opts) {
|
|
|
741
894
|
}
|
|
742
895
|
}
|
|
743
896
|
|
|
744
|
-
console.log("PassControl init");
|
|
897
|
+
console.log(heading("PassControl init"));
|
|
745
898
|
if (opts.global) {
|
|
746
899
|
console.log("Saving a global profile. Only do this on a machine you trust.\n");
|
|
747
900
|
} else {
|
|
@@ -861,6 +1014,108 @@ async function callCommand(rest, opts) {
|
|
|
861
1014
|
ok("done - check the dashboard audit log + spend for this call.");
|
|
862
1015
|
}
|
|
863
1016
|
|
|
1017
|
+
// `passcontrol try` — the 60-second, no-key, no-accounts experience. Uses the
|
|
1018
|
+
// seeded demo passport (demo scope only) to make a GOVERNED call through the
|
|
1019
|
+
// keyless `demo` provider, then arms the kill switch to show the same call
|
|
1020
|
+
// blocked. Everything is real (visa, scope, budget, kill) except the model.
|
|
1021
|
+
async function tryCommand() {
|
|
1022
|
+
const gateway = config.gateway;
|
|
1023
|
+
const demo = { gateway, passportId: DEMO_PASSPORT_ID, passportSecret: DEMO_PASSPORT_SECRET };
|
|
1024
|
+
|
|
1025
|
+
const demoCall = async () => {
|
|
1026
|
+
const { visa } = await mintVisa(demo);
|
|
1027
|
+
return fetch(`${gateway}/api/v1/demo/chat/completions`, {
|
|
1028
|
+
method: "POST",
|
|
1029
|
+
headers: { "content-type": "application/json", authorization: `Bearer ${visa}` },
|
|
1030
|
+
body: JSON.stringify({
|
|
1031
|
+
model: "demo-1",
|
|
1032
|
+
max_tokens: 64,
|
|
1033
|
+
messages: [{ role: "user", content: "Say hi in exactly three words" }],
|
|
1034
|
+
}),
|
|
1035
|
+
});
|
|
1036
|
+
};
|
|
1037
|
+
const setKill = async (armed) => {
|
|
1038
|
+
const res = await fetch(`${gateway}/api/control/v1/kill-switch`, {
|
|
1039
|
+
method: "PUT",
|
|
1040
|
+
headers: {
|
|
1041
|
+
"content-type": "application/json",
|
|
1042
|
+
authorization: `Bearer ${DEMO_API_KEY}`,
|
|
1043
|
+
"idempotency-key": crypto.randomUUID(),
|
|
1044
|
+
},
|
|
1045
|
+
body: JSON.stringify({ armed }),
|
|
1046
|
+
});
|
|
1047
|
+
if (!res.ok) throw new Error(`kill-switch ${armed ? "on" : "off"} → ${res.status} ${await res.text()}`);
|
|
1048
|
+
};
|
|
1049
|
+
|
|
1050
|
+
console.log(`${heading("PassControl — 60-second try (no provider key, no accounts)")}\n`);
|
|
1051
|
+
step(`gateway: ${gateway}`);
|
|
1052
|
+
|
|
1053
|
+
// 1. Governed, keyless call.
|
|
1054
|
+
let res;
|
|
1055
|
+
try {
|
|
1056
|
+
res = await demoCall();
|
|
1057
|
+
} catch (e) {
|
|
1058
|
+
const msg = e?.message || String(e);
|
|
1059
|
+
if (/unknown_passport|Challenge failed|challenge/i.test(msg)) {
|
|
1060
|
+
// Gateway reachable, but the demo passport isn't seeded in ITS database.
|
|
1061
|
+
fail(`The gateway is up, but the demo passport isn't seeded here (${msg}).`);
|
|
1062
|
+
step("Seed + enable the demo on this stack:");
|
|
1063
|
+
step(" PASSCONTROL_DEMO=1 npm run dev:stack # seeds the demo passport + control key");
|
|
1064
|
+
step(" PASSCONTROL_DEMO=1 npm run dev:docker # enables the keyless demo provider");
|
|
1065
|
+
} else {
|
|
1066
|
+
fail(`Could not reach the gateway at ${gateway} (${msg}).`);
|
|
1067
|
+
step("Bring the local demo stack up first:");
|
|
1068
|
+
step(" PASSCONTROL_DEMO=1 npm run dev:stack # Supabase + Redis + migrate + seed the demo passport");
|
|
1069
|
+
step(" PASSCONTROL_DEMO=1 npm run dev:docker # start the gateway with the demo provider enabled");
|
|
1070
|
+
}
|
|
1071
|
+
process.exitCode = 1;
|
|
1072
|
+
return;
|
|
1073
|
+
}
|
|
1074
|
+
if (res.status === 404) {
|
|
1075
|
+
fail("The demo provider is not enabled on this gateway.");
|
|
1076
|
+
step("Start it with PASSCONTROL_DEMO=1 (e.g. `PASSCONTROL_DEMO=1 npm run dev:docker`).");
|
|
1077
|
+
process.exitCode = 1;
|
|
1078
|
+
return;
|
|
1079
|
+
}
|
|
1080
|
+
if (res.status === 401 || res.status === 403) {
|
|
1081
|
+
fail(`Demo passport not accepted (${res.status}). Re-seed the demo stack: PASSCONTROL_DEMO=1 npm run seed`);
|
|
1082
|
+
process.exitCode = 1;
|
|
1083
|
+
return;
|
|
1084
|
+
}
|
|
1085
|
+
if (!res.ok) {
|
|
1086
|
+
fail(`Unexpected ${res.status}: ${await res.text()}`);
|
|
1087
|
+
process.exitCode = 1;
|
|
1088
|
+
return;
|
|
1089
|
+
}
|
|
1090
|
+
|
|
1091
|
+
const json = await res.json().catch(() => ({}));
|
|
1092
|
+
const text = json?.choices?.[0]?.message?.content ?? JSON.stringify(json);
|
|
1093
|
+
const usage = json?.usage ?? {};
|
|
1094
|
+
ok("Governed keyless call succeeded — the passport signed a visa, the gateway enforced scope + budget, and no key was needed:");
|
|
1095
|
+
console.log(`\n ${text}\n`);
|
|
1096
|
+
step(`tokens: ${usage.total_tokens ?? "?"} (prompt ${usage.prompt_tokens ?? "?"} + completion ${usage.completion_tokens ?? "?"})`);
|
|
1097
|
+
|
|
1098
|
+
// 2. Kill switch blocks the very next call.
|
|
1099
|
+
console.log("");
|
|
1100
|
+
step("arming the kill switch…");
|
|
1101
|
+
await setKill(true);
|
|
1102
|
+
try {
|
|
1103
|
+
const blocked = await demoCall();
|
|
1104
|
+
if (blocked.status === 403) {
|
|
1105
|
+
ok(`Kill switch works — the same call is now ${blocked.status} blocked_suspended.`);
|
|
1106
|
+
} else {
|
|
1107
|
+
fail(`Expected 403 after arming the kill switch, got ${blocked.status}.`);
|
|
1108
|
+
}
|
|
1109
|
+
} finally {
|
|
1110
|
+
await setKill(false);
|
|
1111
|
+
step("kill switch disarmed.");
|
|
1112
|
+
}
|
|
1113
|
+
|
|
1114
|
+
console.log("");
|
|
1115
|
+
ok("That's PassControl: cryptographic identity → short-lived visa → governed call → instant kill. The provider key never touched the agent.");
|
|
1116
|
+
step("Next: add a real provider key in the Control Tower and re-point your agent at the gateway (see the README).");
|
|
1117
|
+
}
|
|
1118
|
+
|
|
864
1119
|
async function api(method, pathPart, body) {
|
|
865
1120
|
const apiKey = requireControlApiKey(config);
|
|
866
1121
|
const res = await fetch(`${config.gateway}/api/control/v1${pathPart}`, {
|
|
@@ -1233,7 +1488,7 @@ async function configureCommand(rest, opts = {}) {
|
|
|
1233
1488
|
|
|
1234
1489
|
async function doctorCommand(opts = {}) {
|
|
1235
1490
|
const gateway = await gatewayStatus(false);
|
|
1236
|
-
console.log("PassControl doctor\n
|
|
1491
|
+
console.log(`${heading("PassControl doctor")}\n`);
|
|
1237
1492
|
(gateway.ok ? ok : fail)(`Gateway ${gateway.label}: ${config.gateway}`);
|
|
1238
1493
|
(config.passportId && config.passportSecret ? ok : fail)(
|
|
1239
1494
|
`Passport ${config.passportId && config.passportSecret ? "configured" : "missing"}`
|
|
@@ -1340,7 +1595,7 @@ async function main() {
|
|
|
1340
1595
|
await startDashboard(opts);
|
|
1341
1596
|
break;
|
|
1342
1597
|
case "stop":
|
|
1343
|
-
await
|
|
1598
|
+
await stopCommand(opts);
|
|
1344
1599
|
break;
|
|
1345
1600
|
case "restart":
|
|
1346
1601
|
await restartDashboard(opts);
|
|
@@ -1354,9 +1609,15 @@ async function main() {
|
|
|
1354
1609
|
case "setup":
|
|
1355
1610
|
await setupLocal(opts);
|
|
1356
1611
|
break;
|
|
1612
|
+
case "unlink":
|
|
1613
|
+
unlinkCommand();
|
|
1614
|
+
break;
|
|
1357
1615
|
case "call":
|
|
1358
1616
|
await callCommand(commandRest, opts);
|
|
1359
1617
|
break;
|
|
1618
|
+
case "try":
|
|
1619
|
+
await tryCommand();
|
|
1620
|
+
break;
|
|
1360
1621
|
case "sidecar":
|
|
1361
1622
|
await sidecarCommand(commandRest, opts);
|
|
1362
1623
|
break;
|
package/cli/config.mjs
CHANGED
|
@@ -18,6 +18,25 @@ const CONFIG_KEYS = [
|
|
|
18
18
|
];
|
|
19
19
|
|
|
20
20
|
const trimSlash = (value) => String(value ?? "").replace(/\/+$/, "");
|
|
21
|
+
const ANSI = {
|
|
22
|
+
reset: "\x1b[0m",
|
|
23
|
+
green: "\x1b[32m",
|
|
24
|
+
cyan: "\x1b[36m",
|
|
25
|
+
red: "\x1b[31m",
|
|
26
|
+
yellow: "\x1b[33m",
|
|
27
|
+
heading: "\x1b[1;32m",
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
function paint(code, value) {
|
|
31
|
+
if (
|
|
32
|
+
process.stdout.isTTY !== true ||
|
|
33
|
+
process.env.NO_COLOR !== undefined ||
|
|
34
|
+
process.env.CI
|
|
35
|
+
) {
|
|
36
|
+
return String(value);
|
|
37
|
+
}
|
|
38
|
+
return `${code}${value}${ANSI.reset}`;
|
|
39
|
+
}
|
|
21
40
|
|
|
22
41
|
export function defaultModelForProvider(provider) {
|
|
23
42
|
switch (provider) {
|
|
@@ -170,16 +189,30 @@ export function writeConfigFile(file, values) {
|
|
|
170
189
|
fs.writeFileSync(file, `${lines.join("\n")}\n`, { mode: 0o600 });
|
|
171
190
|
}
|
|
172
191
|
|
|
192
|
+
export function heading(message = "") {
|
|
193
|
+
return paint(ANSI.heading, message);
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
export function formatLabel(label, value, width = 11) {
|
|
197
|
+
return `${paint(ANSI.cyan, `${label}:`.padEnd(width))}${value}`;
|
|
198
|
+
}
|
|
199
|
+
|
|
173
200
|
export function step(message = "") {
|
|
174
|
-
console.log(
|
|
201
|
+
console.log(`${paint(ANSI.cyan, "→")} ${message}`);
|
|
175
202
|
}
|
|
176
203
|
|
|
177
204
|
export function ok(message = "") {
|
|
178
|
-
console.log(
|
|
205
|
+
console.log(`${paint(ANSI.green, "✓")} ${message}`);
|
|
179
206
|
}
|
|
180
207
|
|
|
181
208
|
export function fail(message = "") {
|
|
182
|
-
console.error(
|
|
209
|
+
console.error(`${paint(ANSI.red, "✗")} ${message}`);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
// Goes to stdout, not stderr: a warning accompanies work that still succeeded,
|
|
213
|
+
// so it must not make a passing command look failed to a caller reading stderr.
|
|
214
|
+
export function warn(message = "") {
|
|
215
|
+
console.log(`${paint(ANSI.yellow, "!")} ${message}`);
|
|
183
216
|
}
|
|
184
217
|
|
|
185
218
|
export function die(message) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "passcontrol",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
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",
|