passcontrol 0.9.1 → 0.9.2

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
@@ -1,6 +1,6 @@
1
1
  # PassControl
2
2
 
3
- PassControl **0.9.0** is an identity and credential gateway for AI agents. It keeps
3
+ PassControl is an identity and credential gateway for AI agents. It keeps
4
4
  provider API keys out of agent configuration and applies per-agent scopes, policies,
5
5
  budgets, and stop controls before forwarding model requests.
6
6
 
@@ -44,7 +44,7 @@ Passport sender-proof modes are **off**, **observe**, and **required**. Off igno
44
44
  proofs; observe records what would pass without enforcing it; required rejects missing,
45
45
  invalid, stale, or replayed proofs. Only enforced success is recorded as
46
46
  `passport_proof_per_request`; observing a valid proof does not upgrade authentication.
47
- The 0.9.0 sidecar supplies proofs; the direct CLI call, MCP chat, and TypeScript SDK
47
+ The sidecar supplies proofs; the direct CLI call, MCP chat, and TypeScript SDK
48
48
  do not attach them and cannot use required mode without an additional proof implementation.
49
49
  Proofs do **not** bind the request body or query string and do not attest hardware or
50
50
  key storage. See [authentication and lifecycle](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md).
@@ -164,7 +164,7 @@ output; it does not exercise a billed provider.
164
164
  With Node installed:
165
165
 
166
166
  ```bash
167
- npm install -g passcontrol@0.9.0
167
+ npm install -g passcontrol
168
168
  passcontrol login
169
169
  ```
170
170
 
@@ -77,6 +77,7 @@ import {
77
77
  checkIssuerPublishesKey,
78
78
  generateInstanceKey,
79
79
  instanceKidFromSeed,
80
+ retiredKeyEntry,
80
81
  } from "../cli/instance-key.mjs";
81
82
  import { FAILURE_REASONS, verifyAgentToken, verifyReceipt, verifyStatement } from "../cli/verify.mjs";
82
83
  import { compareProtocolSets } from "../cli/protocols.mjs";
@@ -216,6 +217,9 @@ ${heading("Trust")}
216
217
  ${cmd} key status show the local passport key storage tier
217
218
  ${cmd} key migrate move a tier 0 file key into the OS credential store
218
219
  ${cmd} keygen instance create the receipt-signing key
220
+ ${cmd} keygen instance --retire <seed>
221
+ print the public entry that keeps a rotated-out
222
+ key's receipts verifiable
219
223
  ${cmd} verify receipt <jws> --issuer <origin>
220
224
  verify a signed call receipt
221
225
  ${cmd} verify token <jwt> --audience <aud> --issuer <origin>
