passcontrol 0.9.5 → 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/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
 
@@ -205,7 +205,46 @@ export function assertConfigLoaded() {
205
205
  }
206
206
 
207
207
  export function resolveModel(provider) {
208
- return process.env.MODEL ?? defaultModelForProvider(provider);
208
+ // `||`, not `??`: the config writer emits every key, so a fresh login left
209
+ // `MODEL=` in the file, and an empty string is not a model.
210
+ return process.env.MODEL || defaultModelForProvider(provider);
211
+ }
212
+
213
+ /**
214
+ * Provider and gateway, with an EMPTY value treated as unset. The config writer
215
+ * emits every key, so a fresh `login` wrote `PROVIDER=` — and `??` kept the empty
216
+ * string, so bare `call` and `agent create` failed with `Unknown provider ""`
217
+ * (1.0.0 self-host E2E). Reading empty as unset also repairs the configs 0.9.x
218
+ * logins already wrote.
219
+ */
220
+ export function resolveConfigDefaults(env = process.env) {
221
+ return {
222
+ provider: env.PROVIDER || DEFAULT_PROVIDER,
223
+ gateway: trimSlash(env.PASSCONTROL_GATEWAY || DEFAULT_GATEWAY),
224
+ };
225
+ }
226
+
227
+ /**
228
+ * What `setup` writes to the global config when it activates a local stack.
229
+ *
230
+ * Switching away from another gateway also forgets that gateway's credentials.
231
+ * Otherwise it still RECORDS the local gateway when the file names none: with no
232
+ * config the CLI's built-in default is already localhost, so setup used to think
233
+ * nothing needed writing — while `login`, which deliberately ignores that
234
+ * default, then went to Cloud. Null when the file already names a gateway.
235
+ */
236
+ export function localActivationPatch({ switching, globalValues = {}, targetUrl }) {
237
+ if (switching) {
238
+ return {
239
+ PASSCONTROL_GATEWAY: targetUrl,
240
+ PASSPORT_ID: "",
241
+ PASSPORT_SECRET: "",
242
+ PASSPORT_KEY_STORAGE: "",
243
+ PASSCONTROL_API_KEY: "",
244
+ };
245
+ }
246
+ if (!String(globalValues.PASSCONTROL_GATEWAY ?? "").trim()) return { PASSCONTROL_GATEWAY: targetUrl };
247
+ return null;
209
248
  }
210
249
 
