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 +3 -3
- package/bin/passcontrol.mjs +85 -9
- package/cli/instance-key.mjs +18 -0
- package/cli/passport-key-store.mjs +24 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# PassControl
|
|
2
2
|
|
|
3
|
-
PassControl
|
|
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
|
|
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
|
|
167
|
+
npm install -g passcontrol
|
|
168
168
|
passcontrol login
|
|
169
169
|
```
|
|
170
170
|
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -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
|
-
|
|
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?
|
|
2374
|
-
step("
|
|
2375
|
-
step("
|
|
2376
|
-
step("
|
|
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
|
|
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);
|
package/cli/instance-key.mjs
CHANGED
|
@@ -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(
|
|
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