passcontrol 0.3.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,10 +49,21 @@ 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
- ### Try it in 60 seconds (no key, no signup)
53
- The lowest-friction way to see what PassControl does — a **governed AI call and a live
54
- kill switch, with no provider key and no account**. Enable demo mode when you bring the
55
- local stack up:
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:
56
67
 
57
68
  ```bash
58
69
  git clone https://github.com/<you>/passcontrol && cd passcontrol
@@ -62,35 +73,34 @@ PASSCONTROL_DEMO=1 npm run dev:docker & # run the gateway with demo mode on
62
73
  npx passcontrol try # governed call → arm kill switch → blocked → disarm
63
74
  ```
64
75
 
65
- `passcontrol try` runs the **real** pipeline (passport → work-visa → scope + budget
66
- checks), returns a synthesized `[demo]` response instead of calling a provider, then arms
67
- the kill switch and shows the same call get blocked — the whole PassControl story in one
68
- command. Demo mode is **off by default and must never be enabled in production**: the
69
- keyless `demo` provider is env-gated and never touches the Vault. Ready to use it for
70
- real? Continue with the full quickstart below.
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.
71
81
 
72
82
  ### Local (Docker) quickstart
73
83
  For the fastest local run, use the bundled Docker stack. It starts Supabase locally
74
84
  (Postgres + Vault + Auth), Redis-over-REST, applies migrations inside the DB container, and
75
- seeds a confirmed dev user. Prereqs: Docker Desktop and the Supabase CLI. No host `psql`
76
- is required.
85
+ prompts you to create your Control Tower account. Prereqs: Docker Desktop and the Supabase
86
+ CLI. No host `psql` is required.
77
87
 
78
88
  ```bash
79
89
  git clone https://github.com/<you>/passcontrol && cd passcontrol
80
90
  npm install
81
- 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
82
92
  npm run dev:docker # runs the app against the local stack (loads .env.docker)
83
93
  ```
84
94
 
85
95
  > Use **`npm run dev:docker`**, not `npm run dev`, for the local stack — plain `npm run
86
96
  > dev` loads `.env.local` (your hosted Supabase), not the Docker stack's `.env.docker`.
87
97
 
88
- 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.
89
101
 
90
- ```text
91
- dev@passcontrol.local
92
- passcontrol-dev
93
- ```
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.
94
104
 
95
105
  Then add a provider key in the Control Tower, issue a passport, and run:
96
106
 
@@ -102,6 +112,12 @@ node examples/chat-agent.mjs "Say hello in 3 words"
102
112
  The final agent call uses your real Anthropic/OpenAI key from the local Vault, so start
103
113
  with a non-critical key.
104
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
+
105
121
  ### Manual self-host quickstart
106
122
 
107
123
  > **Supabase specifically** (not vanilla Postgres): the credential vault uses the
@@ -26,6 +26,7 @@ import {
26
26
  requireControlApiKey,
27
27
  requirePassport,
28
28
  step,
29
+ warn,
29
30
  writeConfigFile,
30
31
  } from "../cli/config.mjs";
31
32
  import {
@@ -118,7 +119,7 @@ ${heading("Usage:")}
118
119
  ${cmd} init [--global] create a config profile
119
120
  ${cmd} status [--no-network] show active config
120
121
  ${cmd} start start the configured local dashboard
121
- ${cmd} stop stop the CLI-managed local dashboard
122
+ ${cmd} stop [--dashboard-only] stop the whole local stack (dashboard + Supabase + Redis)
122
123
  ${cmd} restart restart the CLI-managed local dashboard
123
124
  ${cmd} local-logs [--follow] show local dashboard logs
124
125
  ${cmd} doctor [--deep] [--fix] check local setup and repair a stopped dashboard
@@ -126,6 +127,8 @@ ${heading("Usage:")}
126
127
  destroy and recreate the local stack
127
128
  ${cmd} setup [--no-open] [--port-offset N] [--app-dir DIR]
128
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
129
132
  ${cmd} try 60-second demo: governed keyless call + kill switch (no key)
130
133
  ${cmd} call "hi" mint a visa and call a model
131
134
  ${cmd} sidecar [--port 8788] start the local agent bridge
@@ -149,7 +152,10 @@ ${heading("Usage:")}
149
152
  ${heading("Config:")}
150
153
  Env vars win, then nearest .passcontrol, then ~/.config/passcontrol/config.
151
154
  Installed globally, the local-stack commands (setup/start/reset) use a cloned
152
- 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\`).
153
159
  `;
154
160
  }
155
161
 
@@ -259,31 +265,50 @@ function saveAppRoot(dir) {
259
265
  fs.writeFileSync(statePath, `${JSON.stringify({ path: dir, savedAt: new Date().toISOString() })}\n`, { mode: 0o600 });
260
266
  }
261
267
 
268
+ function forgetAppRoot() {
269
+ const saved = readSavedAppRoot();
270
+ fs.rmSync(appRootStatePath(), { force: true });
271
+ return saved;
272
+ }
273
+
262
274
  // Precedence: explicit env override → the surrounding checkout (npm run cli --) →
