passcontrol 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -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 private beta, access by request | You want a managed gateway without running a database or Docker | Your agents and provider account |
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
- [Request beta access](https://passcontrol.vertias.eu/beta). To look around first, try
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 access, install the CLI with Node/npm and sign in:
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`; service presets: `github`, `telegram`; 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,6 +258,8 @@ 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
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
@@ -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
- The cost budget retains a proxy estimate; it does not become knowledge of actual dollars.
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
@@ -323,6 +326,7 @@ All paths below are relative to `/api/v1/<provider>`. SDK base URLs and aliases
323
326
  | `gemini` | Google's **OpenAI-compatible** Chat Completions | Models list/detail |
324
327
  | `xai` | **POST Responses** only (legacy Chat Completions refused) | Models list/detail |
325
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 |
326
330
 
327
331
  Gemini's native `generateContent` API is not supported. Responses is served for OpenAI,
328
332
  xAI and Azure; embeddings for OpenAI, Mistral and Azure, and an embeddings call never fails over, because
@@ -335,7 +339,9 @@ Custom provider base URLs support compatible deployments such as Ollama, vLLM, o
335
339
  LiteLLM without adding provider IDs. They require operator opt-in:
336
340
  `PROVIDER_ENDPOINT_MODE=selfhost` permits HTTP, private addresses, and custom ports;
337
341
  a comma-separated hostname list permits only listed HTTPS hosts on port 443. Unset/off
338
- refuses custom endpoints. Shape validation is **not full SSRF prevention**: it does not
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
339
345
  resolve or pin DNS. Operators must control egress and trust the destination receiving
340
346
  the provider credential. Upstream redirects are refused, never followed.
341
347
 
@@ -364,11 +370,6 @@ check needs the relevant earlier statements or a trusted checkpoint. The public
364
370
  tree ships the format and verification code/page, **not statement production, scheduling,
365
371
  or statement/proof-serving routes**. See [statement format and limits](https://github.com/Vertias3u/PassControl/blob/main/docs/statement-format.md).
366
372
 
367
- Owner binding is per workspace. A typed owner is a declaration; GitHub verification
368
- checks publication of a token in a particular account's repository, and domain
369
- verification checks a well-known HTTPS token. Neither proves a person's legal identity
370
- or trustworthiness. Company registry evidence is also distinct from authority to represent
371
- that company. Only published bindings are attached to public evidence.
372
373
 
373
374
  ![Recorded kill-switch demonstration: subsequent requests are refused](https://raw.githubusercontent.com/Vertias3u/PassControl/main/docs/demo/kill-switch.gif)
374
375
 
@@ -380,7 +381,7 @@ of an already-dispatched stream.
380
381
  ## Self-host operations reference
381
382
 
382
383
  <details>
383
- <summary>Source setup, lifecycle, credential switching, production and portability</summary>
384
+ <summary>Source setup, lifecycle, credential switching and portability</summary>
384
385
 
385
386
  The CLI package declares Node ≥18, but the full stack needs Node 22+: locked Supabase
386
387
  dependencies need ≥20 and Wrangler needs ≥22. Use `passcontrol setup --no-open` to
@@ -414,14 +415,9 @@ Shell or project-file gateway overrides are refused and named before services st
414
415
  global write could not override them safely. Clean up any still-active remote identity at its
415
416
  original gateway.
416
417
 
417
- For production, configure [`.env.example`](https://github.com/Vertias3u/PassControl/blob/main/.env.example), use Supabase (plain Postgres
418
- is insufficient), set `DATABASE_URL` in your shell environment and apply the public migrations with
419
- `npm run migrate`,
420
- and build/run the app. Supported paths are Next.js on Vercel, `npm run build` then
421
- `npm start` on a Node host behind a trusted reverse proxy, and the
422
- [Cloudflare/OpenNext build](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md). Configure Auth/SMTP,
423
- secrets, backups, Redis persistence/no-eviction, and periodic authenticated
424
- `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).
425
421
 
426
422
  | Boundary | Cloud | Public self-host tree |
427
423
  |---|---|---|
@@ -68,24 +68,27 @@ import {
68
68
  isGuiPreset,
69
69
  isIntegration,
70
70
  isServicePreset,
71
+ SERVICE_ENV,
71
72
  supportsWrite,
72
73
  } from "../cli/presets.mjs";
