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 +11 -7
- package/bin/passcontrol.mjs +102 -23
- package/cli/config.mjs +2 -2
- package/cli/gateway-probe.mjs +56 -0
- package/cli/integration-defaults.d.mts +3 -1
- package/cli/integration-defaults.mjs +11 -0
- package/cli/local-stack.mjs +20 -0
- package/cli/menu-session.mjs +8 -2
- 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/package.json +1 -1
- package/sdk/README.md +6 -3
- package/sdk/control.d.ts +7 -5
- package/sdk/control.js +5 -3
- package/sdk/passcontrol.d.ts +1 -1
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
|
|
318
|
+
| `openai` | Chat Completions, **POST Responses** and **POST Embeddings** | Models list/detail |
|
|
319
319
|
| `anthropic` | Messages | Models list/detail |
|
|
320
|
-
| `
|
|
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
|
|
325
|
-
|
|
326
|
-
|
|
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
|
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -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
|
-
|
|
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:
|
|
1236
|
+
return { ok: true, message: `${label}: available.` };
|
|
1244
1237
|
} catch (error) {
|
|
1245
1238
|
return {
|
|
1246
1239
|
ok: false,
|
|
1247
|
-
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
|
-
|
|
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
|
-
|
|
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
|
+
}
|
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/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/package.json
CHANGED
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 `
|
|
162
|
-
Chat Completions.
|
|
163
|
-
|
|
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`
|
|
124
|
-
*
|
|
125
|
-
*
|
|
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`
|
|
99
|
-
*
|
|
100
|
-
*
|
|
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 }),
|
package/sdk/passcontrol.d.ts
CHANGED
|
@@ -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
|