263
- // a previously cloned/saved checkout. Returns null when the CLI is installed
264
- // globally and no stack has been set up yet.
265
- 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() {
266
281
  const envRoot = process.env.PASSCONTROL_APP_ROOT?.trim();
267
282
  if (envRoot) {
268
283
  const abs = path.resolve(envRoot);
269
284
  if (!isRepoCheckout(abs)) {
270
285
  throw new Error(`PASSCONTROL_APP_ROOT=${envRoot} is not a PassControl checkout (missing scripts/dev-stack.sh).`);
271
286
  }
272
- 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" };
273
291
  }
274
- if (process.env.PASSCONTROL_FORCE_INSTALLED !== "1" && isRepoCheckout(PACKAGE_ROOT)) return PACKAGE_ROOT;
275
292
  const saved = readSavedAppRoot();
276
- 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
+ }
277
296
  return null;
278
297
  }
279
298
 
299
+ function resolveAppRoot() {
300
+ return resolveAppRootSource()?.path ?? null;
301
+ }
302
+
280
303
  function defaultAppDir() {
281
304
  return path.join(os.homedir(), "passcontrol");
282
305
  }
283
306
 
284
307
  function appRootLabel() {
285
308
  try {
286
- 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})`;
287
312
  } catch (error) {
288
313
  return error.message;
289
314
  }
@@ -364,15 +389,35 @@ async function confirmYes(question) {
364
389
  // installed globally. `clone: false` never clones — it errors with a pointer to
365
390
  // `passcontrol setup` (used by reset/doctor, where there's nothing yet to act on).
366
391
  async function ensureAppRoot({ clone = false, appDir, yes = false } = {}) {
367
- if (appRoot) return appRoot;
368
- const resolved = resolveAppRoot();
369
- if (resolved) {
370
- 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;
371
406
  return appRoot;
372
407
  }
408
+ if (appRoot) return appRoot;
409
+ if (!explicit) {
410
+ const resolved = resolveAppRoot();
411
+ if (resolved) {
412
+ appRoot = resolved;
413
+ return appRoot;
414
+ }
415
+ }
373
416
  if (!clone) {
374
417
  throw new Error(
375
- `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.`
376
421
  );
377
422
  }
378
423
 
@@ -383,7 +428,9 @@ async function ensureAppRoot({ clone = false, appDir, yes = false } = {}) {
383
428
  );
384
429
  }
385
430
 
386
- 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());
387
434
  if (fs.existsSync(target) && fs.readdirSync(target).length) {
388
435
  if (isRepoCheckout(target)) {
389
436
  saveAppRoot(target);
@@ -652,6 +699,68 @@ async function stopDashboard() {
652
699
  ok(`stopped CLI-managed dashboard (PID ${state.pid})`);
653
700
  }
654
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
+
655
764
  async function restartDashboard(opts = {}) {
656
765
  localDashboard();
657
766
  const managed = runningManagedDashboard();
@@ -696,6 +805,37 @@ async function runLocalCommand(command, args, env = process.env) {
696
805
  await runCommand(command, args, { cwd: appRoot, env });
697
806
  }
698
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
+
699
839
  async function resetLocalStack(opts = {}) {
700
840
  if (opts.local !== true) {
701
841
  throw new Error("Usage: passcontrol reset --local --confirm RESET");
@@ -734,7 +874,7 @@ async function setupLocal(opts = {}) {
734
874
  await startDashboard(opts);
735
875
  if (!opts.noOpen) await openDashboard(opts);
736
876
  console.log(`\n${formatLabel("Local dashboard", dashboard.url, 19)}`);
737
- console.log(formatLabel("Local-only login", "dev@passcontrol.local / passcontrol-dev", 19));
877
+ console.log(formatLabel("Login", "the account you created during setup", 19));
738
878
  step("Add a non-critical provider key, issue a passport, then run `passcontrol doctor --deep`.");
739
879
  }
740
880
 
@@ -1455,7 +1595,7 @@ async function main() {
1455
1595
  await startDashboard(opts);
1456
1596
  break;
1457
1597
  case "stop":
1458
- await stopDashboard();
1598
+ await stopCommand(opts);
1459
1599
  break;
1460
1600
  case "restart":
1461
1601
  await restartDashboard(opts);
@@ -1469,6 +1609,9 @@ async function main() {
1469
1609
  case "setup":
1470
1610
  await setupLocal(opts);
1471
1611
  break;
1612
+ case "unlink":
1613
+ unlinkCommand();
1614
+ break;
1472
1615
  case "call":
1473
1616
  await callCommand(commandRest, opts);
1474
1617
  break;
package/cli/config.mjs CHANGED
@@ -23,6 +23,7 @@ const ANSI = {
23
23
  green: "\x1b[32m",
24
24
  cyan: "\x1b[36m",
25
25
  red: "\x1b[31m",
26
+ yellow: "\x1b[33m",
26
27
  heading: "\x1b[1;32m",
27
28
  };
28
29
 
@@ -208,6 +209,12 @@ export function fail(message = "") {
208
209
  console.error(`${paint(ANSI.red, "✗")} ${message}`);
209
210
  }
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}`);
216
+ }
217
+
211
218
  export function die(message) {
212
219
  fail(message);
213
220
  process.exit(1);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "0.3.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",