passcontrol 1.0.0 → 1.2.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
@@ -10,7 +10,7 @@ stop control without copying provider secrets into every tool. Bring your own pr
10
10
 
11
11
  | Start here | Choose it when | You operate |
12
12
  |---|---|---|
13
- | [Cloud](#cloud) — free private beta, access by request | You want a managed gateway without running a database or Docker | Your agents and provider account |
13
+ | [Cloud](#cloud) — free beta, open sign-up | You want a managed gateway without running a database or Docker | Your agents and provider account |
14
14
  | [Self-host](#self-host) — full working core | You want the gateway and provider credentials on infrastructure you control | Gateway, dashboard, Supabase Auth + Vault + database, and Redis |
15
15
 
16
16
  A **Passport** is an Ed25519 signing key used to obtain a short-lived visa. A **Direct
@@ -23,11 +23,11 @@ independently audited**. Start with a non-critical provider key. Source-availabl
23
23
 
24
24
  ## Cloud
25
25
 
26
- [Request beta access](https://passcontrol.vertias.eu/beta). To look around first, try
26
+ [Create a free account](https://passcontrol.vertias.eu/signup). To look around first, try
27
27
  [the keyless browser demo](https://passcontrol.vertias.eu): it synthesizes output and
28
28
  does not call a billed provider.
29
29
 
30
- Once you have access, install the CLI with Node/npm and sign in:
30
+ Once you have an account, install the CLI with Node/npm and sign in:
31
31
 
32
32
  ```sh
33
33
  npm install -g passcontrol
@@ -161,7 +161,7 @@ API key. Treat access to that local listener as access to the configured agent.
161
161
  not a sandbox against other processes running as you. Its provider CONNECT requests are
162
162
  refused; use base URLs rather than TLS interception.
163
163
 
164
- Presets (from `cli/presets.mjs`): `generic`, `openhands`, `litellm`, `aider`, `hermes`, `cline`, `continue`, `chatbox`, `jan`, `msty`, `cherry-studio`, `open-webui`, `librechat`; MCP presets: `claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
164
+ Presets (from `cli/presets.mjs`): `generic`, `openhands`, `litellm`, `aider`, `hermes`, `cline`, `continue`, `chatbox`, `jan`, `msty`, `cherry-studio`, `open-webui`, `librechat`; service presets: `github`, `telegram`, `brave`, `notion`, `discord`; MCP presets: `claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
165
165
  supported paths. [Hermes configuration](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
166
166
 
167
167
  ## CLI configuration and key storage
@@ -258,8 +258,10 @@ are separate from signature verification.
258
258
  shadow evaluation records candidate decisions without enforcing them.
259
259
  - Token and cost admission limits through atomic reservations and settlement.
260
260
  - Platform/tenant kill switches and per-agent suspension/revocation.
261
+ - "Ask me first" on service calls: a rule can hold the exact request until the owner
262
+ approves it once, from the dashboard or with Telegram buttons.
261
263
  - Provider failover within supported request families and each attempt's authorization
262
- and budget checks; it is not arbitrary API translation.
264
+ and budget checks; it is not arbitrary API translation. Embeddings never fail over.
263
265
  - The injected provider key is removed from what comes back: if an upstream echoes it in
264
266
  an error body, a JSON answer or an event stream (even split across chunks), the agent
265
267
  receives `[REDACTED_PROVIDER_KEY]` instead. This covers the exact key, not a key an
@@ -300,7 +302,8 @@ Prices are an in-code estimate table, one row per model, read from each provider
300
302
  page. Under a dollar limit, a model with no row is refused `402 unpriced_model`; without one it
301
303
  is estimated at the provider's highest listed rate. **Custom endpoints are unpriced**, even when the model name
302
304
  matches: logs mark cost unknown, receipts carry `unp`, and token accounting continues.
303
- The cost budget retains a proxy estimate; it does not become knowledge of actual dollars.
305
+ They add nothing to an agent's cost budget, and an agent with a dollar limit is refused them
306
+ (`402 unpriced_endpoint`): limit those agents by tokens.
304
307
  Known/table-priced cost, conservative enforced spend, and open holds are different figures.
305
308
  The dashboard therefore labels the all-time counter **Settled budget charges** and shows its
306
309
  durable call-attributed charges, separate operator adjustments, any visible difference, and
@@ -315,15 +318,20 @@ All paths below are relative to `/api/v1/<provider>`. SDK base URLs and aliases
315
318
 
316
319
  | Provider ID | Inference | Discovery |
317
320
  |---|---|---|
318
- | `openai` | Chat Completions and **POST Responses** | Models list/detail |
321
+ | `openai` | Chat Completions, **POST Responses** and **POST Embeddings** | Models list/detail |
319
322
  | `anthropic` | Messages | Models list/detail |
320
- | `groq`, `mistral`, `together` | OpenAI-compatible Chat Completions | Models list/detail |
323
+ | `mistral` | OpenAI-compatible Chat Completions and **POST Embeddings** | Models list/detail |
324
+ | `groq`, `together` | OpenAI-compatible Chat Completions | Models list/detail |
321
325
  | `deepseek` | OpenAI-compatible Chat Completions | Not proxied |
322
326
  | `gemini` | Google's **OpenAI-compatible** Chat Completions | Models list/detail |
323
-
324
- Gemini's native `generateContent` API is not supported. Responses support is OpenAI-only;
325
- response retrieval/deletion, embeddings, files, fine-tuning, batches, and token-counting
326
- endpoints are not proxied. OpenAI's hosted tools (web search, file search, code interpreter
327
+ | `xai` | **POST Responses** only (legacy Chat Completions refused) | Models list/detail |
328
+ | `azure` | Azure OpenAI v1: Chat Completions, **POST Responses** and **POST Embeddings**, at the resource address stored with the key | Models list |
329
+ | `local` | A model server you run (Ollama, LM Studio, vLLM): Chat Completions at the address stored with the credential, self-host only | Models list |
330
+
331
+ Gemini's native `generateContent` API is not supported. Responses is served for OpenAI,
332
+ xAI and Azure; embeddings for OpenAI, Mistral and Azure, and an embeddings call never fails over, because
333
+ another model's vectors would not match the ones already stored. Response retrieval/deletion,
334
+ files, fine-tuning, batches, and token-counting endpoints are not proxied. OpenAI's hosted tools (web search, file search, code interpreter
327
335
  and others billed outside tokens) and its search models are refused, because no token budget can
328
336
  hold their fees. Model availability still depends on your provider account.
329
337
 
@@ -331,7 +339,9 @@ Custom provider base URLs support compatible deployments such as Ollama, vLLM, o
331
339
  LiteLLM without adding provider IDs. They require operator opt-in:
332
340
  `PROVIDER_ENDPOINT_MODE=selfhost` permits HTTP, private addresses, and custom ports;
333
341
  a comma-separated hostname list permits only listed HTTPS hosts on port 443. Unset/off
334
- refuses custom endpoints. Shape validation is **not full SSRF prevention**: it does not
342
+ refuses custom endpoints. The local stack (`npm run dev:docker`, `passcontrol start`) runs
343
+ with `selfhost` unless you set `off`: it is one developer's own gateway, so the person who
344
+ sets an endpoint is the person who owns it. A hosted deployment's default stays off. Shape validation is **not full SSRF prevention**: it does not
335
345
  resolve or pin DNS. Operators must control egress and trust the destination receiving
336
346
  the provider credential. Upstream redirects are refused, never followed.
337
347
 
@@ -360,11 +370,6 @@ check needs the relevant earlier statements or a trusted checkpoint. The public
360
370
  tree ships the format and verification code/page, **not statement production, scheduling,
361
371
  or statement/proof-serving routes**. See [statement format and limits](https://github.com/Vertias3u/PassControl/blob/main/docs/statement-format.md).
362
372
 
363
- Owner binding is per workspace. A typed owner is a declaration; GitHub verification
364
- checks publication of a token in a particular account's repository, and domain
365
- verification checks a well-known HTTPS token. Neither proves a person's legal identity
366
- or trustworthiness. Company registry evidence is also distinct from authority to represent
367
- that company. Only published bindings are attached to public evidence.
368
373
 
369
374
  ![Recorded kill-switch demonstration: subsequent requests are refused](https://raw.githubusercontent.com/Vertias3u/PassControl/main/docs/demo/kill-switch.gif)
370
375
 
@@ -376,7 +381,7 @@ of an already-dispatched stream.
376
381
  ## Self-host operations reference
377
382
 
378
383
  <details>
379
- <summary>Source setup, lifecycle, credential switching, production and portability</summary>
384
+ <summary>Source setup, lifecycle, credential switching and portability</summary>
380
385
 
381
386
  The CLI package declares Node ≥18, but the full stack needs Node 22+: locked Supabase
382
387
  dependencies need ≥20 and Wrangler needs ≥22. Use `passcontrol setup --no-open` to
@@ -410,14 +415,9 @@ Shell or project-file gateway overrides are refused and named before services st
410
415
  global write could not override them safely. Clean up any still-active remote identity at its
411
416
  original gateway.
412
417
 
413
- For production, configure [`.env.example`](https://github.com/Vertias3u/PassControl/blob/main/.env.example), use Supabase (plain Postgres
414
- is insufficient), set `DATABASE_URL` in your shell environment and apply the public migrations with
415
- `npm run migrate`,
416
- and build/run the app. Supported paths are Next.js on Vercel, `npm run build` then
417
- `npm start` on a Node host behind a trusted reverse proxy, and the
418
- [Cloudflare/OpenNext build](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md). Configure Auth/SMTP,
419
- secrets, backups, Redis persistence/no-eviction, and periodic authenticated
420
- `GET /api/cron/reconcile`. A local successful boot does not validate production operations.
418
+ Self-host is built for one developer on their own machine; this repository does not ship
419
+ a production deployment path. To let agents running elsewhere reach PassControl, or to give
420
+ passports a verify page anyone can open, use [Cloud](#cloud).
421
421
 
422
422
  | Boundary | Cloud | Public self-host tree |
423
423
  |---|---|---|
@@ -67,6 +67,8 @@ import {
67
67
  integrationChoices,
68
68
  isGuiPreset,
69
69
  isIntegration,
70
+ isServicePreset,
71
+ SERVICE_ENV,
70
72
  supportsWrite,
71
73
  } from "../cli/presets.mjs";
72
74
  import { importCompletionMessage, noAgentCreateMessage } from "../cli/workspace-import-report.mjs";
@@ -83,6 +85,8 @@ import {
83
85
  stackFromConfig,
84
86
  writeMarker,
85
87
  } from "../cli/update.mjs";
88
+ import { isLocalGatewayOrigin, probeGatewayVersion, probeTimeoutMs } from "../cli/gateway-probe.mjs";
89
+ import { dashboardOriginForOffset, portHolders, stackPortConflictMessage } from "../cli/local-stack.mjs";
86
90
  import { startSidecar } from "../cli/sidecar.mjs";
87
91
  import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
88
92
  import { loginCommand } from "../cli/login.mjs";
@@ -324,20 +328,7 @@ async function gatewayStatus(noNetwork = false, gateway = config.gateway) {
324
328
  if (noNetwork) return { label: "not checked", ok: null };
325
329
  const origin = probeGatewayOrigin({ gateway });
326
330
  if (!origin) return { label: "invalid configuration", ok: false };
327
- try {
328
- const res = await fetchWithTimeout(`${origin}/api/version`, {
329
- method: "GET",
330
- headers: { accept: "application/json" },
331
- });
332
- if (!res.ok) return { label: `unhealthy (${res.status})`, ok: false };
333
- const body = await res.json().catch(() => null);
334
- const version = typeof body?.version === "string" && body.version.trim() ? body.version.trim() : null;
335
- return version
336
- ? { label: `online (${res.status}, PassControl ${version})`, ok: true, version }
337
- : { label: "unhealthy (not a PassControl version response)", ok: false };
338
- } catch {
339
- return { label: "offline or unreachable", ok: false };
340
- }
331
+ return probeGatewayVersion(origin);
341
332
  }
342
333
 
343
334
  async function printCockpit({ noNetwork = false, json = false } = {}) {
@@ -1224,31 +1215,60 @@ function ownSupabaseDatabaseIsRunning(offset = 0) {
1224
1215
  }
1225
1216
  }
1226
1217
 
1227
- async function assertLocalStackPortsAvailable(offset = 0) {
1218
+ /** Which containers hold `ports`, so a refusal can name the stack to stop. Empty when Docker cannot say. */
1219
+ function dockerPortHolders(ports) {
1220
+ try {
1221
+ const listing = execFileSync("docker", ["ps", "--format", "{{.Names}}\t{{.Ports}}"], { encoding: "utf8", timeout: DOCKER_TIMEOUT_MS });
1222
+ return portHolders(listing, ports);
1223
+ } catch {
1224
+ return [];
1225
+ }
1226
+ }
1227
+
1228
+ async function assertLocalStackPortsAvailable(offset = 0, { rerun = cliCommand("setup") } = {}) {
1228
1229
  if (ownSupabaseDatabaseIsRunning(offset)) return;
1229
1230
  const busy = [];
1230
1231
  for (const port of LOCAL_STACK_PORTS.map((port) => port + offset)) {
1231
1232
  if (await portIsListening(port)) busy.push(port);
1232
1233
  }
1233
1234
  if (busy.length) {
1234
- throw new Error(
1235
- `Local stack ports ${busy.join(", ")} are in use by another project. Stop that project first (for example, \`supabase stop --project-id <project>\`), then rerun \`passcontrol setup\`.`
1236
- );
1235
+ throw new Error(stackPortConflictMessage({ busy, holders: dockerPortHolders(busy), rerun }));
1237
1236
  }
1238
1237
  }
1239
1238
 
1240
1239
  async function checkLocalStackPorts(offset = 0) {
1240
+ // Named in the line, so an install made with --port-offset can see which
1241
+ // ports were actually checked.
1242
+ const label = offset ? `Local stack ports (offset ${offset})` : "Local stack ports";
1241
1243
  try {
1242
1244
  await assertLocalStackPortsAvailable(offset);
1243
- return { ok: true, message: "Local stack ports: available." };
1245
+ return { ok: true, message: `${label}: available.` };
1244
1246
  } catch (error) {
1245
1247
  return {
1246
1248
  ok: false,
1247
- message: `Local stack ports: unavailable. Fix: stop the conflicting project or rerun setup with --port-offset N. Details: ${error.message}`,
1249
+ message: `${label}: unavailable. Fix: stop the conflicting project or rerun setup with --port-offset N. Details: ${error.message}`,
1248
1250
  };
1249
1251
  }
1250
1252
  }
1251
1253
 
1254
+ /**
1255
+ * The port offset `setup` baked into this checkout's supabase/config.toml, or 0
1256
+ * when it was never set up. Read back, as `update` does (stackFromConfig),
1257
+ * because the offset is a setup-time flag nobody passes again: checking at 0
1258
+ * reported a working --port-offset install as "ports unavailable".
1259
+ */
1260
+ function installedStackOffset() {
1261
+ try {
1262
+ const root = appRoot ?? resolveAppRoot();
1263
+ if (!root) return 0;
1264
+ const configPath = path.join(root, "supabase", "config.toml");
1265
+ if (!fs.existsSync(configPath)) return 0;
1266
+ return stackFromConfig(fs.readFileSync(configPath, "utf8"))?.offset ?? 0;
1267
+ } catch {
1268
+ return 0;
1269
+ }
1270
+ }
1271
+
1252
1272
  async function runLocalPrerequisiteChecks({ offset = 0, report = false, enforce = false } = {}) {
1253
1273
  const results = [
1254
1274
  checkDockerInstalled(),
@@ -1716,6 +1736,18 @@ async function applyAppUpdate(app) {
1716
1736
  `Port ${dashboard.port} is served by something this CLI did not start (a dashboard run by hand?). Stop it, then rerun \`${cliCommand("update")}\`. Nothing was changed.`
1717
1737
  );
1718
1738
  }
1739
+ // The stack's own ports, before anything changes. Another stack on them
1740
+ // (a second checkout at the same offset) only showed up when Supabase failed
1741
+ // to start, after the fast-forward and \`npm ci\`, as "npm exited with code 1".
1742
+ // A running dashboard of THIS install means its own stack holds them, which
1743
+ // assertLocalStackPortsAvailable already allows.
1744
+ try {
1745
+ await assertLocalStackPortsAvailable(app.offset, { rerun: cliCommand(app.resume ? "update --app-only" : "update") });
1746
+ } catch (error) {
1747
+ throw new Error(
1748
+ `${error.message} ${app.resume ? "The earlier update is still unfinished; nothing more was changed." : "Nothing was changed."}`
1749
+ );
1750
+ }
1719
1751
  const restart = app.resume?.wasRunning ?? Boolean(managed);
1720
1752
  const from = app.resume?.from ?? app.head;
1721
1753
  writeMarker({ appRoot: app.root, from, to: app.target, wasRunning: restart, startedAt: new Date().toISOString() });
@@ -1808,18 +1840,26 @@ async function updateCommand(opts = {}) {
1808
1840
  }
1809
1841
 
1810
1842
  async function setupLocal(opts = {}) {
1811
- const dashboard = canonicalLocalDashboard();
1812
- const activation = await prepareLocalActivation(dashboard, opts);
1813
1843
  const offset = opts.portOffset === undefined ? 0 : Number(opts.portOffset);
1814
1844
  if (!Number.isInteger(offset) || offset < 0 || offset > 10000) {
1815
1845
  throw new Error("--port-offset must be an integer from 0 to 10000.");
1816
1846
  }
1847
+ // The dashboard moves with the offset, like Supabase and Redis: a second
1848
+ // install on :3000 would collide with the first one's dashboard. Saved as the
1849
+ // gateway by the activation below, so `start`, `stop` and `status` follow it.
1850
+ const dashboard = parseLocalDashboard(
1851
+ dashboardOriginForOffset(offset),
1852
+ offset ? "the offset local dashboard" : "the canonical local dashboard"
1853
+ );
1854
+ const activation = await prepareLocalActivation(dashboard, opts);
1817
1855
  await runLocalPrerequisiteChecks({ offset, enforce: true });
1818
1856
  await ensureAppRoot({ clone: true, appDir: opts.appDir, yes: opts.yes });
1819
1857
  step("Preparing the local Supabase, Redis, migrations, and dev user…");
1820
1858
  await runLocalCommand(process.platform === "win32" ? "npm.cmd" : "npm", ["run", "dev:stack"], {
1821
1859
  ...process.env,
1822
1860
  PASSCONTROL_PORT_OFFSET: String(offset),
1861
+ // Supabase's site URL and the receipt issuer are written from PORT.
1862
+ PORT: String(dashboard.port),
1823
1863
  PASSCONTROL_VIA_CLI: "1",
1824
1864
  });
1825
1865
  // dev:stack has just brought Supabase and Redis up (and would have exited
@@ -2386,6 +2426,11 @@ function printAgentPreset(name = "generic", opts = {}) {
2386
2426
  return;
2387
2427
  }
2388
2428
 
2429
+ if (isServicePreset(preset)) {
2430
+ printServicePreset(preset, opts);
2431
+ return;
2432
+ }
2433
+
2389
2434
  const { provider, model, apiKey, baseUrl, port } = sidecarBaseUrl(opts);
2390
2435
  const modelWithProvider = `${provider}/${model}`;
2391
2436
  const sidecarStart = opts.port != null || process.env.SIDECAR_PORT != null
@@ -2453,6 +2498,23 @@ function printAgentPreset(name = "generic", opts = {}) {
2453
2498
  }
2454
2499
  }
2455
2500
 
2501
+ // A service preset has no provider and no model: the client is pointed at the
2502
+ // governed service route and sends no service token at all — the gateway
2503
+ // injects the workspace's, and only for calls the agent's rules admit.
2504
+ function printServicePreset(service, opts = {}) {
2505
+ const host = String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1");
2506
+ const port = sidecarPort(opts);
2507
+ const sidecarStart = opts.port != null || process.env.SIDECAR_PORT != null
2508
+ ? cliCommand(`sidecar --port ${port}`)
2509
+ : cliCommand("sidecar");
2510
+ console.log(`# Start the bridge first: ${sidecarStart}`);
2511
+ const entry = Object.hasOwn(SERVICE_ENV, service) ? SERVICE_ENV[service] : null;
2512
+ if (!entry) throw new Error(`Usage: passcontrol env <${integrationChoices()}>`);
2513
+ for (const line of entry.about) console.log(line);
2514
+ printExports([[entry.envVar, `http://${host}:${port}/api/v1/svc/${service}`]]);
2515
+ console.log(entry.usage);
2516
+ }
2517
+
2456
2518
  function aiderConfig(opts = {}) {
2457
2519
  const { provider, model, baseUrl } = sidecarBaseUrl(opts);
2458
2520
  return [
@@ -2560,7 +2622,7 @@ async function serverVersion() {
2560
2622
  const origin = probeGatewayOrigin();
2561
2623
  if (!origin) return { version: null, detail: "the configured gateway is not a bare origin" };
2562
2624
  try {
2563
- const res = await fetchWithTimeout(`${origin}/api/version`);
2625
+ const res = await fetchWithTimeout(`${origin}/api/version`, {}, probeTimeoutMs(origin));
2564
2626
  // A gateway that predates this endpoint is a real PassControl gateway, and
2565
2627
  // saying "unreachable" about one that answered would send an operator to
2566
2628
  // debug their network instead of deploying.
@@ -2711,7 +2773,25 @@ async function doctorCommand(opts = {}) {
2711
2773
  // One authenticated request for this command. Its failure is a failed
2712
2774
  // diagnostic, not a CLI crash: remaining local checks are still useful.
2713
2775
  printSystemHealthDiagnostic(await fetchSystemHealth());
2714
- await runLocalPrerequisiteChecks({ report: true });
2776
+ // Docker, Supabase and the stack's ports matter only where a stack runs. A CLI
2777
+ // pointed at a remote gateway (Cloud) with no app checkout here has none, and
2778
+ // a failing "Local stack ports" line would send that user hunting for one.
2779
+ const probeOrigin = probeGatewayOrigin();
2780
+ const remoteGateway = probeOrigin !== null && !isLocalGatewayOrigin(probeOrigin);
2781
+ let localApp = null;
2782
+ try {
2783
+ localApp = resolveAppRoot();
2784
+ } catch {
2785
+ localApp = null;
2786
+ }
2787
+ if (remoteGateway && !localApp) {
2788
+ step(
2789
+ `Local prerequisites skipped: this CLI uses a remote gateway (${probeOrigin}). Docker and the ` +
2790
+ "local stack are needed only to self-host on this machine."
2791
+ );
2792
+ } else {
2793
+ await runLocalPrerequisiteChecks({ offset: installedStackOffset(), report: true });
2794
+ }
2715
2795
  if (config.passportId && config.passportSecret) {
2716
2796
  // The whole chain, not just the mint. "Visa mint works" proves the passport
2717
2797
  // authenticates and says nothing about scope, budget, the proxy or receipts —
@@ -2745,17 +2825,24 @@ async function doctorCommand(opts = {}) {
2745
2825
  step("Skipping control API check: no PASSCONTROL_API_KEY configured.");
2746
2826
  }
2747
2827
 
2748
- await checkInstanceSigningKey();
2828
+ await checkInstanceSigningKey({ remoteOrigin: remoteGateway ? probeOrigin : null });
2749
2829
  }
2750
2830
 
2751
2831
  // Receipts and agent tokens are signed by a key the DEPLOYMENT owns. A missing
2752
2832
  // key is loud (nothing is signed), but a PASSCONTROL_ISSUER pointing somewhere
2753
2833
  // that does not serve this deployment's JWKS fails silently: every receipt then
2754
2834
  // carries an `iss` whose key set cannot verify it. Check it explicitly.
2755
- async function checkInstanceSigningKey() {
2835
+ async function checkInstanceSigningKey({ remoteOrigin = null } = {}) {
2756
2836
  const seed = process.env.INSTANCE_SIGNING_KEY;
2757
2837
  const issuer = process.env.PASSCONTROL_ISSUER;
2758
2838
 
2839
+ // The key belongs to the deployment. A remote gateway signs with its own, so
2840
+ // its absence from this shell disables nothing.
2841
+ if (!seed && remoteOrigin) {
2842
+ step(`Receipts are signed by the gateway (${remoteOrigin}); its public keys are at ${remoteOrigin}/.well-known/jwks.json.`);
2843
+ return;
2844
+ }
2845
+
2759
2846
  if (!seed) {
2760
2847
  step(
2761
2848
  "Instance signing key not set in this shell — receipts and agent tokens are disabled " +
@@ -3181,6 +3268,9 @@ const IMPORT_REASONS = {
3181
3268
  policy_malformed: "its policy could not be parsed, and creating it without one would leave it unrestricted.",
3182
3269
  policy_shadow_malformed: "its shadow policy could not be parsed.",
3183
3270
  unknown_status: "it records a status this version does not recognise.",
3271
+ account_limit_reached:
3272
+ "this account has reached its agent limit. Nothing was created for it. Revoke agents you no longer use, " +
3273
+ "or ask the operator for a higher limit, then import again: agents already created are skipped.",
3184
3274
  };
3185
3275
 
3186
3276
  async function exportCommand(opts = {}) {
@@ -3423,7 +3513,9 @@ function keyTone(storage) {
3423
3513
  if (storage?.fallback) return ["warn", "file fallback", "the OS store was unavailable"];
3424
3514
  if (storage?.available !== true) return ["idle", "not configured", ""];
3425
3515
  if (storage?.tier === 1) return ["ok", "ready", String(storage.source ?? "OS store")];
3426
- return ["ok", "ready", "file"];
3516
+ // Tier 0 is a config file or the operator's environment; saying "file" for a
3517
+ // key that came from PASSPORT_SECRET sends them looking for a file to clean up.
3518
+ return ["ok", "ready", storage?.source === "environment variable" ? "env var" : "file"];
3427
3519
  }
3428
3520
 
3429
3521
  /**
package/cli/config.mjs CHANGED
@@ -28,8 +28,8 @@ export const PACKAGE_VERSION = (() => {
28
28
  // second numeric copy that can drift from system-health capability reporting.
29
29
  export const WORKSPACE_IMPORT_MAX_VERSION = WORKSPACE_EXPORT_PROTOCOL.maximum;
30
30
 
31
- export const PROVIDERS = ["openai", "anthropic", "groq", "mistral", "together", "deepseek", "gemini"];
32
- export const OPENAI_SHAPE_PROVIDERS = new Set(["openai", "groq", "mistral", "together", "deepseek", "gemini"]);
31
+ export const PROVIDERS = ["openai", "anthropic", "groq", "mistral", "together", "deepseek", "gemini", "xai", "azure", "local"];
32
+ export const OPENAI_SHAPE_PROVIDERS = new Set(["openai", "groq", "mistral", "together", "deepseek", "gemini", "azure", "local"]);
33
33
 
34
34
  const DEFAULT_GATEWAY = "http://localhost:3000";
35
35
 
@@ -0,0 +1,56 @@
1
+ // The unauthenticated "is the gateway there?" probe behind `status`, `version`
2
+ // and the menu: GET /api/version, which carries no credential.
3
+ //
4
+ // A gateway on this machine answers in milliseconds, so a short timeout keeps a
5
+ // stopped local stack from stalling the command. A remote one (Cloud, or a
6
+ // self-host on another host) pays for DNS, TLS and possibly a cold start on the
7
+ // first call, which can exceed a second; with the local timeout, a new Cloud
8
+ // user's first `status` read "offline". A timeout is also reported as one: "no
9
+ // answer" and "offline" send an operator to different places.
10
+ import { isLoopbackBindHost } from "./proxy-policy.mjs";
11
+
12
+ export const LOCAL_PROBE_TIMEOUT_MS = 1200;
13
+ export const REMOTE_PROBE_TIMEOUT_MS = 6000;
14
+
15
+ /** Whether a gateway origin is on this machine. A malformed one counts as local: the checks then run. */
16
+ export function isLocalGatewayOrigin(origin) {
17
+ try {
18
+ return isLoopbackBindHost(new URL(origin).hostname);
19
+ } catch {
20
+ return true;
21
+ }
22
+ }
23
+
24
+ export function probeTimeoutMs(origin) {
25
+ try {
26
+ return isLoopbackBindHost(new URL(origin).hostname) ? LOCAL_PROBE_TIMEOUT_MS : REMOTE_PROBE_TIMEOUT_MS;
27
+ } catch {
28
+ return LOCAL_PROBE_TIMEOUT_MS;
29
+ }
30
+ }
31
+
32
+ /** GET <origin>/api/version with a timeout, as a status row. `origin` must already be validated. */
33
+ export async function probeGatewayVersion(origin, { fetchImpl = fetch, timeoutMs = probeTimeoutMs(origin) } = {}) {
34
+ const controller = new AbortController();
35
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
36
+ try {
37
+ const res = await fetchImpl(`${origin}/api/version`, {
38
+ method: "GET",
39
+ headers: { accept: "application/json" },
40
+ signal: controller.signal,
41
+ });
42
+ if (!res.ok) return { label: `unhealthy (${res.status})`, ok: false };
43
+ const body = await res.json().catch(() => null);
44
+ const version = typeof body?.version === "string" && body.version.trim() ? body.version.trim() : null;
45
+ return version
46
+ ? { label: `online (${res.status}, PassControl ${version})`, ok: true, version }
47
+ : { label: "unhealthy (not a PassControl version response)", ok: false };
48
+ } catch (error) {
49
+ if (controller.signal.aborted || error?.name === "AbortError") {
50
+ return { label: `no answer within ${timeoutMs / 1000} s`, ok: false };
51
+ }
52
+ return { label: "offline or unreachable", ok: false };
53
+ } finally {
54
+ clearTimeout(timer);
55
+ }
56
+ }
@@ -5,7 +5,10 @@ export type IntegrationProvider =
5
5
  | "mistral"
6
6
  | "together"
7
7
  | "deepseek"
8
- | "gemini";
8
+ | "gemini"
9
+ | "xai"
10
+ | "azure"
11
+ | "local";
9
12
 
10
13
  export const DEFAULT_ALLOWED_MODELS: Readonly<Record<IntegrationProvider, string>>;
11
14
  export const DEFAULT_CLIENT_MODELS: Readonly<Record<IntegrationProvider, string>>;
@@ -12,6 +12,16 @@ export const DEFAULT_ALLOWED_MODELS = Object.freeze({
12
12
  together: "openai/gpt-oss-*",
13
13
  deepseek: "deepseek-*",
14
14
  gemini: "gemini-*",
15
+ xai: "grok-*",
16
+ // An Azure `model` is a DEPLOYMENT name the customer chose, not a model id.
17
+ // `gpt-*` covers deployments named after their model and nothing wider: a bare
18
+ // `*` would widen an allowlist to whatever a resource ever deploys. An operator
19
+ // whose deployments are named otherwise edits the scope.
20
+ azure: "gpt-*",
21
+ // A model on the developer's own server: free to them, and whatever they pulled.
22
+ // The admin API (pull, delete) is outside the endpoint allowlist, so `*` widens
23
+ // which local model an agent may run, never what it may do to the server.
24
+ local: "*",
15
25
  });
16
26
 
17
27
  export const DEFAULT_CLIENT_MODELS = Object.freeze({
@@ -22,6 +32,14 @@ export const DEFAULT_CLIENT_MODELS = Object.freeze({
22
32
  together: "openai/gpt-oss-120b",
23
33
  deepseek: "deepseek-flash",
24
34
  gemini: "gemini-3.8-flash",
35
+ // The cheapest listed model that does not reason (docs.x.ai/developers/models.md,
36
+ // 2026-09-27): xAI's reasoning models cannot turn reasoning off.
37
+ xai: "grok-4.20-0309-non-reasoning",
38
+ // A deployment name, so only a guess until the operator names theirs.
39
+ azure: "gpt-4.1-mini",
40
+ // Ollama's most-pulled small model. Only a guess: the dashboard offers the
41
+ // models the server actually has.
42
+ local: "llama3.2",
25
43
  });
26
44
 
27
45
  export function defaultAllowedModelForProvider(provider) {
@@ -0,0 +1,75 @@
1
+ // The local stack's addresses as a function of the port offset `setup` was
2
+ // given. One definition for setup and everything that reads its result, so a
3
+ // second install (`setup --port-offset N`) moves as a whole: Supabase, Redis
4
+ // (scripts/dev-stack.sh) and the dashboard.
5
+
6
+ /** The canonical local dashboard port, used when no offset was given. */
7
+ export const LOCAL_DASHBOARD_PORT = 3000;
8
+
9
+ /** The same bounds setup enforces on --port-offset. */
10
+ function assertOffset(offset) {
11
+ if (!Number.isInteger(offset) || offset < 0 || offset > 10000) {
12
+ throw new Error("--port-offset must be an integer from 0 to 10000.");
13
+ }
14
+ }
15
+
16
+ /** The local dashboard origin for a stack set up with this port offset. */
17
+ export function dashboardOriginForOffset(offset) {
18
+ assertOffset(offset);
19
+ return `http://localhost:${LOCAL_DASHBOARD_PORT + offset}`;
20
+ }
21
+
22
+ // Supabase names each container supabase_<service>_<project>. Services with an
23
+ // underscore come first, so "supabase_edge_runtime_x" is not read as project
24
+ // "runtime_x".
25
+ const SUPABASE_SERVICES = [
26
+ "edge_runtime", "pg_meta", "db", "kong", "inbucket", "mailpit", "analytics",
27
+ "studio", "rest", "auth", "realtime", "storage", "imgproxy", "vector", "pooler",
28
+ ];
29
+
30
+ /** The Supabase project a container belongs to, or null when it is not a Supabase service. */
31
+ export function stackProjectFromContainer(name) {
32
+ for (const service of SUPABASE_SERVICES) {
33
+ const prefix = `supabase_${service}_`;
34
+ if (name.startsWith(prefix) && name.length > prefix.length) return name.slice(prefix.length);
35
+ }
36
+ return null;
37
+ }
38
+
39
+ /**
40
+ * Which running containers publish which of `ports`, from
41
+ * `docker ps --format '{{.Names}}\t{{.Ports}}'`. A port held by something that
42
+ * is not a container (a database installed natively, say) is simply absent.
43
+ */
44
+ export function portHolders(psOutput, ports) {
45
+ const holders = [];
46
+ for (const line of String(psOutput).split("\n")) {
47
+ const [rawName, published = ""] = line.split("\t");
48
+ const container = rawName?.trim();
49
+ if (!container) continue;
50
+ const held = ports.filter((port) => new RegExp(`:${port}->`, "u").test(published));
51
+ if (held.length) holders.push({ container, project: stackProjectFromContainer(container), ports: held });
52
+ }
53
+ return holders;
54
+ }
55
+
56
+ /** The refusal for busy stack ports: who holds them, and the exact command that frees them. */
57
+ export function stackPortConflictMessage({ busy, holders = [], rerun }) {
58
+ const projects = [...new Set(holders.map((holder) => holder.project).filter(Boolean))];
59
+ const containers = holders.filter((holder) => !holder.project).map((holder) => holder.container);
60
+ const owners = [];
61
+ if (projects.length) {
62
+ owners.push(`another local Supabase stack (project ${projects.map((project) => `"${project}"`).join(", ")})`);
63
+ }
64
+ if (containers.length) owners.push(`container ${containers.join(", ")}`);
65
+ const ports = `Local stack ports ${busy.join(", ")} are in use by ${owners.length ? owners.join(" and ") : "another program or project"}.`;
66
+ // `docker stop` keeps a container and its volume, like `supabase stop`.
67
+ const commands = [
68
+ ...projects.map((project) => `\`supabase stop --project-id ${project}\``),
69
+ ...containers.map((container) => `\`docker stop ${container}\``),
70
+ ];
71
+ const fix = commands.length
72
+ ? `Stop ${commands.length > 1 ? "them" : "it"} first (data is kept): ${commands.join(" and ")}`
73
+ : "Stop that project first (for example, `supabase stop --project-id <project>`)";
74
+ return `${ports} ${fix}, then rerun \`${rerun}\`.`;
75
+ }
@@ -6,10 +6,16 @@ export async function collectMenuRemoteStatus({
6
6
  request,
7
7
  safeText = (value, fallback) => value == null ? fallback : String(value),
8
8
  }) {
9
+ const options = { timeoutMs: MENU_STATUS_TIMEOUT_MS };
9
10
  if (!hasApiKey) {
10
- return { account: null, gateway: "not authenticated", fleet: "unavailable", kill: "unavailable", current: {} };
11
+ // The gateway probe reads the public /api/version and carries no
12
+ // credential, so a passport-only machine still learns whether its gateway
13
+ // is up. Everything else needs the key.
14
+ const gateway = await Promise.resolve()
15
+ .then(() => gatewayStatus(options))
16
+ .then((result) => result.label, () => "unavailable");
17
+ return { account: null, gateway, fleet: "unavailable", kill: "unavailable", current: {} };
11
18
  }
12
- const options = { timeoutMs: MENU_STATUS_TIMEOUT_MS };
13
19
  const [gatewayResult, accountResult, fleetResult, killResult] = await Promise.allSettled([
14
20
  gatewayStatus(options),
15
21
  request("/account", options),
package/cli/presets.mjs CHANGED
@@ -30,6 +30,71 @@ export function isGuiPreset(name) {
30
30
  return Object.hasOwn(GUI_PRESET_LABELS, String(name ?? "").toLowerCase());
31
31
  }
32
32
 
33
+ /**
34
+ * Non-LLM APIs a client can be pointed at through the sidecar (any-API). The
35
+ * preset prints the governed base URL for that service; what the agent may call
36
+ * there is set per agent in the dashboard.
37
+ */
38
+ export const SERVICE_PRESETS = ["github", "telegram", "brave", "notion", "discord"];
39
+
40
+ /**
41
+ * What `passcontrol env <service>` prints for each: the variable (the same one
42
+ * the dashboard's Setup names, lib/services/display.ts), two lines on where the
43
+ * agent's access is set, and one usage hint. Pinned to the catalog by
44
+ * tests/cli-service-presets.test.ts.
45
+ */
46
+ export const SERVICE_ENV = {
47
+ github: {
48
+ label: "GitHub",
49
+ envVar: "GITHUB_API_URL",
50
+ about: [
51
+ "# GitHub REST through PassControl. What this agent may do is set on its page in the",
52
+ "# dashboard, under GitHub access; the workspace's GitHub token stays in PassControl.",
53
+ ],
54
+ usage: "# Octokit: new Octokit({ baseUrl: process.env.GITHUB_API_URL }) — and no auth option.",
55
+ },
56
+ telegram: {
57
+ label: "Telegram",
58
+ envVar: "TELEGRAM_API_URL",
59
+ about: [
60
+ "# Telegram Bot API through PassControl. What this agent may do is set on its page in the",
61
+ "# dashboard, under Telegram access; the bot token stays in PassControl.",
62
+ ],
63
+ usage: '# Call a method by name, with no token in the URL: curl "$TELEGRAM_API_URL/getMe"',
64
+ },
65
+ brave: {
66
+ label: "Brave Search",
67
+ envVar: "BRAVE_SEARCH_API_URL",
68
+ about: [
69
+ "# Brave Search through PassControl. What this agent may search is set on its page in the",
70
+ "# dashboard, under Brave Search access; the API key stays in PassControl. Brave bills per search.",
71
+ ],
72
+ usage: '# Search with no key header: curl "$BRAVE_SEARCH_API_URL/web/search?q=passcontrol"',
73
+ },
74
+ notion: {
75
+ label: "Notion",
76
+ envVar: "NOTION_API_URL",
77
+ about: [
78
+ "# Notion through PassControl. What this agent may do is set on its page in the dashboard,",
79
+ "# under Notion access; the integration token stays in PassControl.",
80
+ ],
81
+ usage: "# @notionhq/client: new Client({ baseUrl: process.env.NOTION_API_URL }) — and no auth option.",
82
+ },
83
+ discord: {
84
+ label: "Discord",
85
+ envVar: "DISCORD_API_URL",
86
+ about: [
87
+ "# Discord's bot API through PassControl. What this agent may do is set on its page in the",
88
+ "# dashboard, under Discord access; the bot token stays in PassControl.",
89
+ ],
90
+ usage: '# discord.js: new REST({ api: process.env.DISCORD_API_URL, version: "10" }).setToken("sidecar") — any token; the sidecar replaces it.',
91
+ },
92
+ };
93
+
94
+ export function isServicePreset(name) {
95
+ return SERVICE_PRESETS.includes(String(name ?? "").toLowerCase());
96
+ }
97
+
33
98
  /** Presets that print settings pointing an agent at the local sidecar bridge. */
34
99
  export const SIDECAR_PRESETS = [
35
100
  "generic",
@@ -38,6 +103,7 @@ export const SIDECAR_PRESETS = [
38
103
  "aider",
39
104
  "hermes",
40
105
  ...Object.keys(GUI_PRESET_LABELS),
106
+ ...SERVICE_PRESETS,
41
107
  ];
42
108
 
43
109
  /** MCP client targets. Shares the set the MCP config writer dispatches on. */
@@ -42,11 +42,46 @@ export const PROVIDER_UPSTREAMS = {
42
42
  // as `provider_tunnel_not_governed` — and, deliberately, what makes it
43
43
  // permanently ineligible for `--allow-connect`.
44
44
  gemini: { hostname: "generativelanguage.googleapis.com", basePath: "/v1beta/openai" },
45
+ xai: { hostname: "api.x.ai", basePath: "" },
45
46
  };
46
47
 
47
- const HOST_BY_NAME = new Map(
48
- Object.entries(PROVIDER_UPSTREAMS).map(([provider, entry]) => [entry.hostname, { provider, ...entry }])
49
- );
48
+ /**
49
+ * Non-LLM service upstreams (any-API), as host + base path.
50
+ *
51
+ * A second copy of `lib/services/catalog.ts`'s origins, for the .mjs reason
52
+ * above; `tests/cli-provider-hosts.test.ts` fails when they disagree. A service
53
+ * host is refused for CONNECT and permanently ineligible for `--allow-connect`
54
+ * for the same reason a provider host is: its token lives in the gateway, and a
55
+ * tunnel would be an ungoverned call wearing a governed badge. Its governed
56
+ * route is `/api/v1/svc/<service>`.
57
+ */
58
+ export const SERVICE_UPSTREAMS = {
59
+ github: { hostname: "api.github.com", basePath: "" },
60
+ // Telegram's token is in its URL path, so a tunnel to it would carry the bot
61
+ // token past every control: refused for CONNECT, like every host here.
62
+ telegram: { hostname: "api.telegram.org", basePath: "" },
63
+ // Its key goes in a header; a tunnel would send searches billed to the
64
+ // workspace past the agent's rules and cap.
65
+ // basePath: the prefix the gateway adds itself (the catalog's upstreamUrl),
66
+ // stripped here so a routed request does not carry it twice.
67
+ brave: { hostname: "api.search.brave.com", basePath: "/res/v1" },
68
+ notion: { hostname: "api.notion.com", basePath: "" },
69
+ // discord.com is also Discord's website: an agent's browser-like traffic to it
70
+ // is refused through the sidecar, as every governed service host is.
71
+ discord: { hostname: "discord.com", basePath: "/api" },
72
+ };
73
+
74
+ // `route` is the path segment after /api/v1/ that governs the host.
75
+ const HOST_BY_NAME = new Map([
76
+ ...Object.entries(PROVIDER_UPSTREAMS).map(([provider, entry]) => [
77
+ entry.hostname,
78
+ { provider, route: provider, ...entry },
79
+ ]),
80
+ ...Object.entries(SERVICE_UPSTREAMS).map(([service, entry]) => [
81
+ entry.hostname,
82
+ { provider: service, route: `svc/${service}`, ...entry },
83
+ ]),
84
+ ]);
50
85
 
51
86
  // A hostname carrying any of these is not a hostname. Checked rather than
52
87
  // assumed because the value arrives on a request line from whatever the client
@@ -67,9 +102,24 @@ function normalizeHostname(value) {
67
102
  return host;
68
103
  }
69
104
 
105
+ /**
106
+ * Azure OpenAI has no fixed host: every customer's resource is its own. So it is
107
+ * recognised by the same closed suffix rule the gateway stores its addresses
108
+ * under (lib/providers/endpoint.ts `AZURE_HOST`) — one DNS label, then exactly
109
+ * `openai.azure.com` or `services.ai.azure.com` — rather than by a table row.
110
+ * Being recognised is what makes a CONNECT to a resource refuse, and what routes
111
+ * an absolute-form request to the governed `azure` route. The gateway then sends
112
+ * it to the address stored with the tenant's key, not to the host named here.
113
+ */
114
+ export const AZURE_HOST = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.(?:openai\.azure\.com|services\.ai\.azure\.com)$/;
115
+ const AZURE_UPSTREAM = { provider: "azure", route: "azure", basePath: "/openai/v1" };
116
+
70
117
  /** Exact match only — `evil-api.anthropic.com` is somebody else's hostname. */
71
118
  export function providerForHost(hostname) {
72
- return HOST_BY_NAME.get(normalizeHostname(hostname)) ?? null;
119
+ const host = normalizeHostname(hostname);
120
+ const fixed = HOST_BY_NAME.get(host);
121
+ if (fixed) return fixed;
122
+ return AZURE_HOST.test(host) ? { ...AZURE_UPSTREAM, hostname: host } : null;
73
123
  }
74
124
 
75
125
  function parsePort(value) {
@@ -147,9 +197,9 @@ function refuse(status, code, message, help) {
147
197
  return { allow: false, status, code, message, help };
148
198
  }
149
199
 
150
- function governedPathHelp(provider, localBaseUrl) {
200
+ function governedPathHelp(route, localBaseUrl) {
151
201
  const base = localBaseUrl ? String(localBaseUrl).replace(/\/+$/, "") : "";
152
- return `${base}/api/v1/${provider}`;
202
+ return `${base}/api/v1/${route}`;
153
203
  }
154
204
 
155
205
  /**
@@ -178,7 +228,7 @@ export function classifyConnect({ target, gatewayOrigin, allowHosts = [], localB
178
228
  `PassControl will not tunnel TLS to ${parsed.hostname}. It cannot see inside that connection, so it could ` +
179
229
  "neither inject the provider key nor apply scope, budget or the kill switch — the call would leave " +
180
230
  "ungoverned while appearing to be governed.",
181
- `Point the client's base URL at ${governedPathHelp(provider.provider, localBaseUrl)} instead. ` +
231
+ `Point the client's base URL at ${governedPathHelp(provider.route, localBaseUrl)} instead. ` +
182
232
  "PassControl does not install a TLS-intercepting CA."
183
233
  );
184
234
  }
@@ -250,7 +300,7 @@ export function classifyProxyRequest({ url, gatewayOrigin, localBaseUrl = "" } =
250
300
  rest = rest.slice(provider.basePath.length);
251
301
  }
252
302
  if (!rest.startsWith("/")) rest = `/${rest}`;
253
- return { allow: true, path: `/api/v1/${provider.provider}${rest}${parsed.search}`, reason: "provider" };
303
+ return { allow: true, path: `/api/v1/${provider.route}${rest}${parsed.search}`, reason: "provider" };
254
304
  }
255
305
 
256
306
  const gateway = gatewayTarget(gatewayOrigin);
package/cli/selftest.mjs CHANGED
@@ -111,7 +111,7 @@ export async function proveItWorks({
111
111
  });
112
112
  const visa = await visas.getVisa();
113
113
  proof.visa = true;
114
- ok("minted a visa with the passport this machine just created");
114
+ ok("minted a visa with this passport");
115
115
 
116
116
  const res = await fetchImpl(`${origin}/api/v1/demo/chat/completions`, {
117
117
  method: "POST",
@@ -124,6 +124,16 @@ export async function proveItWorks({
124
124
  });
125
125
 
126
126
  if (!res.ok) {
127
+ // A passport with no model scope (an agent made for GitHub or Telegram
128
+ // only) is refused here by design. Telling it to add a provider key would
129
+ // be advice about a different agent.
130
+ const refusal = res.status === 403 ? await res.json().catch(() => null) : null;
131
+ if (refusal?.error === "blocked_scope") {
132
+ proof.reason = "no_model_scope";
133
+ step("This passport has no model access, so the demo model call was refused, as it should be for an");
134
+ step("agent that calls only GitHub or Telegram. Its service access is set on its page in the dashboard.");
135
+ return proof;
136
+ }
127
137
  // 404 is the ordinary answer from a self-hosted gateway that has not set
128
138
  // PASSCONTROL_DEMO=1 — a correctly configured gateway, not a fault. Say so
129
139
  // in those words, because "404" here would read as something being broken.
package/cli/sidecar.mjs CHANGED
@@ -148,10 +148,19 @@ export function createSidecar({
148
148
  return fetch(`${origin}${path}`, { method: req.method, headers, body: body ?? undefined });
149
149
  }
150
150
 
151
+ // A service call's pagination `link` and same-origin `location` name the
152
+ // GATEWAY (it builds them from its own origin), and following one directly
153
+ // would skip the visa only this sidecar adds. Point them back at the sidecar.
154
+ // Only the exact gateway origin followed by /api/v1/ is rewritten; any other
155
+ // URL — codeload for an archive download — passes through untouched.
156
+ const toLocal = (value) => value.split(`${origin}/api/v1/`).join(`${localBaseUrl()}/api/v1/`);
157
+
151
158
  function writeResponse(res, upstream) {
152
159
  const outHeaders = {};
153
160
  upstream.headers.forEach((v, k) => {
154
- if (!STRIP_RES.has(k.toLowerCase())) outHeaders[k] = v;
161
+ const name = k.toLowerCase();
162
+ if (STRIP_RES.has(name)) return;
163
+ outHeaders[k] = name === "link" || name === "location" ? toLocal(v) : v;
155
164
  });
156
165
  res.writeHead(upstream.status, outHeaders);
157
166
  if (upstream.body) Readable.fromWeb(upstream.body).pipe(res);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "1.0.0",
3
+ "version": "1.2.0",
4
4
  "description": "Identity, scope and budget controls for AI agents while provider keys stay server-side.",
5
5
  "license": "BUSL-1.1",
6
6
  "homepage": "https://passcontrol.vertias.eu",
package/sdk/README.md CHANGED
@@ -158,9 +158,12 @@ The full reference lives in [the public OpenAPI document](https://github.com/Ver
158
158
  ## Compatibility and assurance
159
159
 
160
160
  `clientOptions` accepts `openai`, `anthropic`, `groq`, `mistral`, `together`, `deepseek`,
161
- and `gemini`. OpenAI POST Responses works through `pc.fetch`/the OpenAI SDK as well as
162
- Chat Completions. Gemini uses Google's OpenAI-compatible endpoint; native
163
- `generateContent` is not supported. See [accepted paths](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md#data-plane--proxy-a-model-call).
161
+ `gemini`, `xai`, `azure` and `local` (a model server you run, such as Ollama; self-host only). OpenAI POST Responses works through `pc.fetch`/the OpenAI SDK as well as
162
+ Chat Completions. xAI is served through its Responses API only (`client.responses.create`);
163
+ its legacy Chat Completions endpoint is refused. Gemini uses Google's OpenAI-compatible endpoint; native
164
+ `generateContent` is not supported. Azure OpenAI takes the plain OpenAI client (not
165
+ `AzureOpenAI`), with `model` set to your deployment name; the gateway sends the call to the
166
+ resource address stored with your Azure key. See [accepted paths](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md#data-plane--proxy-a-model-call).
164
167
 
165
168
  The TypeScript SDK **does not attach sender proofs**. Its provider requests use
166
169
  bearer visas: they work with sender-proof mode off/observe, but required mode refuses
package/sdk/control.d.ts CHANGED
@@ -120,21 +120,23 @@ export declare class ControlClient {
120
120
  readonly logs: {
121
121
  /**
122
122
  * `class` selects a view, never a different record: omitted returns every
123
- * call, `inference` drops SDK housekeeping (startup model-listing probes),
124
- * `housekeeping` returns only those. The limit is applied before the
125
- * filter, so a filtered page can be shorter than the limit asked for.
123
+ * call, `inference` returns model calls only (no SDK housekeeping — startup
124
+ * model-listing probes — and no service calls), `housekeeping` returns only
125
+ * those probes, and `service` returns only calls to a non-LLM API such as
126
+ * GitHub. The limit is applied before the filter, so a filtered page can be
127
+ * shorter than the limit asked for.
126
128
  */
127
129
  list: (params?: {
128
130
  agent_id?: string;
129
131
  status?: string;
130
- class?: "inference" | "housekeeping";
132
+ class?: "inference" | "housekeeping" | "service";
131
133
  limit?: number;
132
134
  cursor?: string;
133
135
  }) => Promise<any[]>;
134
136
  page: (params?: {
135
137
  agent_id?: string;
136
138
  status?: string;
137
- class?: "inference" | "housekeeping";
139
+ class?: "inference" | "housekeeping" | "service";
138
140
  limit?: number;
139
141
  cursor?: string;
140
142
  }) => Promise<{
package/sdk/control.js CHANGED
@@ -95,9 +95,11 @@ export class ControlClient {
95
95
  logs = {
96
96
  /**
97
97
  * `class` selects a view, never a different record: omitted returns every
98
- * call, `inference` drops SDK housekeeping (startup model-listing probes),
99
- * `housekeeping` returns only those. The limit is applied before the
100
- * filter, so a filtered page can be shorter than the limit asked for.
98
+ * call, `inference` returns model calls only (no SDK housekeeping — startup
99
+ * model-listing probes — and no service calls), `housekeeping` returns only
100
+ * those probes, and `service` returns only calls to a non-LLM API such as
101
+ * GitHub. The limit is applied before the filter, so a filtered page can be
102
+ * shorter than the limit asked for.
101
103
  */
102
104
  list: (params) => this.req("GET", "/logs", { query: params }),
103
105
  page: (params) => this.request("GET", "/logs", { query: params }),
@@ -1,4 +1,4 @@
1
- export type ProviderId = "openai" | "anthropic" | "groq" | "mistral" | "together" | "deepseek" | "gemini";
1
+ export type ProviderId = "openai" | "anthropic" | "groq" | "mistral" | "together" | "deepseek" | "gemini" | "xai" | "azure" | "local";
2
2
  export interface PassControlOptions {
3
3
  /**
4
4
  * Gateway origin, e.g. https://passcontrol.example.com — scheme, host and