passcontrol 1.0.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -27
- package/bin/passcontrol.mjs +119 -27
- package/cli/config.mjs +2 -2
- package/cli/gateway-probe.mjs +56 -0
- package/cli/integration-defaults.d.mts +4 -1
- package/cli/integration-defaults.mjs +18 -0
- package/cli/local-stack.mjs +75 -0
- package/cli/menu-session.mjs +8 -2
- package/cli/presets.mjs +66 -0
- package/cli/proxy-policy.mjs +58 -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
|
@@ -10,7 +10,7 @@ stop control without copying provider secrets into every tool. Bring your own pr
|
|
|
10
10
|
|
|
11
11
|
| Start here | Choose it when | You operate |
|
|
12
12
|
|---|---|---|
|
|
13
|
-
| [Cloud](#cloud) — free
|
|
13
|
+
| [Cloud](#cloud) — free beta, open sign-up | You want a managed gateway without running a database or Docker | Your agents and provider account |
|
|
14
14
|
| [Self-host](#self-host) — full working core | You want the gateway and provider credentials on infrastructure you control | Gateway, dashboard, Supabase Auth + Vault + database, and Redis |
|
|
15
15
|
|
|
16
16
|
A **Passport** is an Ed25519 signing key used to obtain a short-lived visa. A **Direct
|
|
@@ -23,11 +23,11 @@ independently audited**. Start with a non-critical provider key. Source-availabl
|
|
|
23
23
|
|
|
24
24
|
## Cloud
|
|
25
25
|
|
|
26
|
-
[
|
|
26
|
+
[Create a free account](https://passcontrol.vertias.eu/signup). To look around first, try
|
|
27
27
|
[the keyless browser demo](https://passcontrol.vertias.eu): it synthesizes output and
|
|
28
28
|
does not call a billed provider.
|
|
29
29
|
|
|
30
|
-
Once you have
|
|
30
|
+
Once you have an account, install the CLI with Node/npm and sign in:
|
|
31
31
|
|
|
32
32
|
```sh
|
|
33
33
|
npm install -g passcontrol
|
|
@@ -161,7 +161,7 @@ API key. Treat access to that local listener as access to the configured agent.
|
|
|
161
161
|
not a sandbox against other processes running as you. Its provider CONNECT requests are
|
|
162
162
|
refused; use base URLs rather than TLS interception.
|
|
163
163
|
|
|
164
|
-
Presets (from `cli/presets.mjs`): `generic`, `openhands`, `litellm`, `aider`, `hermes`, `cline`, `continue`, `chatbox`, `jan`, `msty`, `cherry-studio`, `open-webui`, `librechat`; MCP presets: `claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
|
|
164
|
+
Presets (from `cli/presets.mjs`): `generic`, `openhands`, `litellm`, `aider`, `hermes`, `cline`, `continue`, `chatbox`, `jan`, `msty`, `cherry-studio`, `open-webui`, `librechat`; service presets: `github`, `telegram`, `brave`, `notion`, `discord`; MCP presets: `claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
|
|
165
165
|
supported paths. [Hermes configuration](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
|
|
166
166
|
|
|
167
167
|
## CLI configuration and key storage
|
|
@@ -258,8 +258,10 @@ are separate from signature verification.
|
|
|
258
258
|
shadow evaluation records candidate decisions without enforcing them.
|
|
259
259
|
- Token and cost admission limits through atomic reservations and settlement.
|
|
260
260
|
- Platform/tenant kill switches and per-agent suspension/revocation.
|
|
261
|
+
- "Ask me first" on service calls: a rule can hold the exact request until the owner
|
|
262
|
+
approves it once, from the dashboard or with Telegram buttons.
|
|
261
263
|
- Provider failover within supported request families and each attempt's authorization
|
|
262
|
-
and budget checks; it is not arbitrary API translation.
|
|
264
|
+
and budget checks; it is not arbitrary API translation. Embeddings never fail over.
|
|
263
265
|
- The injected provider key is removed from what comes back: if an upstream echoes it in
|
|
264
266
|
an error body, a JSON answer or an event stream (even split across chunks), the agent
|
|
265
267
|
receives `[REDACTED_PROVIDER_KEY]` instead. This covers the exact key, not a key an
|
|
@@ -300,7 +302,8 @@ Prices are an in-code estimate table, one row per model, read from each provider
|
|
|
300
302
|
page. Under a dollar limit, a model with no row is refused `402 unpriced_model`; without one it
|
|
301
303
|
is estimated at the provider's highest listed rate. **Custom endpoints are unpriced**, even when the model name
|
|
302
304
|
matches: logs mark cost unknown, receipts carry `unp`, and token accounting continues.
|
|
303
|
-
|
|
305
|
+
They add nothing to an agent's cost budget, and an agent with a dollar limit is refused them
|
|
306
|
+
(`402 unpriced_endpoint`): limit those agents by tokens.
|
|
304
307
|
Known/table-priced cost, conservative enforced spend, and open holds are different figures.
|
|
305
308
|
The dashboard therefore labels the all-time counter **Settled budget charges** and shows its
|
|
306
309
|
durable call-attributed charges, separate operator adjustments, any visible difference, and
|
|
@@ -315,15 +318,20 @@ All paths below are relative to `/api/v1/<provider>`. SDK base URLs and aliases
|
|
|
315
318
|
|
|
316
319
|
| Provider ID | Inference | Discovery |
|
|
317
320
|
|---|---|---|
|
|
318
|
-
| `openai` | Chat Completions and **POST
|
|
321
|
+
| `openai` | Chat Completions, **POST Responses** and **POST Embeddings** | Models list/detail |
|
|
319
322
|
| `anthropic` | Messages | Models list/detail |
|
|
320
|
-
| `
|
|
323
|
+
| `mistral` | OpenAI-compatible Chat Completions and **POST Embeddings** | Models list/detail |
|
|
324
|
+
| `groq`, `together` | OpenAI-compatible Chat Completions | Models list/detail |
|
|
321
325
|
| `deepseek` | OpenAI-compatible Chat Completions | Not proxied |
|
|
322
326
|
| `gemini` | Google's **OpenAI-compatible** Chat Completions | Models list/detail |
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
+
| `xai` | **POST Responses** only (legacy Chat Completions refused) | Models list/detail |
|
|
328
|
+
| `azure` | Azure OpenAI v1: Chat Completions, **POST Responses** and **POST Embeddings**, at the resource address stored with the key | Models list |
|
|
329
|
+
| `local` | A model server you run (Ollama, LM Studio, vLLM): Chat Completions at the address stored with the credential, self-host only | Models list |
|
|
330
|
+
|
|
331
|
+
Gemini's native `generateContent` API is not supported. Responses is served for OpenAI,
|
|
332
|
+
xAI and Azure; embeddings for OpenAI, Mistral and Azure, and an embeddings call never fails over, because
|
|
333
|
+
another model's vectors would not match the ones already stored. Response retrieval/deletion,
|
|
334
|
+
files, fine-tuning, batches, and token-counting endpoints are not proxied. OpenAI's hosted tools (web search, file search, code interpreter
|
|
327
335
|
and others billed outside tokens) and its search models are refused, because no token budget can
|
|
328
336
|
hold their fees. Model availability still depends on your provider account.
|
|
329
337
|
|
|
@@ -331,7 +339,9 @@ Custom provider base URLs support compatible deployments such as Ollama, vLLM, o
|
|
|
331
339
|
LiteLLM without adding provider IDs. They require operator opt-in:
|
|
332
340
|
`PROVIDER_ENDPOINT_MODE=selfhost` permits HTTP, private addresses, and custom ports;
|
|
333
341
|
a comma-separated hostname list permits only listed HTTPS hosts on port 443. Unset/off
|
|
334
|
-
refuses custom endpoints.
|
|
342
|
+
refuses custom endpoints. The local stack (`npm run dev:docker`, `passcontrol start`) runs
|
|
343
|
+
with `selfhost` unless you set `off`: it is one developer's own gateway, so the person who
|
|
344
|
+
sets an endpoint is the person who owns it. A hosted deployment's default stays off. Shape validation is **not full SSRF prevention**: it does not
|
|
335
345
|
resolve or pin DNS. Operators must control egress and trust the destination receiving
|
|
336
346
|
the provider credential. Upstream redirects are refused, never followed.
|
|
337
347
|
|
|
@@ -360,11 +370,6 @@ check needs the relevant earlier statements or a trusted checkpoint. The public
|
|
|
360
370
|
tree ships the format and verification code/page, **not statement production, scheduling,
|
|
361
371
|
or statement/proof-serving routes**. See [statement format and limits](https://github.com/Vertias3u/PassControl/blob/main/docs/statement-format.md).
|
|
362
372
|
|
|
363
|
-
Owner binding is per workspace. A typed owner is a declaration; GitHub verification
|
|
364
|
-
checks publication of a token in a particular account's repository, and domain
|
|
365
|
-
verification checks a well-known HTTPS token. Neither proves a person's legal identity
|
|
366
|
-
or trustworthiness. Company registry evidence is also distinct from authority to represent
|
|
367
|
-
that company. Only published bindings are attached to public evidence.
|
|
368
373
|
|
|
369
374
|

|
|
370
375
|
|
|
@@ -376,7 +381,7 @@ of an already-dispatched stream.
|
|
|
376
381
|
## Self-host operations reference
|
|
377
382
|
|
|
378
383
|
<details>
|
|
379
|
-
<summary>Source setup, lifecycle, credential switching
|
|
384
|
+
<summary>Source setup, lifecycle, credential switching and portability</summary>
|
|
380
385
|
|
|
381
386
|
The CLI package declares Node ≥18, but the full stack needs Node 22+: locked Supabase
|
|
382
387
|
dependencies need ≥20 and Wrangler needs ≥22. Use `passcontrol setup --no-open` to
|
|
@@ -410,14 +415,9 @@ Shell or project-file gateway overrides are refused and named before services st
|
|
|
410
415
|
global write could not override them safely. Clean up any still-active remote identity at its
|
|
411
416
|
original gateway.
|
|
412
417
|
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
and build/run the app. Supported paths are Next.js on Vercel, `npm run build` then
|
|
417
|
-
`npm start` on a Node host behind a trusted reverse proxy, and the
|
|
418
|
-
[Cloudflare/OpenNext build](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md). Configure Auth/SMTP,
|
|
419
|
-
secrets, backups, Redis persistence/no-eviction, and periodic authenticated
|
|
420
|
-
`GET /api/cron/reconcile`. A local successful boot does not validate production operations.
|
|
418
|
+
Self-host is built for one developer on their own machine; this repository does not ship
|
|
419
|
+
a production deployment path. To let agents running elsewhere reach PassControl, or to give
|
|
420
|
+
passports a verify page anyone can open, use [Cloud](#cloud).
|
|
421
421
|
|
|
422
422
|
| Boundary | Cloud | Public self-host tree |
|
|
423
423
|
|---|---|---|
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -67,6 +67,8 @@ import {
|
|
|
67
67
|
integrationChoices,
|
|
68
68
|
isGuiPreset,
|
|
69
69
|
isIntegration,
|
|
70
|
+
isServicePreset,
|
|
71
|
+
SERVICE_ENV,
|
|
70
72
|
supportsWrite,
|
|
71
73
|
} from "../cli/presets.mjs";
|
|
72
74
|
import { importCompletionMessage, noAgentCreateMessage } from "../cli/workspace-import-report.mjs";
|
|
@@ -83,6 +85,8 @@ import {
|
|
|
83
85
|
stackFromConfig,
|
|
84
86
|
writeMarker,
|
|
85
87
|
} from "../cli/update.mjs";
|
|
88
|
+
import { isLocalGatewayOrigin, probeGatewayVersion, probeTimeoutMs } from "../cli/gateway-probe.mjs";
|
|
89
|
+
import { dashboardOriginForOffset, portHolders, stackPortConflictMessage } from "../cli/local-stack.mjs";
|
|
86
90
|
import { startSidecar } from "../cli/sidecar.mjs";
|
|
87
91
|
import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
|
|
88
92
|
import { loginCommand } from "../cli/login.mjs";
|
|
@@ -324,20 +328,7 @@ async function gatewayStatus(noNetwork = false, gateway = config.gateway) {
|
|
|
324
328
|
if (noNetwork) return { label: "not checked", ok: null };
|
|
325
329
|
const origin = probeGatewayOrigin({ gateway });
|
|
326
330
|
if (!origin) return { label: "invalid configuration", ok: false };
|
|
327
|
-
|
|
328
|
-
const res = await fetchWithTimeout(`${origin}/api/version`, {
|
|
329
|
-
method: "GET",
|
|
330
|
-
headers: { accept: "application/json" },
|
|
331
|
-
});
|
|
332
|
-
if (!res.ok) return { label: `unhealthy (${res.status})`, ok: false };
|
|
333
|
-
const body = await res.json().catch(() => null);
|
|
334
|
-
const version = typeof body?.version === "string" && body.version.trim() ? body.version.trim() : null;
|
|
335
|
-
return version
|
|
336
|
-
? { label: `online (${res.status}, PassControl ${version})`, ok: true, version }
|
|
337
|
-
: { label: "unhealthy (not a PassControl version response)", ok: false };
|
|
338
|
-
} catch {
|
|
339
|
-
return { label: "offline or unreachable", ok: false };
|
|
340
|
-
}
|
|
331
|
+
return probeGatewayVersion(origin);
|
|
341
332
|
}
|
|
342
333
|
|
|
343
334
|
async function printCockpit({ noNetwork = false, json = false } = {}) {
|
|
@@ -1224,31 +1215,60 @@ function ownSupabaseDatabaseIsRunning(offset = 0) {
|
|
|
1224
1215
|
}
|
|
1225
1216
|
}
|
|
1226
1217
|
|
|
1227
|
-
|
|
1218
|
+
/** Which containers hold `ports`, so a refusal can name the stack to stop. Empty when Docker cannot say. */
|
|
1219
|
+
function dockerPortHolders(ports) {
|
|
1220
|
+
try {
|
|
1221
|
+
const listing = execFileSync("docker", ["ps", "--format", "{{.Names}}\t{{.Ports}}"], { encoding: "utf8", timeout: DOCKER_TIMEOUT_MS });
|
|
1222
|
+
return portHolders(listing, ports);
|
|
1223
|
+
} catch {
|
|
1224
|
+
return [];
|
|
1225
|
+
}
|
|
1226
|
+
}
|
|
1227
|
+
|
|
1228
|
+
async function assertLocalStackPortsAvailable(offset = 0, { rerun = cliCommand("setup") } = {}) {
|
|
1228
1229
|
if (ownSupabaseDatabaseIsRunning(offset)) return;
|
|
1229
1230
|
const busy = [];
|
|
1230
1231
|
for (const port of LOCAL_STACK_PORTS.map((port) => port + offset)) {
|
|
1231
1232
|
if (await portIsListening(port)) busy.push(port);
|
|
1232
1233
|
}
|
|
1233
1234
|
if (busy.length) {
|
|
1234
|
-
throw new Error(
|
|
1235
|
-
`Local stack ports ${busy.join(", ")} are in use by another project. Stop that project first (for example, \`supabase stop --project-id <project>\`), then rerun \`passcontrol setup\`.`
|
|
1236
|
-
);
|
|
1235
|
+
throw new Error(stackPortConflictMessage({ busy, holders: dockerPortHolders(busy), rerun }));
|
|
1237
1236
|
}
|
|
1238
1237
|
}
|
|
1239
1238
|
|
|
1240
1239
|
async function checkLocalStackPorts(offset = 0) {
|
|
1240
|
+
// Named in the line, so an install made with --port-offset can see which
|
|
1241
|
+
// ports were actually checked.
|
|
1242
|
+
const label = offset ? `Local stack ports (offset ${offset})` : "Local stack ports";
|
|
1241
1243
|
try {
|
|
1242
1244
|
await assertLocalStackPortsAvailable(offset);
|
|
1243
|
-
return { ok: true, message:
|
|
1245
|
+
return { ok: true, message: `${label}: available.` };
|
|
1244
1246
|
} catch (error) {
|
|
1245
1247
|
return {
|
|
1246
1248
|
ok: false,
|
|
1247
|
-
message:
|
|
1249
|
+
message: `${label}: unavailable. Fix: stop the conflicting project or rerun setup with --port-offset N. Details: ${error.message}`,
|
|
1248
1250
|
};
|
|
1249
1251
|
}
|
|
1250
1252
|
}
|
|
1251
1253
|
|
|
1254
|
+
/**
|
|
1255
|
+
* The port offset `setup` baked into this checkout's supabase/config.toml, or 0
|
|
1256
|
+
* when it was never set up. Read back, as `update` does (stackFromConfig),
|
|
1257
|
+
* because the offset is a setup-time flag nobody passes again: checking at 0
|
|
1258
|
+
* reported a working --port-offset install as "ports unavailable".
|
|
1259
|
+
*/
|
|
1260
|
+
function installedStackOffset() {
|
|
1261
|
+
try {
|
|
1262
|
+
const root = appRoot ?? resolveAppRoot();
|
|
1263
|
+
if (!root) return 0;
|
|
1264
|
+
const configPath = path.join(root, "supabase", "config.toml");
|
|
1265
|
+
if (!fs.existsSync(configPath)) return 0;
|
|
1266
|
+
return stackFromConfig(fs.readFileSync(configPath, "utf8"))?.offset ?? 0;
|
|
1267
|
+
} catch {
|
|
1268
|
+
return 0;
|
|
1269
|
+
}
|
|
1270
|
+
}
|
|
1271
|
+
|
|
1252
1272
|
async function runLocalPrerequisiteChecks({ offset = 0, report = false, enforce = false } = {}) {
|
|
1253
1273
|
const results = [
|
|
1254
1274
|
checkDockerInstalled(),
|
|
@@ -1716,6 +1736,18 @@ async function applyAppUpdate(app) {
|
|
|
1716
1736
|
`Port ${dashboard.port} is served by something this CLI did not start (a dashboard run by hand?). Stop it, then rerun \`${cliCommand("update")}\`. Nothing was changed.`
|
|
1717
1737
|
);
|
|
1718
1738
|
}
|
|
1739
|
+
// The stack's own ports, before anything changes. Another stack on them
|
|
1740
|
+
// (a second checkout at the same offset) only showed up when Supabase failed
|
|
1741
|
+
// to start, after the fast-forward and \`npm ci\`, as "npm exited with code 1".
|
|
1742
|
+
// A running dashboard of THIS install means its own stack holds them, which
|
|
1743
|
+
// assertLocalStackPortsAvailable already allows.
|
|
1744
|
+
try {
|
|
1745
|
+
await assertLocalStackPortsAvailable(app.offset, { rerun: cliCommand(app.resume ? "update --app-only" : "update") });
|
|
1746
|
+
} catch (error) {
|
|
1747
|
+
throw new Error(
|
|
1748
|
+
`${error.message} ${app.resume ? "The earlier update is still unfinished; nothing more was changed." : "Nothing was changed."}`
|
|
1749
|
+
);
|
|
1750
|
+
}
|
|
1719
1751
|
const restart = app.resume?.wasRunning ?? Boolean(managed);
|
|
1720
1752
|
const from = app.resume?.from ?? app.head;
|
|
1721
1753
|
writeMarker({ appRoot: app.root, from, to: app.target, wasRunning: restart, startedAt: new Date().toISOString() });
|
|
@@ -1808,18 +1840,26 @@ async function updateCommand(opts = {}) {
|
|
|
1808
1840
|
}
|
|
1809
1841
|
|
|
1810
1842
|
async function setupLocal(opts = {}) {
|
|
1811
|
-
const dashboard = canonicalLocalDashboard();
|
|
1812
|
-
const activation = await prepareLocalActivation(dashboard, opts);
|
|
1813
1843
|
const offset = opts.portOffset === undefined ? 0 : Number(opts.portOffset);
|
|
1814
1844
|
if (!Number.isInteger(offset) || offset < 0 || offset > 10000) {
|
|
1815
1845
|
throw new Error("--port-offset must be an integer from 0 to 10000.");
|
|
1816
1846
|
}
|
|
1847
|
+
// The dashboard moves with the offset, like Supabase and Redis: a second
|
|
1848
|
+
// install on :3000 would collide with the first one's dashboard. Saved as the
|
|
1849
|
+
// gateway by the activation below, so `start`, `stop` and `status` follow it.
|
|
1850
|
+
const dashboard = parseLocalDashboard(
|
|
1851
|
+
dashboardOriginForOffset(offset),
|
|
1852
|
+
offset ? "the offset local dashboard" : "the canonical local dashboard"
|
|
1853
|
+
);
|
|
1854
|
+
const activation = await prepareLocalActivation(dashboard, opts);
|
|
1817
1855
|
await runLocalPrerequisiteChecks({ offset, enforce: true });
|
|
1818
1856
|
await ensureAppRoot({ clone: true, appDir: opts.appDir, yes: opts.yes });
|
|
1819
1857
|
step("Preparing the local Supabase, Redis, migrations, and dev user…");
|
|
1820
1858
|
await runLocalCommand(process.platform === "win32" ? "npm.cmd" : "npm", ["run", "dev:stack"], {
|
|
1821
1859
|
...process.env,
|
|
1822
1860
|
PASSCONTROL_PORT_OFFSET: String(offset),
|
|
1861
|
+
// Supabase's site URL and the receipt issuer are written from PORT.
|
|
1862
|
+
PORT: String(dashboard.port),
|
|
1823
1863
|
PASSCONTROL_VIA_CLI: "1",
|
|
1824
1864
|
});
|
|
1825
1865
|
// dev:stack has just brought Supabase and Redis up (and would have exited
|
|
@@ -2386,6 +2426,11 @@ function printAgentPreset(name = "generic", opts = {}) {
|
|
|
2386
2426
|
return;
|
|
2387
2427
|
}
|
|
2388
2428
|
|
|
2429
|
+
if (isServicePreset(preset)) {
|
|
2430
|
+
printServicePreset(preset, opts);
|
|
2431
|
+
return;
|
|
2432
|
+
}
|
|
2433
|
+
|
|
2389
2434
|
const { provider, model, apiKey, baseUrl, port } = sidecarBaseUrl(opts);
|
|
2390
2435
|
const modelWithProvider = `${provider}/${model}`;
|
|
2391
2436
|
const sidecarStart = opts.port != null || process.env.SIDECAR_PORT != null
|
|
@@ -2453,6 +2498,23 @@ function printAgentPreset(name = "generic", opts = {}) {
|
|
|
2453
2498
|
}
|
|
2454
2499
|
}
|
|
2455
2500
|
|
|
2501
|
+
// A service preset has no provider and no model: the client is pointed at the
|
|
2502
|
+
// governed service route and sends no service token at all — the gateway
|
|
2503
|
+
// injects the workspace's, and only for calls the agent's rules admit.
|
|
2504
|
+
function printServicePreset(service, opts = {}) {
|
|
2505
|
+
const host = String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1");
|
|
2506
|
+
const port = sidecarPort(opts);
|
|
2507
|
+
const sidecarStart = opts.port != null || process.env.SIDECAR_PORT != null
|
|
2508
|
+
? cliCommand(`sidecar --port ${port}`)
|
|
2509
|
+
: cliCommand("sidecar");
|
|
2510
|
+
console.log(`# Start the bridge first: ${sidecarStart}`);
|
|
2511
|
+
const entry = Object.hasOwn(SERVICE_ENV, service) ? SERVICE_ENV[service] : null;
|
|
2512
|
+
if (!entry) throw new Error(`Usage: passcontrol env <${integrationChoices()}>`);
|
|
2513
|
+
for (const line of entry.about) console.log(line);
|
|
2514
|
+
printExports([[entry.envVar, `http://${host}:${port}/api/v1/svc/${service}`]]);
|
|
2515
|
+
console.log(entry.usage);
|
|
2516
|
+
}
|
|
2517
|
+
|
|
2456
2518
|
function aiderConfig(opts = {}) {
|
|
2457
2519
|
const { provider, model, baseUrl } = sidecarBaseUrl(opts);
|
|
2458
2520
|
return [
|
|
@@ -2560,7 +2622,7 @@ async function serverVersion() {
|
|
|
2560
2622
|
const origin = probeGatewayOrigin();
|
|
2561
2623
|
if (!origin) return { version: null, detail: "the configured gateway is not a bare origin" };
|
|
2562
2624
|
try {
|
|
2563
|
-
const res = await fetchWithTimeout(`${origin}/api/version
|
|
2625
|
+
const res = await fetchWithTimeout(`${origin}/api/version`, {}, probeTimeoutMs(origin));
|
|
2564
2626
|
// A gateway that predates this endpoint is a real PassControl gateway, and
|
|
2565
2627
|
// saying "unreachable" about one that answered would send an operator to
|
|
2566
2628
|
// debug their network instead of deploying.
|
|
@@ -2711,7 +2773,25 @@ async function doctorCommand(opts = {}) {
|
|
|
2711
2773
|
// One authenticated request for this command. Its failure is a failed
|
|
2712
2774
|
// diagnostic, not a CLI crash: remaining local checks are still useful.
|
|
2713
2775
|
printSystemHealthDiagnostic(await fetchSystemHealth());
|
|
2714
|
-
|
|
2776
|
+
// Docker, Supabase and the stack's ports matter only where a stack runs. A CLI
|
|
2777
|
+
// pointed at a remote gateway (Cloud) with no app checkout here has none, and
|
|
2778
|
+
// a failing "Local stack ports" line would send that user hunting for one.
|
|
2779
|
+
const probeOrigin = probeGatewayOrigin();
|
|
2780
|
+
const remoteGateway = probeOrigin !== null && !isLocalGatewayOrigin(probeOrigin);
|
|
2781
|
+
let localApp = null;
|
|
2782
|
+
try {
|
|
2783
|
+
localApp = resolveAppRoot();
|
|
2784
|
+
} catch {
|
|
2785
|
+
localApp = null;
|
|
2786
|
+
}
|
|
2787
|
+
if (remoteGateway && !localApp) {
|
|
2788
|
+
step(
|
|
2789
|
+
`Local prerequisites skipped: this CLI uses a remote gateway (${probeOrigin}). Docker and the ` +
|
|
2790
|
+
"local stack are needed only to self-host on this machine."
|
|
2791
|
+
);
|
|
2792
|
+
} else {
|
|
2793
|
+
await runLocalPrerequisiteChecks({ offset: installedStackOffset(), report: true });
|
|
2794
|
+
}
|
|
2715
2795
|
if (config.passportId && config.passportSecret) {
|
|
2716
2796
|
// The whole chain, not just the mint. "Visa mint works" proves the passport
|
|
2717
2797
|
// authenticates and says nothing about scope, budget, the proxy or receipts —
|
|
@@ -2745,17 +2825,24 @@ async function doctorCommand(opts = {}) {
|
|
|
2745
2825
|
step("Skipping control API check: no PASSCONTROL_API_KEY configured.");
|
|
2746
2826
|
}
|
|
2747
2827
|
|
|
2748
|
-
await checkInstanceSigningKey();
|
|
2828
|
+
await checkInstanceSigningKey({ remoteOrigin: remoteGateway ? probeOrigin : null });
|
|
2749
2829
|
}
|
|
2750
2830
|
|
|
2751
2831
|
// Receipts and agent tokens are signed by a key the DEPLOYMENT owns. A missing
|
|
2752
2832
|
// key is loud (nothing is signed), but a PASSCONTROL_ISSUER pointing somewhere
|
|
2753
2833
|
// that does not serve this deployment's JWKS fails silently: every receipt then
|
|
2754
2834
|
// carries an `iss` whose key set cannot verify it. Check it explicitly.
|
|
2755
|
-
async function checkInstanceSigningKey() {
|
|
2835
|
+
async function checkInstanceSigningKey({ remoteOrigin = null } = {}) {
|
|
2756
2836
|
const seed = process.env.INSTANCE_SIGNING_KEY;
|
|
2757
2837
|
const issuer = process.env.PASSCONTROL_ISSUER;
|
|
2758
2838
|
|
|
2839
|
+
// The key belongs to the deployment. A remote gateway signs with its own, so
|
|
2840
|
+
// its absence from this shell disables nothing.
|
|
2841
|
+
if (!seed && remoteOrigin) {
|
|
2842
|
+
step(`Receipts are signed by the gateway (${remoteOrigin}); its public keys are at ${remoteOrigin}/.well-known/jwks.json.`);
|
|
2843
|
+
return;
|
|
2844
|
+
}
|
|
2845
|
+
|
|
2759
2846
|
if (!seed) {
|
|
2760
2847
|
step(
|
|
2761
2848
|
"Instance signing key not set in this shell — receipts and agent tokens are disabled " +
|
|
@@ -3181,6 +3268,9 @@ const IMPORT_REASONS = {
|
|
|
3181
3268
|
policy_malformed: "its policy could not be parsed, and creating it without one would leave it unrestricted.",
|
|
3182
3269
|
policy_shadow_malformed: "its shadow policy could not be parsed.",
|
|
3183
3270
|
unknown_status: "it records a status this version does not recognise.",
|
|
3271
|
+
account_limit_reached:
|
|
3272
|
+
"this account has reached its agent limit. Nothing was created for it. Revoke agents you no longer use, " +
|
|
3273
|
+
"or ask the operator for a higher limit, then import again: agents already created are skipped.",
|
|
3184
3274
|
};
|
|
3185
3275
|
|
|
3186
3276
|
async function exportCommand(opts = {}) {
|
|
@@ -3423,7 +3513,9 @@ function keyTone(storage) {
|
|
|
3423
3513
|
if (storage?.fallback) return ["warn", "file fallback", "the OS store was unavailable"];
|
|
3424
3514
|
if (storage?.available !== true) return ["idle", "not configured", ""];
|
|
3425
3515
|
if (storage?.tier === 1) return ["ok", "ready", String(storage.source ?? "OS store")];
|
|
3426
|
-
|
|
3516
|
+
// Tier 0 is a config file or the operator's environment; saying "file" for a
|
|
3517
|
+
// key that came from PASSPORT_SECRET sends them looking for a file to clean up.
|
|
3518
|
+
return ["ok", "ready", storage?.source === "environment variable" ? "env var" : "file"];
|
|
3427
3519
|
}
|
|
3428
3520
|
|
|
3429
3521
|
/**
|
package/cli/config.mjs
CHANGED
|
@@ -28,8 +28,8 @@ export const PACKAGE_VERSION = (() => {
|
|
|
28
28
|
// second numeric copy that can drift from system-health capability reporting.
|
|
29
29
|
export const WORKSPACE_IMPORT_MAX_VERSION = WORKSPACE_EXPORT_PROTOCOL.maximum;
|
|
30
30
|
|
|
31
|
-
export const PROVIDERS = ["openai", "anthropic", "groq", "mistral", "together", "deepseek", "gemini"];
|
|
32
|
-
export const OPENAI_SHAPE_PROVIDERS = new Set(["openai", "groq", "mistral", "together", "deepseek", "gemini"]);
|
|
31
|
+
export const PROVIDERS = ["openai", "anthropic", "groq", "mistral", "together", "deepseek", "gemini", "xai", "azure", "local"];
|
|
32
|
+
export const OPENAI_SHAPE_PROVIDERS = new Set(["openai", "groq", "mistral", "together", "deepseek", "gemini", "azure", "local"]);
|
|
33
33
|
|
|
34
34
|
const DEFAULT_GATEWAY = "http://localhost:3000";
|
|
35
35
|
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
// The unauthenticated "is the gateway there?" probe behind `status`, `version`
|
|
2
|
+
// and the menu: GET /api/version, which carries no credential.
|
|
3
|
+
//
|
|
4
|
+
// A gateway on this machine answers in milliseconds, so a short timeout keeps a
|
|
5
|
+
// stopped local stack from stalling the command. A remote one (Cloud, or a
|
|
6
|
+
// self-host on another host) pays for DNS, TLS and possibly a cold start on the
|
|
7
|
+
// first call, which can exceed a second; with the local timeout, a new Cloud
|
|
8
|
+
// user's first `status` read "offline". A timeout is also reported as one: "no
|
|
9
|
+
// answer" and "offline" send an operator to different places.
|
|
10
|
+
import { isLoopbackBindHost } from "./proxy-policy.mjs";
|
|
11
|
+
|
|
12
|
+
export const LOCAL_PROBE_TIMEOUT_MS = 1200;
|
|
13
|
+
export const REMOTE_PROBE_TIMEOUT_MS = 6000;
|
|
14
|
+
|
|
15
|
+
/** Whether a gateway origin is on this machine. A malformed one counts as local: the checks then run. */
|
|
16
|
+
export function isLocalGatewayOrigin(origin) {
|
|
17
|
+
try {
|
|
18
|
+
return isLoopbackBindHost(new URL(origin).hostname);
|
|
19
|
+
} catch {
|
|
20
|
+
return true;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export function probeTimeoutMs(origin) {
|
|
25
|
+
try {
|
|
26
|
+
return isLoopbackBindHost(new URL(origin).hostname) ? LOCAL_PROBE_TIMEOUT_MS : REMOTE_PROBE_TIMEOUT_MS;
|
|
27
|
+
} catch {
|
|
28
|
+
return LOCAL_PROBE_TIMEOUT_MS;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** GET <origin>/api/version with a timeout, as a status row. `origin` must already be validated. */
|
|
33
|
+
export async function probeGatewayVersion(origin, { fetchImpl = fetch, timeoutMs = probeTimeoutMs(origin) } = {}) {
|
|
34
|
+
const controller = new AbortController();
|
|
35
|
+
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
36
|
+
try {
|
|
37
|
+
const res = await fetchImpl(`${origin}/api/version`, {
|
|
38
|
+
method: "GET",
|
|
39
|
+
headers: { accept: "application/json" },
|
|
40
|
+
signal: controller.signal,
|
|
41
|
+
});
|
|
42
|
+
if (!res.ok) return { label: `unhealthy (${res.status})`, ok: false };
|
|
43
|
+
const body = await res.json().catch(() => null);
|
|
44
|
+
const version = typeof body?.version === "string" && body.version.trim() ? body.version.trim() : null;
|
|
45
|
+
return version
|
|
46
|
+
? { label: `online (${res.status}, PassControl ${version})`, ok: true, version }
|
|
47
|
+
: { label: "unhealthy (not a PassControl version response)", ok: false };
|
|
48
|
+
} catch (error) {
|
|
49
|
+
if (controller.signal.aborted || error?.name === "AbortError") {
|
|
50
|
+
return { label: `no answer within ${timeoutMs / 1000} s`, ok: false };
|
|
51
|
+
}
|
|
52
|
+
return { label: "offline or unreachable", ok: false };
|
|
53
|
+
} finally {
|
|
54
|
+
clearTimeout(timer);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
@@ -5,7 +5,10 @@ export type IntegrationProvider =
|
|
|
5
5
|
| "mistral"
|
|
6
6
|
| "together"
|
|
7
7
|
| "deepseek"
|
|
8
|
-
| "gemini"
|
|
8
|
+
| "gemini"
|
|
9
|
+
| "xai"
|
|
10
|
+
| "azure"
|
|
11
|
+
| "local";
|
|
9
12
|
|
|
10
13
|
export const DEFAULT_ALLOWED_MODELS: Readonly<Record<IntegrationProvider, string>>;
|
|
11
14
|
export const DEFAULT_CLIENT_MODELS: Readonly<Record<IntegrationProvider, string>>;
|
|
@@ -12,6 +12,16 @@ export const DEFAULT_ALLOWED_MODELS = Object.freeze({
|
|
|
12
12
|
together: "openai/gpt-oss-*",
|
|
13
13
|
deepseek: "deepseek-*",
|
|
14
14
|
gemini: "gemini-*",
|
|
15
|
+
xai: "grok-*",
|
|
16
|
+
// An Azure `model` is a DEPLOYMENT name the customer chose, not a model id.
|
|
17
|
+
// `gpt-*` covers deployments named after their model and nothing wider: a bare
|
|
18
|
+
// `*` would widen an allowlist to whatever a resource ever deploys. An operator
|
|
19
|
+
// whose deployments are named otherwise edits the scope.
|
|
20
|
+
azure: "gpt-*",
|
|
21
|
+
// A model on the developer's own server: free to them, and whatever they pulled.
|
|
22
|
+
// The admin API (pull, delete) is outside the endpoint allowlist, so `*` widens
|
|
23
|
+
// which local model an agent may run, never what it may do to the server.
|
|
24
|
+
local: "*",
|
|
15
25
|
});
|
|
16
26
|
|
|
17
27
|
export const DEFAULT_CLIENT_MODELS = Object.freeze({
|
|
@@ -22,6 +32,14 @@ export const DEFAULT_CLIENT_MODELS = Object.freeze({
|
|
|
22
32
|
together: "openai/gpt-oss-120b",
|
|
23
33
|
deepseek: "deepseek-flash",
|
|
24
34
|
gemini: "gemini-3.8-flash",
|
|
35
|
+
// The cheapest listed model that does not reason (docs.x.ai/developers/models.md,
|
|
36
|
+
// 2026-09-27): xAI's reasoning models cannot turn reasoning off.
|
|
37
|
+
xai: "grok-4.20-0309-non-reasoning",
|
|
38
|
+
// A deployment name, so only a guess until the operator names theirs.
|
|
39
|
+
azure: "gpt-4.1-mini",
|
|
40
|
+
// Ollama's most-pulled small model. Only a guess: the dashboard offers the
|
|
41
|
+
// models the server actually has.
|
|
42
|
+
local: "llama3.2",
|
|
25
43
|
});
|
|
26
44
|
|
|
27
45
|
export function defaultAllowedModelForProvider(provider) {
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
// The local stack's addresses as a function of the port offset `setup` was
|
|
2
|
+
// given. One definition for setup and everything that reads its result, so a
|
|
3
|
+
// second install (`setup --port-offset N`) moves as a whole: Supabase, Redis
|
|
4
|
+
// (scripts/dev-stack.sh) and the dashboard.
|
|
5
|
+
|
|
6
|
+
/** The canonical local dashboard port, used when no offset was given. */
|
|
7
|
+
export const LOCAL_DASHBOARD_PORT = 3000;
|
|
8
|
+
|
|
9
|
+
/** The same bounds setup enforces on --port-offset. */
|
|
10
|
+
function assertOffset(offset) {
|
|
11
|
+
if (!Number.isInteger(offset) || offset < 0 || offset > 10000) {
|
|
12
|
+
throw new Error("--port-offset must be an integer from 0 to 10000.");
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** The local dashboard origin for a stack set up with this port offset. */
|
|
17
|
+
export function dashboardOriginForOffset(offset) {
|
|
18
|
+
assertOffset(offset);
|
|
19
|
+
return `http://localhost:${LOCAL_DASHBOARD_PORT + offset}`;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
// Supabase names each container supabase_<service>_<project>. Services with an
|
|
23
|
+
// underscore come first, so "supabase_edge_runtime_x" is not read as project
|
|
24
|
+
// "runtime_x".
|
|
25
|
+
const SUPABASE_SERVICES = [
|
|
26
|
+
"edge_runtime", "pg_meta", "db", "kong", "inbucket", "mailpit", "analytics",
|
|
27
|
+
"studio", "rest", "auth", "realtime", "storage", "imgproxy", "vector", "pooler",
|
|
28
|
+
];
|
|
29
|
+
|
|
30
|
+
/** The Supabase project a container belongs to, or null when it is not a Supabase service. */
|
|
31
|
+
export function stackProjectFromContainer(name) {
|
|
32
|
+
for (const service of SUPABASE_SERVICES) {
|
|
33
|
+
const prefix = `supabase_${service}_`;
|
|
34
|
+
if (name.startsWith(prefix) && name.length > prefix.length) return name.slice(prefix.length);
|
|
35
|
+
}
|
|
36
|
+
return null;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Which running containers publish which of `ports`, from
|
|
41
|
+
* `docker ps --format '{{.Names}}\t{{.Ports}}'`. A port held by something that
|
|
42
|
+
* is not a container (a database installed natively, say) is simply absent.
|
|
43
|
+
*/
|
|
44
|
+
export function portHolders(psOutput, ports) {
|
|
45
|
+
const holders = [];
|
|
46
|
+
for (const line of String(psOutput).split("\n")) {
|
|
47
|
+
const [rawName, published = ""] = line.split("\t");
|
|
48
|
+
const container = rawName?.trim();
|
|
49
|
+
if (!container) continue;
|
|
50
|
+
const held = ports.filter((port) => new RegExp(`:${port}->`, "u").test(published));
|
|
51
|
+
if (held.length) holders.push({ container, project: stackProjectFromContainer(container), ports: held });
|
|
52
|
+
}
|
|
53
|
+
return holders;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** The refusal for busy stack ports: who holds them, and the exact command that frees them. */
|
|
57
|
+
export function stackPortConflictMessage({ busy, holders = [], rerun }) {
|
|
58
|
+
const projects = [...new Set(holders.map((holder) => holder.project).filter(Boolean))];
|
|
59
|
+
const containers = holders.filter((holder) => !holder.project).map((holder) => holder.container);
|
|
60
|
+
const owners = [];
|
|
61
|
+
if (projects.length) {
|
|
62
|
+
owners.push(`another local Supabase stack (project ${projects.map((project) => `"${project}"`).join(", ")})`);
|
|
63
|
+
}
|
|
64
|
+
if (containers.length) owners.push(`container ${containers.join(", ")}`);
|
|
65
|
+
const ports = `Local stack ports ${busy.join(", ")} are in use by ${owners.length ? owners.join(" and ") : "another program or project"}.`;
|
|
66
|
+
// `docker stop` keeps a container and its volume, like `supabase stop`.
|
|
67
|
+
const commands = [
|
|
68
|
+
...projects.map((project) => `\`supabase stop --project-id ${project}\``),
|
|
69
|
+
...containers.map((container) => `\`docker stop ${container}\``),
|
|
70
|
+
];
|
|
71
|
+
const fix = commands.length
|
|
72
|
+
? `Stop ${commands.length > 1 ? "them" : "it"} first (data is kept): ${commands.join(" and ")}`
|
|
73
|
+
: "Stop that project first (for example, `supabase stop --project-id <project>`)";
|
|
74
|
+
return `${ports} ${fix}, then rerun \`${rerun}\`.`;
|
|
75
|
+
}
|
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,71 @@ export function isGuiPreset(name) {
|
|
|
30
30
|
return Object.hasOwn(GUI_PRESET_LABELS, String(name ?? "").toLowerCase());
|
|
31
31
|
}
|
|
32
32
|
|
|
33
|
+
/**
|
|
34
|
+
* Non-LLM APIs a client can be pointed at through the sidecar (any-API). The
|
|
35
|
+
* preset prints the governed base URL for that service; what the agent may call
|
|
36
|
+
* there is set per agent in the dashboard.
|
|
37
|
+
*/
|
|
38
|
+
export const SERVICE_PRESETS = ["github", "telegram", "brave", "notion", "discord"];
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* What `passcontrol env <service>` prints for each: the variable (the same one
|
|
42
|
+
* the dashboard's Setup names, lib/services/display.ts), two lines on where the
|
|
43
|
+
* agent's access is set, and one usage hint. Pinned to the catalog by
|
|
44
|
+
* tests/cli-service-presets.test.ts.
|
|
45
|
+
*/
|
|
46
|
+
export const SERVICE_ENV = {
|
|
47
|
+
github: {
|
|
48
|
+
label: "GitHub",
|
|
49
|
+
envVar: "GITHUB_API_URL",
|
|
50
|
+
about: [
|
|
51
|
+
"# GitHub REST through PassControl. What this agent may do is set on its page in the",
|
|
52
|
+
"# dashboard, under GitHub access; the workspace's GitHub token stays in PassControl.",
|
|
53
|
+
],
|
|
54
|
+
usage: "# Octokit: new Octokit({ baseUrl: process.env.GITHUB_API_URL }) — and no auth option.",
|
|
55
|
+
},
|
|
56
|
+
telegram: {
|
|
57
|
+
label: "Telegram",
|
|
58
|
+
envVar: "TELEGRAM_API_URL",
|
|
59
|
+
about: [
|
|
60
|
+
"# Telegram Bot API through PassControl. What this agent may do is set on its page in the",
|
|
61
|
+
"# dashboard, under Telegram access; the bot token stays in PassControl.",
|
|
62
|
+
],
|
|
63
|
+
usage: '# Call a method by name, with no token in the URL: curl "$TELEGRAM_API_URL/getMe"',
|
|
64
|
+
},
|
|
65
|
+
brave: {
|
|
66
|
+
label: "Brave Search",
|
|
67
|
+
envVar: "BRAVE_SEARCH_API_URL",
|
|
68
|
+
about: [
|
|
69
|
+
"# Brave Search through PassControl. What this agent may search is set on its page in the",
|
|
70
|
+
"# dashboard, under Brave Search access; the API key stays in PassControl. Brave bills per search.",
|
|
71
|
+
],
|
|
72
|
+
usage: '# Search with no key header: curl "$BRAVE_SEARCH_API_URL/web/search?q=passcontrol"',
|
|
73
|
+
},
|
|
74
|
+
notion: {
|
|
75
|
+
label: "Notion",
|
|
76
|
+
envVar: "NOTION_API_URL",
|
|
77
|
+
about: [
|
|
78
|
+
"# Notion through PassControl. What this agent may do is set on its page in the dashboard,",
|
|
79
|
+
"# under Notion access; the integration token stays in PassControl.",
|
|
80
|
+
],
|
|
81
|
+
usage: "# @notionhq/client: new Client({ baseUrl: process.env.NOTION_API_URL }) — and no auth option.",
|
|
82
|
+
},
|
|
83
|
+
discord: {
|
|
84
|
+
label: "Discord",
|
|
85
|
+
envVar: "DISCORD_API_URL",
|
|
86
|
+
about: [
|
|
87
|
+
"# Discord's bot API through PassControl. What this agent may do is set on its page in the",
|
|
88
|
+
"# dashboard, under Discord access; the bot token stays in PassControl.",
|
|
89
|
+
],
|
|
90
|
+
usage: '# discord.js: new REST({ api: process.env.DISCORD_API_URL, version: "10" }).setToken("sidecar") — any token; the sidecar replaces it.',
|
|
91
|
+
},
|
|
92
|
+
};
|
|
93
|
+
|
|
94
|
+
export function isServicePreset(name) {
|
|
95
|
+
return SERVICE_PRESETS.includes(String(name ?? "").toLowerCase());
|
|
96
|
+
}
|
|
97
|
+
|
|
33
98
|
/** Presets that print settings pointing an agent at the local sidecar bridge. */
|
|
34
99
|
export const SIDECAR_PRESETS = [
|
|
35
100
|
"generic",
|
|
@@ -38,6 +103,7 @@ export const SIDECAR_PRESETS = [
|
|
|
38
103
|
"aider",
|
|
39
104
|
"hermes",
|
|
40
105
|
...Object.keys(GUI_PRESET_LABELS),
|
|
106
|
+
...SERVICE_PRESETS,
|
|
41
107
|
];
|
|
42
108
|
|
|
43
109
|
/** MCP client targets. Shares the set the MCP config writer dispatches on. */
|
package/cli/proxy-policy.mjs
CHANGED
|
@@ -42,11 +42,46 @@ export const PROVIDER_UPSTREAMS = {
|
|
|
42
42
|
// as `provider_tunnel_not_governed` — and, deliberately, what makes it
|
|
43
43
|
// permanently ineligible for `--allow-connect`.
|
|
44
44
|
gemini: { hostname: "generativelanguage.googleapis.com", basePath: "/v1beta/openai" },
|
|
45
|
+
xai: { hostname: "api.x.ai", basePath: "" },
|
|
45
46
|
};
|
|
46
47
|
|
|
47
|
-
|
|
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
|
+
// Its key goes in a header; a tunnel would send searches billed to the
|
|
64
|
+
// workspace past the agent's rules and cap.
|
|
65
|
+
// basePath: the prefix the gateway adds itself (the catalog's upstreamUrl),
|
|
66
|
+
// stripped here so a routed request does not carry it twice.
|
|
67
|
+
brave: { hostname: "api.search.brave.com", basePath: "/res/v1" },
|
|
68
|
+
notion: { hostname: "api.notion.com", basePath: "" },
|
|
69
|
+
// discord.com is also Discord's website: an agent's browser-like traffic to it
|
|
70
|
+
// is refused through the sidecar, as every governed service host is.
|
|
71
|
+
discord: { hostname: "discord.com", basePath: "/api" },
|
|
72
|
+
};
|
|
73
|
+
|
|
74
|
+
// `route` is the path segment after /api/v1/ that governs the host.
|
|
75
|
+
const HOST_BY_NAME = new Map([
|
|
76
|
+
...Object.entries(PROVIDER_UPSTREAMS).map(([provider, entry]) => [
|
|
77
|
+
entry.hostname,
|
|
78
|
+
{ provider, route: provider, ...entry },
|
|
79
|
+
]),
|
|
80
|
+
...Object.entries(SERVICE_UPSTREAMS).map(([service, entry]) => [
|
|
81
|
+
entry.hostname,
|
|
82
|
+
{ provider: service, route: `svc/${service}`, ...entry },
|
|
83
|
+
]),
|
|
84
|
+
]);
|
|
50
85
|
|
|
51
86
|
// A hostname carrying any of these is not a hostname. Checked rather than
|
|
52
87
|
// assumed because the value arrives on a request line from whatever the client
|
|
@@ -67,9 +102,24 @@ function normalizeHostname(value) {
|
|
|
67
102
|
return host;
|
|
68
103
|
}
|
|
69
104
|
|
|
105
|
+
/**
|
|
106
|
+
* Azure OpenAI has no fixed host: every customer's resource is its own. So it is
|
|
107
|
+
* recognised by the same closed suffix rule the gateway stores its addresses
|
|
108
|
+
* under (lib/providers/endpoint.ts `AZURE_HOST`) — one DNS label, then exactly
|
|
109
|
+
* `openai.azure.com` or `services.ai.azure.com` — rather than by a table row.
|
|
110
|
+
* Being recognised is what makes a CONNECT to a resource refuse, and what routes
|
|
111
|
+
* an absolute-form request to the governed `azure` route. The gateway then sends
|
|
112
|
+
* it to the address stored with the tenant's key, not to the host named here.
|
|
113
|
+
*/
|
|
114
|
+
export const AZURE_HOST = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.(?:openai\.azure\.com|services\.ai\.azure\.com)$/;
|
|
115
|
+
const AZURE_UPSTREAM = { provider: "azure", route: "azure", basePath: "/openai/v1" };
|
|
116
|
+
|
|
70
117
|
/** Exact match only — `evil-api.anthropic.com` is somebody else's hostname. */
|
|
71
118
|
export function providerForHost(hostname) {
|
|
72
|
-
|
|
119
|
+
const host = normalizeHostname(hostname);
|
|
120
|
+
const fixed = HOST_BY_NAME.get(host);
|
|
121
|
+
if (fixed) return fixed;
|
|
122
|
+
return AZURE_HOST.test(host) ? { ...AZURE_UPSTREAM, hostname: host } : null;
|
|
73
123
|
}
|
|
74
124
|
|
|
75
125
|
function parsePort(value) {
|
|
@@ -147,9 +197,9 @@ function refuse(status, code, message, help) {
|
|
|
147
197
|
return { allow: false, status, code, message, help };
|
|
148
198
|
}
|
|
149
199
|
|
|
150
|
-
function governedPathHelp(
|
|
200
|
+
function governedPathHelp(route, localBaseUrl) {
|
|
151
201
|
const base = localBaseUrl ? String(localBaseUrl).replace(/\/+$/, "") : "";
|
|
152
|
-
return `${base}/api/v1/${
|
|
202
|
+
return `${base}/api/v1/${route}`;
|
|
153
203
|
}
|
|
154
204
|
|
|
155
205
|
/**
|
|
@@ -178,7 +228,7 @@ export function classifyConnect({ target, gatewayOrigin, allowHosts = [], localB
|
|
|
178
228
|
`PassControl will not tunnel TLS to ${parsed.hostname}. It cannot see inside that connection, so it could ` +
|
|
179
229
|
"neither inject the provider key nor apply scope, budget or the kill switch — the call would leave " +
|
|
180
230
|
"ungoverned while appearing to be governed.",
|
|
181
|
-
`Point the client's base URL at ${governedPathHelp(provider.
|
|
231
|
+
`Point the client's base URL at ${governedPathHelp(provider.route, localBaseUrl)} instead. ` +
|
|
182
232
|
"PassControl does not install a TLS-intercepting CA."
|
|
183
233
|
);
|
|
184
234
|
}
|
|
@@ -250,7 +300,7 @@ export function classifyProxyRequest({ url, gatewayOrigin, localBaseUrl = "" } =
|
|
|
250
300
|
rest = rest.slice(provider.basePath.length);
|
|
251
301
|
}
|
|
252
302
|
if (!rest.startsWith("/")) rest = `/${rest}`;
|
|
253
|
-
return { allow: true, path: `/api/v1/${provider.
|
|
303
|
+
return { allow: true, path: `/api/v1/${provider.route}${rest}${parsed.search}`, reason: "provider" };
|
|
254
304
|
}
|
|
255
305
|
|
|
256
306
|
const gateway = gatewayTarget(gatewayOrigin);
|
package/cli/selftest.mjs
CHANGED
|
@@ -111,7 +111,7 @@ export async function proveItWorks({
|
|
|
111
111
|
});
|
|
112
112
|
const visa = await visas.getVisa();
|
|
113
113
|
proof.visa = true;
|
|
114
|
-
ok("minted a visa with
|
|
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`, `azure` and `local` (a model server you run, such as Ollama; self-host only). OpenAI POST Responses works through `pc.fetch`/the OpenAI SDK as well as
|
|
162
|
+
Chat Completions. xAI is served through its Responses API only (`client.responses.create`);
|
|
163
|
+
its legacy Chat Completions endpoint is refused. Gemini uses Google's OpenAI-compatible endpoint; native
|
|
164
|
+
`generateContent` is not supported. Azure OpenAI takes the plain OpenAI client (not
|
|
165
|
+
`AzureOpenAI`), with `model` set to your deployment name; the gateway sends the call to the
|
|
166
|
+
resource address stored with your Azure key. See [accepted paths](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md#data-plane--proxy-a-model-call).
|
|
164
167
|
|
|
165
168
|
The TypeScript SDK **does not attach sender proofs**. Its provider requests use
|
|
166
169
|
bearer visas: they work with sender-proof mode off/observe, but required mode refuses
|
package/sdk/control.d.ts
CHANGED
|
@@ -120,21 +120,23 @@ export declare class ControlClient {
|
|
|
120
120
|
readonly logs: {
|
|
121
121
|
/**
|
|
122
122
|
* `class` selects a view, never a different record: omitted returns every
|
|
123
|
-
* call, `inference`
|
|
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" | "local";
|
|
2
2
|
export interface PassControlOptions {
|
|
3
3
|
/**
|
|
4
4
|
* Gateway origin, e.g. https://passcontrol.example.com — scheme, host and
|