passcontrol 0.1.2 → 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.
@@ -11,13 +11,16 @@ import {
11
11
  CONFIG_FILE,
12
12
  OPENAI_SHAPE_PROVIDERS,
13
13
  PROVIDERS,
14
+ assertConfigLoaded,
14
15
  config,
15
16
  configPathLabel,
16
17
  defaultModelForProvider,
17
18
  fail,
19
+ formatLabel,
18
20
  formatChallengeError,
19
21
  formatProxyError,
20
22
  globalConfigPath,
23
+ heading,
21
24
  ok,
22
25
  redact,
23
26
  requireControlApiKey,
@@ -25,12 +28,38 @@ import {
25
28
  step,
26
29
  writeConfigFile,
27
30
  } from "../cli/config.mjs";
31
+ import {
32
+ CLAUDE_CODE_ADD_COMMAND,
33
+ isMcpIntegration,
34
+ mcpClientConfigPath,
35
+ mcpServerEntry,
36
+ mcpServersDocument,
37
+ writeMcpClientConfig,
38
+ } from "../cli/mcp/integration.mjs";
28
39
  import { startSidecar } from "../cli/sidecar.mjs";
29
40
 
30
41
  const b64url = (bytes) =>
31
42
  Buffer.from(bytes).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
32
43
  const fromB64url = (s) => new Uint8Array(Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64"));
33
- const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
44
+ const CLI_ENTRY = fileURLToPath(import.meta.url);
45
+ const PACKAGE_ROOT = path.resolve(path.dirname(CLI_ENTRY), "..");
46
+ const CLI_VERSION = (() => {
47
+ try {
48
+ return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version ?? "0.0.0";
49
+ } catch {
50
+ return "0.0.0";
51
+ }
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";
34
63
  const DASHBOARD_STATE_FILE = "local-dashboard.json";
35
64
  const APP_STATE_FILE = "app.json";
36
65
  const PUBLIC_REPO_URL = "https://github.com/Vertias3u/PassControl.git";
@@ -82,9 +111,9 @@ function cliCommand(args = "") {
82
111
 
83
112
  function usage() {
84
113
  const cmd = cliPrefix();
85
- return `PassControl
114
+ return `${heading("PassControl")}
86
115
 
87
- Usage:
116
+ ${heading("Usage:")}
88
117
  ${cmd} show cockpit status
89
118
  ${cmd} init [--global] create a config profile
90
119
  ${cmd} status [--no-network] show active config
@@ -97,10 +126,14 @@ Usage:
97
126
  destroy and recreate the local stack
98
127
  ${cmd} setup [--no-open] [--port-offset N] [--app-dir DIR]
99
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)
100
130
  ${cmd} call "hi" mint a visa and call a model
101
131
  ${cmd} sidecar [--port 8788] start the local agent bridge
132
+ ${cmd} mcp start the local stdio MCP server
102
133
  ${cmd} env [openhands] print sidecar settings for agents
103
- ${cmd} configure <integration> [--write]
134
+ ${cmd} env claude-desktop|cursor|claude-code
135
+ print secret-free MCP client settings
136
+ ${cmd} configure <integration> [--write] [--force]
104
137
  preview or create a supported integration config
105
138
  ${cmd} agent list list agents
106
139
  ${cmd} agent create <name> create an agent passport
@@ -113,7 +146,7 @@ Usage:
113
146
  ${cmd} kill on|off toggle tenant kill switch
114
147
  ${cmd} open start (if needed) and open the dashboard
115
148
 
116
- Config:
149
+ ${heading("Config:")}
117
150
  Env vars win, then nearest .passcontrol, then ~/.config/passcontrol/config.
118
151
  Installed globally, the local-stack commands (setup/start/reset) use a cloned
119
152
  app checkout; override its location with PASSCONTROL_APP_ROOT.
@@ -158,17 +191,17 @@ async function printCockpit({ noNetwork = false } = {}) {
158
191
  const passportConfigured = Boolean(config.passportId && config.passportSecret);
159
192
  const adminConfigured = Boolean(config.apiKey);
160
193
 
161
- console.log("PassControl\n");
162
- console.log(`Gateway: ${gateway.label} ${config.gateway}`);
163
- console.log(`Dashboard: ${dashboardStatusLabel(gateway, noNetwork)}`);
164
- console.log(`App: ${appRootLabel()}`);
165
- console.log(`Config: ${configPathLabel(config.sources)}`);
166
- console.log(`Provider: ${config.provider}`);
167
- console.log(`Model: ${config.model}`);
168
- console.log(`Passport: ${passportConfigured ? redact(config.passportId) : "missing"}`);
169
- console.log(`Admin key: ${adminConfigured ? redact(config.apiKey, 6) : "missing"}`);
170
- console.log(`Sidecar: foreground command (\`${cliCommand("sidecar")}\`)\n`);
171
- 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:"));
172
205
  console.log(` ${cliCommand("start")} start the local dashboard`);
173
206
  console.log(` ${cliCommand("stop")} stop the local dashboard`);
174
207
  console.log(` ${cliCommand("restart")} restart the local dashboard`);
@@ -700,8 +733,8 @@ async function setupLocal(opts = {}) {
700
733
  });
701
734
  await startDashboard(opts);
702
735
  if (!opts.noOpen) await openDashboard(opts);
703
- console.log(`\nLocal dashboard: ${dashboard.url}`);
704
- 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));
705
738
  step("Add a non-critical provider key, issue a passport, then run `passcontrol doctor --deep`.");
706
739
  }
707
740
 
@@ -721,7 +754,7 @@ async function initCommand(opts) {
721
754
  }
722
755
  }
723
756
 
724
- console.log("PassControl init");
757
+ console.log(heading("PassControl init"));
725
758
  if (opts.global) {
726
759
  console.log("Saving a global profile. Only do this on a machine you trust.\n");
727
760
  } else {
@@ -841,6 +874,108 @@ async function callCommand(rest, opts) {
841
874
  ok("done - check the dashboard audit log + spend for this call.");
842
875
  }
843
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
+
844
979
  async function api(method, pathPart, body) {
845
980
  const apiKey = requireControlApiKey(config);
846
981
  const res = await fetch(`${config.gateway}/api/control/v1${pathPart}`, {
@@ -974,17 +1109,25 @@ async function logsCommand(opts) {
974
1109
  })
975
1110
  );
976
1111
  console.table(
977
- rows.map((row) => ({
978
- at: row.created_at,
979
- agent: row.agent_id,
980
- provider: row.provider,
981
- model: row.model,
982
- status: row.status,
983
- in: row.input_tokens,
984
- out: row.output_tokens,
985
- total: row.total_tokens,
986
- usd: usd(row.cost_microcents),
987
- }))
1112
+ rows.map((row) => {
1113
+ const input = typeof row.input_tokens === "number" && Number.isFinite(row.input_tokens)
1114
+ ? row.input_tokens
1115
+ : null;
1116
+ const output = typeof row.output_tokens === "number" && Number.isFinite(row.output_tokens)
1117
+ ? row.output_tokens
1118
+ : null;
1119
+ return {
1120
+ at: row.created_at,
1121
+ agent: row.agent_id,
1122
+ provider: row.provider,
1123
+ model: row.model,
1124
+ status: row.status,
1125
+ in: input ?? "-",
1126
+ out: output ?? "-",
1127
+ total: input === null && output === null ? "-" : (input ?? 0) + (output ?? 0),
1128
+ usd: usd(row.cost_microcents),
1129
+ };
1130
+ })
988
1131
  );
989
1132
  }
990
1133
 
@@ -1018,6 +1161,12 @@ async function sidecarCommand(rest, opts) {
1018
1161
  }
1019
1162
  }
1020
1163
 
1164
+ async function mcpCommand() {
1165
+ const { passportId, passportSecret } = requirePassport(config);
1166
+ const { startMcpServer } = await import("../cli/mcp/server.mjs");
1167
+ await startMcpServer({ gateway: config.gateway, passportId, passportSecret });
1168
+ }
1169
+
1021
1170
  function sidecarBaseUrl(opts = {}) {
1022
1171
  const provider = String(opts.provider || config.provider);
1023
1172
  assertProvider(provider);
@@ -1041,8 +1190,42 @@ function printExports(values) {
1041
1190
  }
1042
1191
  }
1043
1192
 
1193
+ function requireGlobalMcpPassport() {
1194
+ assertConfigLoaded();
1195
+ const globalSource = config.sources.find((source) => source.type === "global");
1196
+ const passportId = String(globalSource?.values?.PASSPORT_ID ?? "").trim();
1197
+ const passportSecret = String(globalSource?.values?.PASSPORT_SECRET ?? "").trim();
1198
+ if (!passportId || !passportSecret) {
1199
+ throw new Error(
1200
+ "MCP client setup requires a passport in the global PassControl config. Run `passcontrol init --global` first."
1201
+ );
1202
+ }
1203
+ }
1204
+
1205
+ function passControlMcpEntry() {
1206
+ return mcpServerEntry({ cliPath: CLI_ENTRY });
1207
+ }
1208
+
1209
+ function printMcpPreset(integration) {
1210
+ requireGlobalMcpPassport();
1211
+ if (integration === "claude-code") {
1212
+ console.log("# Add PassControl to Claude Code:");
1213
+ console.log(CLAUDE_CODE_ADD_COMMAND);
1214
+ return;
1215
+ }
1216
+
1217
+ const label = integration === "cursor" ? "Cursor" : "Claude Desktop";
1218
+ console.log(`# ${label} mcpServers config:`);
1219
+ console.log(JSON.stringify(mcpServersDocument(passControlMcpEntry()), null, 2));
1220
+ }
1221
+
1044
1222
  function printAgentPreset(name = "generic", opts = {}) {
1045
1223
  const preset = name.toLowerCase();
1224
+ if (isMcpIntegration(preset)) {
1225
+ printMcpPreset(preset);
1226
+ return;
1227
+ }
1228
+
1046
1229
  const { provider, model, apiKey, baseUrl } = sidecarBaseUrl(opts);
1047
1230
  const modelWithProvider = `${provider}/${model}`;
1048
1231
  const sidecarStart = opts.port ? cliCommand(`sidecar --port ${opts.port}`) : cliCommand("sidecar");
@@ -1089,7 +1272,9 @@ function printAgentPreset(name = "generic", opts = {}) {
1089
1272
  ]);
1090
1273
  break;
1091
1274
  default:
1092
- throw new Error("Usage: passcontrol env [generic|openhands|litellm|aider|cline|continue]");
1275
+ throw new Error(
1276
+ "Usage: passcontrol env [generic|openhands|litellm|aider|cline|continue|claude-desktop|cursor|claude-code]"
1277
+ );
1093
1278
  }
