passcontrol 0.5.3 → 0.6.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/cli/config.mjs CHANGED
@@ -134,16 +134,44 @@ export function loadConfigSources({ cwd = process.cwd(), env = process.env } = {
134
134
  return sources;
135
135
  }
136
136
 
137
+ /**
138
+ * Keys that arrived from a `.passcontrol` FILE rather than the operator's shell.
139
+ *
140
+ * A config file is checked in and travels with a repository, so for anything
141
+ * security-relevant "the environment says so" and "the operator said so" are not
142
+ * the same statement. Recorded at injection time rather than derived afterwards:
143
+ * a key present in BOTH the shell and a file keeps its shell value below, and
144
+ * that value is the operator's — so asking the file later would wrongly disown it.
145
+ */
146
+ export const configInjectedKeys = new Set();
147
+
137
148
  export function applyConfigSourcesToEnv({ cwd = process.cwd(), env = process.env } = {}) {
138
149
  const sources = loadConfigSources({ cwd, env });
139
150
  const merged = {};
140
151
  for (const source of sources) Object.assign(merged, source.values);
141
152
  for (const [key, value] of Object.entries(merged)) {
142
- if (env[key] === undefined) env[key] = value;
153
+ if (env[key] === undefined) {
154
+ env[key] = value;
155
+ configInjectedKeys.add(key);
156
+ }
143
157
  }
144
158
  return sources;
145
159
  }
146
160
 
161
+ /**
162
+ * Read an environment variable ONLY if the operator set it.
163
+ *
164
+ * For an egress or credential control, a value a cloned repository's
165
+ * `.passcontrol` dropped into the environment must not stand in for a decision
166
+ * the operator made. Everything else — `MODEL`, `SIDECAR_PORT`, `PROMPT` — is
167
+ * still perfectly good to configure from a file and goes on reading `process.env`
168
+ * directly; this is deliberately opt-in per key rather than a blanket filter,
169
+ * because narrowing what a config file may set would break ordinary use.
170
+ */
171
+ export function operatorEnv(key, { env = process.env, injected = configInjectedKeys } = {}) {
172
+ return injected.has(key) ? undefined : env[key];
173
+ }
174
+
147
175
  export let configLoadError = null;
148
176
  export let configSources = [];
149
177
 
@@ -253,6 +281,101 @@ export function requireControlApiKey(current = config) {
253
281
  return current.apiKey;
254
282
  }
255
283
 
284
+ /**
285
+ * The only hosts allowed to speak plain HTTP. Exact matches, never a prefix or
286
+ * suffix: `localhost.`, `localhost.example` and `127.0.0.1.attacker.example` are
287
+ * other people's hostnames. Compared against the parsed `hostname`, which the URL
288
+ * parser has already lowercased and canonicalised (`127.1` → `127.0.0.1`), so
289
+ * shorthand loopback spellings land here instead of slipping past a string test.
290
+ */
291
+ const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
292
+
293
+ /**
294
+ * Validate a gateway value and return the origin to build URLs from.
295
+ *
296
+ * A bare HTTPS origin — scheme, host, optional port — with no path beyond `/`,
297
+ * no query, fragment, username or password. HTTP only on loopback. The value is
298
+ * parsed and the result re-derived from `URL.origin`, so no path material
299
+ * survives into a request URL and `https://trusted.example@attacker.example`
300
+ * cannot pose as the host it imitates.
301
+ *
302
+ * **This is deliberately the same rule as `sdk/gateway.ts`'s
303
+ * `requireGatewayOrigin`, and deliberately a second implementation of it.** The
304
+ * SDK is TypeScript that only becomes JavaScript after `tsc`; `cli/` is plain
305
+ * .mjs run straight from the repository, so importing across that line works in
306
+ * the published package and breaks every CLI invocation in a checkout. The two
307
+ * are held in agreement by `tests/cli-control-gateway.test.ts`, which runs one
308
+ * table through both — if you change one, that test fails until you change both.
309
+ *
310
+ * Throws rather than `die`s: `bin/passcontrol.mjs` has a top-level handler that
311
+ * prints the message and exits 1, and `doctor` catches it to report a failed
312
+ * check instead of vanishing mid-diagnosis. The message never quotes the value,
313
+ * because a rejected gateway can itself carry credentials.
314
+ */
315
+ export function bareGatewayOrigin(gateway, label = "PASSCONTROL_GATEWAY") {
316
+ let url;
317
+ try {
318
+ url = new URL(String(gateway ?? ""));
319
+ } catch {
320
+ throw new Error(
321
+ `${label} must be an absolute URL (for example https://passcontrol.example.com).`
322
+ );
323
+ }
324
+ const loopback = LOOPBACK_HOSTNAMES.has(url.hostname);
325
+ if (
326
+ (url.protocol !== "https:" && !(loopback && url.protocol === "http:")) ||
327
+ url.username ||
328
+ url.password ||
329
+ url.search ||
330
+ url.hash ||
331
+ url.pathname !== "/"
332
+ ) {
333
+ throw new Error(
334
+ `${label} must be a bare HTTPS origin — scheme, host and optional port, with no path, ` +
335
+ "query, fragment or embedded credentials. Plain HTTP is accepted only for localhost, " +
336
+ "127.0.0.1 and [::1]. The configured value is refused and is not printed here, because " +
337
+ "a gateway URL can itself contain a credential."
338
+ );
339
+ }
340
+ return url.origin;
341
+ }
342
+
343
+ /**
344
+ * The gateway guard for the control plane, beside the key guard above.
345
+ *
346
+ * A `pc_` key is long-lived and manages the whole fleet, so where it is sent is
347
+ * part of the credential's security, not configuration taste. Every `api()` call
348
+ * resolves its destination through this, never through the raw config string.
349
+ */
350
+ export function requireControlGateway(current = config) {
351
+ assertConfigLoaded();
352
+ return bareGatewayOrigin(current.gateway);
353
+ }
354
+
355
+ /**
356
+ * The same guard for the passport paths — `call`, `try`, `doctor --deep`,
357
+ * `sidecar`, `mcp`.
358
+ *
359
+ * It exists as its own name because the two credentials fail differently, not
360
+ * because the rule differs: it is `bareGatewayOrigin` in both cases, so the two
361
+ * cannot drift. A `pc_` key is long-lived and manages the fleet; what travels
362
+ * here is an Ed25519 challenge signature and the short-lived visa minted from
363
+ * it. That signature is the passport proving itself, and
364
+ * `app/api/auth/challenge/route.ts` binds it to no audience — so a copy taken
365
+ * off the wire replays against the REAL gateway for as long as its `SKEW_MS`
366
+ * window allows, and mints a genuine visa carrying the agent's scope and budget.
367
+ *
368
+ * Which is why this must be called BEFORE the credentials are read, before the
369
+ * signature is computed, and before the destination is echoed to the terminal.
370
+ * Every caller resolves its URLs from the returned origin, never from
371
+ * `config.gateway`; `tests/cli-passport-gateway.test.ts` pins both the ordering
372
+ * and the absence of raw-string interpolation.
373
+ */
374
+ export function requirePassportGateway(current = config) {
375
+ assertConfigLoaded();
376
+ return bareGatewayOrigin(current.gateway);
377
+ }
378
+
256
379
  export function redact(value, keep = 4) {
257
380
  if (!value) return "missing";
258
381
  const s = String(value);
@@ -1,11 +1,9 @@
1
1
  import { decodeJwt } from "jose";
2
- import { OPENAI_SHAPE_PROVIDERS, formatProxyError } from "../config.mjs";
2
+ import { OPENAI_SHAPE_PROVIDERS, bareGatewayOrigin, formatProxyError } from "../config.mjs";
3
3
  import { createVisaClient } from "../visa-client.mjs";
4
4
 
5
5
  const DEFAULT_ANTHROPIC_MAX_TOKENS = 1024;
6
6
 
7
- const trimSlash = (value) => String(value ?? "").replace(/\/+$/, "");
8
-
9
7
  function requestFor({ provider, model, messages, max_tokens, temperature }) {
10
8
  if (provider === "anthropic") {
11
9
  const system = messages
@@ -110,7 +108,9 @@ export function createGatewayClient({
110
108
  randomUUID = () => globalThis.crypto.randomUUID(),
111
109
  refreshSkewSeconds = 30,
112
110
  }) {
113
- const baseUrl = trimSlash(gateway);
111
+ // `trimSlash` tidied a string; it never judged the destination. Every proxied
112
+ // call below carries a bearer visa, so the base is the validated origin.
113
+ const baseUrl = bareGatewayOrigin(gateway);
114
114
  const visas = createVisaClient({
115
115
  gateway: baseUrl,
116
116
  passportId,
package/cli/presets.mjs CHANGED
@@ -36,6 +36,7 @@ export const SIDECAR_PRESETS = [
36
36
  "openhands",
37
37
  "litellm",
38
38
  "aider",
39
+ "hermes",
39
40
  ...Object.keys(GUI_PRESET_LABELS),
40
41
  ];
41
42
 
@@ -0,0 +1,276 @@
1
+ // Destination policy for the sidecar's forward-proxy front door.
2
+ //
3
+ // Everything else in the sidecar routes to a destination WE configured. This
4
+ // module is the one place that judges a destination the CLIENT chose, which is
5
+ // what `HTTPS_PROXY=http://127.0.0.1:8788` turns every agent request into. Two
6
+ // failures are possible and both are bad:
7
+ //
8
+ // * tunnel a provider host → an ungoverned provider call carried by the
9
+ // component whose entire job is governing it, with the operator believing
10
+ // scope and budget applied;
11
+ // * tunnel anything asked → an open proxy on a developer laptop.
12
+ //
13
+ // So the rule is deny-by-default with two narrow exits: the gateway we already
14
+ // send visas to, and hosts the operator named on the command line.
15
+ //
16
+ // Why a provider CONNECT is refused rather than governed: injecting the key
17
+ // would mean terminating the TLS, which means a locally trusted CA that can
18
+ // impersonate any host to any process trusting it. PassControl exists to get a
19
+ // secret with a one-provider blast radius off the agent's machine; installing a
20
+ // broader one to save an environment variable is the wrong trade, and every
21
+ // mainstream provider SDK already honours a base-URL variable that needs no CA.
22
+
23
+ /**
24
+ * The provider upstreams, as host + base path.
25
+ *
26
+ * A second copy of `lib/providers.ts`'s `upstreamBaseUrl`, for the same reason
27
+ * `bareGatewayOrigin` exists twice: `cli/` is plain .mjs run straight from the
28
+ * checkout and published as-is, so it cannot import TypeScript that only exists
29
+ * after `tsc`. `tests/cli-provider-hosts.test.ts` runs both through one table and
30
+ * fails the moment they disagree — a provider added there and missed here is a
31
+ * provider this file would let through.
32
+ */
33
+ export const PROVIDER_UPSTREAMS = {
34
+ openai: { hostname: "api.openai.com", basePath: "" },
35
+ anthropic: { hostname: "api.anthropic.com", basePath: "" },
36
+ groq: { hostname: "api.groq.com", basePath: "/openai" },
37
+ mistral: { hostname: "api.mistral.ai", basePath: "" },
38
+ together: { hostname: "api.together.ai", basePath: "" },
39
+ deepseek: { hostname: "api.deepseek.com", basePath: "" },
40
+ };
41
+
42
+ const HOST_BY_NAME = new Map(
43
+ Object.entries(PROVIDER_UPSTREAMS).map(([provider, entry]) => [entry.hostname, { provider, ...entry }])
44
+ );
45
+
46
+ // A hostname carrying any of these is not a hostname. Checked rather than
47
+ // assumed because the value arrives on a request line from whatever the client
48
+ // felt like sending.
49
+ const NOT_IN_A_HOSTNAME = /[\s/\\@?#]/;
50
+
51
+ /**
52
+ * Lower-case, unbracket, and drop the fully-qualified trailing dot.
53
+ *
54
+ * `api.anthropic.com.` resolves to exactly the same address as
55
+ * `api.anthropic.com`, so a string comparison that treats them as different
56
+ * hosts is a one-character bypass of the provider refusal below.
57
+ */
58
+ function normalizeHostname(value) {
59
+ let host = String(value ?? "").trim().toLowerCase();
60
+ if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
61
+ if (host.endsWith(".")) host = host.slice(0, -1);
62
+ return host;
63
+ }
64
+
65
+ /** Exact match only — `evil-api.anthropic.com` is somebody else's hostname. */
66
+ export function providerForHost(hostname) {
67
+ return HOST_BY_NAME.get(normalizeHostname(hostname)) ?? null;
68
+ }
69
+
70
+ function parsePort(value) {
71
+ if (!/^\d{1,5}$/.test(String(value))) return null;
72
+ const port = Number(value);
73
+ return port >= 1 && port <= 65535 ? port : null;
74
+ }
75
+
76
+ /**
77
+ * Split a CONNECT authority-form target (`host:port`) as RFC 9110 defines it.
78
+ *
79
+ * The port is mandatory: a bare host is not a valid CONNECT target, and guessing
80
+ * 443 for it would mean inventing a destination the client never named.
81
+ */
82
+ export function parseConnectTarget(raw) {
83
+ const value = String(raw ?? "").trim();
84
+ if (!value) return null;
85
+
86
+ let hostPart;
87
+ let portPart;
88
+ if (value.startsWith("[")) {
89
+ const close = value.indexOf("]");
90
+ if (close === -1 || value[close + 1] !== ":") return null;
91
+ hostPart = value.slice(0, close + 1);
92
+ portPart = value.slice(close + 2);
93
+ } else {
94
+ const colon = value.indexOf(":");
95
+ // Exactly one colon outside brackets. `a:1:2` is malformed, not an address.
96
+ if (colon === -1 || value.indexOf(":", colon + 1) !== -1) return null;
97
+ hostPart = value.slice(0, colon);
98
+ portPart = value.slice(colon + 1);
99
+ }
100
+
101
+ const hostname = normalizeHostname(hostPart);
102
+ const port = parsePort(portPart);
103
+ if (!hostname || port === null || NOT_IN_A_HOSTNAME.test(hostname)) return null;
104
+ return { hostname, port };
105
+ }
106
+
107
+ /** The gateway's own host and effective port, which CONNECT is allowed to reach. */
108
+ function gatewayTarget(gatewayOrigin) {
109
+ let url;
110
+ try {
111
+ url = new URL(String(gatewayOrigin ?? ""));
112
+ } catch {
113
+ return null;
114
+ }
115
+ const port = url.port ? parsePort(url.port) : url.protocol === "https:" ? 443 : 80;
116
+ if (port === null) return null;
117
+ return { hostname: normalizeHostname(url.hostname), port };
118
+ }
119
+
120
+ /** `host` (any port) or `host:port` (that port only). */
121
+ function parseAllowEntry(entry) {
122
+ const value = String(entry ?? "").trim();
123
+ if (!value) return null;
124
+ const withPort = parseConnectTarget(value);
125
+ if (withPort) return withPort;
126
+
127
+ const hostname = normalizeHostname(value);
128
+ if (!hostname || NOT_IN_A_HOSTNAME.test(hostname) || hostname.includes(":")) return null;
129
+ return { hostname, port: null };
130
+ }
131
+
132
+ export function parseAllowHosts(entries) {
133
+ const list = Array.isArray(entries)
134
+ ? entries
135
+ : String(entries ?? "")
136
+ .split(",")
137
+ .filter(Boolean);
138
+ return list.map(parseAllowEntry).filter(Boolean);
139
+ }
140
+
141
+ function refuse(status, code, message, help) {
142
+ return { allow: false, status, code, message, help };
143
+ }
144
+
145
+ function governedPathHelp(provider, localBaseUrl) {
146
+ const base = localBaseUrl ? String(localBaseUrl).replace(/\/+$/, "") : "";
147
+ return `${base}/api/v1/${provider}`;
148
+ }
149
+
150
+ /**
151
+ * Decide what to do with `CONNECT host:port`.
152
+ *
153
+ * Order matters: the provider check runs FIRST, before the operator allowlist.
154
+ * An allowlist that could name a provider would stop being an egress control and
155
+ * become an off-switch for governance.
156
+ */
157
+ export function classifyConnect({ target, gatewayOrigin, allowHosts = [], localBaseUrl = "" } = {}) {
158
+ const parsed = parseConnectTarget(target);
159
+ if (!parsed) {
160
+ return refuse(
161
+ 400,
162
+ "bad_connect_target",
163
+ "CONNECT needs an authority-form target, for example api.example.com:443.",
164
+ "Check the proxy setting; PassControl received a target it could not parse."
165
+ );
166
+ }
167
+
168
+ const provider = providerForHost(parsed.hostname);
169
+ if (provider) {
170
+ return refuse(
171
+ 403,
172
+ "provider_tunnel_not_governed",
173
+ `PassControl will not tunnel TLS to ${parsed.hostname}. It cannot see inside that connection, so it could ` +
174
+ "neither inject the provider key nor apply scope, budget or the kill switch — the call would leave " +
175
+ "ungoverned while appearing to be governed.",
176
+ `Point the client's base URL at ${governedPathHelp(provider.provider, localBaseUrl)} instead. ` +
177
+ "PassControl does not install a TLS-intercepting CA."
178
+ );
179
+ }
180
+
181
+ const gateway = gatewayTarget(gatewayOrigin);
182
+ if (gateway && parsed.hostname === gateway.hostname && parsed.port === gateway.port) {
183
+ return { allow: true, ...parsed, reason: "gateway" };
184
+ }
185
+
186
+ const allowed = parseAllowHosts(allowHosts).some(
187
+ (entry) => entry.hostname === parsed.hostname && (entry.port === null || entry.port === parsed.port)
188
+ );
189
+ if (allowed) return { allow: true, ...parsed, reason: "allowlist" };
190
+
191
+ return refuse(
192
+ 403,
193
+ "host_not_allowed",
194
+ `PassControl is not an open proxy and will not tunnel to ${parsed.hostname}.`,
195
+ `Allow it explicitly with \`passcontrol sidecar --allow-connect ${parsed.hostname}\` if the agent needs it.`
196
+ );
197
+ }
198
+
199
+ /**
200
+ * Decide what to do with a request line.
201
+ *
202
+ * Origin-form (`/api/v1/…`) is the sidecar's original mode and passes through.
203
+ * Absolute-form (`http://api.anthropic.com/v1/messages`) is what a proxy client
204
+ * sends for a plain-HTTP URL; it used to be concatenated onto the gateway origin
205
+ * verbatim, producing `https://gateway/http://api.anthropic.com/v1/messages`.
206
+ */
207
+ export function classifyProxyRequest({ url, gatewayOrigin, localBaseUrl = "" } = {}) {
208
+ const target = String(url ?? "");
209
+ if (target.startsWith("/")) return { allow: true, path: target, reason: "origin-form" };
210
+
211
+ if (!/^https?:\/\//i.test(target)) {
212
+ return refuse(
213
+ 400,
214
+ "bad_request_target",
215
+ "PassControl received a request target that is neither a path nor an absolute URL.",
216
+ "Point the client at the sidecar's base URL, or set HTTP_PROXY/HTTPS_PROXY to it."
217
+ );
218
+ }
219
+
220
+ let parsed;
221
+ try {
222
+ parsed = new URL(target);
223
+ } catch {
224
+ return refuse(400, "bad_request_target", "PassControl could not parse that request target.", "Check the client's base URL.");
225
+ }
226
+ // Never echoed anywhere below, and refused outright: a URL carrying userinfo
227
+ // is a credential in a request line, and the same rule already governs
228
+ // PASSCONTROL_GATEWAY in `bareGatewayOrigin`.
229
+ if (parsed.username || parsed.password) {
230
+ return refuse(
231
+ 400,
232
+ "bad_request_target",
233
+ "PassControl refuses a request target with embedded credentials.",
234
+ "Remove the user:password@ prefix from the client's base URL."
235
+ );
236
+ }
237
+
238
+ const hostname = normalizeHostname(parsed.hostname);
239
+ const provider = providerForHost(hostname);
240
+ if (provider) {
241
+ // The gateway re-adds the provider's base path from `upstreamBaseUrl`, so
242
+ // forwarding groq's `/openai` prefix as well would double it.
243
+ let rest = parsed.pathname;
244
+ if (provider.basePath && (rest === provider.basePath || rest.startsWith(`${provider.basePath}/`))) {
245
+ rest = rest.slice(provider.basePath.length);
246
+ }
247
+ if (!rest.startsWith("/")) rest = `/${rest}`;
248
+ return { allow: true, path: `/api/v1/${provider.provider}${rest}${parsed.search}`, reason: "provider" };
249
+ }
250
+
251
+ const gateway = gatewayTarget(gatewayOrigin);
252
+ const port = parsed.port ? parsePort(parsed.port) : parsed.protocol === "https:" ? 443 : 80;
253
+ if (gateway && hostname === gateway.hostname && port === gateway.port) {
254
+ return { allow: true, path: `${parsed.pathname}${parsed.search}`, reason: "gateway" };
255
+ }
256
+
257
+ return refuse(
258
+ 403,
259
+ "host_not_allowed",
260
+ `PassControl is not an open proxy and will not forward to ${hostname}.`,
261
+ "Only the configured gateway and the supported providers are routed."
262
+ );
263
+ }
264
+
265
+ /**
266
+ * Loopback bind addresses.
267
+ *
268
+ * The sidecar holds the passport and mints visas on demand, so a listener
269
+ * reachable off-host is a credential-issuing endpoint for anyone who can route
270
+ * to it. `127.0.0.0/8` in full, because `127.0.0.2` is as loopback as `127.0.0.1`.
271
+ */
272
+ export function isLoopbackBindHost(host) {
273
+ const value = normalizeHostname(host);
274
+ if (!value) return false;
275
+ return value === "localhost" || value === "::1" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(value);
276
+ }