passcontrol 0.2.0 → 0.3.0

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
@@ -49,6 +49,26 @@ Stack: **Next.js** (App Router, edge routes) · **Supabase** (Postgres + Vault +
49
49
  **Upstash Redis**. Deploy on Vercel or any Node host (`next start`). No Vercel-proprietary
50
50
  services are required — the kill switch is Redis-backed.
51
51
 
52
+ ### Try it in 60 seconds (no key, no signup)
53
+ The lowest-friction way to see what PassControl does — a **governed AI call and a live
54
+ kill switch, with no provider key and no account**. Enable demo mode when you bring the
55
+ local stack up:
56
+
57
+ ```bash
58
+ git clone https://github.com/<you>/passcontrol && cd passcontrol
59
+ npm install
60
+ PASSCONTROL_DEMO=1 npm run dev:stack # local stack + a keyless demo passport
61
+ PASSCONTROL_DEMO=1 npm run dev:docker & # run the gateway with demo mode on
62
+ npx passcontrol try # governed call → arm kill switch → blocked → disarm
63
+ ```
64
+
65
+ `passcontrol try` runs the **real** pipeline (passport → work-visa → scope + budget
66
+ checks), returns a synthesized `[demo]` response instead of calling a provider, then arms
67
+ the kill switch and shows the same call get blocked — the whole PassControl story in one
68
+ command. Demo mode is **off by default and must never be enabled in production**: the
69
+ keyless `demo` provider is env-gated and never touches the Vault. Ready to use it for
70
+ real? Continue with the full quickstart below.
71
+
52
72
  ### Local (Docker) quickstart
53
73
  For the fastest local run, use the bundled Docker stack. It starts Supabase locally
54
74
  (Postgres + Vault + Auth), Redis-over-REST, applies migrations inside the DB container, and
@@ -16,9 +16,11 @@ import {
16
16
  configPathLabel,
17
17
  defaultModelForProvider,
18
18
  fail,
19
+ formatLabel,
19
20
  formatChallengeError,
20
21
  formatProxyError,
21
22
  globalConfigPath,
23
+ heading,
22
24
  ok,
23
25
  redact,
24
26
  requireControlApiKey,
@@ -48,6 +50,16 @@ const CLI_VERSION = (() => {
48
50
  return "0.0.0";
49
51
  }
50
52
  })();
53
+
54
+ // Fixed demo credentials for `passcontrol try` — LOCAL demo stack ONLY. The demo
55
+ // passport can only ever reach the keyless `demo` provider (no real key, no cost,
56
+ // no real upstream); the demo provider + these seeds exist only when the stack is
57
+ // brought up with PASSCONTROL_DEMO=1. Hardcoding them is safe, like the seeded dev
58
+ // password — they grant nothing in a real deployment.
59
+ // App-side source of truth: lib/demo/identity.ts (duplicated here to keep the shipped plain-ESM CLI transpilation-free).
60
+ const DEMO_PASSPORT_ID = "kZCFp7d2x4VDruiulJ21gogYbczBDAGZa-OuwR3qgh8";
61
+ const DEMO_PASSPORT_SECRET = "XqsVuXtmWiu6bKEmmqov2Q2TwkOVdzlZMWR-NWubSKo";
62
+ const DEMO_API_KEY = "pc_demolocaltrydemolocaltrydemolocaltry0000";
51
63
  const DASHBOARD_STATE_FILE = "local-dashboard.json";
52
64
  const APP_STATE_FILE = "app.json";
53
65
  const PUBLIC_REPO_URL = "https://github.com/Vertias3u/PassControl.git";
@@ -99,9 +111,9 @@ function cliCommand(args = "") {
99
111
 
100
112
  function usage() {
101
113
  const cmd = cliPrefix();
102
- return `PassControl
114
+ return `${heading("PassControl")}
103
115
 
104
- Usage:
116
+ ${heading("Usage:")}
105
117
  ${cmd} show cockpit status
106
118
  ${cmd} init [--global] create a config profile
107
119
  ${cmd} status [--no-network] show active config
@@ -114,6 +126,7 @@ Usage:
114
126
  destroy and recreate the local stack
115
127
  ${cmd} setup [--no-open] [--port-offset N] [--app-dir DIR]
116
128
  clone the app (if needed), start local services, open the dashboard
129
+ ${cmd} try 60-second demo: governed keyless call + kill switch (no key)
117
130
  ${cmd} call "hi" mint a visa and call a model
118
131
  ${cmd} sidecar [--port 8788] start the local agent bridge
119
132
  ${cmd} mcp start the local stdio MCP server
@@ -133,7 +146,7 @@ Usage:
133
146
  ${cmd} kill on|off toggle tenant kill switch
134
147
  ${cmd} open start (if needed) and open the dashboard
135
148
 
136
- Config:
149
+ ${heading("Config:")}
137
150
  Env vars win, then nearest .passcontrol, then ~/.config/passcontrol/config.
138
151
  Installed globally, the local-stack commands (setup/start/reset) use a cloned
139
152
  app checkout; override its location with PASSCONTROL_APP_ROOT.
@@ -178,17 +191,17 @@ async function printCockpit({ noNetwork = false } = {}) {
178
191
  const passportConfigured = Boolean(config.passportId && config.passportSecret);
179
192
  const adminConfigured = Boolean(config.apiKey);
180
193
 
181
- console.log("PassControl\n");
182
- console.log(`Gateway: ${gateway.label} ${config.gateway}`);
183
- console.log(`Dashboard: ${dashboardStatusLabel(gateway, noNetwork)}`);
184
- console.log(`App: ${appRootLabel()}`);
185
- console.log(`Config: ${configPathLabel(config.sources)}`);
186
- console.log(`Provider: ${config.provider}`);
187
- console.log(`Model: ${config.model}`);
188
- console.log(`Passport: ${passportConfigured ? redact(config.passportId) : "missing"}`);
189
- console.log(`Admin key: ${adminConfigured ? redact(config.apiKey, 6) : "missing"}`);
190
- console.log(`Sidecar: foreground command (\`${cliCommand("sidecar")}\`)\n`);
191
- console.log("Next commands:");
194
+ console.log(`${heading("PassControl")}\n`);
195
+ console.log(formatLabel("Gateway", `${gateway.label} ${config.gateway}`));
196
+ console.log(formatLabel("Dashboard", dashboardStatusLabel(gateway, noNetwork)));
197
+ console.log(formatLabel("App", appRootLabel()));
198
+ console.log(formatLabel("Config", configPathLabel(config.sources)));
199
+ console.log(formatLabel("Provider", config.provider));
200
+ console.log(formatLabel("Model", config.model));
201
+ console.log(formatLabel("Passport", passportConfigured ? redact(config.passportId) : "missing"));
202
+ console.log(formatLabel("Admin key", adminConfigured ? redact(config.apiKey, 6) : "missing"));
203
+ console.log(`${formatLabel("Sidecar", `foreground command (\`${cliCommand("sidecar")}\`)`)}\n`);
204
+ console.log(heading("Next commands:"));
192
205
  console.log(` ${cliCommand("start")} start the local dashboard`);
193
206
  console.log(` ${cliCommand("stop")} stop the local dashboard`);
194
207
  console.log(` ${cliCommand("restart")} restart the local dashboard`);
@@ -720,8 +733,8 @@ async function setupLocal(opts = {}) {
720
733
  });
721
734
  await startDashboard(opts);
722
735
  if (!opts.noOpen) await openDashboard(opts);
723
- console.log(`\nLocal dashboard: ${dashboard.url}`);
724
- console.log("Local-only login: dev@passcontrol.local / passcontrol-dev");
736
+ console.log(`\n${formatLabel("Local dashboard", dashboard.url, 19)}`);
737
+ console.log(formatLabel("Local-only login", "dev@passcontrol.local / passcontrol-dev", 19));
725
738
  step("Add a non-critical provider key, issue a passport, then run `passcontrol doctor --deep`.");
726
739
  }
727
740
 
@@ -741,7 +754,7 @@ async function initCommand(opts) {
741
754
  }
742
755
  }
743
756
 
744
- console.log("PassControl init");
757
+ console.log(heading("PassControl init"));
745
758
  if (opts.global) {
746
759
  console.log("Saving a global profile. Only do this on a machine you trust.\n");
747
760
  } else {
@@ -861,6 +874,108 @@ async function callCommand(rest, opts) {
861
874
  ok("done - check the dashboard audit log + spend for this call.");
862
875
  }
863
876
 
877
+ // `passcontrol try` — the 60-second, no-key, no-accounts experience. Uses the
878
+ // seeded demo passport (demo scope only) to make a GOVERNED call through the
879
+ // keyless `demo` provider, then arms the kill switch to show the same call
880
+ // blocked. Everything is real (visa, scope, budget, kill) except the model.
881
+ async function tryCommand() {
882
+ const gateway = config.gateway;
883
+ const demo = { gateway, passportId: DEMO_PASSPORT_ID, passportSecret: DEMO_PASSPORT_SECRET };
884
+
885
+ const demoCall = async () => {
886
+ const { visa } = await mintVisa(demo);
887
+ return fetch(`${gateway}/api/v1/demo/chat/completions`, {
888
+ method: "POST",
889
+ headers: { "content-type": "application/json", authorization: `Bearer ${visa}` },
890
+ body: JSON.stringify({
891
+ model: "demo-1",
892
+ max_tokens: 64,
893
+ messages: [{ role: "user", content: "Say hi in exactly three words" }],
894
+ }),
895
+ });
896
+ };
897
+ const setKill = async (armed) => {
898
+ const res = await fetch(`${gateway}/api/control/v1/kill-switch`, {
899
+ method: "PUT",
900
+ headers: {
901
+ "content-type": "application/json",
902
+ authorization: `Bearer ${DEMO_API_KEY}`,
903
+ "idempotency-key": crypto.randomUUID(),
904
+ },
905
+ body: JSON.stringify({ armed }),
906
+ });
907
+ if (!res.ok) throw new Error(`kill-switch ${armed ? "on" : "off"} → ${res.status} ${await res.text()}`);
908
+ };
909
+
910
+ console.log(`${heading("PassControl — 60-second try (no provider key, no accounts)")}\n`);
911
+ step(`gateway: ${gateway}`);
912
+
913
+ // 1. Governed, keyless call.
914
+ let res;
915
+ try {
916
+ res = await demoCall();
917
+ } catch (e) {
918
+ const msg = e?.message || String(e);
919
+ if (/unknown_passport|Challenge failed|challenge/i.test(msg)) {
920
+ // Gateway reachable, but the demo passport isn't seeded in ITS database.
921
+ fail(`The gateway is up, but the demo passport isn't seeded here (${msg}).`);
922
+ step("Seed + enable the demo on this stack:");
923
+ step(" PASSCONTROL_DEMO=1 npm run dev:stack # seeds the demo passport + control key");
924
+ step(" PASSCONTROL_DEMO=1 npm run dev:docker # enables the keyless demo provider");
925
+ } else {
926
+ fail(`Could not reach the gateway at ${gateway} (${msg}).`);
927
+ step("Bring the local demo stack up first:");
928
+ step(" PASSCONTROL_DEMO=1 npm run dev:stack # Supabase + Redis + migrate + seed the demo passport");
929
+ step(" PASSCONTROL_DEMO=1 npm run dev:docker # start the gateway with the demo provider enabled");
930
+ }
931
+ process.exitCode = 1;
932
+ return;
933
+ }
934
+ if (res.status === 404) {
935
+ fail("The demo provider is not enabled on this gateway.");
936
+ step("Start it with PASSCONTROL_DEMO=1 (e.g. `PASSCONTROL_DEMO=1 npm run dev:docker`).");
937
+ process.exitCode = 1;
938
+ return;
939
+ }
940
+ if (res.status === 401 || res.status === 403) {
941
+ fail(`Demo passport not accepted (${res.status}). Re-seed the demo stack: PASSCONTROL_DEMO=1 npm run seed`);
942
+ process.exitCode = 1;
943
+ return;
944
+ }
945
+ if (!res.ok) {
946
+ fail(`Unexpected ${res.status}: ${await res.text()}`);
947
+ process.exitCode = 1;
948
+ return;
949
+ }
950
+
951
+ const json = await res.json().catch(() => ({}));
952
+ const text = json?.choices?.[0]?.message?.content ?? JSON.stringify(json);
953
+ const usage = json?.usage ?? {};
954
+ ok("Governed keyless call succeeded — the passport signed a visa, the gateway enforced scope + budget, and no key was needed:");
955
+ console.log(`\n ${text}\n`);
956
+ step(`tokens: ${usage.total_tokens ?? "?"} (prompt ${usage.prompt_tokens ?? "?"} + completion ${usage.completion_tokens ?? "?"})`);
957
+
958
+ // 2. Kill switch blocks the very next call.
959
+ console.log("");
960
+ step("arming the kill switch…");
961
+ await setKill(true);
962
+ try {
963
+ const blocked = await demoCall();
964
+ if (blocked.status === 403) {
965
+ ok(`Kill switch works — the same call is now ${blocked.status} blocked_suspended.`);
966
+ } else {
967
+ fail(`Expected 403 after arming the kill switch, got ${blocked.status}.`);
968
+ }
969
+ } finally {
970
+ await setKill(false);
971
+ step("kill switch disarmed.");
972
+ }
973
+
974
+ console.log("");
975
+ ok("That's PassControl: cryptographic identity → short-lived visa → governed call → instant kill. The provider key never touched the agent.");
976
+ step("Next: add a real provider key in the Control Tower and re-point your agent at the gateway (see the README).");
977
+ }
978
+
864
979
  async function api(method, pathPart, body) {
865
980
  const apiKey = requireControlApiKey(config);
866
981
  const res = await fetch(`${config.gateway}/api/control/v1${pathPart}`, {
@@ -1233,7 +1348,7 @@ async function configureCommand(rest, opts = {}) {
1233
1348
 
1234
1349
  async function doctorCommand(opts = {}) {
1235
1350
  const gateway = await gatewayStatus(false);
1236
- console.log("PassControl doctor\n");
1351
+ console.log(`${heading("PassControl doctor")}\n`);
1237
1352
  (gateway.ok ? ok : fail)(`Gateway ${gateway.label}: ${config.gateway}`);
1238
1353
  (config.passportId && config.passportSecret ? ok : fail)(
1239
1354
  `Passport ${config.passportId && config.passportSecret ? "configured" : "missing"}`
@@ -1357,6 +1472,9 @@ async function main() {
1357
1472
  case "call":
1358
1473
  await callCommand(commandRest, opts);
1359
1474
  break;
1475
+ case "try":
1476
+ await tryCommand();
1477
+ break;
1360
1478
  case "sidecar":
1361
1479
  await sidecarCommand(commandRest, opts);
1362
1480
  break;
package/cli/config.mjs CHANGED
@@ -18,6 +18,24 @@ const CONFIG_KEYS = [
18
18
  ];
19
19
 
20
20
  const trimSlash = (value) => String(value ?? "").replace(/\/+$/, "");
21
+ const ANSI = {
22
+ reset: "\x1b[0m",
23
+ green: "\x1b[32m",
24
+ cyan: "\x1b[36m",
25
+ red: "\x1b[31m",
26
+ heading: "\x1b[1;32m",
27
+ };
28
+
29
+ function paint(code, value) {
30
+ if (
31
+ process.stdout.isTTY !== true ||
32
+ process.env.NO_COLOR !== undefined ||
33
+ process.env.CI
34
+ ) {
35
+ return String(value);
36
+ }
37
+ return `${code}${value}${ANSI.reset}`;
38
+ }
21
39
 
22
40
  export function defaultModelForProvider(provider) {
23
41
  switch (provider) {
@@ -170,16 +188,24 @@ export function writeConfigFile(file, values) {
170
188
  fs.writeFileSync(file, `${lines.join("\n")}\n`, { mode: 0o600 });
171
189
  }
172
190
 
191
+ export function heading(message = "") {
192
+ return paint(ANSI.heading, message);
193
+ }
194
+
195
+ export function formatLabel(label, value, width = 11) {
196
+ return `${paint(ANSI.cyan, `${label}:`.padEnd(width))}${value}`;
197
+ }
198
+
173
199
  export function step(message = "") {
174
- console.log(`→ ${message}`);
200
+ console.log(`${paint(ANSI.cyan, "→")} ${message}`);
175
201
  }
176
202
 
177
203
  export function ok(message = "") {
178
- console.log(`✓ ${message}`);
204
+ console.log(`${paint(ANSI.green, "✓")} ${message}`);
179
205
  }
180
206
 
181
207
  export function fail(message = "") {
182
- console.error(`✗ ${message}`);
208
+ console.error(`${paint(ANSI.red, "✗")} ${message}`);
183
209
  }
184
210
 
185
211
  export function die(message) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Secure Agent Control Plane & Passport Vault — identity-aware reverse proxy for AI agent credentials.",
5
5
  "license": "BUSL-1.1",
6
6
  "homepage": "https://github.com/Vertias3u/PassControl#readme",