211
250
  export function resolvedConfig() {
@@ -214,7 +253,7 @@ export function resolvedConfig() {
214
253
  }
215
254
 
216
255
  function currentConfig() {
217
- const provider = process.env.PROVIDER ?? DEFAULT_PROVIDER;
256
+ const { provider, gateway } = resolveConfigDefaults(process.env);
218
257
  const passportId = process.env.PASSPORT_ID ?? "";
219
258
  const fileSecret = process.env.PASSPORT_SECRET ?? "";
220
259
  const passportStorageMarker = process.env.PASSPORT_KEY_STORAGE ?? "";
@@ -234,7 +273,7 @@ function currentConfig() {
234
273
  return passport;
235
274
  };
236
275
  return {
237
- gateway: trimSlash(process.env.PASSCONTROL_GATEWAY ?? DEFAULT_GATEWAY),
276
+ gateway,
238
277
  passportId,
239
278
  get passportSecret() {
240
279
  return resolvedPassport().secret;
@@ -598,8 +637,52 @@ export function formatChallengeError(status, body) {
598
637
  return `Challenge failed: ${status} ${detail}`;
599
638
  }
600
639
 
640
+ /** The gateway's JSON error body, or {} when it is not one. */
641
+ function errorBody(detail) {
642
+ try {
643
+ const parsed = JSON.parse(detail);
644
+ return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
645
+ } catch {
646
+ return {};
647
+ }
648
+ }
649
+
601
650
  export function formatProxyError(status, body) {
602
651
  const detail = String(body ?? "").trim();
652
+ const { error, rule, reason, limit } = errorBody(detail);
653
+ const blocked = `Proxy blocked the call with ${status}: ${detail}`;
654
+ if (status === 402 && error === "blocked_budget_period") {
655
+ return `${blocked}\n→ The agent's daily or monthly limit is spent; it resets at the next UTC day or month (see the retry-after header).\n→ Fix: wait for the reset, or raise the limit in the dashboard.`;
656
+ }
657
+ if (status === 403 && error === "blocked_policy" && rule === "max_output_tokens") {
658
+ const ceiling = Number.isSafeInteger(limit) ? ` (${limit})` : "";
659
+ return reason === "missing"
660
+ ? `${blocked}\n→ The agent's policy has an output ceiling${ceiling}, and this request did not state an output limit.\n→ Fix: state an output limit — max_tokens (or max_completion_tokens / max_output_tokens) no higher than the ceiling.`
661
+ : `${blocked}\n→ The request asked for more output than the agent's output ceiling${ceiling}.\n→ Fix: send a smaller max_tokens, or raise the ceiling in the agent's policy.`;
662
+ }
663
+ if (status === 403 && error === "blocked_policy") {
664
+ return `${blocked}\n→ A rule in the agent's live policy refused this call (a deny rule, time window or hourly cap).\n→ Fix: review the policy on the agent's page, or use its decision trace to see which rule.`;
665
+ }
666
+ if (status === 403 && error === "blocked_scope") {
667
+ return `${blocked}\n→ This provider and model are outside the agent's allowed models.\n→ Fix: call an allowed model, or widen the agent's scope in the dashboard.`;
668
+ }
669
+ if (status === 409 && error === "no_provider_key") {
670
+ return `${blocked}\n→ The workspace has no provider key stored for this provider.\n→ Fix: add one under Settings → Provider credentials in the dashboard.`;
671
+ }
672
+ if (status === 400 && error === "server_side_tools_unsupported") {
673
+ return `${blocked}\n→ The request uses a hosted tool (such as web search) that the provider bills outside tokens, which no budget here can hold.\n→ Fix: remove the hosted tool, or call that feature outside PassControl.`;
674
+ }
675
+ // 402 is also how the gateway refuses a call it cannot price under a dollar
676
+ // limit; a bigger budget fixes none of those, so each gets its own advice.
677
+ if (status === 402 && error === "unpriced_model") {
678
+ return `${blocked}\n→ PassControl has no price for this model, so the agent's dollar limit cannot be enforced against it.\n→ Fix: use a model PassControl prices, or remove the dollar limit (a token cap still works).`;
679
+ }
680
+ if (status === 402 && error === "unpriced_option") {
681
+ return `${blocked}\n→ The named request field bills above the model's listed price, so the agent's dollar limit cannot hold it.\n→ Fix: drop that field (e.g. service_tier), or remove the dollar limit.`;
682
+ }
683
+ if (status === 402 && error === "unpriced_endpoint") {
684
+ return `${blocked}\n→ This agent's provider goes through a custom endpoint PassControl cannot price, so its dollar limit cannot be enforced.\n→ Fix: remove the dollar limit (a token cap still works), or use the provider's own endpoint.`;
685
+ }
603
686
  if (status === 402) {
604
687
  return `Proxy blocked the call with 402: ${detail}\n→ Fix: raise or clear the agent budget in the dashboard, then retry.`;
605
688
  }
@@ -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>>;
@@ -7,21 +7,32 @@
7
7
  export const DEFAULT_ALLOWED_MODELS = Object.freeze({
8
8
  anthropic: "claude-*",
9
9
  openai: "gpt-*",
10
- groq: "llama-*",
10
+ groq: "openai/gpt-oss-*",
11
11
  mistral: "mistral-*",
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({
18
24
  anthropic: "claude-haiku-4-5",
19
25
  openai: "gpt-5-mini",
20
- groq: "llama-3.3-70b-versatile",
26
+ groq: "openai/gpt-oss-20b",
21
27
  mistral: "mistral-small-latest",
22
- together: "openai/gpt-oss-20b",
23
- deepseek: "deepseek-chat",
24
- gemini: "gemini-2.5-flash",
28
+ together: "openai/gpt-oss-120b",
29
+ deepseek: "deepseek-flash",
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
+ }
package/cli/mcp/README.md CHANGED
@@ -6,6 +6,8 @@ It reads the same environment, nearest `.passcontrol`, and global
6
6
  passport in the global profile so clients can launch from any working directory without
7
7
  embedding a secret:
8
8
 
9
+ On Windows, run these shell commands in PowerShell. Replace placeholders before running.
10
+
9
11
  ```sh
10
12
  passcontrol passport import --global --gateway https://YOUR-PASSCONTROL-HOST --id PUBLIC_PASSPORT_ID
11
13
  # paste the one-time secret at the hidden prompt
@@ -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/menu.mjs CHANGED
@@ -226,6 +226,7 @@ export const GROUPS = [
226
226
  command({ id: "doctor", label: "Diagnose setup", run: ["doctor"], detail: "doctor", description: "Inspect the local stack, gateway, credentials, and protocol compatibility.", network: "gateway", current: currentFrom("gateway") }),
227
227
  command({ id: "status", label: "Show cockpit status", run: ["status"], detail: "status", description: "Show local configuration, gateway health, and the next useful action.", network: "gateway", current: currentFrom("gateway") }),
228
228
  command({ id: "version", label: "CLI, gateway and schema versions", run: ["version"], detail: "version", description: "Compare CLI, gateway build, schema, and protocol versions.", network: "gateway" }),
229
+ command({ id: "update", label: "Update PassControl", run: ["update"], detail: "update [--check]", description: "Update the CLI and the local app: code, dependencies, migrations.", effect: "irreversible", network: "provider", keywords: ["upgrade", "new version", "migrate"] }),
229
230
  command({ id: "open", label: "Open the Control Tower", run: ["open"], detail: "open", description: "Open the configured dashboard in the system browser.", effect: "launch", network: "browser" }),
230
231
  command({ id: "call", label: "Make a governed model call", run: ["call"], detail: "call \"<prompt>\"", description: "Mint a visa and make a billable governed provider call.", effect: "tenant_write", network: "provider", needsArgs: true, current: currentFrom("provider") }),
231
232
  ],
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);
@@ -16,7 +16,8 @@
16
16
  // wall-clock time rather than by how often the CLI is run.
17
17
  //
18
18
  // It reports only that a newer version exists. It never downloads, installs or
19
- // runs anything — upgrading stays a thing the operator types.
19
+ // runs anything — upgrading stays a thing the operator types (`passcontrol update`,
20
+ // cli/update.mjs, which asks before it changes anything).
20
21
  import fs from "node:fs";
21
22
  import os from "node:os";
22
23
  import path from "node:path";
@@ -110,7 +111,7 @@ export function writeCache(file, data) {
110
111
  /** The notice itself, or null when there is nothing worth saying. */
111
112
  export function updateNotice(current, latest) {
112
113
  if (!isNewer(latest, current)) return null;
113
- return `Update available ${current} → ${latest} npm install -g passcontrol@latest`;
114
+ return `Update available ${current} → ${latest} passcontrol update`;
114
115
  }
115
116
 
116
117
  /**
@@ -124,7 +125,10 @@ export async function fetchLatest(url = REGISTRY_URL, timeoutMs = 1500, fetchImp
124
125
  try {
125
126
  const res = await fetchImpl(url, {
126
127
  signal: controller.signal,
127
- headers: { accept: "application/vnd.npm.install-v1+json" },
128
+ // Plain JSON. The abbreviated-metadata type is for the full packument; on
129
+ // /latest the registry answers 406 to it, which made every check return
130
+ // null and no notice was ever shown (found 2026-09-27).
131
+ headers: { accept: "application/json" },
128
132
  });
129
133
  if (!res.ok) return null;
130
134
  const body = await res.json();