passcontrol 0.6.2 → 0.7.1

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.
@@ -8,6 +8,7 @@ import { createInterface } from "node:readline/promises";
8
8
  import { fileURLToPath } from "node:url";
9
9
  import { ed25519 } from "@noble/curves/ed25519";
10
10
  import {
11
+ CLOUD_GATEWAY,
11
12
  CONFIG_FILE,
12
13
  OPENAI_SHAPE_PROVIDERS,
13
14
  PROVIDERS,
@@ -52,6 +53,7 @@ import {
52
53
  import { importCompletionMessage, noAgentCreateMessage } from "../cli/workspace-import-report.mjs";
53
54
  import { checkForUpdate } from "../cli/update-check.mjs";
54
55
  import { startSidecar } from "../cli/sidecar.mjs";
56
+ import { loginCommand } from "../cli/login.mjs";
55
57
  import {
56
58
  checkIssuerPublishesKey,
57
59
  generateInstanceKey,
@@ -85,6 +87,14 @@ const DEMO_API_KEY = "pc_demolocaltrydemolocaltrydemolocaltry0000";
85
87
  const DASHBOARD_STATE_FILE = "local-dashboard.json";
86
88
  const APP_STATE_FILE = "app.json";
87
89
  const PUBLIC_REPO_URL = "https://github.com/Vertias3u/PassControl.git";
90
+ // The hosted demo. `try` cannot simply DEFAULT here: its second step arms and
91
+ // disarms the tenant kill switch, so concurrent visitors would collide on shared
92
+ // demo-tenant state and an aborted run would leave the public demo killed. It is
93
+ // offered as a browser link instead — the one zero-install way to see the
94
+ // pipeline when there is no local stack yet.
95
+ // One literal, in cli/config.mjs. The demo and the Cloud gateway are the same
96
+ // origin, and keeping two copies is how they stop being the same origin.
97
+ const HOSTED_DEMO_URL = CLOUD_GATEWAY;
88
98
  const LOCAL_DASHBOARD_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
89
99
  const LOCAL_STACK_PORTS = [54321, 54322, 54324, 54327, 8079];
90
100
  // The local stack (Supabase + Redis + dashboard) lives in a PassControl repo
@@ -141,19 +151,21 @@ ${heading("Usage:")}
141
151
  ${cmd} <command> [options]
142
152
 
143
153
  ${heading("Quick start")}
144
- ${cmd} init [--global] configure this project
145
- ${cmd} start [--dashboard-only] start the whole local stack (dashboard + Supabase + Redis)
146
- ${cmd} open start if needed and open the Control Tower
154
+ Cloud. No Docker, no database — this CLI is the only thing you install.
155
+ ${cmd} login [--project] sign in through your browser and set this machine up
147
156
  ${cmd} try run the 60-second keyless guided demo
157
+ ${cmd} call "hi" mint a visa and make a governed model call
158
+ ${cmd} mcp passport identity for Claude Desktop, Cursor, Claude Code
159
+ ${cmd} sidecar [--port 8788] [--allow-connect host[,host]]
160
+ passport identity for any tool that takes an api_key
148
161
 
149
162
  ${heading("Operate")}
150
163
  ${cmd} status [--no-network] [--json]
151
164
  show active config and instance state
152
165
  ${cmd} version [--json] CLI, gateway and database schema versions
153
166
  ${cmd} doctor [--deep] [--fix] diagnose setup and repair a stopped dashboard
154
- ${cmd} call "hi" mint a visa and make a governed model call
155
- ${cmd} sidecar [--port 8788] [--allow-connect host[,host]]
156
- start the local agent bridge
167
+ ${cmd} open open the Control Tower in a browser
168
+ ${cmd} init [--global] configure by hand, without a browser
157
169
 
158
170
  ${heading("Manage")}
159
171
  ${cmd} agent list [--json] list agents
@@ -177,7 +189,6 @@ ${heading("Integrate")}
177
189
  ${cmd} env [integration] print settings without writing anything
178
190
  ${cmd} configure <integration> [--write] [--force]
179
191
  preview or write integration config
180
- ${cmd} mcp start the stdio MCP server
181
192
  integrations: ${integrationChoices()}
182
193
 
183
194
  ${heading("Trust")}
@@ -187,9 +198,12 @@ ${heading("Trust")}
187
198
  ${cmd} verify token <jwt> --audience <aud> --issuer <origin>
188
199
  verify an agent-to-agent token
189
200
 
190
- ${heading("Local stack")}
201
+ ${heading("Self-host — run your own gateway")}
202
+ Clones the app and runs Docker + Supabase + Redis here. You operate it, and
203
+ your instance signs its own receipts — they verify against your JWKS, not ours.
191
204
  ${cmd} setup [--no-open] [--port-offset N] [--app-dir DIR]
192
- clone if needed, start services, open dashboard
205
+ clone the app, start Docker + Supabase + Redis
206
+ ${cmd} start [--dashboard-only] start the whole local stack (clones the app if missing)
193
207
  ${cmd} stop [--dashboard-only] stop the whole local stack (dashboard + Supabase + Redis)
194
208
  ${cmd} restart restart the CLI-managed local dashboard
195
209
  ${cmd} local-logs [--follow] show local dashboard logs
@@ -199,8 +213,8 @@ ${heading("Local stack")}
199
213
 
200
214
  ${heading("Config:")}
201
215
  Env vars win, then nearest .passcontrol, then ~/.config/passcontrol/config.
202
- Installed globally, the local-stack commands (setup/start/reset) use a cloned
203
- app checkout, resolved in this order:
216
+ Only the self-host commands (setup/start/reset) ever clone anything. Installed
217
+ globally, they resolve a cloned app checkout in this order:
204
218
  --app-dir DIR → PASSCONTROL_APP_ROOT → surrounding checkout → remembered
205
219
  checkout in ~/.config/passcontrol/app.json (survives npm uninstall; clear
206
220
  it with \`${cmd} unlink\`).
@@ -530,6 +544,14 @@ function checkDockerInstalled() {
530
544
  };
531
545
  }
532
546
 
547
+ // Every docker call the CLI makes needs a bound, not just the daemon probe. A
548
+ // wedged Docker Desktop leaves its CLI socket present and answers nothing, so an
549
+ // unbounded `docker ps` waits forever — which is how `doctor --deep` hung
550
+ // indefinitely on the very check that exists to REPORT a wedged engine. The
551
+ // value is the cold-start allowance argued for in checkDockerDaemon below;
552
+ // sharing it keeps one number rather than three that drift.
553
+ const DOCKER_TIMEOUT_MS = 15_000;
554
+
533
555
  function checkDockerDaemon() {
534
556
  if (!commandExists("docker")) {
535
557
  return {
@@ -548,7 +570,7 @@ function checkDockerDaemon() {
548
570
  // where Docker was available throughout, and it would tell a first-time user
549
571
  // on a slow laptop to go start something already running. A wedged engine
550
572
  // still gets caught; it just takes fifteen seconds to say so.
551
- execFileSync("docker", ["info"], { stdio: "ignore", timeout: 15_000 });
573
+ execFileSync("docker", ["info"], { stdio: "ignore", timeout: DOCKER_TIMEOUT_MS });
552
574
  return { ok: true, message: "Docker daemon: running." };
553
575
  } catch (error) {
554
576
  // A timeout and a stopped daemon need different things from the reader, so
@@ -594,9 +616,18 @@ async function promptLine(question, fallback) {
594
616
  }
595
617
  }
596
618
 
597
- async function confirmYes(question) {
619
+ /**
620
+ * Yes/no prompt. Enter means YES unless `{ default: false }` is passed.
621
+ *
622
+ * The option exists for one caller — `passcontrol login` asking before it
623
+ * replaces a passport secret. That answer is unrecoverable, so the reply an
624
+ * operator gives by reflex has to be the one that changes nothing. Every other
625
+ * caller keeps the enter-means-yes behaviour it was written against.
626
+ */
627
+ async function confirmYes(question, { default: fallback = true } = {}) {
598
628
  const answer = (await promptLine(question, "")).toLowerCase();
599
- return answer === "" || answer === "y" || answer === "yes";
629
+ if (answer === "") return fallback;
630
+ return answer === "y" || answer === "yes";
600
631
  }
601
632
 
602
633
  // Resolve the stack checkout, cloning the public repo on demand when the CLI is
@@ -694,7 +725,7 @@ function localSupabaseIsRunning() {
694
725
  execFileSync(
695
726
  "docker",
696
727
  ["ps", "-q", "--filter", `label=com.supabase.cli.project=${localSupabaseProjectId()}`, "--filter", "name=supabase_db"],
697
- { encoding: "utf8" }
728
+ { encoding: "utf8", timeout: DOCKER_TIMEOUT_MS }
698
729
  ).trim()
699
730
  );
700
731
  } catch {
@@ -863,7 +894,7 @@ function ownSupabaseDatabaseIsRunning(offset = 0) {
863
894
  if (!root) return false;
864
895
  const project = `${path.basename(root)}${offset ? `-${offset}` : ""}`;
865
896
  return Boolean(
866
- execFileSync("docker", ["ps", "-q", "--filter", `name=^/supabase_db_${project}$`], { encoding: "utf8" }).trim()
897
+ execFileSync("docker", ["ps", "-q", "--filter", `name=^/supabase_db_${project}$`], { encoding: "utf8", timeout: DOCKER_TIMEOUT_MS }).trim()
867
898
  );
868
899
  } catch {
869
900
  return false;
@@ -910,8 +941,16 @@ async function runLocalPrerequisiteChecks({ offset = 0, report = false, enforce
910
941
  }
911
942
 
912
943
  if (enforce) {
913
- const failure = results.find((result) => !result.ok);
914
- if (failure) throw new Error(failure.message);
944
+ // Every failure, not just the first. These checks are independent, and each
945
+ // one a first-time user hits is its own install-and-come-back detour; finding
946
+ // them one run at a time turns a single setup into three sittings. `results`
947
+ // already holds them all — only the reporting was lossy.
948
+ const failures = results.filter((result) => !result.ok);
949
+ if (failures.length > 0) {
950
+ // `fail()` marks the first line; the rest carry their own marker so a
951
+ // four-item list does not read as one failure with three stray sentences.
952
+ throw new Error(failures.map((failure) => failure.message).join("\n\u2717 "));
953
+ }
915
954
  }
916
955
  return results;
917
956
  }
@@ -1383,7 +1422,8 @@ async function tryCommand() {
1383
1422
  step(" PASSCONTROL_DEMO=1 npm run dev:docker # enables the keyless demo provider");
1384
1423
  } else {
1385
1424
  fail(`Could not reach the gateway at ${gateway} (${msg}).`);
1386
- step("Bring the local demo stack up first:");
1425
+ step(`Nothing installed yet? The same pipeline runs keyless in your browser: ${HOSTED_DEMO_URL}`);
1426
+ step("To run it here instead, bring the local demo stack up first:");
1387
1427
  step(" PASSCONTROL_DEMO=1 npm run dev:stack # Supabase + Redis + migrate + seed the demo passport");
1388
1428
  step(" PASSCONTROL_DEMO=1 npm run dev:docker # start the gateway with the demo provider enabled");
1389
1429
  }
@@ -2250,11 +2290,32 @@ async function openDashboard(opts = {}) {
2250
2290
  const url = parsed.protocol === "http:" && LOCAL_DASHBOARD_HOSTS.has(parsed.hostname)
2251
2291
  ? (await startDashboard(opts)).url
2252
2292
  : config.gateway;
2293
+ openUrl(url);
2294
+ }
2295
+
2296
+ /**
2297
+ * Open a URL in the operator's browser. Nothing else.
2298
+ *
2299
+ * Extracted from openDashboard because openDashboard is NOT a URL opener: for a
2300
+ * localhost gateway it routes through startDashboard, which is
2301
+ * `ensureAppRoot({ clone: true })`. Any new caller that reached for the obvious
2302
+ * function would have put a self-host `git clone` on the Cloud path — and
2303
+ * tests/cli-cloud-path-no-clone.test.ts could not have seen it, because that
2304
+ * guard pins DIRECT cloning callers and startDashboard is legitimately one.
2305
+ *
2306
+ * So this is the safe half, with no stack logic attached.
2307
+ * tests/cli-login-shape.test.ts pins both that it exists and that openDashboard
2308
+ * still delegates to it — a second hand-rolled spawn would pass the first check
2309
+ * and quietly lose the degradation below.
2310
+ */
2311
+ function openUrl(url) {
2253
2312
  const platform = process.platform;
2254
2313
  const command =
2255
2314
  platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
2256
2315
  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
2257
2316
  const child = spawn(command, args, { detached: true, stdio: "ignore" });
2317
+ // A headless box, a container, or a machine with no handler: say the URL out
2318
+ // loud rather than appearing to hang.
2258
2319
  child.on("error", () => step(`Open this URL: ${url}`));
2259
2320
  child.unref();
2260
2321
  ok(`opening ${url}`);
@@ -2416,6 +2477,11 @@ async function main() {
2416
2477
  case "status":
2417
2478
  await printCockpit({ noNetwork: Boolean(opts.noNetwork), json: Boolean(opts.json) });
2418
2479
  break;
2480
+ case "login":
2481
+ // openUrl, never openDashboard: the latter routes a localhost gateway
2482
+ // through startDashboard, which clones the self-host repo.
2483
+ await loginCommand(opts, { openUrl, promptLine, confirmYes });
2484
+ break;
2419
2485
  case "init":
2420
2486
  await initCommand(opts);
2421
2487
  break;
package/cli/config.mjs CHANGED
@@ -26,6 +26,20 @@ export const PROVIDERS = ["openai", "anthropic", "groq", "mistral", "together",
26
26
  export const OPENAI_SHAPE_PROVIDERS = new Set(["openai", "groq", "mistral", "together", "deepseek", "gemini"]);
27
27
 
28
28
  const DEFAULT_GATEWAY = "http://localhost:3000";
29
+
30
+ /**
31
+ * The hosted Cloud instance — the one origin this CLI knows by name.
32
+ *
33
+ * Declared HERE, once, because two copies drift: `bin/passcontrol.mjs` had the
34
+ * only literal (as `HOSTED_DEMO_URL`) and now imports this instead.
35
+ *
36
+ * It is NOT the same thing as DEFAULT_GATEWAY above, and the difference matters.
37
+ * DEFAULT_GATEWAY is what an already-configured operator falls back to while
38
+ * working locally. This is where a machine with NO configuration at all should
39
+ * be pointed — which is `passcontrol login` and nothing else, because login is
40
+ * the one command whose whole job is running before any config exists.
41
+ */
42
+ export const CLOUD_GATEWAY = "https://passcontrol.vertias.eu";
29
43
  const DEFAULT_PROVIDER = "anthropic";
30
44
  const CONFIG_KEYS = [
31
45
  "PASSCONTROL_GATEWAY",
@@ -225,8 +239,23 @@ export function configPathLabel(sources = configSources) {
225
239
  return "none";
226
240
  }
227
241
 
242
+ /**
243
+ * Write the whole config. Every CONFIG_KEY is emitted, so a key absent from
244
+ * `values` is BLANKED — that is correct for `init`, which collects all of them,
245
+ * and wrong for any caller that means to change a subset. Use mergeConfigFile
246
+ * for those.
247
+ *
248
+ * The chmod is not redundant with the `mode` option. Node applies `mode` only
249
+ * when it CREATES the file, so overwriting a config that already exists as 0644
250
+ * leaves it 0644 — and this file holds a passport secret. The directory mode is
251
+ * applied on the global path only: for a project-local `.passcontrol` the
252
+ * dirname is the user's own project directory, and silently 0700-ing that is a
253
+ * surprising thing for a config write to do.
254
+ */
228
255
  export function writeConfigFile(file, values) {
229
- fs.mkdirSync(path.dirname(file), { recursive: true });
256
+ const dir = path.dirname(file);
257
+ const isGlobal = path.resolve(file) === path.resolve(globalConfigPath());
258
+ fs.mkdirSync(dir, { recursive: true, ...(isGlobal ? { mode: 0o700 } : {}) });
230
259
  const lines = [
231
260
  "# PassControl CLI config.",
232
261
  "# Keep this file private: it can contain a passport secret.",
@@ -236,6 +265,33 @@ export function writeConfigFile(file, values) {
236
265
  lines.push(`${key}=${values[key] ?? ""}`);
237
266
  }
238
267
  fs.writeFileSync(file, `${lines.join("\n")}\n`, { mode: 0o600 });
268
+ // Explicit, because `mode` above is a no-op on an existing file.
269
+ try {
270
+ fs.chmodSync(file, 0o600);
271
+ if (isGlobal) fs.chmodSync(dir, 0o700);
272
+ } catch {
273
+ // Windows and some network filesystems have no meaningful POSIX mode. A
274
+ // config that is written but not tightened beats a login that dies here.
275
+ }
276
+ }
277
+
278
+ /**
279
+ * Change SOME keys, keeping the rest.
280
+ *
281
+ * `passcontrol login` writes three credential keys. Routing that through
282
+ * writeConfigFile would emit `PROVIDER=`, `MODEL=` and `PASSCONTROL_GATEWAY=`
283
+ * as empty strings and wipe a working setup — right result, wrong side effect,
284
+ * and invisible until the next call failed against the wrong provider.
285
+ */
286
+ export function mergeConfigFile(file, patch) {
287
+ let existing = {};
288
+ try {
289
+ existing = readConfigFile(file);
290
+ } catch {
291
+ // No file yet, or unreadable. A first login lands here, and writing the
292
+ // patch alone is exactly right — there is nothing to preserve.
293
+ }
294
+ writeConfigFile(file, { ...existing, ...patch });
239
295
  }
240
296
 
241
297
  export function heading(message = "") {