1094
1279
  }
1095
1280
 
@@ -1105,9 +1290,43 @@ function aiderConfig(opts = {}) {
1105
1290
  ].join("\n");
1106
1291
  }
1107
1292
 
1293
+ function configureMcpClient(integration, opts = {}) {
1294
+ requireGlobalMcpPassport();
1295
+ if (integration === "claude-code") {
1296
+ console.log("Claude Code manages MCP servers through its CLI. Run:");
1297
+ console.log(CLAUDE_CODE_ADD_COMMAND);
1298
+ return;
1299
+ }
1300
+
1301
+ const target = mcpClientConfigPath(integration);
1302
+ const entry = passControlMcpEntry();
1303
+ const preview = JSON.stringify(mcpServersDocument(entry), null, 2);
1304
+ console.log(`Preview: ${target}\n\n${preview}`);
1305
+ if (!opts.write) {
1306
+ step("Dry run only. Re-run with `--write` to merge this entry.");
1307
+ return;
1308
+ }
1309
+
1310
+ const result = writeMcpClientConfig({ target, entry, force: Boolean(opts.force) });
1311
+ if (!result.changed) {
1312
+ ok(`${target} already contains this PassControl MCP entry`);
1313
+ return;
1314
+ }
1315
+ if (result.backupPath) step(`backed up ${result.backupPath}`);
1316
+ ok(`wrote ${target}`);
1317
+ }
1318
+
1108
1319
  async function configureCommand(rest, opts = {}) {
1109
1320
  const integration = String(rest[0] ?? "").toLowerCase();
1110
- if (!integration) throw new Error("Usage: passcontrol configure <aider|cline|continue|openhands> [--write]");
1321
+ if (!integration) {
1322
+ throw new Error(
1323
+ "Usage: passcontrol configure <aider|cline|continue|openhands|claude-desktop|cursor|claude-code> [--write] [--force]"
1324
+ );
1325
+ }
1326
+ if (isMcpIntegration(integration)) {
1327
+ configureMcpClient(integration, opts);
1328
+ return;
1329
+ }
1111
1330
  if (integration !== "aider") {
1112
1331
  if (opts.write) throw new Error(`${integration} configuration is UI- or project-schema-specific; no file was written. Use the preview below.`);
1113
1332
  printAgentPreset(integration, opts);
@@ -1129,7 +1348,7 @@ async function configureCommand(rest, opts = {}) {
1129
1348
 
1130
1349
  async function doctorCommand(opts = {}) {
1131
1350
  const gateway = await gatewayStatus(false);
1132
- console.log("PassControl doctor\n");
1351
+ console.log(`${heading("PassControl doctor")}\n`);
1133
1352
  (gateway.ok ? ok : fail)(`Gateway ${gateway.label}: ${config.gateway}`);
1134
1353
  (config.passportId && config.passportSecret ? ok : fail)(
1135
1354
  `Passport ${config.passportId && config.passportSecret ? "configured" : "missing"}`
@@ -1217,7 +1436,7 @@ async function main() {
1217
1436
  return;
1218
1437
  }
1219
1438
  if (opts.version || command === "version") {
1220
- console.log("passcontrol 0.1.0");
1439
+ console.log(`passcontrol ${CLI_VERSION}`);
1221
1440
  return;
1222
1441
  }
1223
1442
 
@@ -1253,9 +1472,15 @@ async function main() {
1253
1472
  case "call":
1254
1473
  await callCommand(commandRest, opts);
1255
1474
  break;
1475
+ case "try":
1476
+ await tryCommand();
1477
+ break;
1256
1478
  case "sidecar":
1257
1479
  await sidecarCommand(commandRest, opts);
1258
1480
  break;
1481
+ case "mcp":
1482
+ await mcpCommand();
1483
+ break;
1259
1484
  case "env":
1260
1485
  printAgentPreset(commandRest[0] || "generic", opts);
1261
1486
  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) {
@@ -0,0 +1,54 @@
1
+ # PassControl MCP server
2
+
3
+ `passcontrol mcp` starts a local stdio MCP server with `chat` and `list_models`.
4
+ It reads the same environment, nearest `.passcontrol`, and global
5
+ `~/.config/passcontrol/config` sources as the rest of the CLI. MCP client setup requires a
6
+ passport in the global profile so clients can launch from any working directory without
7
+ embedding a secret:
8
+
9
+ ```sh
10
+ passcontrol init --global
11
+ ```
12
+
13
+ The client receives neither the provider key nor the short-lived work visa. The
14
+ server mints the visa locally and sends every model call through the configured
15
+ PassControl gateway.
16
+
17
+ ## Claude Desktop
18
+
19
+ Preview or merge the entry into Claude Desktop's real per-OS config path:
20
+
21
+ ```sh
22
+ passcontrol env claude-desktop
23
+ passcontrol configure claude-desktop --write
24
+ ```
25
+
26
+ ## Cursor
27
+
28
+ Preview or merge `mcpServers.passcontrol` into `~/.cursor/mcp.json`:
29
+
30
+ ```sh
31
+ passcontrol env cursor
32
+ passcontrol configure cursor --write
33
+ ```
34
+
35
+ ## Claude Code
36
+
37
+ Claude Code manages this setting through its CLI. Either command below prints the exact
38
+ `claude mcp add` command to run:
39
+
40
+ ```sh
41
+ passcontrol env claude-code
42
+ passcontrol configure claude-code
43
+ ```
44
+
45
+ The equivalent private, user-scoped command is:
46
+
47
+ ```sh
48
+ claude mcp add --scope user passcontrol -- passcontrol mcp
49
+ ```
50
+
51
+ Desktop/Cursor entries use absolute Node and `bin/passcontrol.mjs` paths because GUI clients
52
+ may not inherit shell `PATH`. Existing `mcpServers` entries are preserved, an existing file is
53
+ backed up to `.bak`, and a different PassControl entry requires `--force`. No generated client
54
+ config contains a passport secret or provider key.
@@ -0,0 +1,158 @@
1
+ import { decodeJwt } from "jose";
2
+ import { OPENAI_SHAPE_PROVIDERS, formatProxyError } from "../config.mjs";
3
+ import { createVisaClient } from "../visa-client.mjs";
4
+
5
+ const DEFAULT_ANTHROPIC_MAX_TOKENS = 1024;
6
+
7
+ const trimSlash = (value) => String(value ?? "").replace(/\/+$/, "");
8
+
9
+ function requestFor({ provider, model, messages, max_tokens, temperature }) {
10
+ if (provider === "anthropic") {
11
+ const system = messages
12
+ .filter((message) => message.role === "system")
13
+ .map((message) => message.content)
14
+ .join("\n\n");
15
+ const providerMessages = messages.filter((message) => message.role !== "system");
16
+ if (providerMessages.length === 0) {
17
+ throw new Error("Anthropic chat requires at least one user or assistant message.");
18
+ }
19
+
20
+ return {
21
+ path: "v1/messages",
22
+ body: {
23
+ model,
24
+ max_tokens: max_tokens ?? DEFAULT_ANTHROPIC_MAX_TOKENS,
25
+ messages: providerMessages,
26
+ ...(system ? { system } : {}),
27
+ ...(temperature === undefined ? {} : { temperature }),
28
+ },
29
+ };
30
+ }
31
+
32
+ if (OPENAI_SHAPE_PROVIDERS.has(provider)) {
33
+ return {
34
+ path: "chat/completions",
35
+ body: {
36
+ model,
37
+ messages,
38
+ ...(max_tokens === undefined ? {} : { max_tokens }),
39
+ ...(temperature === undefined ? {} : { temperature }),
40
+ },
41
+ };
42
+ }
43
+
44
+ throw new Error(`Provider ${provider} is not supported by PassControl MCP.`);
45
+ }
46
+
47
+ function extractAssistantText(provider, data) {
48
+ if (provider === "anthropic") {
49
+ const text = Array.isArray(data?.content)
50
+ ? data.content
51
+ .filter((part) => part?.type === "text" && typeof part.text === "string")
52
+ .map((part) => part.text)
53
+ .join("")
54
+ : "";
55
+ if (text) return text;
56
+ } else {
57
+ const content = data?.choices?.[0]?.message?.content;
58
+ if (typeof content === "string" && content) return content;
59
+ if (Array.isArray(content)) {
60
+ const text = content
61
+ .map((part) => (typeof part === "string" ? part : typeof part?.text === "string" ? part.text : ""))
62
+ .join("");
63
+ if (text) return text;
64
+ }
65
+ }
66
+
67
+ throw new Error(`${provider} returned no assistant text.`);
68
+ }
69
+
70
+ function proxyError(status, body) {
71
+ if (status === 401) {
72
+ const detail = String(body ?? "").trim();
73
+ return `Gateway rejected the work visa with 401: ${detail}. Check the passport and gateway, then retry.`;
74
+ }
75
+ return formatProxyError(status, body);
76
+ }
77
+
78
+ function usageFrom(data) {
79
+ return data?.usage && typeof data.usage === "object" && !Array.isArray(data.usage)
80
+ ? data.usage
81
+ : undefined;
82
+ }
83
+
84
+ function modelsFromVisa(visa) {
85
+ let payload;
86
+ try {
87
+ payload = decodeJwt(visa);
88
+ } catch {
89
+ throw new Error("Gateway returned a work visa with an unreadable scope.");
90
+ }
91
+
92
+ if (!Array.isArray(payload.scope)) {
93
+ throw new Error("Gateway work visa did not contain a model scope.");
94
+ }
95
+
96
+ return payload.scope.flatMap((entry) => {
97
+ if (!entry || typeof entry.provider !== "string" || !Array.isArray(entry.models)) return [];
98
+ return entry.models
99
+ .filter((model) => typeof model === "string")
100
+ .map((model) => ({ provider: entry.provider, model }));
101
+ });
102
+ }
103
+
104
+ export function createGatewayClient({
105
+ gateway,
106
+ passportId,
107
+ passportSecret,
108
+ fetch: fetchImpl = globalThis.fetch,
109
+ now = () => Date.now(),
110
+ randomUUID = () => globalThis.crypto.randomUUID(),
111
+ refreshSkewSeconds = 30,
112
+ }) {
113
+ const baseUrl = trimSlash(gateway);
114
+ const visas = createVisaClient({
115
+ gateway: baseUrl,
116
+ passportId,
117
+ passportSecret,
118
+ fetch: fetchImpl,
119
+ now,
120
+ randomUUID,
121
+ refreshSkewSeconds,
122
+ missingVisaMessage: "Challenge returned no visa.",
123
+ });
124
+
125
+ async function proxyChat(input, visa) {
126
+ const { path, body } = requestFor(input);
127
+ return fetchImpl(`${baseUrl}/api/v1/${input.provider}/${path}`, {
128
+ method: "POST",
129
+ headers: {
130
+ "content-type": "application/json",
131
+ authorization: `Bearer ${visa}`,
132
+ },
133
+ body: JSON.stringify(body),
134
+ });
135
+ }
136
+
137
+ return {
138
+ async chat(input) {
139
+ const response = await visas.fetchWithVisa((visa) => proxyChat(input, visa));
140
+ if (!response.ok) throw new Error(proxyError(response.status, await response.text()));
141
+
142
+ let data;
143
+ try {
144
+ data = await response.json();
145
+ } catch {
146
+ throw new Error(`Gateway returned a non-JSON ${input.provider} response.`);
147
+ }
148
+ return {
149
+ text: extractAssistantText(input.provider, data),
150
+ usage: usageFrom(data),
151
+ };
152
+ },
153
+
154
+ async listModels() {
155
+ return modelsFromVisa(await visas.getVisa());
156
+ },
157
+ };
158
+ }