@@ -1039,7 +1043,18 @@ async function startDashboard(opts = {}) {
1039
1043
  const logPath = dashboardLogPath();
1040
1044
  fs.mkdirSync(path.dirname(statePath), { recursive: true, mode: 0o700 });
1041
1045
  const logFd = fs.openSync(logPath, "a", 0o600);
1042
- const child = spawn(process.platform === "win32" ? "npm.cmd" : "npm", ["run", "dev:docker"], {
1046
+ // `node scripts/dev-docker.mjs` rather than `npm run dev:docker`: identical
1047
+ // work (that is all the npm script is now), minus two wrapper processes. The
1048
+ // pid recorded below is then the dev server itself, which matters because
1049
+ // stopDashboard signals a single pid on Windows rather than a process group —
1050
+ // through npm.cmd it would kill the wrapper and leave the server holding the
1051
+ // port. It also keeps the one path that runs daily clear of the Windows
1052
+ // batch-file spawn restriction that batchFileShell exists to work around.
1053
+ const devServer = path.join(appRoot, "scripts", "dev-docker.mjs");
1054
+ if (!fs.existsSync(devServer)) {
1055
+ 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.`);
1056
+ }
1057
+ const child = spawn(process.execPath, [devServer], {
1043
1058
  cwd: appRoot,
1044
1059
  detached: process.platform !== "win32",
1045
1060
  env: { ...process.env, PORT: String(dashboard.port) },
@@ -1185,9 +1200,22 @@ async function localLogsCommand(opts = {}) {
1185
1200
  });
1186
1201
  }
1187
1202
 
1203
+ // Windows will not spawn a `.cmd`/`.bat` without a shell. Since Node 18.20.2 /
1204
+ // 20.12.2 (the CVE-2024-27980 hardening) it refuses outright with EINVAL rather
1205
+ // than executing it, which is how `passcontrol setup` died on the very first
1206
+ // step with nothing but `✗ spawn EINVAL` to go on.
1207
+ //
1208
+ // Scoped to batch files ON PURPOSE, not applied to every spawn. `runCommand`
1209
+ // also carries `docker compose -f docker/compose.yml` and `supabase start`;
1210
+ // routing those through cmd.exe would re-introduce shell quoting to arguments
1211
+ // that today are passed as an array and are safe in a path containing spaces.
1212
+ function batchFileShell(command) {
1213
+ return process.platform === "win32" && /\.(cmd|bat)$/i.test(command) ? { shell: true } : {};
1214
+ }
1215
+
1188
1216
  async function runCommand(command, args, { cwd = appRoot, env = process.env } = {}) {
1189
1217
  await new Promise((resolve, reject) => {
1190
- const child = spawn(command, args, { cwd, env, stdio: "inherit" });
1218
+ const child = spawn(command, args, { cwd, env, stdio: "inherit", ...batchFileShell(command) });
1191
1219
  child.once("error", reject);
1192
1220
  child.once("exit", (code) => code === 0 ? resolve() : reject(new Error(`${command} exited with code ${code}.`)));
1193
1221
  });
@@ -2355,12 +2383,35 @@ async function statementsCommand(opts) {
2355
2383
  );
2356
2384
  }
2357
2385
 
2358
- async function keygenCommand(rest) {
2386
+ async function keygenCommand(rest, opts = {}) {
2359
2387
  const target = rest[0];
2360
2388
  if (target !== "instance") {
2361
2389
  throw new Error(`Usage: ${cliCommand("keygen instance")}`);
2362
2390
  }
2363
2391
 
2392
+ // `--retire <seed>` prints the public pair for a key being taken out of
2393
+ // service. Nothing about it is secret, and that is the point: the operator
2394
+ // has no other way to derive a public half, and the alternative they reach
2395
+ // for — pasting the seed — is 32 base64url bytes too.
2396
+ // From `opts`, not `rest`: parseArgv consumes every `--flag` and its value
2397
+ // before the command ever sees the array, so scanning `rest` for "--retire"
2398
+ // finds nothing and silently generates a NEW key instead — which, run against
2399
+ // a live deployment's seed, looks like it worked.
2400
+ if (opts.retire !== undefined) {
2401
+ const seed = typeof opts.retire === "string" ? opts.retire : "";
2402
+ if (!seed) throw new Error(`Usage: ${cliCommand("keygen instance --retire <seed>")}`);
2403
+ const { entry, kid } = retiredKeyEntry(seed);
2404
+ ok(`Retired key ${kid}.`);
2405
+ step("Append this to INSTANCE_SIGNING_KEY_HISTORY (comma-separated) and leave it there");
2406
+ step("forever — receipts carry no expiry, so this is what keeps old ones checkable:");
2407
+ console.log(` ${entry}`);
2408
+ console.log("");
2409
+ step("It is a PUBLIC key. It cannot sign, which is why history takes this and not the");
2410
+ step("seed: a retired seed left in configuration can mint new receipts under the old kid.");
2411
+ step("Delete the seed once this is in place.");
2412
+ return;
2413
+ }
2414
+
2364
2415
  const { seed, kid } = generateInstanceKey();
2365
2416
  ok("Generated an Ed25519 instance signing key.");
2366
2417
  step("This key signs call receipts and agent-to-agent tokens. Store the seed like a password:");
@@ -2370,10 +2421,14 @@ async function keygenCommand(rest) {
2370
2421
  step("Also set PASSCONTROL_ISSUER to this deployment's https origin — it becomes the");
2371
2422
  step("`iss` claim, and the origin other deployments use to find this one's JWKS.");
2372
2423
  step("");
2373
- step("Rotating? Move the current value to INSTANCE_SIGNING_KEY_PREV and keep it there.");
2374
- step("Unlike VISA_SECRET_PREV we never sign with it — its public key stays published so");
2375
- step("receipts signed before the rotation still verify. Publish the new key, wait one");
2376
- step("JWKS max-age window, then start signing with it.");
2424
+ step("Rotating? Two steps, and the FIRST is the one that lasts:");
2425
+ step(` 1. ${cliCommand("keygen instance --retire <the old seed>")} — append the pair it prints`);
2426
+ step(" to INSTANCE_SIGNING_KEY_HISTORY. That list is permanent and public-only.");
2427
+ step(" 2. Move the old seed to INSTANCE_SIGNING_KEY_PREV for the changeover, then delete it.");
2428
+ step("Unlike VISA_SECRET_PREV we never sign with either — their public keys stay published");
2429
+ step("so receipts signed before the rotation still verify. _PREV holds ONE generation, so");
2430
+ step("history is what keeps the receipts from the rotation before this one checkable.");
2431
+ step("Publish the new key, wait one JWKS max-age window, then start signing with it.");
2377
2432
  }
2378
2433
 
2379
2434
  function passportFileForMigration() {
@@ -2546,11 +2601,32 @@ async function importCommand(rest = [], opts = {}) {
2546
2601
  );
2547
2602
  }
2548
2603
 
2604
+ // The envelope, before anything is planned or sent.
2605
+ //
2606
+ // This used to be `snapshot.workspace?.agents ?? []`, which turns a truncated
2607
+ // file into an empty fleet: the API plans nothing, `every()` over an empty
2608
+ // plan is true, the report says `complete: true`, and the CLI prints "Nothing
2609
+ // to create." and exits 0. A damaged snapshot restored no fleet at all and
2610
+ // every surface reported success (T4-03). A MISSING agents collection is
2611
+ // corruption; an EMPTY one is a workspace that genuinely has no agents and
2612
+ // still imports fine.
2613
+ //
2614
+ // The server validates this independently — it has to, since anyone can curl
2615
+ // it — but the operator holding the damaged file is here, so this is where the
2616
+ // message can name the file and say what is wrong with it.
2617
+ if (!Array.isArray(snapshot.workspace?.agents)) {
2618
+ throw new Error(
2619
+ `${file} has no "workspace.agents" array. That is a truncated or damaged export, ` +
2620
+ `not an empty workspace — importing it would restore nothing and report success. ` +
2621
+ `Re-export from the source deployment.`
2622
+ );
2623
+ }
2624
+
2549
2625
  // Only what the import writes goes on the wire. Provider mappings, break-glass
2550
2626
  // grants, the exclusions prose and the display settings stay on disk — they
2551
2627
  // are not importable, so sending them would spend the size budget on bytes the
2552
2628
  // server ignores.
2553
- const agents = snapshot.workspace?.agents ?? [];
2629
+ const agents = snapshot.workspace.agents;
2554
2630
  const payload = { agents, ownership: snapshot.workspace?.ownership ?? null };
2555
2631
  const size = Buffer.byteLength(JSON.stringify(payload));
2556
2632
  if (size > IMPORT_BODY_LIMIT) {
@@ -3141,7 +3217,7 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
3141
3217
  await openDashboard(opts);
3142
3218
  break;
3143
3219
  case "keygen":
3144
- await keygenCommand(commandRest);
3220
+ await keygenCommand(commandRest, opts);
3145
3221
  break;
3146
3222
  case "key":
3147
3223
  await keyCommand(commandRest, opts);
@@ -27,6 +27,24 @@ export function generateInstanceKey() {
27
27
  return { seed, kid: instanceKidFromSeed(seed) };
28
28
  }
29
29
 
30
+ /**
31
+ * Turn a retiring SEED into the `<kid>:<x>` pair that goes in
32
+ * INSTANCE_SIGNING_KEY_HISTORY — public half only, so a retired key can never
33
+ * sign again.
34
+ *
35
+ * This exists because the operator cannot derive a public key by hand. Without
36
+ * it they would paste the seed, which is also 32 base64url bytes and would sail
37
+ * through any length check; the app rejects that pair because the kid does not
38
+ * recompute, but "rejected" only helps if there is a right value to type
39
+ * instead. Throws on anything that is not a 32-byte seed.
40
+ */
41
+ export function retiredKeyEntry(seed) {
42
+ const bytes = fromB64url(seed);
43
+ if (bytes.length !== 32) throw new Error("A signing seed is 32 bytes, base64url-encoded.");
44
+ const x = b64url(ed25519.getPublicKey(bytes));
45
+ return { entry: `${instanceKidFromSeed(seed)}:${x}`, kid: instanceKidFromSeed(seed) };
46
+ }
47
+
30
48
  /**
31
49
  * Verify that PASSCONTROL_ISSUER resolves to a deployment publishing OUR key.
32
50
  *
@@ -22,7 +22,11 @@ const MACOS_PASSWORD_PROMPT = /password data for new item/iu;
22
22
  * exists for the same reason — so that check costs under a second instead of the
23
23
  * full helper timeout.
24
24
  */
25
- export function runProcess(command, args, { input = "", env = {}, timeoutMs = COMMAND_TIMEOUT_MS } = {}) {
25
+ export function runProcess(
26
+ command,
27
+ args,
28
+ { input = "", env = {}, timeoutMs = COMMAND_TIMEOUT_MS, detached = false } = {}
29
+ ) {
26
30
  const result = spawnSync(command, args, {
27
31
  input,
28
32
  encoding: "utf8",
@@ -31,6 +35,11 @@ export function runProcess(command, args, { input = "", env = {}, timeoutMs = CO
31
35
  maxBuffer: 64 * 1024,
32
36
  env: { ...process.env, ...env },
33
37
  stdio: ["pipe", "pipe", "pipe"],
38
+ // `detached` puts the child in its own session (setsid), which leaves it with
39
+ // NO controlling terminal. Only one caller wants that and it is documented at
40
+ // that call site; it is off by default because on Windows the same flag opens
41
+ // a new console window, which no adapter here has any use for.
42
+ detached,
34
43
  });
35
44
  // Deliberately omit stderr and the native Error object. Helpers sometimes
36
45
  // repeat their input in diagnostics, and no caller may log that raw text.
@@ -159,10 +168,23 @@ export function createPassportCredentialStore({
159
168
  if (/[\r\n]/u.test(secret)) {
160
169
  return fixedFailure("macOS Keychain cannot store a key containing a newline");
161
170
  }
171
+ // `detached` is what makes the stdin above reachable, and without it none
172
+ // of the reasoning in the comment above holds. Given a controlling
173
+ // terminal, security(1) does not read the prompt from stdin at all — it
174
+ // opens /dev/tty and asks the human, so the pipe is ignored, the write
175
+ // stalls until the helper timeout, and the key never lands. Detaching the
176
+ // child into its own session removes the terminal it would have reached
177
+ // for, and it falls back to stdin, which is where the secret already is.
178
+ //
179
+ // The consequence of getting this wrong is not a flaky test: it is that
180
+ // the feature works in every context that has no tty — CI, an agent shell,
181
+ // a piped script — and fails in the ONLY context that has one, which is a
182
+ // person at a terminal. tests/passport-key-store-os.test.ts owns a pty for
183
+ // exactly this reason.
162
184
  const result = invoke(run,
163
185
  "security",
164
186
  ["add-generic-password", "-U", "-a", passportId, "-s", SERVICE, "-w"],
165
- { input: `${secret}\n${secret}\n` }
187
+ { input: `${secret}\n${secret}\n`, detached: true }
166
188
  );
167
189
  if (result.timedOut) {
168
190
  // The one place the prompt bit earns its keep: `security` stalling
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "0.9.1",
3
+ "version": "0.9.2",
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",