passcontrol 1.4.0 → 1.5.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/LICENSE +3 -1
- package/README.md +10 -1
- package/bin/passcontrol.mjs +266 -8
- package/cli/budget-format.mjs +37 -0
- package/cli/claude-code.mjs +179 -0
- package/cli/client-events-upload.mjs +212 -0
- package/cli/config.mjs +35 -1
- package/cli/declared-session.mjs +32 -4
- package/cli/delegation.d.mts +60 -0
- package/cli/delegation.mjs +192 -0
- package/cli/menu.mjs +4 -0
- package/cli/otlp-logs.mjs +96 -0
- package/cli/profiles.mjs +92 -0
- package/cli/protocols.mjs +3 -1
- package/cli/sidecar.mjs +441 -21
- package/cli/statusline.mjs +223 -1
- package/cli/subscription-gate.mjs +213 -0
- package/cli/tool-gate.mjs +152 -0
- package/cli/tool-rules.d.mts +28 -0
- package/cli/tool-rules.mjs +206 -0
- package/cli/usage-window.mjs +66 -0
- package/cli/visa-client.mjs +5 -1
- package/cli/watch-feed.mjs +345 -0
- package/cli/watch.mjs +640 -0
- package/package.json +1 -1
- package/sdk/index.d.ts +2 -1
- package/sdk/index.js +3 -0
- package/sdk/passcontrol.d.ts +46 -0
- package/sdk/passcontrol.js +47 -2
- package/sdk/verify.d.ts +7 -0
package/cli/sidecar.mjs
CHANGED
|
@@ -5,8 +5,14 @@ import { Readable } from "node:stream";
|
|
|
5
5
|
import { bareGatewayOrigin, fail, ok, step, warn } from "./config.mjs";
|
|
6
6
|
import { classifyConnect, classifyProxyRequest, isLoopbackBindHost } from "./proxy-policy.mjs";
|
|
7
7
|
import { createVisaClient } from "./visa-client.mjs";
|
|
8
|
-
import { declaredSession } from "./declared-session.mjs";
|
|
8
|
+
import { declaredLineage, declaredSession } from "./declared-session.mjs";
|
|
9
9
|
import { defaultJournalDir, openJournal } from "./journal.mjs";
|
|
10
|
+
import { answer, createWatchFeed, isNotACall, isLocalCaller, LOCAL_PREFIX, peekText, providerOf, refusalCode, requestModel } from "./watch-feed.mjs";
|
|
11
|
+
import { createStopGate, HOOK_PATH, selfAnswerState } from "./subscription-gate.mjs";
|
|
12
|
+
import { createToolGate } from "./tool-gate.mjs";
|
|
13
|
+
import { OTLP_LOGS_PATH, readClaudeCodeEvents } from "./otlp-logs.mjs";
|
|
14
|
+
import { CLIENT_EVENTS_PATH, CLIENT_EVENTS_SOURCE, createCallUploader } from "./client-events-upload.mjs";
|
|
15
|
+
import { heldUsageWindow, WINDOW_PATH } from "./usage-window.mjs";
|
|
10
16
|
|
|
11
17
|
// Hop-by-hop headers plus the ones the sidecar rebuilds itself. `proxy-connection`
|
|
12
18
|
// and friends only appear once something is used as a FORWARD proxy, which is
|
|
@@ -45,6 +51,24 @@ function isStripped(name) {
|
|
|
45
51
|
const STRIP_RES = new Set(["content-encoding", "content-length", "transfer-encoding", "connection"]);
|
|
46
52
|
|
|
47
53
|
const STATUS_TEXT = { 400: "Bad Request", 403: "Forbidden", 502: "Bad Gateway" };
|
|
54
|
+
// An OTLP log export batches every event of a few seconds; Claude Code's run ~30 KB.
|
|
55
|
+
const OTLP_BODY_LIMIT = 4 * 1024 * 1024;
|
|
56
|
+
// Sessions whose calls this sidecar relays, remembered so their telemetry is not
|
|
57
|
+
// counted a second time. Bounded: the oldest is forgotten first.
|
|
58
|
+
const RELAYED_SESSIONS_MAX = 1000;
|
|
59
|
+
|
|
60
|
+
// Claude Code's hook input carries the tool's input (a whole file for Write), so it
|
|
61
|
+
// is not small; past this it is refused rather than buffered.
|
|
62
|
+
const HOOK_BODY_LIMIT = 1024 * 1024;
|
|
63
|
+
|
|
64
|
+
// How long Claude Code waits for the hook, as configure wrote it into the URL
|
|
65
|
+
// (`?t=600`); null for a hook that does not say (a Phase 1 install).
|
|
66
|
+
function hookTimeoutS(url) {
|
|
67
|
+
const t = new URL(url ?? "/", "http://127.0.0.1").searchParams.get("t");
|
|
68
|
+
return t !== null && /^\d{1,4}$/.test(t) && Number(t) > 0 ? Number(t) : null;
|
|
69
|
+
}
|
|
70
|
+
// A usage window is two numbers and two times.
|
|
71
|
+
const WINDOW_BODY_LIMIT = 4 * 1024;
|
|
48
72
|
|
|
49
73
|
/**
|
|
50
74
|
* A header value is a single line of printable ASCII, always.
|
|
@@ -115,6 +139,13 @@ export function createSidecar({
|
|
|
115
139
|
runId = randomUUID(),
|
|
116
140
|
// cli/journal.mjs, or null for `--no-journal`.
|
|
117
141
|
journal = null,
|
|
142
|
+
// `passcontrol watch`'s feed (cli/watch-feed.mjs). Off when bound off loopback.
|
|
143
|
+
watchFeed = isLoopbackBindHost(host),
|
|
144
|
+
watchCapacity = 200,
|
|
145
|
+
watchMaxSubscribers = 8,
|
|
146
|
+
// Subscription mode, Phase 1b: upload the calls Claude Code reports to the
|
|
147
|
+
// gateway's agent page (cli/client-events-upload.mjs). `--no-report-calls` turns it off.
|
|
148
|
+
reportCalls = true,
|
|
118
149
|
}) {
|
|
119
150
|
// The upstream URL below is built from this, not from the argument: the
|
|
120
151
|
// sidecar forwards a bearer visa on every proxied request, so its destination
|
|
@@ -131,6 +162,264 @@ export function createSidecar({
|
|
|
131
162
|
|
|
132
163
|
// Used only to print the governed base URL back in a refusal. Read from the
|
|
133
164
|
// live listener when there is one so the advice names the port actually bound.
|
|
165
|
+
const feed = createWatchFeed({ runId, capacity: watchCapacity, maxSubscribers: watchMaxSubscribers, enabled: watchFeed });
|
|
166
|
+
const lineageOf = (headers) =>
|
|
167
|
+
declaredLineage((name) => {
|
|
168
|
+
const v = headers?.[name];
|
|
169
|
+
return Array.isArray(v) ? v[0] : v;
|
|
170
|
+
}, runId);
|
|
171
|
+
|
|
172
|
+
// Subscription mode's Stop (cli/subscription-gate.mjs): Claude Code's hooks ask
|
|
173
|
+
// here, and the answer comes from the gateway's /api/v1/self, read with this
|
|
174
|
+
// sidecar's visa and the session the hook names.
|
|
175
|
+
const SELF_TIMEOUT_MS = 2_000;
|
|
176
|
+
async function readSelf(session) {
|
|
177
|
+
try {
|
|
178
|
+
const response = await visas.fetchWithVisa((visa) => {
|
|
179
|
+
// The tool rules ride on every gate read (Phase 2): no call of their own.
|
|
180
|
+
const path = "/api/v1/self?include=tool_rules";
|
|
181
|
+
const headers = {
|
|
182
|
+
accept: "application/json",
|
|
183
|
+
authorization: `Bearer ${visa}`,
|
|
184
|
+
"x-passcontrol-run": runId,
|
|
185
|
+
"x-passcontrol-proof": visas.createProof(visa, "GET", new URL(path, origin)),
|
|
186
|
+
"accept-encoding": "identity",
|
|
187
|
+
};
|
|
188
|
+
if (session) headers["x-claude-code-session-id"] = session;
|
|
189
|
+
return fetch(`${origin}${path}`, { headers, signal: AbortSignal.timeout(SELF_TIMEOUT_MS) });
|
|
190
|
+
});
|
|
191
|
+
return await selfAnswerState(response);
|
|
192
|
+
} catch (error) {
|
|
193
|
+
return { state: "unknown", reason: error?.name === "TimeoutError" ? "the gateway did not answer in time" : (error?.message ?? "error") };
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
const stopGate = createStopGate({ readSelf, dashboardUrl: `${origin}/dashboard` });
|
|
197
|
+
|
|
198
|
+
// Phase 2's `ask_owner` tool rules: the gateway asks the owner (their alert
|
|
199
|
+
// destination is in its Vault) and holds each request a few seconds; this asks
|
|
200
|
+
// again until the owner answers or the tool gate's wait runs out.
|
|
201
|
+
const TOOL_APPROVALS_PATH = "/api/v1/tool-approvals";
|
|
202
|
+
const APPROVAL_REQUEST_TIMEOUT_MS = 25_000;
|
|
203
|
+
const APPROVAL_RETRY_MS = 1_000;
|
|
204
|
+
async function askOwner(input, { session, waitMs }) {
|
|
205
|
+
const deadline = Date.now() + waitMs;
|
|
206
|
+
const body = JSON.stringify({ session: session ?? undefined, tool_name: input.tool_name, tool_input: input.tool_input, cwd: input.cwd });
|
|
207
|
+
while (Date.now() < deadline - 500) {
|
|
208
|
+
let response;
|
|
209
|
+
try {
|
|
210
|
+
response = await visas.fetchWithVisa((visa) => {
|
|
211
|
+
const headers = {
|
|
212
|
+
"content-type": "application/json",
|
|
213
|
+
authorization: `Bearer ${visa}`,
|
|
214
|
+
"x-passcontrol-run": runId,
|
|
215
|
+
"x-passcontrol-proof": visas.createProof(visa, "POST", new URL(TOOL_APPROVALS_PATH, origin)),
|
|
216
|
+
"accept-encoding": "identity",
|
|
217
|
+
};
|
|
218
|
+
if (session) headers["x-claude-code-session-id"] = session;
|
|
219
|
+
return fetch(`${origin}${TOOL_APPROVALS_PATH}`, {
|
|
220
|
+
method: "POST",
|
|
221
|
+
headers,
|
|
222
|
+
body,
|
|
223
|
+
signal: AbortSignal.timeout(Math.min(APPROVAL_REQUEST_TIMEOUT_MS, Math.max(1_000, deadline - Date.now()))),
|
|
224
|
+
});
|
|
225
|
+
});
|
|
226
|
+
} catch {
|
|
227
|
+
// The gateway did not answer this round: ask again while there is time.
|
|
228
|
+
await new Promise((resolve) => setTimeout(resolve, Math.min(APPROVAL_RETRY_MS, Math.max(0, deadline - Date.now()))));
|
|
229
|
+
continue;
|
|
230
|
+
}
|
|
231
|
+
const answered = await response.json().catch(() => ({}));
|
|
232
|
+
if (response.status === 409) return { state: "refused" };
|
|
233
|
+
if (response.status === 413) return { state: "too_large" };
|
|
234
|
+
if (response.status !== 200) return { state: "unavailable" };
|
|
235
|
+
if (["approved", "denied", "full"].includes(answered?.state)) return { state: answered.state };
|
|
236
|
+
if (answered?.state !== "pending") return { state: "unavailable" };
|
|
237
|
+
}
|
|
238
|
+
return { state: "timeout" };
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
// The reported calls go to the gateway as this agent, straight from here: never
|
|
242
|
+
// through this sidecar's own listener, so they are never a call on the board.
|
|
243
|
+
const UPLOAD_TIMEOUT_MS = 10_000;
|
|
244
|
+
async function sendReportedCalls(events) {
|
|
245
|
+
const response = await visas.fetchWithVisa((visa) =>
|
|
246
|
+
fetch(`${origin}${CLIENT_EVENTS_PATH}`, {
|
|
247
|
+
method: "POST",
|
|
248
|
+
headers: {
|
|
249
|
+
"content-type": "application/json",
|
|
250
|
+
authorization: `Bearer ${visa}`,
|
|
251
|
+
"x-passcontrol-run": runId,
|
|
252
|
+
"x-passcontrol-proof": visas.createProof(visa, "POST", new URL(CLIENT_EVENTS_PATH, origin)),
|
|
253
|
+
"accept-encoding": "identity",
|
|
254
|
+
},
|
|
255
|
+
body: JSON.stringify({ source: CLIENT_EVENTS_SOURCE, events }),
|
|
256
|
+
signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
|
|
257
|
+
})
|
|
258
|
+
);
|
|
259
|
+
const body = await response.json().catch(() => ({}));
|
|
260
|
+
return { status: response.status, error: body?.error, retryAfterS: Number(response.headers.get("retry-after")) };
|
|
261
|
+
}
|
|
262
|
+
const uploader = reportCalls ? createCallUploader({ send: sendReportedCalls }) : null;
|
|
263
|
+
// Its decisions reach the agent's page with the reported calls (same opt-out).
|
|
264
|
+
const toolGate = createToolGate({
|
|
265
|
+
askOwner,
|
|
266
|
+
dashboardUrl: `${origin}/dashboard`,
|
|
267
|
+
onDecision: (record) => uploader?.add({ kind: "tool_decision", at: Date.now(), ...record }),
|
|
268
|
+
});
|
|
269
|
+
|
|
270
|
+
const relayedSessions = new Set();
|
|
271
|
+
function rememberRelayed(headers) {
|
|
272
|
+
const session = lineageOf(headers)?.session;
|
|
273
|
+
if (!session || relayedSessions.has(session)) return;
|
|
274
|
+
relayedSessions.add(session);
|
|
275
|
+
if (relayedSessions.size > RELAYED_SESSIONS_MAX) relayedSessions.delete(relayedSessions.values().next().value);
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** Reads a local caller's body up to `limit`; resolves null when it is over. */
|
|
279
|
+
function readLocalBody(req, limit) {
|
|
280
|
+
return new Promise((resolve) => {
|
|
281
|
+
const chunks = [];
|
|
282
|
+
let size = 0;
|
|
283
|
+
let over = false;
|
|
284
|
+
req.on("data", (c) => {
|
|
285
|
+
size += c.length;
|
|
286
|
+
if (size > limit) over = true;
|
|
287
|
+
else chunks.push(c);
|
|
288
|
+
});
|
|
289
|
+
req.on("end", () => resolve(over ? null : Buffer.concat(chunks)));
|
|
290
|
+
req.on("error", () => resolve(null));
|
|
291
|
+
});
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
// Subscription mode's telemetry (cli/otlp-logs.mjs): Claude Code's log exporter
|
|
295
|
+
// posts here. Answered as an OTLP collector does, `{}` on success.
|
|
296
|
+
async function serveOtlpLogs(req, res) {
|
|
297
|
+
const port = server.address()?.port;
|
|
298
|
+
if (req.method !== "POST") {
|
|
299
|
+
req.resume();
|
|
300
|
+
return answer(res, 405, "method_not_allowed", "The telemetry endpoint answers POST only.");
|
|
301
|
+
}
|
|
302
|
+
if (!isLocalCaller(req, port)) {
|
|
303
|
+
req.resume();
|
|
304
|
+
return answer(res, 403, "telemetry_refused", "The telemetry endpoint is for Claude Code on this machine only.");
|
|
305
|
+
}
|
|
306
|
+
if (!String(req.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) {
|
|
307
|
+
req.resume();
|
|
308
|
+
return answer(res, 415, "telemetry_protocol", "Send OTLP as JSON: set OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/json.");
|
|
309
|
+
}
|
|
310
|
+
const raw = await readLocalBody(req, OTLP_BODY_LIMIT);
|
|
311
|
+
if (raw === null) return answer(res, 413, "telemetry_too_large", "Log export over 4 MB.");
|
|
312
|
+
let body;
|
|
313
|
+
try {
|
|
314
|
+
body = JSON.parse(raw.toString("utf8"));
|
|
315
|
+
} catch {
|
|
316
|
+
return answer(res, 400, "telemetry_not_json", "The log export is not JSON.");
|
|
317
|
+
}
|
|
318
|
+
for (const event of readClaudeCodeEvents(body)) {
|
|
319
|
+
if (event.session && relayedSessions.has(event.session)) continue;
|
|
320
|
+
feed.report({
|
|
321
|
+
at: event.at ?? Date.now(),
|
|
322
|
+
lineage: { session: event.session, agent: event.agent },
|
|
323
|
+
model: event.model,
|
|
324
|
+
provider: "anthropic",
|
|
325
|
+
outcome: event.kind === "api_request" ? "seen" : "error",
|
|
326
|
+
status: event.status,
|
|
327
|
+
ms: event.durationMs,
|
|
328
|
+
cost: event.costMicros,
|
|
329
|
+
});
|
|
330
|
+
uploader?.add(event);
|
|
331
|
+
}
|
|
332
|
+
res.writeHead(200, { "content-type": "application/json", "content-length": 2, "cache-control": "no-store" });
|
|
333
|
+
res.end("{}");
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
// Subscription mode's usage window (cli/usage-window.mjs): the status line posts
|
|
337
|
+
// what Claude Code told it; `watch` gets it on the feed, `/passcontrol` asks for it.
|
|
338
|
+
async function serveWindow(req, res) {
|
|
339
|
+
const port = server.address()?.port;
|
|
340
|
+
if (req.method !== "GET" && req.method !== "POST") {
|
|
341
|
+
req.resume();
|
|
342
|
+
return answer(res, 405, "method_not_allowed", "The usage-window endpoint answers GET and POST only.");
|
|
343
|
+
}
|
|
344
|
+
if (!isLocalCaller(req, port)) {
|
|
345
|
+
req.resume();
|
|
346
|
+
return answer(res, 403, "window_refused", "The usage-window endpoint is for this machine only.");
|
|
347
|
+
}
|
|
348
|
+
if (req.method === "GET") {
|
|
349
|
+
req.resume();
|
|
350
|
+
const current = feed.window();
|
|
351
|
+
if (!current) return answer(res, 404, "window_unknown", "No usage window reported yet.");
|
|
352
|
+
const body = JSON.stringify({ fiveHour: current.fiveHour, sevenDay: current.sevenDay, at: current.at });
|
|
353
|
+
res.writeHead(200, { "content-type": "application/json", "content-length": Buffer.byteLength(body), "cache-control": "no-store" });
|
|
354
|
+
return res.end(body);
|
|
355
|
+
}
|
|
356
|
+
const raw = await readLocalBody(req, WINDOW_BODY_LIMIT);
|
|
357
|
+
let window = null;
|
|
358
|
+
try {
|
|
359
|
+
window = raw === null ? null : heldUsageWindow(JSON.parse(raw.toString("utf8")));
|
|
360
|
+
} catch {
|
|
361
|
+
window = null;
|
|
362
|
+
}
|
|
363
|
+
if (!window) return answer(res, 400, "window_invalid", "Expected a usage window: { fiveHour, sevenDay }.");
|
|
364
|
+
feed.setWindow(window);
|
|
365
|
+
res.writeHead(204, { "cache-control": "no-store" });
|
|
366
|
+
res.end();
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
function serveHook(req, res) {
|
|
370
|
+
const port = server.address()?.port;
|
|
371
|
+
if (req.method !== "POST") {
|
|
372
|
+
req.resume();
|
|
373
|
+
return answer(res, 405, "method_not_allowed", "The hook endpoint answers POST only.");
|
|
374
|
+
}
|
|
375
|
+
if (!isLocalCaller(req, port)) {
|
|
376
|
+
req.resume();
|
|
377
|
+
return answer(res, 403, "hook_refused", "The hook endpoint is for Claude Code on this machine only.");
|
|
378
|
+
}
|
|
379
|
+
const chunks = [];
|
|
380
|
+
let size = 0;
|
|
381
|
+
let tooBig = false;
|
|
382
|
+
req.on("data", (c) => {
|
|
383
|
+
size += c.length;
|
|
384
|
+
if (size > HOOK_BODY_LIMIT) tooBig = true;
|
|
385
|
+
else chunks.push(c);
|
|
386
|
+
});
|
|
387
|
+
req.on("end", async () => {
|
|
388
|
+
if (tooBig) return answer(res, 413, "hook_too_large", "Hook input over 1 MB.");
|
|
389
|
+
let input;
|
|
390
|
+
try {
|
|
391
|
+
input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
|
|
392
|
+
} catch {
|
|
393
|
+
input = null;
|
|
394
|
+
}
|
|
395
|
+
if (!input || typeof input !== "object" || Array.isArray(input)) {
|
|
396
|
+
return answer(res, 400, "hook_not_json", "Expected Claude Code's hook input, a JSON object.");
|
|
397
|
+
}
|
|
398
|
+
let out;
|
|
399
|
+
try {
|
|
400
|
+
out = await stopGate.decide(input);
|
|
401
|
+
} catch {
|
|
402
|
+
out = {};
|
|
403
|
+
}
|
|
404
|
+
// A stop ends the turn whatever the tool rules say; otherwise a PreToolUse is
|
|
405
|
+
// the tool gate's, which needs to know how long Claude Code waits for this hook.
|
|
406
|
+
if (out.continue !== false && input.hook_event_name === "PreToolUse") {
|
|
407
|
+
let tool;
|
|
408
|
+
try {
|
|
409
|
+
tool = await toolGate.decide(input, stopGate.toolRules(), hookTimeoutS(req.url));
|
|
410
|
+
} catch {
|
|
411
|
+
tool = {};
|
|
412
|
+
}
|
|
413
|
+
const messages = [out.systemMessage, tool.systemMessage].filter(Boolean);
|
|
414
|
+
out = { ...tool, ...(messages.length ? { systemMessage: messages.join("\n") } : {}) };
|
|
415
|
+
}
|
|
416
|
+
const body = JSON.stringify(out);
|
|
417
|
+
res.writeHead(200, { "content-type": "application/json", "content-length": Buffer.byteLength(body), "cache-control": "no-store" });
|
|
418
|
+
res.end(body);
|
|
419
|
+
});
|
|
420
|
+
req.on("error", () => res.destroy());
|
|
421
|
+
}
|
|
422
|
+
|
|
134
423
|
const localBaseUrl = () => {
|
|
135
424
|
const address = server?.listening ? server.address() : null;
|
|
136
425
|
return `http://${host}:${address?.port ?? port}`;
|
|
@@ -165,7 +454,11 @@ export function createSidecar({
|
|
|
165
454
|
// URL — codeload for an archive download — passes through untouched.
|
|
166
455
|
const toLocal = (value) => value.split(`${origin}/api/v1/`).join(`${localBaseUrl()}/api/v1/`);
|
|
167
456
|
|
|
168
|
-
|
|
457
|
+
// `watch` is the board's handle on this call ({ call, startedAt }), or null for one
|
|
458
|
+
// the board does not show. Its outcome is read from the status and, for an error,
|
|
459
|
+
// from a capped peek at a CLONE of the body, so the client's bytes are untouched
|
|
460
|
+
// and nothing here waits on the peek.
|
|
461
|
+
function writeResponse(res, upstream, reqHeaders, watch = null) {
|
|
169
462
|
// At the headers, not at the end of the body: a streamed call whose client
|
|
170
463
|
// disconnects mid-stream still produced a receipt, and the user's record of
|
|
171
464
|
// it must not depend on how long they kept reading. With the session the call
|
|
@@ -184,33 +477,89 @@ export function createSidecar({
|
|
|
184
477
|
if (STRIP_RES.has(name)) return;
|
|
185
478
|
outHeaders[k] = name === "link" || name === "location" ? toLocal(v) : v;
|
|
186
479
|
});
|
|
480
|
+
let peek = null;
|
|
481
|
+
if (watch) {
|
|
482
|
+
const ttfb = Date.now() - watch.startedAt;
|
|
483
|
+
const status = upstream.status;
|
|
484
|
+
res.on("close", () => watch.call.finish());
|
|
485
|
+
if (status < 400) watch.call.settle({ outcome: "boarded", status, ttfb });
|
|
486
|
+
else if (!upstream.body) watch.call.settle({ outcome: "error", status, ttfb });
|
|
487
|
+
else {
|
|
488
|
+
try {
|
|
489
|
+
peek = upstream.clone().body;
|
|
490
|
+
} catch {
|
|
491
|
+
watch.call.settle({ outcome: "error", status, ttfb });
|
|
492
|
+
}
|
|
493
|
+
if (peek) {
|
|
494
|
+
peekText(peek).then((text) => {
|
|
495
|
+
const code = refusalCode(text);
|
|
496
|
+
watch.call.settle({ outcome: code ? "denied" : "error", code, status, ttfb });
|
|
497
|
+
});
|
|
498
|
+
}
|
|
499
|
+
}
|
|
500
|
+
}
|
|
187
501
|
res.writeHead(upstream.status, outHeaders);
|
|
188
502
|
if (upstream.body) Readable.fromWeb(upstream.body).pipe(res);
|
|
189
503
|
else res.end();
|
|
190
504
|
}
|
|
191
505
|
|
|
506
|
+
/** Begins the board's record of a forwarded call, unless it is not a call (the budget read, an upload). */
|
|
507
|
+
function watchCall(req, path, body, startedAt) {
|
|
508
|
+
if (isNotACall(path)) return null;
|
|
509
|
+
rememberRelayed(req.headers);
|
|
510
|
+
try {
|
|
511
|
+
return { startedAt, call: feed.begin({ startedAt, lineage: lineageOf(req.headers), model: requestModel(body), provider: providerOf(path) }) };
|
|
512
|
+
} catch {
|
|
513
|
+
return null;
|
|
514
|
+
}
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
/** A forwarded call that failed before the gateway answered: shown, then answered 502. */
|
|
518
|
+
function upstreamFailed(res, watch, req, path, e) {
|
|
519
|
+
if (!res.headersSent) {
|
|
520
|
+
if (watch) {
|
|
521
|
+
watch.call.settle({ outcome: "error", code: "sidecar_upstream_error", status: 502 });
|
|
522
|
+
watch.call.finish();
|
|
523
|
+
} else if (!isNotACall(path)) {
|
|
524
|
+
feed.record({ outcome: "error", code: "sidecar_upstream_error", status: 502, lineage: lineageOf(req.headers), provider: providerOf(path) });
|
|
525
|
+
}
|
|
526
|
+
res.writeHead(502, { "content-type": "application/json" });
|
|
527
|
+
res.end(JSON.stringify({ error: "sidecar_upstream_error", message: e.message }));
|
|
528
|
+
} else {
|
|
529
|
+
res.end();
|
|
530
|
+
}
|
|
531
|
+
}
|
|
532
|
+
|
|
192
533
|
const server = http.createServer(async (req, res) => {
|
|
534
|
+
// The sidecar's own paths: answered here, never forwarded with a visa.
|
|
535
|
+
if (String(req.url ?? "").startsWith(LOCAL_PREFIX)) {
|
|
536
|
+
const localPath = String(req.url).split("?")[0];
|
|
537
|
+
if (localPath === HOOK_PATH) return serveHook(req, res);
|
|
538
|
+
if (localPath === OTLP_LOGS_PATH) return serveOtlpLogs(req, res);
|
|
539
|
+
if (localPath === WINDOW_PATH) return serveWindow(req, res);
|
|
540
|
+
feed.serve(req, res, { port: server.address()?.port });
|
|
541
|
+
return;
|
|
542
|
+
}
|
|
543
|
+
const startedAt = Date.now();
|
|
193
544
|
// Judge the destination before reading the body: a refused host should not
|
|
194
545
|
// get to make the sidecar buffer megabytes on its way to a 403.
|
|
195
546
|
const verdict = classifyProxyRequest({ url: req.url, gatewayOrigin: origin, localBaseUrl: localBaseUrl() });
|
|
196
547
|
if (!verdict.allow) {
|
|
197
548
|
req.resume();
|
|
198
549
|
onRefusal(verdict);
|
|
550
|
+
feed.record({ outcome: "denied", code: verdict.code, status: verdict.status, lineage: lineageOf(req.headers), startedAt });
|
|
199
551
|
writeRefusal(res, verdict);
|
|
200
552
|
return;
|
|
201
553
|
}
|
|
202
554
|
|
|
555
|
+
let watch = null;
|
|
203
556
|
try {
|
|
204
557
|
const body = await readBody(req);
|
|
558
|
+
watch = watchCall(req, verdict.path, body, startedAt);
|
|
205
559
|
const upstream = await visas.fetchWithVisa((visa) => fetchUpstream(req, verdict.path, body, visa));
|
|
206
|
-
writeResponse(res, upstream, req.headers);
|
|
560
|
+
writeResponse(res, upstream, req.headers, watch);
|
|
207
561
|
} catch (e) {
|
|
208
|
-
|
|
209
|
-
res.writeHead(502, { "content-type": "application/json" });
|
|
210
|
-
res.end(JSON.stringify({ error: "sidecar_upstream_error", message: e.message }));
|
|
211
|
-
} else {
|
|
212
|
-
res.end();
|
|
213
|
-
}
|
|
562
|
+
upstreamFailed(res, watch, req, verdict.path, e);
|
|
214
563
|
}
|
|
215
564
|
});
|
|
216
565
|
|
|
@@ -239,24 +588,24 @@ export function createSidecar({
|
|
|
239
588
|
const probe = url.pathname === "/";
|
|
240
589
|
const mapped = `/api/v1/local${probe ? "/api/version" : url.pathname}${probe ? "" : url.search}`;
|
|
241
590
|
const method = probe ? "GET" : req.method;
|
|
591
|
+
const startedAt = Date.now();
|
|
592
|
+
let watch = null;
|
|
242
593
|
try {
|
|
243
594
|
const body = probe ? null : await readBody(req);
|
|
244
595
|
if (probe) req.resume();
|
|
596
|
+
watch = watchCall(req, mapped, body, startedAt);
|
|
245
597
|
const upstream = await visas.fetchWithVisa((visa) => fetchUpstream({ method, headers: req.headers }, mapped, body, visa));
|
|
246
598
|
if (req.method === "HEAD") {
|
|
599
|
+
watch?.call.settle({ outcome: upstream.status < 400 ? "boarded" : "error", status: upstream.status, ttfb: Date.now() - startedAt });
|
|
600
|
+
watch?.call.finish();
|
|
247
601
|
res.writeHead(upstream.status);
|
|
248
602
|
res.end();
|
|
249
603
|
await upstream.body?.cancel().catch(() => {});
|
|
250
604
|
return;
|
|
251
605
|
}
|
|
252
|
-
writeResponse(res, upstream, req.headers);
|
|
606
|
+
writeResponse(res, upstream, req.headers, watch);
|
|
253
607
|
} catch (e) {
|
|
254
|
-
|
|
255
|
-
res.writeHead(502, { "content-type": "application/json" });
|
|
256
|
-
res.end(JSON.stringify({ error: "sidecar_upstream_error", message: e.message }));
|
|
257
|
-
} else {
|
|
258
|
-
res.end();
|
|
259
|
-
}
|
|
608
|
+
upstreamFailed(res, watch, req, mapped, e);
|
|
260
609
|
}
|
|
261
610
|
});
|
|
262
611
|
|
|
@@ -275,6 +624,7 @@ export function createSidecar({
|
|
|
275
624
|
});
|
|
276
625
|
if (!verdict.allow) {
|
|
277
626
|
onRefusal(verdict);
|
|
627
|
+
feed.record({ outcome: "denied", code: verdict.code, status: verdict.status, lineage: lineageOf(req.headers) });
|
|
278
628
|
writeConnectRefusal(clientSocket, verdict);
|
|
279
629
|
return;
|
|
280
630
|
}
|
|
@@ -292,6 +642,7 @@ export function createSidecar({
|
|
|
292
642
|
clientSocket.destroy();
|
|
293
643
|
return;
|
|
294
644
|
}
|
|
645
|
+
feed.record({ outcome: "error", code: "tunnel_unreachable", status: 502, lineage: lineageOf(req.headers) });
|
|
295
646
|
writeConnectRefusal(clientSocket, {
|
|
296
647
|
status: 502,
|
|
297
648
|
code: "tunnel_unreachable",
|
|
@@ -302,7 +653,8 @@ export function createSidecar({
|
|
|
302
653
|
clientSocket.on("close", () => upstream.destroy());
|
|
303
654
|
});
|
|
304
655
|
|
|
305
|
-
|
|
656
|
+
server.on("close", () => uploader?.close());
|
|
657
|
+
return { server, ollamaServer, getVisa: visas.getVisa, runId, feed, uploader };
|
|
306
658
|
}
|
|
307
659
|
|
|
308
660
|
/**
|
|
@@ -335,7 +687,7 @@ export function startSidecar(opts) {
|
|
|
335
687
|
onError: (e) =>
|
|
336
688
|
warn(`journal: could not write ${journal.path} (${e.message}). Calls are unaffected; this run is no longer being recorded.`),
|
|
337
689
|
});
|
|
338
|
-
const { server, ollamaServer, getVisa } = createSidecar({ ...opts, runId, journal });
|
|
690
|
+
const { server, ollamaServer, getVisa, feed } = createSidecar({ ...opts, runId, journal });
|
|
339
691
|
if (ollamaPort != null) {
|
|
340
692
|
ollamaServer.listen(ollamaPort, host, () => {
|
|
341
693
|
step(`Ollama API (local models) on http://${host}:${ollamaPort}: set OLLAMA_HOST=${host}:${ollamaPort}`);
|
|
@@ -351,6 +703,11 @@ export function startSidecar(opts) {
|
|
|
351
703
|
? `Journal: ${journal.path} (receipt ids, times, statuses and declared sessions only; --no-journal turns it off)`
|
|
352
704
|
: "Journal: off (--no-journal). Session seals cannot be checked against this run."
|
|
353
705
|
);
|
|
706
|
+
step(
|
|
707
|
+
isLoopbackBindHost(host)
|
|
708
|
+
? `Watch live: passcontrol watch --port ${port} (this machine only; held in memory, never written)`
|
|
709
|
+
: "Watch: off, because this sidecar is bound off loopback."
|
|
710
|
+
);
|
|
354
711
|
// Said at startup rather than only in a refusal, because the whole point of
|
|
355
712
|
// HTTPS_PROXY is that nobody reads the docs first.
|
|
356
713
|
step("HTTPS_PROXY: CONNECT to a provider is refused, not tunnelled — PassControl cannot");
|
|
@@ -363,9 +720,72 @@ export function startSidecar(opts) {
|
|
|
363
720
|
? `CONNECT allowlist: ${allowConnectHosts.join(", ")} (provider hosts are never eligible).\n`
|
|
364
721
|
: "CONNECT allowlist: none — only the gateway.\n"
|
|
365
722
|
);
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
723
|
+
warmVisa({
|
|
724
|
+
getVisa,
|
|
725
|
+
gateway,
|
|
726
|
+
// Closed rather than process.exit(): stderr to a pipe is written
|
|
727
|
+
// asynchronously, and exit() can drop the reason this just printed.
|
|
728
|
+
onRefused: () => {
|
|
729
|
+
process.exitCode = 1;
|
|
730
|
+
// A watching board holds its connection open, and close() waits for it.
|
|
731
|
+
feed.close();
|
|
732
|
+
server.close();
|
|
733
|
+
if (ollamaServer.listening) ollamaServer.close();
|
|
734
|
+
setTimeout(() => process.exit(1), 1000).unref();
|
|
735
|
+
},
|
|
736
|
+
});
|
|
369
737
|
});
|
|
370
738
|
return server;
|
|
371
739
|
}
|
|
740
|
+
|
|
741
|
+
/** Waits between attempts to mint the first visa: backoff, then every 30 seconds. */
|
|
742
|
+
export const WARM_RETRY_MS = [1000, 2000, 4000, 8000, 15000, 30000];
|
|
743
|
+
|
|
744
|
+
/**
|
|
745
|
+
* A gateway that answered and refused the passport: any 4xx except 408 and 429,
|
|
746
|
+
* which mean "not now". No status (no connection) and 5xx mean "not up yet".
|
|
747
|
+
*/
|
|
748
|
+
export function isPassportRefusal(error) {
|
|
749
|
+
const status = error?.status;
|
|
750
|
+
return typeof status === "number" && status >= 400 && status < 500 && status !== 408 && status !== 429;
|
|
751
|
+
}
|
|
752
|
+
|
|
753
|
+
/**
|
|
754
|
+
* The first visa (sprint T2). A sidecar is often started before its gateway, by
|
|
755
|
+
* `passcontrol start` or a login script, so a gateway that is not answering is
|
|
756
|
+
* waited for, on screen; a refusal ends the process, because retrying it can only
|
|
757
|
+
* fail again and a sidecar that cannot mint must not look like it is running.
|
|
758
|
+
* Resolves true once warmed, false after a refusal (onRefused has run).
|
|
759
|
+
*/
|
|
760
|
+
export async function warmVisa({
|
|
761
|
+
getVisa,
|
|
762
|
+
gateway,
|
|
763
|
+
onRefused,
|
|
764
|
+
sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
|
|
765
|
+
log = { ok, warn, fail },
|
|
766
|
+
delays = WARM_RETRY_MS,
|
|
767
|
+
}) {
|
|
768
|
+
for (let attempt = 0; ; attempt++) {
|
|
769
|
+
try {
|
|
770
|
+
await getVisa();
|
|
771
|
+
log.ok(attempt === 0 ? "visa warmed" : `visa warmed: ${gateway} is answering now`);
|
|
772
|
+
return true;
|
|
773
|
+
} catch (error) {
|
|
774
|
+
if (isPassportRefusal(error)) {
|
|
775
|
+
log.fail(`could not mint a visa: ${error.message}`);
|
|
776
|
+
onRefused(error);
|
|
777
|
+
return false;
|
|
778
|
+
}
|
|
779
|
+
const delay = delays[Math.min(attempt, delays.length - 1)];
|
|
780
|
+
if (attempt === 0) {
|
|
781
|
+
log.warn(
|
|
782
|
+
`${gateway} is not answering yet (${error.message}). Waiting for it, and retrying on its own; ` +
|
|
783
|
+
"calls made before it answers get a 502."
|
|
784
|
+
);
|
|
785
|
+
} else if (attempt % 10 === 0) {
|
|
786
|
+
log.warn(`still waiting for ${gateway} (${error.message})`);
|
|
787
|
+
}
|
|
788
|
+
await sleep(delay);
|
|
789
|
+
}
|
|
790
|
+
}
|
|
791
|
+
}
|