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/README.md +251 -140
- package/bin/passcontrol.mjs +377 -34
- package/cli/config.mjs +88 -5
- package/cli/gateway-probe.mjs +56 -0
- package/cli/integration-defaults.d.mts +3 -1
- package/cli/integration-defaults.mjs +16 -5
- package/cli/local-stack.mjs +20 -0
- package/cli/mcp/README.md +2 -0
- package/cli/menu-session.mjs +8 -2
- package/cli/menu.mjs +1 -0
- package/cli/presets.mjs +12 -0
- package/cli/proxy-policy.mjs +49 -8
- package/cli/selftest.mjs +11 -1
- package/cli/sidecar.mjs +10 -1
- package/cli/update-check.mjs +7 -3
- package/cli/update.mjs +214 -0
- package/package.json +1 -1
- package/sdk/README.md +15 -10
- package/sdk/control.d.ts +10 -5
- package/sdk/control.js +5 -3
- package/sdk/passcontrol.d.ts +1 -1
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
|
-
|
|
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
|
|
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
|
|
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: "
|
|
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: "
|
|
26
|
+
groq: "openai/gpt-oss-20b",
|
|
21
27
|
mistral: "mistral-small-latest",
|
|
22
|
-
together: "openai/gpt-oss-
|
|
23
|
-
deepseek: "deepseek-
|
|
24
|
-
gemini: "gemini-
|
|
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
|
package/cli/menu-session.mjs
CHANGED
|
@@ -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
|
-
|
|
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. */
|
package/cli/proxy-policy.mjs
CHANGED
|
@@ -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
|
-
|
|
48
|
-
|
|
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
|
-
|
|
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(
|
|
191
|
+
function governedPathHelp(route, localBaseUrl) {
|
|
151
192
|
const base = localBaseUrl ? String(localBaseUrl).replace(/\/+$/, "") : "";
|
|
152
|
-
return `${base}/api/v1/${
|
|
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.
|
|
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.
|
|
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
|
|
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
|
-
|
|
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/cli/update-check.mjs
CHANGED
|
@@ -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}
|
|
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
|
-
|
|
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();
|