passcontrol 1.0.0 → 1.1.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
@@ -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`; 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
@@ -259,7 +259,7 @@ are separate from signature verification.
259
259
  - Token and cost admission limits through atomic reservations and settlement.
260
260
  - Platform/tenant kill switches and per-agent suspension/revocation.
261
261
  - Provider failover within supported request families and each attempt's authorization
262
- and budget checks; it is not arbitrary API translation.
262
+ and budget checks; it is not arbitrary API translation. Embeddings never fail over.
263
263
  - The injected provider key is removed from what comes back: if an upstream echoes it in
264
264
  an error body, a JSON answer or an event stream (even split across chunks), the agent
265
265
  receives `[REDACTED_PROVIDER_KEY]` instead. This covers the exact key, not a key an
@@ -315,15 +315,19 @@ All paths below are relative to `/api/v1/<provider>`. SDK base URLs and aliases
315
315
 
316
316
  | Provider ID | Inference | Discovery |
317
317
  |---|---|---|
318
- | `openai` | Chat Completions and **POST Responses** | Models list/detail |
318
+ | `openai` | Chat Completions, **POST Responses** and **POST Embeddings** | Models list/detail |
319
319
  | `anthropic` | Messages | Models list/detail |
320
- | `groq`, `mistral`, `together` | OpenAI-compatible Chat Completions | Models list/detail |
320
+ | `mistral` | OpenAI-compatible Chat Completions and **POST Embeddings** | Models list/detail |
321
+ | `groq`, `together` | OpenAI-compatible Chat Completions | Models list/detail |
321
322
  | `deepseek` | OpenAI-compatible Chat Completions | Not proxied |
322
323
  | `gemini` | Google's **OpenAI-compatible** Chat Completions | Models list/detail |
324
+ | `xai` | **POST Responses** only (legacy Chat Completions refused) | Models list/detail |
325
+ | `azure` | Azure OpenAI v1: Chat Completions, **POST Responses** and **POST Embeddings**, at the resource address stored with the key | Models list |
323
326
 
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
+ Gemini's native `generateContent` API is not supported. Responses is served for OpenAI,
328
+ xAI and Azure; embeddings for OpenAI, Mistral and Azure, and an embeddings call never fails over, because
329
+ another model's vectors would not match the ones already stored. Response retrieval/deletion,
330
+ files, fine-tuning, batches, and token-counting endpoints are not proxied. OpenAI's hosted tools (web search, file search, code interpreter
327
331
  and others billed outside tokens) and its search models are refused, because no token budget can
328
332
  hold their fees. Model availability still depends on your provider account.
329
333
 
@@ -67,6 +67,7 @@ import {
67
67
  integrationChoices,
68
68
  isGuiPreset,
69
69
  isIntegration,
70
+ isServicePreset,
70
71
  supportsWrite,
71
72
  } from "../cli/presets.mjs";
72
73
  import { importCompletionMessage, noAgentCreateMessage } from "../cli/workspace-import-report.mjs";
@@ -83,6 +84,8 @@ import {
83
84
  stackFromConfig,
84
85
  writeMarker,
85
86
  } from "../cli/update.mjs";
87
+ import { isLocalGatewayOrigin, probeGatewayVersion, probeTimeoutMs } from "../cli/gateway-probe.mjs";
88
+ import { dashboardOriginForOffset } from "../cli/local-stack.mjs";
86
89
  import { startSidecar } from "../cli/sidecar.mjs";
87
90
  import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
88
91
  import { loginCommand } from "../cli/login.mjs";
@@ -324,20 +327,7 @@ async function gatewayStatus(noNetwork = false, gateway = config.gateway) {
324
327
  if (noNetwork) return { label: "not checked", ok: null };
325
328
  const origin = probeGatewayOrigin({ gateway });
326
329
  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
- }
330
+ return probeGatewayVersion(origin);
341
331
  }
342
332
 
343
333
  async function printCockpit({ noNetwork = false, json = false } = {}) {
@@ -1238,17 +1228,38 @@ async function assertLocalStackPortsAvailable(offset = 0) {
1238
1228
  }
1239
1229
 
1240
1230
  async function checkLocalStackPorts(offset = 0) {
1231
+ // Named in the line, so an install made with --port-offset can see which
1232
+ // ports were actually checked.
1233
+ const label = offset ? `Local stack ports (offset ${offset})` : "Local stack ports";
1241
1234
  try {
1242
1235
  await assertLocalStackPortsAvailable(offset);
1243
- return { ok: true, message: "Local stack ports: available." };
1236
+ return { ok: true, message: `${label}: available.` };
1244
1237
  } catch (error) {
1245
1238
  return {
1246
1239
  ok: false,
1247
- message: `Local stack ports: unavailable. Fix: stop the conflicting project or rerun setup with --port-offset N. Details: ${error.message}`,
1240
+ message: `${label}: unavailable. Fix: stop the conflicting project or rerun setup with --port-offset N. Details: ${error.message}`,
1248
1241
  };
1249
1242
  }
1250
1243
  }
1251
1244
 
1245
+ /**
1246
+ * The port offset `setup` baked into this checkout's supabase/config.toml, or 0
1247
+ * when it was never set up. Read back, as `update` does (stackFromConfig),
1248
+ * because the offset is a setup-time flag nobody passes again: checking at 0
1249
+ * reported a working --port-offset install as "ports unavailable".
1250
+ */
1251
+ function installedStackOffset() {
1252
+ try {
1253
+ const root = appRoot ?? resolveAppRoot();
1254
+ if (!root) return 0;
1255
+ const configPath = path.join(root, "supabase", "config.toml");
1256
+ if (!fs.existsSync(configPath)) return 0;
1257
+ return stackFromConfig(fs.readFileSync(configPath, "utf8"))?.offset ?? 0;
1258
+ } catch {
1259
+ return 0;
1260
+ }
1261
+ }
1262
+
1252
1263
  async function runLocalPrerequisiteChecks({ offset = 0, report = false, enforce = false } = {}) {
1253
1264
  const results = [
1254
1265
  checkDockerInstalled(),
@@ -1808,18 +1819,26 @@ async function updateCommand(opts = {}) {
1808
1819
  }
1809
1820
 
1810
1821
  async function setupLocal(opts = {}) {
1811
- const dashboard = canonicalLocalDashboard();
1812
- const activation = await prepareLocalActivation(dashboard, opts);
1813
1822
  const offset = opts.portOffset === undefined ? 0 : Number(opts.portOffset);
1814
1823
  if (!Number.isInteger(offset) || offset < 0 || offset > 10000) {
1815
1824
  throw new Error("--port-offset must be an integer from 0 to 10000.");
1816
1825
  }
1826
+ // The dashboard moves with the offset, like Supabase and Redis: a second
1827
+ // install on :3000 would collide with the first one's dashboard. Saved as the
1828
+ // gateway by the activation below, so `start`, `stop` and `status` follow it.
1829
+ const dashboard = parseLocalDashboard(
1830
+ dashboardOriginForOffset(offset),
1831
+ offset ? "the offset local dashboard" : "the canonical local dashboard"
1832
+ );
1833
+ const activation = await prepareLocalActivation(dashboard, opts);
1817
1834
  await runLocalPrerequisiteChecks({ offset, enforce: true });
1818
1835
  await ensureAppRoot({ clone: true, appDir: opts.appDir, yes: opts.yes });
1819
1836
  step("Preparing the local Supabase, Redis, migrations, and dev user…");
1820
1837
  await runLocalCommand(process.platform === "win32" ? "npm.cmd" : "npm", ["run", "dev:stack"], {
1821
1838
  ...process.env,
1822
1839
  PASSCONTROL_PORT_OFFSET: String(offset),
1840
+ // Supabase's site URL and the receipt issuer are written from PORT.
1841
+ PORT: String(dashboard.port),
1823
1842
  PASSCONTROL_VIA_CLI: "1",
1824
1843
  });
1825
1844
  // dev:stack has just brought Supabase and Redis up (and would have exited
@@ -2386,6 +2405,11 @@ function printAgentPreset(name = "generic", opts = {}) {
2386
2405
  return;
2387
2406
  }
2388
2407
 
2408
+ if (isServicePreset(preset)) {
2409
+ printServicePreset(preset, opts);
2410
+ return;
2411
+ }
2412
+
2389
2413
  const { provider, model, apiKey, baseUrl, port } = sidecarBaseUrl(opts);
2390
2414
  const modelWithProvider = `${provider}/${model}`;
2391
2415
  const sidecarStart = opts.port != null || process.env.SIDECAR_PORT != null
@@ -2453,6 +2477,34 @@ function printAgentPreset(name = "generic", opts = {}) {
2453
2477
  }
2454
2478
  }
2455
2479
 
2480
+ // A service preset has no provider and no model: the client is pointed at the
2481
+ // governed service route and sends no service token at all — the gateway
2482
+ // injects the workspace's, and only for calls the agent's rules admit.
2483
+ function printServicePreset(service, opts = {}) {
2484
+ const host = String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1");
2485
+ const port = sidecarPort(opts);
2486
+ const sidecarStart = opts.port != null || process.env.SIDECAR_PORT != null
2487
+ ? cliCommand(`sidecar --port ${port}`)
2488
+ : cliCommand("sidecar");
2489
+ console.log(`# Start the bridge first: ${sidecarStart}`);
2490
+ switch (service) {
2491
+ case "github":
2492
+ console.log("# GitHub REST through PassControl. What this agent may do is set on its page in the");
2493
+ console.log("# dashboard, under GitHub access; the workspace's GitHub token stays in PassControl.");
2494
+ printExports([["GITHUB_API_URL", `http://${host}:${port}/api/v1/svc/github`]]);
2495
+ console.log("# Octokit: new Octokit({ baseUrl: process.env.GITHUB_API_URL }) — and no auth option.");
2496
+ break;
2497
+ case "telegram":
2498
+ console.log("# Telegram Bot API through PassControl. What this agent may do is set on its page in the");
2499
+ console.log("# dashboard, under Telegram access; the bot token stays in PassControl.");
2500
+ printExports([["TELEGRAM_API_URL", `http://${host}:${port}/api/v1/svc/telegram`]]);
2501
+ console.log('# Call a method by name, with no token in the URL: curl "$TELEGRAM_API_URL/getMe"');
2502
+ break;
2503
+ default:
2504
+ throw new Error(`Usage: passcontrol env <${integrationChoices()}>`);
2505
+ }
2506
+ }
2507
+
2456
2508
  function aiderConfig(opts = {}) {
2457
2509
  const { provider, model, baseUrl } = sidecarBaseUrl(opts);
2458
2510
  return [
@@ -2560,7 +2612,7 @@ async function serverVersion() {
2560
2612
  const origin = probeGatewayOrigin();
2561
2613
  if (!origin) return { version: null, detail: "the configured gateway is not a bare origin" };
2562
2614
  try {
2563
- const res = await fetchWithTimeout(`${origin}/api/version`);
2615
+ const res = await fetchWithTimeout(`${origin}/api/version`, {}, probeTimeoutMs(origin));
2564
2616
  // A gateway that predates this endpoint is a real PassControl gateway, and
2565
2617
  // saying "unreachable" about one that answered would send an operator to
2566
2618
  // debug their network instead of deploying.
@@ -2711,7 +2763,25 @@ async function doctorCommand(opts = {}) {
2711
2763
  // One authenticated request for this command. Its failure is a failed
2712
2764
  // diagnostic, not a CLI crash: remaining local checks are still useful.
2713
2765
  printSystemHealthDiagnostic(await fetchSystemHealth());
2714
- await runLocalPrerequisiteChecks({ report: true });
2766
+ // Docker, Supabase and the stack's ports matter only where a stack runs. A CLI
2767
+ // pointed at a remote gateway (Cloud) with no app checkout here has none, and
2768
+ // a failing "Local stack ports" line would send that user hunting for one.
2769
+ const probeOrigin = probeGatewayOrigin();
2770
+ const remoteGateway = probeOrigin !== null && !isLocalGatewayOrigin(probeOrigin);
2771
+ let localApp = null;
2772
+ try {
2773
+ localApp = resolveAppRoot();
2774
+ } catch {
2775
+ localApp = null;
2776
+ }
2777
+ if (remoteGateway && !localApp) {
2778
+ step(
2779
+ `Local prerequisites skipped: this CLI uses a remote gateway (${probeOrigin}). Docker and the ` +
2780
+ "local stack are needed only to self-host on this machine."
2781
+ );
2782
+ } else {
2783
+ await runLocalPrerequisiteChecks({ offset: installedStackOffset(), report: true });
2784
+ }
2715
2785
  if (config.passportId && config.passportSecret) {
2716
2786
  // The whole chain, not just the mint. "Visa mint works" proves the passport
2717
2787
  // authenticates and says nothing about scope, budget, the proxy or receipts —
@@ -2745,17 +2815,24 @@ async function doctorCommand(opts = {}) {
2745
2815
  step("Skipping control API check: no PASSCONTROL_API_KEY configured.");
2746
2816
  }
2747
2817
 
2748
- await checkInstanceSigningKey();
2818
+ await checkInstanceSigningKey({ remoteOrigin: remoteGateway ? probeOrigin : null });
2749
2819
  }
2750
2820
 
2751
2821
  // Receipts and agent tokens are signed by a key the DEPLOYMENT owns. A missing
2752
2822
  // key is loud (nothing is signed), but a PASSCONTROL_ISSUER pointing somewhere
2753
2823
  // that does not serve this deployment's JWKS fails silently: every receipt then
2754
2824
  // carries an `iss` whose key set cannot verify it. Check it explicitly.
2755
- async function checkInstanceSigningKey() {
2825
+ async function checkInstanceSigningKey({ remoteOrigin = null } = {}) {
2756
2826
  const seed = process.env.INSTANCE_SIGNING_KEY;
2757
2827
  const issuer = process.env.PASSCONTROL_ISSUER;
2758
2828
 
2829
+ // The key belongs to the deployment. A remote gateway signs with its own, so
2830
+ // its absence from this shell disables nothing.
2831
+ if (!seed && remoteOrigin) {
2832
+ step(`Receipts are signed by the gateway (${remoteOrigin}); its public keys are at ${remoteOrigin}/.well-known/jwks.json.`);
2833
+ return;
2834
+ }
2835
+
2759
2836
  if (!seed) {
2760
2837
  step(
2761
2838
  "Instance signing key not set in this shell — receipts and agent tokens are disabled " +
@@ -3423,7 +3500,9 @@ function keyTone(storage) {
3423
3500
  if (storage?.fallback) return ["warn", "file fallback", "the OS store was unavailable"];
3424
3501
  if (storage?.available !== true) return ["idle", "not configured", ""];
3425
3502
  if (storage?.tier === 1) return ["ok", "ready", String(storage.source ?? "OS store")];
3426
- return ["ok", "ready", "file"];
3503
+ // Tier 0 is a config file or the operator's environment; saying "file" for a
3504
+ // key that came from PASSPORT_SECRET sends them looking for a file to clean up.
3505
+ return ["ok", "ready", storage?.source === "environment variable" ? "env var" : "file"];
3427
3506
  }
3428
3507
 
3429
3508
  /**
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"];
32
+ export const OPENAI_SHAPE_PROVIDERS = new Set(["openai", "groq", "mistral", "together", "deepseek", "gemini", "azure"]);
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,9 @@ export type IntegrationProvider =
5
5
  | "mistral"
6
6
  | "together"
7
7
  | "deepseek"
8
- | "gemini";
8
+ | "gemini"
9
+ | "xai"
10
+ | "azure";
9
11
 
10
12
  export const DEFAULT_ALLOWED_MODELS: Readonly<Record<IntegrationProvider, string>>;
11
13
  export const DEFAULT_CLIENT_MODELS: Readonly<Record<IntegrationProvider, string>>;
@@ -12,6 +12,12 @@ 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-*",
15
21
  });
16
22
 
17
23
  export const DEFAULT_CLIENT_MODELS = Object.freeze({
@@ -22,6 +28,11 @@ export const DEFAULT_CLIENT_MODELS = Object.freeze({
22
28
  together: "openai/gpt-oss-120b",
23
29
  deepseek: "deepseek-flash",
24
30
  gemini: "gemini-3.8-flash",
31
+ // The cheapest listed model that does not reason (docs.x.ai/developers/models.md,
32
+ // 2026-09-27): xAI's reasoning models cannot turn reasoning off.
33
+ xai: "grok-4.20-0309-non-reasoning",
34
+ // A deployment name, so only a guess until the operator names theirs.
35
+ azure: "gpt-4.1-mini",
25
36
  });
26
37
 
27
38
  export function defaultAllowedModelForProvider(provider) {
@@ -0,0 +1,20 @@
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
+ }
@@ -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,17 @@ 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"];
39
+
40
+ export function isServicePreset(name) {
41
+ return SERVICE_PRESETS.includes(String(name ?? "").toLowerCase());
42
+ }
43
+
33
44
  /** Presets that print settings pointing an agent at the local sidecar bridge. */
34
45
  export const SIDECAR_PRESETS = [
35
46
  "generic",
@@ -38,6 +49,7 @@ export const SIDECAR_PRESETS = [
38
49
  "aider",
39
50
  "hermes",
40
51
  ...Object.keys(GUI_PRESET_LABELS),
52
+ ...SERVICE_PRESETS,
41
53
  ];
42
54
 
43
55
  /** MCP client targets. Shares the set the MCP config writer dispatches on. */
@@ -42,11 +42,37 @@ 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
+ };
64
+
65
+ // `route` is the path segment after /api/v1/ that governs the host.
66
+ const HOST_BY_NAME = new Map([
67
+ ...Object.entries(PROVIDER_UPSTREAMS).map(([provider, entry]) => [
68
+ entry.hostname,
69
+ { provider, route: provider, ...entry },
70
+ ]),
71
+ ...Object.entries(SERVICE_UPSTREAMS).map(([service, entry]) => [
72
+ entry.hostname,
73
+ { provider: service, route: `svc/${service}`, ...entry },
74
+ ]),
75
+ ]);
50
76
 
51
77
  // A hostname carrying any of these is not a hostname. Checked rather than
52
78
  // assumed because the value arrives on a request line from whatever the client
@@ -67,9 +93,24 @@ function normalizeHostname(value) {
67
93
  return host;
68
94
  }
69
95
 
96
+ /**
97
+ * Azure OpenAI has no fixed host: every customer's resource is its own. So it is
98
+ * recognised by the same closed suffix rule the gateway stores its addresses
99
+ * under (lib/providers/endpoint.ts `AZURE_HOST`) — one DNS label, then exactly
100
+ * `openai.azure.com` or `services.ai.azure.com` — rather than by a table row.
101
+ * Being recognised is what makes a CONNECT to a resource refuse, and what routes
102
+ * an absolute-form request to the governed `azure` route. The gateway then sends
103
+ * it to the address stored with the tenant's key, not to the host named here.
104
+ */
105
+ export const AZURE_HOST = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.(?:openai\.azure\.com|services\.ai\.azure\.com)$/;
106
+ const AZURE_UPSTREAM = { provider: "azure", route: "azure", basePath: "/openai/v1" };
107
+
70
108
  /** Exact match only — `evil-api.anthropic.com` is somebody else's hostname. */
71
109
  export function providerForHost(hostname) {
72
- return HOST_BY_NAME.get(normalizeHostname(hostname)) ?? null;
110
+ const host = normalizeHostname(hostname);
111
+ const fixed = HOST_BY_NAME.get(host);
112
+ if (fixed) return fixed;
113
+ return AZURE_HOST.test(host) ? { ...AZURE_UPSTREAM, hostname: host } : null;
73
114
  }
74
115
 
75
116
  function parsePort(value) {
@@ -147,9 +188,9 @@ function refuse(status, code, message, help) {
147
188
  return { allow: false, status, code, message, help };
148
189
  }
149
190
 
150
- function governedPathHelp(provider, localBaseUrl) {
191
+ function governedPathHelp(route, localBaseUrl) {
151
192
  const base = localBaseUrl ? String(localBaseUrl).replace(/\/+$/, "") : "";
152
- return `${base}/api/v1/${provider}`;
193
+ return `${base}/api/v1/${route}`;
153
194
  }
154
195
 
155
196
  /**
@@ -178,7 +219,7 @@ export function classifyConnect({ target, gatewayOrigin, allowHosts = [], localB
178
219
  `PassControl will not tunnel TLS to ${parsed.hostname}. It cannot see inside that connection, so it could ` +
179
220
  "neither inject the provider key nor apply scope, budget or the kill switch — the call would leave " +
180
221
  "ungoverned while appearing to be governed.",
181
- `Point the client's base URL at ${governedPathHelp(provider.provider, localBaseUrl)} instead. ` +
222
+ `Point the client's base URL at ${governedPathHelp(provider.route, localBaseUrl)} instead. ` +
182
223
  "PassControl does not install a TLS-intercepting CA."
183
224
  );
184
225
  }
@@ -250,7 +291,7 @@ export function classifyProxyRequest({ url, gatewayOrigin, localBaseUrl = "" } =
250
291
  rest = rest.slice(provider.basePath.length);
251
292
  }
252
293
  if (!rest.startsWith("/")) rest = `/${rest}`;
253
- return { allow: true, path: `/api/v1/${provider.provider}${rest}${parsed.search}`, reason: "provider" };
294
+ return { allow: true, path: `/api/v1/${provider.route}${rest}${parsed.search}`, reason: "provider" };
254
295
  }
255
296
 
256
297
  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.1.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` and `azure`. 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";
2
2
  export interface PassControlOptions {
3
3
  /**
4
4
  * Gateway origin, e.g. https://passcontrol.example.com — scheme, host and