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 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
- seeds a confirmed dev user. Prereqs: Docker Desktop and the Supabase CLI. No host `psql`
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, seeds a dev user
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
- Open `http://localhost:3000` and log in with:
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
- ```text
71
- dev@passcontrol.local
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
@@ -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 `PassControl
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 stop the CLI-managed local dashboard
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; override its location with PASSCONTROL_APP_ROOT.
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(`Gateway: ${gateway.label} ${config.gateway}`);
183
- console.log(`Dashboard: ${dashboardStatusLabel(gateway, noNetwork)}`);
184
- console.log(`App: ${appRootLabel()}`);
185
- console.log(`Config: ${configPathLabel(config.sources)}`);
186
- console.log(`Provider: ${config.provider}`);
187
- console.log(`Model: ${config.model}`);
188
- console.log(`Passport: ${passportConfigured ? redact(config.passportId) : "missing"}`);
189
- console.log(`Admin key: ${adminConfigured ? redact(config.apiKey, 6) : "missing"}`);
190
- console.log(`Sidecar: foreground command (\`${cliCommand("sidecar")}\`)\n`);
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. Returns null when the CLI is installed
251
- // globally and no stack has been set up yet.
252
- function resolveAppRoot() {
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)) return path.resolve(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
- return resolveAppRoot() ?? `not set up (run \`${cliCommand("setup")}\`)`;
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
- if (appRoot) return appRoot;
355
- const resolved = resolveAppRoot();
356
- if (resolved) {
357
- appRoot = resolved;
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
- `No PassControl app checkout found. Run \`${cliCommand("setup")}\` to clone and start it, or set PASSCONTROL_APP_ROOT to an existing checkout.`
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 = path.resolve(appDir || (interactive ? await promptLine(`Where should the PassControl app be cloned? [${defaultAppDir()}] `, defaultAppDir()) : defaultAppDir()));
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(`\nLocal dashboard: ${dashboard.url}`);
724
- console.log("Local-only login: dev@passcontrol.local / passcontrol-dev");
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 stopDashboard();
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(`→ ${message}`);
201
+ console.log(`${paint(ANSI.cyan, "→")} ${message}`);
175
202
  }
176
203
 
177
204
  export function ok(message = "") {
178
- console.log(`✓ ${message}`);
205
+ console.log(`${paint(ANSI.green, "✓")} ${message}`);
179
206
  }
180
207
 
181
208
  export function fail(message = "") {
182
- console.error(`✗ ${message}`);
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.2.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",