passcontrol 1.2.1 → 1.3.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 +3 -2
- package/bin/passcontrol.mjs +136 -15
- package/cli/claude-code.mjs +96 -0
- package/cli/codex.mjs +102 -0
- package/cli/config.mjs +3 -3
- package/cli/integration-defaults.d.mts +1 -0
- package/cli/integration-defaults.mjs +5 -0
- package/cli/presets.mjs +15 -5
- package/cli/proxy-policy.mjs +1 -0
- package/cli/sidecar.mjs +54 -3
- package/package.json +2 -2
- package/sdk/README.md +1 -1
- package/sdk/passcontrol.d.ts +1 -1
package/README.md
CHANGED
|
@@ -154,14 +154,14 @@ in the generated configuration:
|
|
|
154
154
|
passcontrol configure claude-desktop --write
|
|
155
155
|
```
|
|
156
156
|
|
|
157
|
-
The cursor preset also writes configuration
|
|
157
|
+
The cursor preset also writes configuration. `passcontrol configure claude-code --write` routes Claude Code's own model calls through the sidecar by merging two keys into its settings. `passcontrol configure codex --write` does the same for Codex with a profile file of its own, used as `codex --profile passcontrol`.
|
|
158
158
|
|
|
159
159
|
The sidecar listens on loopback by default and substitutes a visa for the client's dummy
|
|
160
160
|
API key. Treat access to that local listener as access to the configured agent. It is
|
|
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`, `brave`, `notion`, `discord`; 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`; coding agent: `codex`; 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
|
|
@@ -325,6 +325,7 @@ All paths below are relative to `/api/v1/<provider>`. SDK base URLs and aliases
|
|
|
325
325
|
| `deepseek` | OpenAI-compatible Chat Completions | Not proxied |
|
|
326
326
|
| `gemini` | Google's **OpenAI-compatible** Chat Completions | Models list/detail |
|
|
327
327
|
| `xai` | **POST Responses** only (legacy Chat Completions refused) | Models list/detail |
|
|
328
|
+
| `openrouter` | OpenRouter's Chat Completions, one key for its whole catalog; charged at the cost OpenRouter reports | Models list |
|
|
328
329
|
| `azure` | Azure OpenAI v1: Chat Completions, **POST Responses** and **POST Embeddings**, at the resource address stored with the key | Models list |
|
|
329
330
|
| `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
|
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -90,6 +90,8 @@ import {
|
|
|
90
90
|
import { isLocalGatewayOrigin, probeGatewayVersion, probeTimeoutMs } from "../cli/gateway-probe.mjs";
|
|
91
91
|
import { dashboardOriginForOffset, portHolders, stackPortConflictMessage } from "../cli/local-stack.mjs";
|
|
92
92
|
import { startSidecar } from "../cli/sidecar.mjs";
|
|
93
|
+
import { claudeCodeEnv, claudeCodeSettingsPath, removeClaudeCodeSettings, writeClaudeCodeSettings } from "../cli/claude-code.mjs";
|
|
94
|
+
import { CODEX_PROFILE, codexProfilePath, codexProfileToml, codexStoresApiKey, removeCodexProfile, writeCodexProfile } from "../cli/codex.mjs";
|
|
93
95
|
import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
|
|
94
96
|
import { loginCommand } from "../cli/login.mjs";
|
|
95
97
|
import { logoutCommand } from "../cli/logout.mjs";
|
|
@@ -198,7 +200,7 @@ ${heading("Quick start")}
|
|
|
198
200
|
${cmd} login [--project] sign in through your browser and set this machine up
|
|
199
201
|
${cmd} call "hi" mint a visa and make a governed model call
|
|
200
202
|
${cmd} mcp passport identity for Claude Desktop, Cursor, Claude Code
|
|
201
|
-
${cmd} sidecar [--port 8788] [--allow-connect host[,host]]
|
|
203
|
+
${cmd} sidecar [--port 8788] [--allow-connect host[,host]] [--ollama-port 11435]
|
|
202
204
|
passport identity for any tool that takes an api_key
|
|
203
205
|
|
|
204
206
|
${heading("Operate")}
|
|
@@ -2362,6 +2364,7 @@ async function sidecarCommand(rest, opts) {
|
|
|
2362
2364
|
passportSecret,
|
|
2363
2365
|
keyStorage,
|
|
2364
2366
|
port: sidecarPort(opts),
|
|
2367
|
+
ollamaPort: opts.ollamaPort != null ? ollamaPort(opts) : null,
|
|
2365
2368
|
host: String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1"),
|
|
2366
2369
|
// Named on the command line, never inferred. A sidecar reachable off-host
|
|
2367
2370
|
// mints visas for whoever connects, so widening the bind is a decision the
|
|
@@ -2442,11 +2445,14 @@ function passControlMcpEntry() {
|
|
|
2442
2445
|
return mcpServerEntry({ cliPath: CLI_ENTRY });
|
|
2443
2446
|
}
|
|
2444
2447
|
|
|
2445
|
-
function printMcpPreset(integration) {
|
|
2448
|
+
function printMcpPreset(integration, opts = {}) {
|
|
2446
2449
|
requireGlobalMcpPassport();
|
|
2447
2450
|
if (integration === "claude-code") {
|
|
2448
|
-
|
|
2449
|
-
console.log(
|
|
2451
|
+
const { baseUrl } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
|
|
2452
|
+
console.log("# Route Claude Code's model calls through the sidecar (start it first):");
|
|
2453
|
+
printExports(Object.entries(claudeCodeEnv(baseUrl)));
|
|
2454
|
+
console.log("# Optional: also add PassControl's chat tool to Claude Code:");
|
|
2455
|
+
console.log(`# ${CLAUDE_CODE_ADD_COMMAND}`);
|
|
2450
2456
|
return;
|
|
2451
2457
|
}
|
|
2452
2458
|
|
|
@@ -2455,10 +2461,40 @@ function printMcpPreset(integration) {
|
|
|
2455
2461
|
console.log(JSON.stringify(mcpServersDocument(passControlMcpEntry()), null, 2));
|
|
2456
2462
|
}
|
|
2457
2463
|
|
|
2464
|
+
/** The Ollama listener's port: `--ollama-port N`, or 11435 when the flag has no number. */
|
|
2465
|
+
const DEFAULT_OLLAMA_PORT = 11435;
|
|
2466
|
+
function ollamaPort(opts = {}) {
|
|
2467
|
+
const raw = opts.ollamaPort;
|
|
2468
|
+
if (raw == null || raw === true) return DEFAULT_OLLAMA_PORT;
|
|
2469
|
+
const port = Number(raw);
|
|
2470
|
+
if (!Number.isInteger(port) || port < 1 || port > 65535) {
|
|
2471
|
+
throw new Error(`--ollama-port must be a port number (1-65535), not "${raw}".`);
|
|
2472
|
+
}
|
|
2473
|
+
return port;
|
|
2474
|
+
}
|
|
2475
|
+
|
|
2476
|
+
function printOllamaPreset(opts = {}) {
|
|
2477
|
+
const port = ollamaPort(opts);
|
|
2478
|
+
const host = String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1");
|
|
2479
|
+
console.log("# Apps that only take OLLAMA_HOST: point them at PassControl's Ollama listener.");
|
|
2480
|
+
printExports([["OLLAMA_HOST", `${host}:${port}`]]);
|
|
2481
|
+
console.log(`# Start it with: ${cliCommand(`sidecar --ollama-port${port === DEFAULT_OLLAMA_PORT ? "" : ` ${port}`}`)}`);
|
|
2482
|
+
console.log("# Calls go to the workspace's `local` model server (Settings → Models on this machine).");
|
|
2483
|
+
console.log("# Local models have no price: give the agent a token budget, not a dollar limit.");
|
|
2484
|
+
}
|
|
2485
|
+
|
|
2458
2486
|
function printAgentPreset(name = "generic", opts = {}) {
|
|
2459
2487
|
const preset = name.toLowerCase();
|
|
2460
2488
|
if (isMcpIntegration(preset)) {
|
|
2461
|
-
printMcpPreset(preset);
|
|
2489
|
+
printMcpPreset(preset, opts);
|
|
2490
|
+
return;
|
|
2491
|
+
}
|
|
2492
|
+
if (preset === "ollama") {
|
|
2493
|
+
printOllamaPreset(opts);
|
|
2494
|
+
return;
|
|
2495
|
+
}
|
|
2496
|
+
if (preset === "codex") {
|
|
2497
|
+
printCodexPreset(opts);
|
|
2462
2498
|
return;
|
|
2463
2499
|
}
|
|
2464
2500
|
|
|
@@ -2563,19 +2599,100 @@ function aiderConfig(opts = {}) {
|
|
|
2563
2599
|
].join("\n");
|
|
2564
2600
|
}
|
|
2565
2601
|
|
|
2602
|
+
/**
|
|
2603
|
+
* Claude Code's own model calls, through the sidecar (cli/claude-code.mjs). The
|
|
2604
|
+
* project's settings by default; `--global` for every session; `--remove` takes
|
|
2605
|
+
* PassControl's two keys back out. The MCP chat tool stays a separate command
|
|
2606
|
+
* Claude Code owns.
|
|
2607
|
+
*/
|
|
2608
|
+
function configureClaudeCode(opts = {}) {
|
|
2609
|
+
const scope = opts.global ? "user" : "project";
|
|
2610
|
+
const target = claudeCodeSettingsPath({ scope });
|
|
2611
|
+
if (opts.remove) {
|
|
2612
|
+
const result = removeClaudeCodeSettings({ target });
|
|
2613
|
+
if (result.changed) ok(`removed PassControl from ${target}`);
|
|
2614
|
+
else step(`${target} has no PassControl entry; nothing to remove.`);
|
|
2615
|
+
return;
|
|
2616
|
+
}
|
|
2617
|
+
const { baseUrl, port } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
|
|
2618
|
+
console.log(`Preview: ${target}\n\n${JSON.stringify({ env: claudeCodeEnv(baseUrl) }, null, 2)}`);
|
|
2619
|
+
if (!opts.write) {
|
|
2620
|
+
step(`Dry run only. Re-run with \`--write\` to merge these two keys${scope === "project" ? " (or --write --global for every session)" : ""}.`);
|
|
2621
|
+
} else {
|
|
2622
|
+
const result = writeClaudeCodeSettings({ target, baseUrl, force: Boolean(opts.force) });
|
|
2623
|
+
if (!result.changed) ok(`${target} already routes Claude Code through PassControl`);
|
|
2624
|
+
else {
|
|
2625
|
+
if (result.backupPath) step(`backed up ${result.backupPath}`);
|
|
2626
|
+
ok(`wrote ${target}`);
|
|
2627
|
+
}
|
|
2628
|
+
if (result.rawKeyFound) {
|
|
2629
|
+
warn(`${target} also holds a raw ANTHROPIC_API_KEY. PassControl does not need it there; remove it so no key sits on disk.`);
|
|
2630
|
+
}
|
|
2631
|
+
}
|
|
2632
|
+
step(`Start the sidecar before Claude Code: ${cliCommand(port === 8788 ? "sidecar" : `sidecar --port ${port}`)}`);
|
|
2633
|
+
step("The agent's Anthropic scope must allow the models Claude Code uses (its main model, and Haiku for small tasks).");
|
|
2634
|
+
step(`Optional, the chat tool as well: ${CLAUDE_CODE_ADD_COMMAND}`);
|
|
2635
|
+
step(`To undo: ${cliCommand(`configure claude-code --remove${scope === "user" ? " --global" : ""}`)}`);
|
|
2636
|
+
}
|
|
2637
|
+
|
|
2638
|
+
/**
|
|
2639
|
+
* Codex speaks only OpenAI's Responses API, so its profile always points at the
|
|
2640
|
+
* sidecar's OpenAI route. A model is written only when one is named with
|
|
2641
|
+
* --model; otherwise Codex keeps the model its own config chose.
|
|
2642
|
+
*/
|
|
2643
|
+
function codexSettings(opts = {}) {
|
|
2644
|
+
if (opts.provider != null && String(opts.provider).toLowerCase() !== "openai") {
|
|
2645
|
+
throw new Error(`Codex goes through PassControl's OpenAI route only, not "${opts.provider}". Drop --provider.`);
|
|
2646
|
+
}
|
|
2647
|
+
const { baseUrl, port } = sidecarBaseUrl({ ...opts, provider: "openai" });
|
|
2648
|
+
const model = typeof opts.model === "string" && opts.model ? opts.model : undefined;
|
|
2649
|
+
return { baseUrl, port, model };
|
|
2650
|
+
}
|
|
2651
|
+
|
|
2652
|
+
function printCodexPreset(opts = {}) {
|
|
2653
|
+
const { baseUrl, model } = codexSettings(opts);
|
|
2654
|
+
console.log(`# Save as ${codexProfilePath()} (or run: ${cliCommand("configure codex --write")}):`);
|
|
2655
|
+
console.log(codexProfileToml({ baseUrl, model }).trimEnd());
|
|
2656
|
+
}
|
|
2657
|
+
|
|
2658
|
+
/**
|
|
2659
|
+
* Codex's own model calls, through the sidecar (cli/codex.mjs): a profile file
|
|
2660
|
+
* Codex layers over its config when started with `--profile passcontrol`.
|
|
2661
|
+
* `--remove` deletes that file, and only when PassControl wrote it.
|
|
2662
|
+
*/
|
|
2663
|
+
function configureCodex(opts = {}) {
|
|
2664
|
+
const target = codexProfilePath();
|
|
2665
|
+
if (opts.remove) {
|
|
2666
|
+
const result = removeCodexProfile({ target });
|
|
2667
|
+
if (result.changed) ok(`removed ${target}`);
|
|
2668
|
+
else step(`${target} is not a profile PassControl wrote; nothing to remove.`);
|
|
2669
|
+
return;
|
|
2670
|
+
}
|
|
2671
|
+
const { baseUrl, port, model } = codexSettings(opts);
|
|
2672
|
+
console.log(`Preview: ${target}\n\n${codexProfileToml({ baseUrl, model })}`);
|
|
2673
|
+
if (!opts.write) {
|
|
2674
|
+
step("Dry run only. Re-run with `--write` to create this profile. Codex's config.toml is not touched.");
|
|
2675
|
+
} else {
|
|
2676
|
+
const result = writeCodexProfile({ target, baseUrl, model, force: Boolean(opts.force) });
|
|
2677
|
+
if (!result.changed) ok(`${target} already routes Codex through PassControl`);
|
|
2678
|
+
else {
|
|
2679
|
+
if (result.backupPath) step(`backed up ${result.backupPath}`);
|
|
2680
|
+
ok(`wrote ${target}`);
|
|
2681
|
+
}
|
|
2682
|
+
if (codexStoresApiKey()) {
|
|
2683
|
+
warn("Codex also keeps an OpenAI API key of its own (auth.json). The PassControl profile never sends it, but plain `codex` does; `codex logout` removes it.");
|
|
2684
|
+
}
|
|
2685
|
+
}
|
|
2686
|
+
step(`Start the sidecar first: ${cliCommand(port === 8788 ? "sidecar" : `sidecar --port ${port}`)}`);
|
|
2687
|
+
step(`Then run Codex with the profile: codex --profile ${CODEX_PROFILE} (plain \`codex\` still goes straight to OpenAI)`);
|
|
2688
|
+
step("The agent's OpenAI scope must allow the model Codex uses (set with -m, or `model` in Codex's config).");
|
|
2689
|
+
step(`To undo: ${cliCommand("configure codex --remove")}`);
|
|
2690
|
+
}
|
|
2691
|
+
|
|
2566
2692
|
function configureMcpClient(integration, opts = {}) {
|
|
2567
2693
|
requireGlobalMcpPassport();
|
|
2568
2694
|
if (integration === "claude-code") {
|
|
2569
|
-
|
|
2570
|
-
// config file for us to merge into. `--write` used to be accepted here and
|
|
2571
|
-
// silently do nothing — refuse it and hand back the command that works.
|
|
2572
|
-
if (opts.write) {
|
|
2573
|
-
throw new Error(
|
|
2574
|
-
`Claude Code manages MCP servers through its own CLI, so there is no file to write. Run:\n ${CLAUDE_CODE_ADD_COMMAND}`
|
|
2575
|
-
);
|
|
2576
|
-
}
|
|
2577
|
-
console.log("Claude Code manages MCP servers through its CLI. Run:");
|
|
2578
|
-
console.log(CLAUDE_CODE_ADD_COMMAND);
|
|
2695
|
+
configureClaudeCode(opts);
|
|
2579
2696
|
return;
|
|
2580
2697
|
}
|
|
2581
2698
|
|
|
@@ -2609,6 +2726,10 @@ async function configureCommand(rest, opts = {}) {
|
|
|
2609
2726
|
`Unknown integration "${integration}". Use one of: ${integrationChoices()}.`
|
|
2610
2727
|
);
|
|
2611
2728
|
}
|
|
2729
|
+
if (integration === "codex") {
|
|
2730
|
+
configureCodex(opts);
|
|
2731
|
+
return;
|
|
2732
|
+
}
|
|
2612
2733
|
if (isMcpIntegration(integration)) {
|
|
2613
2734
|
configureMcpClient(integration, opts);
|
|
2614
2735
|
return;
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
// Route Claude Code's own model calls through the PassControl sidecar.
|
|
2
|
+
//
|
|
3
|
+
// Claude Code reads an `env` block from its settings files wherever it is
|
|
4
|
+
// started (verified 2026-10-07, Claude Code 2.1.292): ANTHROPIC_BASE_URL sends
|
|
5
|
+
// its calls to the sidecar, and ANTHROPIC_AUTH_TOKEN, a placeholder, rides as a
|
|
6
|
+
// Bearer token with no "use this API key?" prompt. The sidecar strips it and the
|
|
7
|
+
// gateway injects the real key, so Claude Code never holds one.
|
|
8
|
+
//
|
|
9
|
+
// The settings file belongs to the user. Only these two keys are written or
|
|
10
|
+
// removed, the previous file is backed up, a file that is not a JSON object is
|
|
11
|
+
// refused rather than overwritten, and a different gateway already configured is
|
|
12
|
+
// not replaced without --force.
|
|
13
|
+
import fs from "node:fs";
|
|
14
|
+
import os from "node:os";
|
|
15
|
+
import path from "node:path";
|
|
16
|
+
|
|
17
|
+
/** Not a secret: the sidecar discards whatever arrives in this header. */
|
|
18
|
+
export const CLAUDE_CODE_AUTH_PLACEHOLDER = "passcontrol-sidecar";
|
|
19
|
+
|
|
20
|
+
export function claudeCodeEnv(baseUrl) {
|
|
21
|
+
return { ANTHROPIC_BASE_URL: baseUrl, ANTHROPIC_AUTH_TOKEN: CLAUDE_CODE_AUTH_PLACEHOLDER };
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* `project`: this directory's `.claude/settings.local.json`, the file Claude Code
|
|
26
|
+
* keeps out of git. `user`: every Claude Code session, under CLAUDE_CONFIG_DIR
|
|
27
|
+
* when set, as Claude Code itself resolves it.
|
|
28
|
+
*/
|
|
29
|
+
export function claudeCodeSettingsPath({ scope, cwd = process.cwd(), env = process.env }) {
|
|
30
|
+
if (scope === "user") {
|
|
31
|
+
const dir = env.CLAUDE_CONFIG_DIR || path.join(env.HOME || os.homedir(), ".claude");
|
|
32
|
+
return path.join(dir, "settings.json");
|
|
33
|
+
}
|
|
34
|
+
return path.join(cwd, ".claude", "settings.local.json");
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function readSettings(target) {
|
|
38
|
+
if (!fs.existsSync(target)) return { exists: false, value: {} };
|
|
39
|
+
const text = fs.readFileSync(target, "utf8");
|
|
40
|
+
if (!text.trim()) return { exists: true, value: {} };
|
|
41
|
+
let value;
|
|
42
|
+
try {
|
|
43
|
+
value = JSON.parse(text);
|
|
44
|
+
} catch {
|
|
45
|
+
throw new Error(`${target} is not valid JSON; fix or move it, then run this again. Nothing was written.`);
|
|
46
|
+
}
|
|
47
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
48
|
+
throw new Error(`${target} is not a JSON object; nothing was written.`);
|
|
49
|
+
}
|
|
50
|
+
return { exists: true, value };
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function save(target, value, exists) {
|
|
54
|
+
fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
|
|
55
|
+
let backupPath = null;
|
|
56
|
+
if (exists) {
|
|
57
|
+
backupPath = `${target}.bak`;
|
|
58
|
+
fs.copyFileSync(target, backupPath);
|
|
59
|
+
fs.chmodSync(backupPath, 0o600);
|
|
60
|
+
}
|
|
61
|
+
fs.writeFileSync(target, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
|
|
62
|
+
fs.chmodSync(target, 0o600);
|
|
63
|
+
return backupPath;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export function writeClaudeCodeSettings({ target, baseUrl, force = false }) {
|
|
67
|
+
const { exists, value } = readSettings(target);
|
|
68
|
+
const env = typeof value.env === "object" && value.env !== null && !Array.isArray(value.env) ? value.env : {};
|
|
69
|
+
const rawKeyFound = typeof env.ANTHROPIC_API_KEY === "string" && env.ANTHROPIC_API_KEY.length > 0;
|
|
70
|
+
const current = env.ANTHROPIC_BASE_URL;
|
|
71
|
+
if (current === baseUrl && env.ANTHROPIC_AUTH_TOKEN === CLAUDE_CODE_AUTH_PLACEHOLDER) {
|
|
72
|
+
return { changed: false, backupPath: null, rawKeyFound };
|
|
73
|
+
}
|
|
74
|
+
if (typeof current === "string" && current && current !== baseUrl && !force) {
|
|
75
|
+
throw new Error(
|
|
76
|
+
`${target} already points Claude Code at ${current}. Re-run with --force to replace that address with PassControl's.`
|
|
77
|
+
);
|
|
78
|
+
}
|
|
79
|
+
const backupPath = save(target, { ...value, env: { ...env, ...claudeCodeEnv(baseUrl) } }, exists);
|
|
80
|
+
return { changed: true, backupPath, rawKeyFound };
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
export function removeClaudeCodeSettings({ target }) {
|
|
84
|
+
if (!fs.existsSync(target)) return { changed: false };
|
|
85
|
+
const { value } = readSettings(target);
|
|
86
|
+
const env = typeof value.env === "object" && value.env !== null && !Array.isArray(value.env) ? value.env : null;
|
|
87
|
+
// Only an address this command could have written: a gateway someone else set
|
|
88
|
+
// up is not ours to remove.
|
|
89
|
+
if (!env || env.ANTHROPIC_AUTH_TOKEN !== CLAUDE_CODE_AUTH_PLACEHOLDER) return { changed: false };
|
|
90
|
+
const { ANTHROPIC_BASE_URL: _url, ANTHROPIC_AUTH_TOKEN: _token, ...rest } = env;
|
|
91
|
+
const next = { ...value };
|
|
92
|
+
if (Object.keys(rest).length) next.env = rest;
|
|
93
|
+
else delete next.env;
|
|
94
|
+
save(target, next, true);
|
|
95
|
+
return { changed: true };
|
|
96
|
+
}
|
package/cli/codex.mjs
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
// Route Codex's own model calls through the PassControl sidecar.
|
|
2
|
+
//
|
|
3
|
+
// Codex takes a custom model provider only from user-level config: a project's
|
|
4
|
+
// `.codex/config.toml` cannot set one, and the old `profile = "..."` selector is
|
|
5
|
+
// refused (verified 2026-10-07, Codex CLI 0.160.1). So this writes a profile file,
|
|
6
|
+
// `$CODEX_HOME/passcontrol.config.toml`, which Codex layers over config.toml when
|
|
7
|
+
// started with `codex --profile passcontrol`. With no key configured for the
|
|
8
|
+
// provider, Codex sends no Authorization header at all (captured); the sidecar
|
|
9
|
+
// adds the agent's credential and the gateway injects the real OpenAI key.
|
|
10
|
+
//
|
|
11
|
+
// config.toml is never opened: the Codex app shares it, and PassControl would
|
|
12
|
+
// need a TOML parser to edit it safely. The profile file is PassControl's own,
|
|
13
|
+
// marked on its first line, so a file at that path without the marker is someone
|
|
14
|
+
// else's and is not replaced without --force, nor ever removed.
|
|
15
|
+
import fs from "node:fs";
|
|
16
|
+
import os from "node:os";
|
|
17
|
+
import path from "node:path";
|
|
18
|
+
|
|
19
|
+
export const CODEX_PROFILE = "passcontrol";
|
|
20
|
+
export const CODEX_PROFILE_MARKER = "# Written by `passcontrol configure codex`.";
|
|
21
|
+
|
|
22
|
+
function codexHome(env) {
|
|
23
|
+
return env.CODEX_HOME || path.join(env.HOME || os.homedir(), ".codex");
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export function codexProfilePath({ env = process.env } = {}) {
|
|
27
|
+
return path.join(codexHome(env), `${CODEX_PROFILE}.config.toml`);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Whether Codex keeps an OpenAI API key of its own (`codex login --api-key`, in
|
|
32
|
+
* auth.json). The profile never sends it, but plain `codex` does. True or false
|
|
33
|
+
* only: the value is never returned, and an unreadable file counts as no key.
|
|
34
|
+
*/
|
|
35
|
+
export function codexStoresApiKey({ env = process.env } = {}) {
|
|
36
|
+
try {
|
|
37
|
+
const auth = JSON.parse(fs.readFileSync(path.join(codexHome(env), "auth.json"), "utf8"));
|
|
38
|
+
return typeof auth?.OPENAI_API_KEY === "string" && auth.OPENAI_API_KEY.length > 0;
|
|
39
|
+
} catch {
|
|
40
|
+
return false;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
// A TOML basic string. JSON's escapes (\" \\ \n \uXXXX …) are all valid TOML
|
|
45
|
+
// escapes, so a value cannot close its string and start a key of its own.
|
|
46
|
+
const tomlString = (value) => JSON.stringify(String(value));
|
|
47
|
+
|
|
48
|
+
export function codexProfileToml({ baseUrl, model }) {
|
|
49
|
+
let url;
|
|
50
|
+
try {
|
|
51
|
+
url = new URL(baseUrl);
|
|
52
|
+
} catch {
|
|
53
|
+
url = null;
|
|
54
|
+
}
|
|
55
|
+
if (!url || (url.protocol !== "http:" && url.protocol !== "https:")) {
|
|
56
|
+
throw new Error(`The sidecar address must be an http(s) URL, not ${JSON.stringify(String(baseUrl))}.`);
|
|
57
|
+
}
|
|
58
|
+
return [
|
|
59
|
+
CODEX_PROFILE_MARKER,
|
|
60
|
+
`# Use it with: codex --profile ${CODEX_PROFILE}`,
|
|
61
|
+
"# Codex's model calls go to the PassControl sidecar, which must be running. No OpenAI",
|
|
62
|
+
"# key belongs here: the gateway adds the real one. Undo: passcontrol configure codex --remove",
|
|
63
|
+
...(model ? [`model = ${tomlString(model)}`] : []),
|
|
64
|
+
`model_provider = ${tomlString(CODEX_PROFILE)}`,
|
|
65
|
+
"",
|
|
66
|
+
`[model_providers.${CODEX_PROFILE}]`,
|
|
67
|
+
'name = "PassControl"',
|
|
68
|
+
`base_url = ${tomlString(baseUrl)}`,
|
|
69
|
+
'wire_api = "responses"',
|
|
70
|
+
"",
|
|
71
|
+
].join("\n");
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
const isOurs = (text) => text.startsWith(CODEX_PROFILE_MARKER);
|
|
75
|
+
|
|
76
|
+
export function writeCodexProfile({ target, baseUrl, model, force = false }) {
|
|
77
|
+
const next = codexProfileToml({ baseUrl, model });
|
|
78
|
+
const exists = fs.existsSync(target);
|
|
79
|
+
let backupPath = null;
|
|
80
|
+
if (exists) {
|
|
81
|
+
const current = fs.readFileSync(target, "utf8");
|
|
82
|
+
if (current === next) return { changed: false, backupPath: null };
|
|
83
|
+
if (!isOurs(current) && !force) {
|
|
84
|
+
throw new Error(
|
|
85
|
+
`${target} exists and was not written by PassControl. Re-run with --force to replace it (a backup is kept).`
|
|
86
|
+
);
|
|
87
|
+
}
|
|
88
|
+
backupPath = `${target}.bak`;
|
|
89
|
+
fs.copyFileSync(target, backupPath);
|
|
90
|
+
fs.chmodSync(backupPath, 0o600);
|
|
91
|
+
}
|
|
92
|
+
fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
|
|
93
|
+
fs.writeFileSync(target, next, { mode: 0o600 });
|
|
94
|
+
fs.chmodSync(target, 0o600);
|
|
95
|
+
return { changed: true, backupPath };
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
export function removeCodexProfile({ target }) {
|
|
99
|
+
if (!fs.existsSync(target) || !isOurs(fs.readFileSync(target, "utf8"))) return { changed: false };
|
|
100
|
+
fs.rmSync(target);
|
|
101
|
+
return { changed: true };
|
|
102
|
+
}
|
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", "local"];
|
|
32
|
-
export const OPENAI_SHAPE_PROVIDERS = new Set(["openai", "groq", "mistral", "together", "deepseek", "gemini", "azure", "local"]);
|
|
31
|
+
export const PROVIDERS = ["openai", "anthropic", "groq", "mistral", "together", "deepseek", "gemini", "xai", "openrouter", "azure", "local"];
|
|
32
|
+
export const OPENAI_SHAPE_PROVIDERS = new Set(["openai", "groq", "mistral", "together", "deepseek", "gemini", "openrouter", "azure", "local"]);
|
|
33
33
|
|
|
34
34
|
const DEFAULT_GATEWAY = "http://localhost:3000";
|
|
35
35
|
|
|
@@ -671,7 +671,7 @@ export function formatProxyError(status, body) {
|
|
|
671
671
|
return `${blocked}\n→ The workspace has no provider key stored for this provider.\n→ Fix: add one under Settings → Provider credentials in the dashboard.`;
|
|
672
672
|
}
|
|
673
673
|
if (status === 400 && error === "server_side_tools_unsupported") {
|
|
674
|
-
return `${blocked}\n→ The request uses a hosted tool
|
|
674
|
+
return `${blocked}\n→ The request uses a hosted tool PassControl does not price, such as image generation or an MCP server.\n→ Fix: remove that tool, or call it outside PassControl. Priced tools such as web search pass.`;
|
|
675
675
|
}
|
|
676
676
|
// 402 is also how the gateway refuses a call it cannot price under a dollar
|
|
677
677
|
// limit; a bigger budget fixes none of those, so each gets its own advice.
|
|
@@ -13,6 +13,9 @@ export const DEFAULT_ALLOWED_MODELS = Object.freeze({
|
|
|
13
13
|
deepseek: "deepseek-*",
|
|
14
14
|
gemini: "gemini-*",
|
|
15
15
|
xai: "grok-*",
|
|
16
|
+
// OpenRouter's free router: it only ever picks a $0 model, so the default grant
|
|
17
|
+
// spends nothing. A paid model is a scope the operator widens on purpose.
|
|
18
|
+
openrouter: "openrouter/free",
|
|
16
19
|
// An Azure `model` is a DEPLOYMENT name the customer chose, not a model id.
|
|
17
20
|
// `gpt-*` covers deployments named after their model and nothing wider: a bare
|
|
18
21
|
// `*` would widen an allowlist to whatever a resource ever deploys. An operator
|
|
@@ -35,6 +38,8 @@ export const DEFAULT_CLIENT_MODELS = Object.freeze({
|
|
|
35
38
|
// The cheapest listed model that does not reason (docs.x.ai/developers/models.md,
|
|
36
39
|
// 2026-09-27): xAI's reasoning models cannot turn reasoning off.
|
|
37
40
|
xai: "grok-4.20-0309-non-reasoning",
|
|
41
|
+
// Stable, where individual `:free` model ids come and go.
|
|
42
|
+
openrouter: "openrouter/free",
|
|
38
43
|
// A deployment name, so only a guess until the operator names theirs.
|
|
39
44
|
azure: "gpt-4.1-mini",
|
|
40
45
|
// Ollama's most-pulled small model. Only a guess: the dashboard offers the
|
package/cli/presets.mjs
CHANGED
|
@@ -98,6 +98,8 @@ export function isServicePreset(name) {
|
|
|
98
98
|
/** Presets that print settings pointing an agent at the local sidecar bridge. */
|
|
99
99
|
export const SIDECAR_PRESETS = [
|
|
100
100
|
"generic",
|
|
101
|
+
// Apps that only take OLLAMA_HOST: the sidecar's Ollama listener (`--ollama-port`).
|
|
102
|
+
"ollama",
|
|
101
103
|
"openhands",
|
|
102
104
|
"litellm",
|
|
103
105
|
"aider",
|
|
@@ -106,19 +108,27 @@ export const SIDECAR_PRESETS = [
|
|
|
106
108
|
...SERVICE_PRESETS,
|
|
107
109
|
];
|
|
108
110
|
|
|
111
|
+
/**
|
|
112
|
+
* Coding agents configured by a file of their own rather than by a base URL and
|
|
113
|
+
* a model: Codex reads a profile (cli/codex.mjs). Kept apart from SIDECAR_PRESETS,
|
|
114
|
+
* whose members take any provider; Codex speaks only OpenAI's Responses API.
|
|
115
|
+
*/
|
|
116
|
+
export const AGENT_CLI_PRESETS = ["codex"];
|
|
117
|
+
|
|
109
118
|
/** MCP client targets. Shares the set the MCP config writer dispatches on. */
|
|
110
119
|
export const MCP_PRESETS = [...MCP_INTEGRATIONS];
|
|
111
120
|
|
|
112
121
|
/** Everything both commands accept. */
|
|
113
|
-
export const INTEGRATIONS = [...SIDECAR_PRESETS, ...MCP_PRESETS];
|
|
122
|
+
export const INTEGRATIONS = [...SIDECAR_PRESETS, ...AGENT_CLI_PRESETS, ...MCP_PRESETS];
|
|
114
123
|
|
|
115
124
|
/**
|
|
116
125
|
* Integrations where `configure --write` actually writes a file. Everything else
|
|
117
|
-
* is UI- or project-schema-specific
|
|
118
|
-
*
|
|
119
|
-
*
|
|
126
|
+
* is UI- or project-schema-specific, so `--write` is refused with the real
|
|
127
|
+
* instruction instead of being accepted and silently doing nothing. claude-code
|
|
128
|
+
* writes Claude Code's settings (cli/claude-code.mjs); its MCP registry stays
|
|
129
|
+
* owned by Claude Code's own CLI. codex writes a Codex profile (cli/codex.mjs).
|
|
120
130
|
*/
|
|
121
|
-
export const WRITABLE_INTEGRATIONS = ["aider", "claude-desktop", "cursor"];
|
|
131
|
+
export const WRITABLE_INTEGRATIONS = ["aider", "claude-desktop", "cursor", "claude-code", "codex"];
|
|
122
132
|
|
|
123
133
|
export function isIntegration(name) {
|
|
124
134
|
return INTEGRATIONS.includes(String(name ?? "").toLowerCase());
|
package/cli/proxy-policy.mjs
CHANGED
|
@@ -43,6 +43,7 @@ export const PROVIDER_UPSTREAMS = {
|
|
|
43
43
|
// permanently ineligible for `--allow-connect`.
|
|
44
44
|
gemini: { hostname: "generativelanguage.googleapis.com", basePath: "/v1beta/openai" },
|
|
45
45
|
xai: { hostname: "api.x.ai", basePath: "" },
|
|
46
|
+
openrouter: { hostname: "openrouter.ai", basePath: "/api" },
|
|
46
47
|
};
|
|
47
48
|
|
|
48
49
|
/**
|
package/cli/sidecar.mjs
CHANGED
|
@@ -192,6 +192,52 @@ export function createSidecar({
|
|
|
192
192
|
}
|
|
193
193
|
});
|
|
194
194
|
|
|
195
|
+
// ── The Ollama listener (1.3.0 #3) ────────────────────────────────────────
|
|
196
|
+
//
|
|
197
|
+
// For apps that only take OLLAMA_HOST, which is host:port with no path. Every
|
|
198
|
+
// request on this port is the gateway's `local` provider: `/api/chat` becomes
|
|
199
|
+
// `/api/v1/local/api/chat`, and the OpenAI-compatible `/v1/...` paths map the
|
|
200
|
+
// same way. Its own port, so the main listener's forward-proxy handling is
|
|
201
|
+
// untouched; an absolute-form request (a proxy request for another host) is
|
|
202
|
+
// refused here rather than becoming a governed local call.
|
|
203
|
+
//
|
|
204
|
+
// The path is normalised by the URL parser BEFORE the prefix is added, so a
|
|
205
|
+
// `..` segment (encoded or not) resolves inside it and cannot carry the visa
|
|
206
|
+
// to another gateway route. The health probe (`/`, which the ollama CLI HEADs)
|
|
207
|
+
// is not answered here: it goes to the gateway as `/api/version`, so an app
|
|
208
|
+
// sees the gateway's real answer, including a refusal where `local` is off.
|
|
209
|
+
const ollamaServer = http.createServer(async (req, res) => {
|
|
210
|
+
if (!String(req.url ?? "").startsWith("/")) {
|
|
211
|
+
req.resume();
|
|
212
|
+
res.writeHead(400, { "content-type": "application/json" });
|
|
213
|
+
res.end(JSON.stringify({ error: "ollama_listener_absolute_form", message: "This port serves Ollama's API for the local provider only; it is not a proxy." }));
|
|
214
|
+
return;
|
|
215
|
+
}
|
|
216
|
+
const url = new URL(req.url, "http://ollama.invalid");
|
|
217
|
+
const probe = url.pathname === "/";
|
|
218
|
+
const mapped = `/api/v1/local${probe ? "/api/version" : url.pathname}${probe ? "" : url.search}`;
|
|
219
|
+
const method = probe ? "GET" : req.method;
|
|
220
|
+
try {
|
|
221
|
+
const body = probe ? null : await readBody(req);
|
|
222
|
+
if (probe) req.resume();
|
|
223
|
+
const upstream = await visas.fetchWithVisa((visa) => fetchUpstream({ method, headers: req.headers }, mapped, body, visa));
|
|
224
|
+
if (req.method === "HEAD") {
|
|
225
|
+
res.writeHead(upstream.status);
|
|
226
|
+
res.end();
|
|
227
|
+
await upstream.body?.cancel().catch(() => {});
|
|
228
|
+
return;
|
|
229
|
+
}
|
|
230
|
+
writeResponse(res, upstream);
|
|
231
|
+
} catch (e) {
|
|
232
|
+
if (!res.headersSent) {
|
|
233
|
+
res.writeHead(502, { "content-type": "application/json" });
|
|
234
|
+
res.end(JSON.stringify({ error: "sidecar_upstream_error", message: e.message }));
|
|
235
|
+
} else {
|
|
236
|
+
res.end();
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
});
|
|
240
|
+
|
|
195
241
|
// `CONNECT host:port` — what every client with HTTPS_PROXY set sends first.
|
|
196
242
|
// PassControl cannot govern what it cannot read, and it deliberately does not
|
|
197
243
|
// terminate TLS to make it readable, so a provider target is refused here
|
|
@@ -234,7 +280,7 @@ export function createSidecar({
|
|
|
234
280
|
clientSocket.on("close", () => upstream.destroy());
|
|
235
281
|
});
|
|
236
282
|
|
|
237
|
-
return { server, getVisa: visas.getVisa };
|
|
283
|
+
return { server, ollamaServer, getVisa: visas.getVisa };
|
|
238
284
|
}
|
|
239
285
|
|
|
240
286
|
/**
|
|
@@ -255,9 +301,14 @@ export function assertBindHost(host, allowNonLoopback = false) {
|
|
|
255
301
|
}
|
|
256
302
|
|
|
257
303
|
export function startSidecar(opts) {
|
|
258
|
-
const { gateway, port = 8788, host = "127.0.0.1", allowNonLoopback = false, allowConnectHosts = [] } = opts;
|
|
304
|
+
const { gateway, port = 8788, host = "127.0.0.1", allowNonLoopback = false, allowConnectHosts = [], ollamaPort = null } = opts;
|
|
259
305
|
assertBindHost(host, allowNonLoopback);
|
|
260
|
-
const { server, getVisa } = createSidecar(opts);
|
|
306
|
+
const { server, ollamaServer, getVisa } = createSidecar(opts);
|
|
307
|
+
if (ollamaPort != null) {
|
|
308
|
+
ollamaServer.listen(ollamaPort, host, () => {
|
|
309
|
+
step(`Ollama API (local models) on http://${host}:${ollamaPort}: set OLLAMA_HOST=${host}:${ollamaPort}`);
|
|
310
|
+
});
|
|
311
|
+
}
|
|
261
312
|
server.listen(port, host, () => {
|
|
262
313
|
step(`PassControl visa sidecar forwarding to ${gateway}`);
|
|
263
314
|
step(`Listening on http://${host}:${port}`);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "passcontrol",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.0",
|
|
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",
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
"./package.json": "./package.json"
|
|
42
42
|
},
|
|
43
43
|
"dependencies": {
|
|
44
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
44
|
+
"@modelcontextprotocol/sdk": "^1.32.1",
|
|
45
45
|
"@noble/curves": "^1.6.0",
|
|
46
46
|
"@noble/hashes": "^1.5.0",
|
|
47
47
|
"jose": "^5.9.3",
|
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`, `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
|
|
161
|
+
`gemini`, `xai`, `openrouter`, `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
|
package/sdk/passcontrol.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type ProviderId = "openai" | "anthropic" | "groq" | "mistral" | "together" | "deepseek" | "gemini" | "xai" | "azure" | "local";
|
|
1
|
+
export type ProviderId = "openai" | "anthropic" | "groq" | "mistral" | "together" | "deepseek" | "gemini" | "xai" | "openrouter" | "azure" | "local";
|
|
2
2
|
export interface PassControlOptions {
|
|
3
3
|
/**
|
|
4
4
|
* Gateway origin, e.g. https://passcontrol.example.com — scheme, host and
|