73
74
  import { importCompletionMessage, noAgentCreateMessage } from "../cli/workspace-import-report.mjs";
74
- import { checkForUpdate, fetchLatest, REGISTRY_URL } from "../cli/update-check.mjs";
75
+ import { announcesAfter, checkForUpdate, fetchLatest, REGISTRY_URL } from "../cli/update-check.mjs";
75
76
  import {
76
77
  clearMarker,
77
78
  detectInstall,
78
79
  dirtyBlockers,
79
80
  expectedProjectId,
81
+ finishLines,
80
82
  formatPlan,
81
83
  isPublicRepoUrl,
84
+ migrationBase,
82
85
  planUpdate,
83
86
  readMarker,
84
87
  stackFromConfig,
85
88
  writeMarker,
86
89
  } from "../cli/update.mjs";
87
90
  import { isLocalGatewayOrigin, probeGatewayVersion, probeTimeoutMs } from "../cli/gateway-probe.mjs";
88
- import { dashboardOriginForOffset } from "../cli/local-stack.mjs";
91
+ import { dashboardOriginForOffset, portHolders, stackPortConflictMessage } from "../cli/local-stack.mjs";
89
92
  import { startSidecar } from "../cli/sidecar.mjs";
90
93
  import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
91
94
  import { loginCommand } from "../cli/login.mjs";
@@ -330,6 +333,9 @@ async function gatewayStatus(noNetwork = false, gateway = config.gateway) {
330
333
  return probeGatewayVersion(origin);
331
334
  }
332
335
 
336
+ // Wide enough for "System health:", the longest label status prints.
337
+ const STATUS_LABEL_WIDTH = 15;
338
+
333
339
  async function printCockpit({ noNetwork = false, json = false } = {}) {
334
340
  const gateway = await gatewayStatus(noNetwork);
335
341
  const local = managedDashboardTarget();
@@ -368,17 +374,17 @@ async function printCockpit({ noNetwork = false, json = false } = {}) {
368
374
  }
369
375
 
370
376
  console.log(`${heading("PassControl")}\n`);
371
- console.log(formatLabel("Gateway", `${gateway.label} ${config.gateway}`));
372
- console.log(formatLabel("Dashboard", `${dashboard} ${local.url}`));
373
- console.log(formatLabel("App", app));
374
- console.log(formatLabel("Config", configFile));
375
- console.log(formatLabel("Provider", config.provider));
376
- console.log(formatLabel("Model", config.model));
377
- console.log(formatLabel("Passport", passportConfigured ? redact(config.passportId) : "missing"));
378
- console.log(formatLabel("Key storage", passportStorage.message));
379
- console.log(formatLabel("Admin key", adminConfigured ? redact(config.apiKey, 6) : "missing"));
380
- console.log(formatLabel("System health", systemHealthLabel(systemHealth)));
381
- console.log(`${formatLabel("Sidecar", `foreground command (\`${cliCommand("sidecar")}\`)`)}\n`);
377
+ console.log(formatLabel("Gateway", `${gateway.label} ${config.gateway}`, STATUS_LABEL_WIDTH));
378
+ console.log(formatLabel("Dashboard", `${dashboard} ${local.url}`, STATUS_LABEL_WIDTH));
379
+ console.log(formatLabel("App", app, STATUS_LABEL_WIDTH));
380
+ console.log(formatLabel("Config", configFile, STATUS_LABEL_WIDTH));
381
+ console.log(formatLabel("Provider", config.provider, STATUS_LABEL_WIDTH));
382
+ console.log(formatLabel("Model", config.model, STATUS_LABEL_WIDTH));
383
+ console.log(formatLabel("Passport", passportConfigured ? redact(config.passportId) : "missing", STATUS_LABEL_WIDTH));
384
+ console.log(formatLabel("Key storage", passportStorage.message, STATUS_LABEL_WIDTH));
385
+ console.log(formatLabel("Admin key", adminConfigured ? redact(config.apiKey, 6) : "missing", STATUS_LABEL_WIDTH));
386
+ console.log(formatLabel("System health", systemHealthLabel(systemHealth), STATUS_LABEL_WIDTH));
387
+ console.log(`${formatLabel("Sidecar", `foreground command (\`${cliCommand("sidecar")}\`)`, STATUS_LABEL_WIDTH)}\n`);
382
388
  const next = [];
383
389
  if (config.sources.length === 0) {
384
390
  next.push(["init", "configure this project"]);
@@ -1214,16 +1220,24 @@ function ownSupabaseDatabaseIsRunning(offset = 0) {
1214
1220
  }
1215
1221
  }
1216
1222
 
1217
- async function assertLocalStackPortsAvailable(offset = 0) {
1223
+ /** Which containers hold `ports`, so a refusal can name the stack to stop. Empty when Docker cannot say. */
1224
+ function dockerPortHolders(ports) {
1225
+ try {
1226
+ const listing = execFileSync("docker", ["ps", "--format", "{{.Names}}\t{{.Ports}}"], { encoding: "utf8", timeout: DOCKER_TIMEOUT_MS });
1227
+ return portHolders(listing, ports);
1228
+ } catch {
1229
+ return [];
1230
+ }
1231
+ }
1232
+
1233
+ async function assertLocalStackPortsAvailable(offset = 0, { rerun = cliCommand("setup") } = {}) {
1218
1234
  if (ownSupabaseDatabaseIsRunning(offset)) return;
1219
1235
  const busy = [];
1220
1236
  for (const port of LOCAL_STACK_PORTS.map((port) => port + offset)) {
1221
1237
  if (await portIsListening(port)) busy.push(port);
1222
1238
  }
1223
1239
  if (busy.length) {
1224
- throw new Error(
1225
- `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\`.`
1226
- );
1240
+ throw new Error(stackPortConflictMessage({ busy, holders: dockerPortHolders(busy), rerun }));
1227
1241
  }
