passcontrol 0.9.4 → 0.9.5

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.
@@ -47,6 +47,7 @@ import {
47
47
  probeGatewayOrigin,
48
48
  requirePassportGateway,
49
49
  requirePassport,
50
+ shellQuotingHint,
50
51
  step,
51
52
  warn,
52
53
  writeConfigFile,
@@ -1248,13 +1249,28 @@ async function startDashboard(opts = {}) {
1248
1249
  // work (that is all the npm script is now), minus npm/cmd wrappers. Next's CLI
1249
1250
  // still forks its HTTP worker, so this pid is deliberately the SUPERVISOR.
1250
1251
  // Unix stops its process group; Windows uses taskkill /T for the whole tree.
1252
+ //
1253
+ // `detached` is set on BOTH platforms, and the two reasons are different.
1254
+ // Unix needs it for the process group `stopDashboard` signals with kill(-pid).
1255
+ // Windows needs it for something else entirely: it is what lets the child
1256
+ // outlive us at all. This read `process.platform !== "win32"` — detached only
1257
+ // on Unix, on the reasoning that Windows takes its tree from taskkill and so
1258
+ // has no use for a process group. True, and it answered the wrong question.
1259
+ //
1260
+ // `child.unref()` below only lets the PARENT exit; it does not let the child
1261
+ // survive. So on Windows `passcontrol start` raised the dashboard, waited for
1262
+ // it, truthfully printed "dashboard online" — waitForGateway requires a live
1263
+ // pid and an answering gateway on the same poll — and then killed it by
1264
+ // returning. `setup` did the same, which is worse: a first-run self-hoster is
1265
+ // handed a URL that stops working as they read it, with an empty log and no
1266
+ // error anywhere. Reported and reproduced on Windows 11, 2026-09-13.
1251
1267
  const devServer = path.join(appRoot, "scripts", "dev-docker.mjs");
1252
1268
  if (!fs.existsSync(devServer)) {
1253
1269
  throw new Error(`${devServer} is missing — this checkout is incomplete or predates the local-stack launcher. Re-clone, or run \`npm run dev:docker\` from ${appRoot} by hand.`);
1254
1270
  }
1255
1271
  const child = spawn(process.execPath, [devServer], {
1256
1272
  cwd: appRoot,
1257
- detached: process.platform !== "win32",
1273
+ detached: true,
1258
1274
  env: { ...process.env, PORT: String(dashboard.port) },
1259
1275
  stdio: ["ignore", logFd, logFd],
1260
1276
  });
@@ -1275,6 +1291,35 @@ async function startDashboard(opts = {}) {
1275
1291
  return dashboard;
1276
1292
  }
1277
1293
 
1294
+ /**
1295
+ * Take down pid and everything below it on Windows. Reports, never throws.
1296
+ *
1297
+ * `taskkill /T` WITHOUT `/F` asks politely, and asking needs somewhere to ask:
1298
+ * a `DETACHED_PROCESS` child has no console and no window, so Windows answers
1299
+ * "This process can only be terminated forcefully (with /F option)" and taskkill
1300
+ * exits NON-ZERO. `execFileSync` turns a non-zero exit into a throw.
1301
+ *
1302
+ * That throw is why `passcontrol stop --dashboard-only` refused on Windows the
1303
+ * moment the dashboard started being spawned detached: the catch around it only
1304
+ * rescued `ESRCH`, a POSIX errno a failing taskkill cannot produce, so it
1305
+ * rethrew and abandoned the stop eight lines above the `/F` escalation the
1306
+ * function already had. The two-stage design was right; the throw jumped stage
1307
+ * two. Reported from a Windows 11 box, 2026-09-13.
1308
+ *
1309
+ * So a non-zero exit is an ANSWER here, not an exception — it is how Windows
1310
+ * says "use /F" — and the caller decides what to do about it. Whether the
1311
+ * dashboard is actually down is settled by the port, not by this.
1312
+ */
1313
+ function windowsTaskkillTree(pid, { force }) {
1314
+ const args = ["/PID", String(pid), "/T", ...(force ? ["/F"] : [])];
1315
+ try {
1316
+ execFileSync("taskkill.exe", args, { encoding: "utf8", timeout: 10_000, windowsHide: true });
1317
+ return true;
1318
+ } catch {
1319
+ return false;
1320
+ }
1321
+ }
1322
+
1278
1323
  async function stopDashboard() {
1279
1324
  const state = runningManagedDashboard();
1280
1325
  if (!state) {
@@ -1282,34 +1327,32 @@ async function stopDashboard() {
1282
1327
  return;
1283
1328
  }
1284
1329
 
1285
- try {
1286
- if (process.platform === "win32") {
1287
- execFileSync("taskkill.exe", ["/PID", String(state.pid), "/T"], {
1288
- encoding: "utf8",
1289
- timeout: 10_000,
1290
- windowsHide: true,
1291
- });
1292
- } else process.kill(-state.pid, "SIGTERM");
1293
- } catch (error) {
1294
- if (error.code === "ESRCH") {
1295
- removeDashboardState();
1296
- ok("No CLI-managed local dashboard is running.");
1297
- return;
1330
+ if (process.platform === "win32") {
1331
+ // Politely first — it lets Next flush if anything is listening for it — but
1332
+ // escalate the instant taskkill says it cannot, rather than waiting out a
1333
+ // port that a refused kill is never going to release. The port check below
1334
+ // is still the authority, and still escalates on its own.
1335
+ if (!windowsTaskkillTree(state.pid, { force: false })) {
1336
+ windowsTaskkillTree(state.pid, { force: true });
1337
+ }
1338
+ } else {
1339
+ try {
1340
+ process.kill(-state.pid, "SIGTERM");
1341
+ } catch (error) {
1342
+ if (error.code === "ESRCH") {
1343
+ removeDashboardState();
1344
+ ok("No CLI-managed local dashboard is running.");
1345
+ return;
1346
+ }
1347
+ throw error;
1298
1348
  }
1299
- throw error;
1300
1349
  }
1301
1350
 
1302
1351
  if (!await waitForPortRelease(state.port)) {
1303
- if (process.platform === "win32") {
1304
- execFileSync("taskkill.exe", ["/PID", String(state.pid), "/T", "/F"], {
1305
- encoding: "utf8",
1306
- timeout: 10_000,
1307
- windowsHide: true,
1308
- });
1309
- }
1352
+ if (process.platform === "win32") windowsTaskkillTree(state.pid, { force: true });
1310
1353
  else process.kill(-state.pid, "SIGKILL");
1311
1354
  if (!await waitForPortRelease(state.port)) {
1312
- throw new Error(`Dashboard process group ${state.pid} did not release port ${state.port}.`);
1355
+ throw new Error(`Dashboard (PID ${state.pid}) did not release port ${state.port}.`);
1313
1356
  }
1314
1357
  }
1315
1358
  removeDashboardState();
@@ -2742,7 +2785,13 @@ async function passportCommand(rest, opts = {}) {
2742
2785
  const gateway = bareGatewayOrigin(opts.gateway, "--gateway");
2743
2786
  const passportId = opts.id.trim();
2744
2787
  if (!isEncodedEd25519Key(passportId)) {
2745
- throw new Error("--id must be a 32-byte Ed25519 public key encoded as unpadded base64url.");
2788
+ // Same hint as --gateway above, because it is the same operator on the same
2789
+ // line: cmd.exe hands both flags their quotes. The id at least refuses a
2790
+ // quoted value rather than storing one — base64url has no quote character —
2791
+ // so this only ever needed the explanation, never a repair.
2792
+ throw new Error(
2793
+ `--id must be a 32-byte Ed25519 public key encoded as unpadded base64url.${shellQuotingHint(passportId)}`
2794
+ );
2746
2795
  }
2747
2796
 
2748
2797
  const project = config.sources.find((source) =>
package/cli/config.mjs CHANGED
@@ -431,6 +431,42 @@ export function requireControlApiKey(current = config) {
431
431
  */
432
432
  const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
433
433
 
434
+ /**
435
+ * A value that still carries its own quote characters, explained.
436
+ *
437
+ * `cmd.exe` does not treat `'` as quoting. A Windows operator copying a POSIX
438
+ * invocation out of a README types `--gateway 'http://localhost:3000'` and the
439
+ * CLI receives those quotes as part of the argument — so a value that is right
440
+ * on the line they typed is refused by a message about the string that arrived.
441
+ * The same trap already broke `npm run dev:docker`, which was a bash one-liner
442
+ * in single quotes until cmd handed bash `'set` as its whole command; see the
443
+ * header of `scripts/dev-docker.mjs`.
444
+ *
445
+ * Deliberately a hint and not a repair. The callers below validate values that
446
+ * decide where a credential is sent, and quietly normalizing an argument before
447
+ * a strict rule sees it is how strict rules stop being strict. This only
448
+ * explains the refusal.
449
+ *
450
+ * Returns a sentence to append, or "". It describes the shape and never the
451
+ * value: a gateway URL or a passport id can itself be a credential.
452
+ *
453
+ * @param {unknown} value
454
+ * @returns {string}
455
+ */
456
+ export function shellQuotingHint(value) {
457
+ const text = String(value ?? "");
458
+ if (text.length < 2) return "";
459
+ const quote = text[0];
460
+ if ((quote !== "'" && quote !== '"') || text[text.length - 1] !== quote) return "";
461
+ // Only single quotes get the cmd.exe sentence: cmd *does* strip double
462
+ // quotes, so a value that arrives wrapped in them came from a config file or
463
+ // another shell, and naming cmd would send the reader somewhere wrong.
464
+ const cause =
465
+ quote === "'" ? " Windows cmd.exe does not treat ' as quoting and passes it through literally." : "";
466
+ const name = quote === "'" ? "a single quote" : "a double quote";
467
+ return ` The value starts and ends with ${name}, so the quote characters are part of it.${cause} Retype it with no quotes around it.`;
468
+ }
469
+
434
470
  /**
435
471
  * Validate a gateway value and return the origin to build URLs from.
436
472
  *
@@ -452,6 +488,11 @@ const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
452
488
  * prints the message and exits 1, and `doctor` catches it to report a failed
453
489
  * check instead of vanishing mid-diagnosis. The message never quotes the value,
454
490
  * because a rejected gateway can itself carry credentials.
491
+ *
492
+ * The unparseable branch appends `shellQuotingHint`, which the SDK has no reason
493
+ * to carry — it is never handed a cmd.exe argv. That is a message, not a rule:
494
+ * what this accepts and refuses is still identical to the SDK's, which is all
495
+ * the parity test asserts.
455
496
  */
456
497
  export function bareGatewayOrigin(gateway, label = "PASSCONTROL_GATEWAY") {
457
498
  let url;
@@ -459,7 +500,8 @@ export function bareGatewayOrigin(gateway, label = "PASSCONTROL_GATEWAY") {
459
500
  url = new URL(String(gateway ?? ""));
460
501
  } catch {
461
502
  throw new Error(
462
- `${label} must be an absolute URL (for example https://passcontrol.example.com).`
503
+ `${label} must be an absolute URL (for example https://passcontrol.example.com).` +
504
+ shellQuotingHint(gateway)
463
505
  );
464
506
  }
465
507
  const loopback = LOOPBACK_HOSTNAMES.has(url.hostname);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "0.9.4",
3
+ "version": "0.9.5",
4
4
  "description": "Identity, scope and budget controls for AI agents while provider keys stay server-side.",
5
5
  "license": "BUSL-1.1",
6
6
  "homepage": "https://passcontrol.vertias.eu",