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.
- package/README.md +423 -216
- package/bin/passcontrol.mjs +85 -19
- package/cli/config.mjs +57 -1
- package/cli/login.mjs +466 -0
- package/package.json +1 -1
package/bin/passcontrol.mjs
CHANGED
|
@@ -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
|
-
|
|
145
|
-
${cmd}
|
|
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}
|
|
155
|
-
${cmd}
|
|
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("
|
|
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
|
|
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
|
-
|
|
203
|
-
app checkout
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
914
|
-
|
|
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(
|
|
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
|
-
|
|
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 = "") {
|