1228
1242
  }
1229
1243
 
@@ -1710,7 +1724,19 @@ function analyzeAppForUpdate({ fetchRemote = true } = {}) {
1710
1724
  const behind = Number(gitIn(root, ["rev-list", "--count", "HEAD..origin/main"]));
1711
1725
  const base = { root, offset: stack.offset, head, target, resume, lockfileDirty: gitIn(root, ["status", "--porcelain", "--untracked-files=no", "--", "package-lock.json"]) !== "" };
1712
1726
  if (behind === 0) return { status: "current", ...base };
1713
- const migrations = gitIn(root, ["diff", "--name-only", "--diff-filter=A", head, target, "--", "db/migrations"]).split("\n").filter(Boolean);
1727
+ const since = migrationBase({
1728
+ head,
1729
+ resumeFrom: resume?.from,
1730
+ isAncestor: (rev) => {
1731
+ try {
1732
+ gitIn(root, ["merge-base", "--is-ancestor", rev, head]);
1733
+ return true;
1734
+ } catch {
1735
+ return false;
1736
+ }
1737
+ },
1738
+ });
1739
+ const migrations = gitIn(root, ["diff", "--name-only", "--diff-filter=A", since, target, "--", "db/migrations"]).split("\n").filter(Boolean);
1714
1740
  return { status: "behind", behind, from: head.slice(0, 7), to: target.slice(0, 7), migrations, ...base };
1715
1741
  }
1716
1742
 
@@ -1727,6 +1753,18 @@ async function applyAppUpdate(app) {
1727
1753
  `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.`
1728
1754
  );
1729
1755
  }
1756
+ // The stack's own ports, before anything changes. Another stack on them
1757
+ // (a second checkout at the same offset) only showed up when Supabase failed
1758
+ // to start, after the fast-forward and \`npm ci\`, as "npm exited with code 1".
1759
+ // A running dashboard of THIS install means its own stack holds them, which
1760
+ // assertLocalStackPortsAvailable already allows.
1761
+ try {
1762
+ await assertLocalStackPortsAvailable(app.offset, { rerun: cliCommand(app.resume ? "update --app-only" : "update") });
1763
+ } catch (error) {
1764
+ throw new Error(
1765
+ `${error.message} ${app.resume ? "The earlier update is still unfinished; nothing more was changed." : "Nothing was changed."}`
1766
+ );
1767
+ }
1730
1768
  const restart = app.resume?.wasRunning ?? Boolean(managed);
1731
1769
  const from = app.resume?.from ?? app.head;
1732
1770
  writeMarker({ appRoot: app.root, from, to: app.target, wasRunning: restart, startedAt: new Date().toISOString() });
