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 +20 -0
- package/bin/passcontrol.mjs +136 -18
- package/cli/config.mjs +29 -3
- package/package.json +1 -1
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
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -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
|
|
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(
|
|
183
|
-
console.log(
|
|
184
|
-
console.log(
|
|
185
|
-
console.log(
|
|
186
|
-
console.log(
|
|
187
|
-
console.log(
|
|
188
|
-
console.log(
|
|
189
|
-
console.log(
|
|
190
|
-
console.log(`
|
|
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(`\
|
|
724
|
-
console.log("Local-only login
|
|
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(
|
|
200
|
+
console.log(`${paint(ANSI.cyan, "→")} ${message}`);
|
|
175
201
|
}
|
|
176
202
|
|
|
177
203
|
export function ok(message = "") {
|
|
178
|
-
console.log(
|
|
204
|
+
console.log(`${paint(ANSI.green, "✓")} ${message}`);
|
|
179
205
|
}
|
|
180
206
|
|
|
181
207
|
export function fail(message = "") {
|
|
182
|
-
console.error(
|
|
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.
|
|
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",
|