@@ -1739,15 +1777,26 @@ async function applyAppUpdate(app) {
1739
1777
  // npm's own rewrite of the lockfile (see dirtyBlockers); \`npm ci\` below
1740
1778
  // installs exactly what the new lockfile says.
1741
1779
  if (app.lockfileDirty) gitIn(app.root, ["checkout", "--", "package-lock.json"]);
1742
- step(`Fast-forwarding ${app.from} → ${app.to}…`);
1743
- await runCommand("git", ["merge", "--ff-only", "origin/main"], { cwd: app.root });
1780
+ // One summary line, not git's per-file list (277 lines for 1.2.0).
1781
+ const changed = gitIn(app.root, ["diff", "--shortstat", "HEAD", "origin/main"]);
1782
+ step(`Fast-forwarding ${app.from} → ${app.to}${changed ? ` (${changed})` : ""}…`);
1783
+ await runCommand("git", ["merge", "--ff-only", "--quiet", "origin/main"], { cwd: app.root });
1744
1784
  }
1745
1785
  step("Installing dependencies (npm ci)…");
1746
- await runCommand(npm, ["ci"], { cwd: app.root });
1786
+ // Errors still print; deprecation warnings, funding and audit chatter do not.
1787
+ await runCommand(npm, ["ci", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: app.root });
1747
1788
  step("Applying migrations and refreshing the local stack…");
1748
- await runCommand(npm, ["run", "dev:stack"], {
1789
+ await runCommand(npm, ["run", "--silent", "dev:stack"], {
1749
1790
  cwd: app.root,
1750
- env: { ...process.env, PASSCONTROL_PORT_OFFSET: String(app.offset), PASSCONTROL_SKIP_SEED: "1", PASSCONTROL_VIA_CLI: "1" },
1791
+ env: {
1792
+ ...process.env,
1793
+ PASSCONTROL_PORT_OFFSET: String(app.offset),
1794
+ PASSCONTROL_SKIP_SEED: "1",
1795
+ PASSCONTROL_VIA_CLI: "1",
1796
+ // dev-stack.sh keeps Supabase's banner (with its local keys) to a log it
1797
+ // prints only on failure, and lists only migrations it applies.
1798
+ PASSCONTROL_QUIET: "1",
1799
+ },
1751
1800
  });
1752
1801
  if (restart) await startDashboard({ dashboardOnly: true });
1753
1802
  } catch (error) {
@@ -1758,8 +1807,16 @@ async function applyAppUpdate(app) {
1758
1807
  );
1759
1808
  }
1760
1809
  clearMarker();
1761
- ok(`App updated to ${String(app.target).slice(0, 7)}.`);
1762
- step(`To roll back the code: git -C ${app.root} checkout ${from}. Database migrations only go forward.`);
1810
+ const closing = finishLines({
1811
+ target: app.target,
1812
+ root: app.root,
1813
+ restarted: restart,
1814
+ // The commit THIS run moved from. The marker's `from` can predate an
1815
+ // earlier, interrupted update; rolling back there skips a release.
1816
+ rollbackTo: app.status === "behind" ? app.head : null,
1817
+ startCommand: cliCommand("start"),
1818
+ });
1819
+ for (const [kind, text] of closing) (kind === "ok" ? ok : step)(text);
1763
1820
  }
1764
1821
 
1765
1822
  async function updateCommand(opts = {}) {
@@ -2487,22 +2544,11 @@ function printServicePreset(service, opts = {}) {
2487
2544
  ? cliCommand(`sidecar --port ${port}`)
2488
2545
  : cliCommand("sidecar");
2489
2546
  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
- }
2547
+ const entry = Object.hasOwn(SERVICE_ENV, service) ? SERVICE_ENV[service] : null;
2548
+ if (!entry) throw new Error(`Usage: passcontrol env <${integrationChoices()}>`);
2549
+ for (const line of entry.about) console.log(line);
2550
+ printExports([[entry.envVar, `http://${host}:${port}/api/v1/svc/${service}`]]);
2551
+ console.log(entry.usage);
2506
2552
  }
2507
2553
 
2508
2554
  function aiderConfig(opts = {}) {
@@ -3258,6 +3304,9 @@ const IMPORT_REASONS = {
3258
3304
  policy_malformed: "its policy could not be parsed, and creating it without one would leave it unrestricted.",
3259
3305
  policy_shadow_malformed: "its shadow policy could not be parsed.",
3260
3306
  unknown_status: "it records a status this version does not recognise.",
3307
+ account_limit_reached:
3308
+ "this account has reached its agent limit. Nothing was created for it. Revoke agents you no longer use, " +
3309
+ "or ask the operator for a higher limit, then import again: agents already created are skipped.",
3261
3310
  };
3262
3311
 
3263
3312
  async function exportCommand(opts = {}) {
@@ -3782,7 +3831,7 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
3782
3831
  // it can never turn a registry outage into a slow `passcontrol call`.
3783
3832
  // .catch() rather than try/catch: an unhandled rejection from a background
3784
3833
  // nicety must not take down a command that already did its job.
3785
- const updateNotice = runtime.skipUpdate ? Promise.resolve(null) : checkForUpdate({
3834
+ const updateNotice = runtime.skipUpdate || !announcesAfter(command) ? Promise.resolve(null) : checkForUpdate({
3786
3835
  current: CLI_VERSION,
3787
3836
  json: Boolean(opts.json),
3788
3837
  }).catch(() => null);
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", "xai", "azure"];
32
- export const OPENAI_SHAPE_PROVIDERS = new Set(["openai", "groq", "mistral", "together", "deepseek", "gemini", "azure"]);
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
 
@@ -404,7 +404,8 @@ export const amber = (value) => paint(ANSI.yellow, value);
404
404
  export const alarm = (value) => paint(ANSI.red, value);
405
405
 
406
406
  export function formatLabel(label, value, width = 11) {
407
- return `${paint(ANSI.cyan, `${label}:`.padEnd(width))}${value}`;
407
+ // A label longer than the column still gets one space before its value.
408
+ return `${paint(ANSI.cyan, `${label}:`.padEnd(Math.max(width, label.length + 2)))}${value}`;
408
409
  }
409
410
 
410
411
  export function step(message = "") {
@@ -7,7 +7,8 @@ export type IntegrationProvider =
7
7
  | "deepseek"
8
8
  | "gemini"
9
9
  | "xai"
10
- | "azure";
10
+ | "azure"
11
+ | "local";
11
12
 
12
13
  export const DEFAULT_ALLOWED_MODELS: Readonly<Record<IntegrationProvider, string>>;
13
14
  export const DEFAULT_CLIENT_MODELS: Readonly<Record<IntegrationProvider, string>>;
@@ -18,6 +18,10 @@ export const DEFAULT_ALLOWED_MODELS = Object.freeze({
18
18
  // `*` would widen an allowlist to whatever a resource ever deploys. An operator
19
19
  // whose deployments are named otherwise edits the scope.
20
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: "*",
21
25
  });
22
26
 
23
27
  export const DEFAULT_CLIENT_MODELS = Object.freeze({
@@ -33,6 +37,9 @@ export const DEFAULT_CLIENT_MODELS = Object.freeze({
33
37
  xai: "grok-4.20-0309-non-reasoning",
34
38
  // A deployment name, so only a guess until the operator names theirs.
35
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",
36
43
  });
37
44
 
38
45
  export function defaultAllowedModelForProvider(provider) {
@@ -18,3 +18,58 @@ export function dashboardOriginForOffset(offset) {
18
18
  assertOffset(offset);
19
19
  return `http://localhost:${LOCAL_DASHBOARD_PORT + offset}`;
20
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/presets.mjs CHANGED
@@ -35,7 +35,61 @@ export function isGuiPreset(name) {
35
35
  * preset prints the governed base URL for that service; what the agent may call
36
36
  * there is set per agent in the dashboard.
37
37
  */
38
- export const SERVICE_PRESETS = ["github", "telegram"];
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
+ };
39
93
 
40
94
  export function isServicePreset(name) {
41
95
  return SERVICE_PRESETS.includes(String(name ?? "").toLowerCase());
@@ -60,6 +60,15 @@ export const SERVICE_UPSTREAMS = {
60
60
  // Telegram's token is in its URL path, so a tunnel to it would carry the bot
61
61
  // token past every control: refused for CONNECT, like every host here.
62
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" },
63
72
  };
64
73
 
65
74
  // `route` is the path segment after /api/v1/ that governs the host.
@@ -71,6 +71,14 @@ export function mayAnnounce({ isTty, json = false, env = process.env } = {}) {
71
71
  return true;
72
72
  }
73
73
 
74
+ /**
75
+ * Whether a command ends with the notice. Not `update`: it reports versions
76
+ * itself, and its notice was looked up before the update ran.
77
+ */
78
+ export function announcesAfter(command) {
79
+ return command !== "update";
80
+ }
81
+
74
82
  /** May we ask the registry again, or is the cached answer still fresh? */
75
83
  export function shouldFetch({ now = Date.now(), cache = null, ttlMs = CACHE_TTL_MS } = {}) {
76
84
  if (cache && typeof cache.checkedAt === "number" && now - cache.checkedAt < ttlMs) return false;
package/cli/update.mjs CHANGED
@@ -164,10 +164,13 @@ export function formatPlan(plan) {
164
164
  break;
165
165
  case "behind": {
166
166
  lines.push(`App: ${app.behind} new commit(s), ${app.from} → ${app.to}`);
167
+ if (app.resume?.from) {
168
+ lines.push(` an earlier update (from ${String(app.resume.from).slice(0, 7)}) did not finish; this one completes it`);
169
+ }
167
170
  const migrations = app.migrations ?? [];
168
171
  lines.push(
169
172
  migrations.length
170
- ? ` new database migrations (they only go forward): ${migrations.map((m) => path.basename(m)).join(", ")}`
173
+ ? ` database migrations to apply (they only go forward): ${migrations.map((m) => path.basename(m)).join(", ")}`
171
174
  : " no new database migrations"
172
175
  );
173
176
  lines.push(" steps: stop the dashboard, fast-forward, npm ci, apply migrations, start the dashboard again if it was running");
@@ -179,6 +182,32 @@ export function formatPlan(plan) {
179
182
  return lines;
180
183
  }
181
184
 
185
+ /**
186
+ * Where to count new migrations from. After an interrupted update the checkout
187
+ * is already at (or past) that update's target while its migrations never ran,
188
+ * so counting from HEAD names too few (found 2026-10-06: three named, eight
189
+ * applied). Count from where the interrupted update started, if this checkout
190
+ * still contains that commit.
191
+ */
192
+ export function migrationBase({ head, resumeFrom, isAncestor }) {
193
+ if (resumeFrom && isAncestor(resumeFrom)) return resumeFrom;
194
+ return head;
195
+ }
196
+
197
+ /**
198
+ * The closing lines of a finished app update, as [kind, text] pairs ("ok" or
199
+ * "step"). `rollbackTo` is the commit this run fast-forwarded from, or null when
200
+ * it only finished an earlier update and did not move the code.
201
+ */
202
+ export function finishLines({ target, root, restarted, rollbackTo, startCommand }) {
203
+ const lines = [["ok", `App updated to ${String(target).slice(0, 7)}.`]];
204
+ if (!restarted) lines.push(["step", `The dashboard is not running. Start it with \`${startCommand}\`.`]);
205
+ if (rollbackTo) {
206
+ lines.push(["step", `To roll back the code: git -C ${root} checkout ${rollbackTo}. Database migrations only go forward.`]);
207
+ }
208
+ return lines;
209
+ }
210
+
182
211
  // ── Resume marker ─────────────────────────────────────────────────────────────
183
212
  //
184
213
  // Written before the first change to the checkout and cleared on success. After
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "1.1.0",
3
+ "version": "1.2.1",
4
4
  "description": "Identity, scope and budget controls for AI agents while provider keys stay server-side.",
5
5
  "license": "BUSL-1.1",
6
6
  "homepage": "https://passcontrol.vertias.eu",
package/sdk/README.md CHANGED
@@ -158,7 +158,7 @@ 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
- `gemini`, `xai` and `azure`. OpenAI POST Responses works through `pc.fetch`/the OpenAI SDK as well as
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
162
  Chat Completions. xAI is served through its Responses API only (`client.responses.create`);
163
163
  its legacy Chat Completions endpoint is refused. Gemini uses Google's OpenAI-compatible endpoint; native
164
164
  `generateContent` is not supported. Azure OpenAI takes the plain OpenAI client (not
@@ -1,4 +1,4 @@
1
- export type ProviderId = "openai" | "anthropic" | "groq" | "mistral" | "together" | "deepseek" | "gemini" | "xai" | "azure";
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