@sema-agent/server 7.136.0 → 7.138.0

package/dist/broker/broker.js

@@ -0,0 +1,287 @@
+import * as http from "node:http";
+import * as net from "node:net";
+import * as tls from "node:tls";
+import { readFileSync } from "node:fs";
+import { BROKER_READY_PATH, BROKER_UPSTREAM_CONNECT_MS, BROKER_UPSTREAM_HEADERS_MS } from "./constants.js";
+import { ByteReader, FORWARDED_REQUEST_HEADERS, FORWARDED_RESPONSE_HEADERS, INFO_REFS_QUERIES, MAX_HEAD_BYTES, UPSTREAM_PATH, WireError, judgeRequest, judgeResponseFraming, parseRequestHead, parseResponseHead, readChunked, valuesOf, } from "./http1.js";
+import { LeaseBook, systemMonotonicClock } from "./lease-book.js";
+export function createUpstreamConnector(impl = {}) {
+    const tlsConnect = impl.tlsConnect ?? ((opts) => tls.connect(opts));
+    const netConnect = impl.netConnect ?? ((opts) => net.connect(opts));
+    return (t) => {
+        const host = t.hostname.replace(/^\[(.*)\]$/, "$1");
+        if (t.protocol === "http:")
+            return netConnect({ host, port: t.port });
+        return tlsConnect({ host, port: t.port, ...(net.isIP(host) === 0 ? { servername: host } : {}), rejectUnauthorized: true, ALPNProtocols: ["http/1.1"] });
+    };
+}
+export const BROKER_UPSTREAM_TIMEOUTS_DEFAULT = { connectMs: BROKER_UPSTREAM_CONNECT_MS, headersMs: BROKER_UPSTREAM_HEADERS_MS };
+export function createBrokerServer(deps) {
+    return net.createServer((socket) => void serveOne(socket, deps));
+}
+const REASON = { 200: "OK", 400: "Bad Request", 401: "Unauthorized", 417: "Expectation Failed", 502: "Bad Gateway", 503: "Service Unavailable" };
+const PIECE = 64 * 1024;
+async function serveOne(down, deps) {
+    down.on("error", () => { });
+    const reader = new ByteReader(down);
+    let head;
+    try {
+        const buf = await reader.readUntil("\r\n\r\n", MAX_HEAD_BYTES);
+        if (buf === undefined)
+            return void down.destroy();
+        head = parseRequestHead(buf);
+    }
+    catch (e) {
+        return refuse(down, deps, e instanceof WireError ? e.status : 400, e instanceof WireError ? e.rule : "the request head could not be read");
+    }
+    if (head.method === "GET" && head.target === BROKER_READY_PATH) {
+        const ready = deps.book.ready();
+        return answer(down, ready ? 200 : 503, ready ? "ready" : "not ready");
+    }
+    const verdict = judgeRequest(head, (i) => deps.book.view(i) !== undefined);
+    if (!verdict.ok)
+        return refuse(down, deps, verdict.status, verdict.rule);
+    await forward(down, reader, head, verdict.route, verdict.framing, verdict.expectContinue, deps);
+}
+function refuse(down, deps, status, rule) {
+    deps.log({ event: "refused", status, rule });
+    answer(down, status, `sandbox git broker: ${rule}`);
+}
+function answer(down, status, text, contentType = "text/plain; charset=utf-8") {
+    const body = Buffer.from(`${text}\n`, "utf8");
+    down.end(Buffer.concat([Buffer.from(`HTTP/1.1 ${status} ${REASON[status] ?? ""}\r\nContent-Type: ${contentType}\r\nContent-Length: ${body.length}\r\nConnection: close\r\n\r\n`, "latin1"), body]));
+}
+async function within(work, ms, what) {
+    let timer;
+    const late = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new WireError(502, `upstream_timeout — ${what} within ${ms} ms`)), ms);
+    });
+    try {
+        return await Promise.race([work, late]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function write(stream, buf) {
+    return new Promise((resolve, reject) => {
+        if (stream.destroyed)
+            return reject(new Error("the connection is gone"));
+        stream.write(buf, (err) => (err ? reject(err) : resolve()));
+    });
+}
+const canonical = (name) => name.replace(/(^|-)([a-z])/g, (_m, dash, c) => dash + c.toUpperCase());
+async function forward(down, reader, head, route, framing, expectContinue, deps) {
+    const view = deps.book.view(route.i);
+    const origin = new URL(view.origin);
+    const upstreamPath = `/${route.owner}/${route.repo}/${route.endpoint}${route.service !== undefined ? `?service=${route.service}` : ""}`;
+    let up;
+    const state = { cut: false, done: false, answered: false };
+    const exchange = {
+        destroy: () => {
+            state.cut = true;
+            down.destroy();
+            up?.destroy();
+        },
+    };
+    const auth = deps.book.authorize(route.i, exchange);
+    try {
+        up = deps.connect({ protocol: origin.protocol === "https:" ? "https:" : "http:", hostname: origin.hostname, port: origin.port !== "" ? Number(origin.port) : origin.protocol === "https:" ? 443 : 80 });
+        up.on("error", () => { });
+        const upReader = new ByteReader(up);
+        if (expectContinue)
+            down.write("HTTP/1.1 100 Continue\r\n\r\n");
+        const lines = [`${head.method} ${upstreamPath} HTTP/1.1`, `Host: ${origin.host}`];
+        for (const [n, v] of head.headers)
+            if (FORWARDED_REQUEST_HEADERS.has(n))
+                lines.push(`${canonical(n)}: ${v}`);
+        if (auth !== undefined)
+            lines.push(`Authorization: ${auth.authorization}`);
+        if (framing.kind === "length")
+            lines.push(`Content-Length: ${framing.n}`);
+        if (framing.kind === "chunked")
+            lines.push("Transfer-Encoding: chunked");
+        lines.push("Connection: close");
+        const bounds = deps.timeouts ?? BROKER_UPSTREAM_TIMEOUTS_DEFAULT;
+        await within(write(up, Buffer.from(`${lines.join("\r\n")}\r\n\r\n`, "latin1")), bounds.connectMs, "the origin did not accept the connection");
+        const upstream = up;
+        const sent = pumpRequestBody(reader, upstream, framing);
+        sent.catch((e) => {
+            if (state.done || state.cut)
+                return;
+            deps.log({ event: "aborted", i: route.i, endpoint: route.endpoint, why: e instanceof WireError ? e.rule : "the request body could not be forwarded" });
+            exchange.destroy();
+        });
+        const res = await readResponseHead(upReader, sent, bounds.headersMs);
+        deps.log({ event: "exchange", i: route.i, method: head.method, endpoint: route.endpoint, upstreamStatus: res.status, authenticated: auth !== undefined });
+        if (res.status === 401) {
+            state.answered = true;
+            answerUnauthorized(down, route, auth !== undefined ? (view.rejectedMessage ?? view.unusableMessage) : view.unusableMessage);
+            return;
+        }
+        const resFraming = judgeResponseFraming(res);
+        if ("problem" in resFraming)
+            throw new WireError(502, resFraming.problem);
+        let location;
+        if (res.status >= 300 && res.status < 400) {
+            const loc = valuesOf(res.headers, "location");
+            location = loc.length === 1 ? rewriteLocation(loc[0], `${view.origin}${upstreamPath}`, view.origin, route.i) : undefined;
+            if (location === undefined)
+                throw new WireError(502, "the upstream redirected outside this origin's git namespace (not followed)");
+        }
+        const out = [`HTTP/1.1 ${res.status} ${res.reason.replace(/[^\x20-\x7e]/g, "")}`];
+        for (const [n, v] of res.headers)
+            if (FORWARDED_RESPONSE_HEADERS.has(n))
+                out.push(`${canonical(n)}: ${v}`);
+        if (location !== undefined)
+            out.push(`Location: ${location}`);
+        if (resFraming.kind === "length")
+            out.push(`Content-Length: ${resFraming.n}`);
+        if (resFraming.kind === "chunked")
+            out.push("Transfer-Encoding: chunked");
+        out.push("Connection: close");
+        state.answered = true;
+        await write(down, Buffer.from(`${out.join("\r\n")}\r\n\r\n`, "latin1"));
+        await pumpBody(upReader, down, resFraming, "drop", 502);
+        state.done = true;
+        down.end();
+    }
+    catch (e) {
+        if (state.cut) {
+            deps.log({ event: "aborted", i: route.i, endpoint: route.endpoint, why: "cut (lease ended, entry withdrawn, or a side went away)" });
+            return;
+        }
+        const problem = e instanceof WireError ? e.rule : "the upstream connection failed";
+        deps.log({ event: "upstream_failed", i: route.i, endpoint: route.endpoint, problem });
+        if (state.answered)
+            down.destroy();
+        else
+            answer(down, 502, `sandbox git broker: ${problem}`);
+    }
+    finally {
+        state.done = true;
+        auth?.release();
+        up?.destroy();
+    }
+}
+async function readResponseHead(upReader, sent, headersMs) {
+    const head = (async () => {
+        for (;;) {
+            const buf = await upReader.readUntil("\r\n\r\n", MAX_HEAD_BYTES);
+            if (buf === undefined)
+                throw new WireError(502, "the upstream closed before answering");
+            const h = parseResponseHead(buf);
+            if (h.status >= 200)
+                return h;
+        }
+    })();
+    const first = await Promise.race([head.then(() => "head"), sent.then(() => "sent", () => "sent")]);
+    return first === "head" ? head : within(head, headersMs, "the origin did not answer the request");
+}
+async function pumpRequestBody(reader, up, framing) {
+    await pumpBody(reader, up, framing, "refuse", 400);
+}
+async function pumpBody(from, to, framing, trailers, failStatus) {
+    switch (framing.kind) {
+        case "none":
+            return;
+        case "length": {
+            let left = framing.n;
+            while (left > 0) {
+                const piece = await from.readSome(Math.min(left, PIECE));
+                if (piece === undefined)
+                    throw new WireError(failStatus, "the stream ended before its declared length");
+                left -= piece.length;
+                await write(to, piece);
+            }
+            return;
+        }
+        case "chunked": {
+            for await (const piece of readChunked(from, trailers, failStatus)) {
+                await write(to, Buffer.concat([Buffer.from(`${piece.length.toString(16)}\r\n`, "latin1"), piece, Buffer.from("\r\n", "latin1")]));
+            }
+            await write(to, Buffer.from("0\r\n\r\n", "latin1"));
+            return;
+        }
+        case "close": {
+            for (;;) {
+                const piece = await from.readSome(PIECE);
+                if (piece === undefined)
+                    return;
+                await write(to, piece);
+            }
+        }
+    }
+}
+function answerUnauthorized(down, route, sentence) {
+    if (route.endpoint !== "info/refs" || route.service === undefined)
+        return answer(down, 401, sentence);
+    const pkt = (s) => `${(Buffer.byteLength(s, "utf8") + 4).toString(16).padStart(4, "0")}${s}`;
+    const body = Buffer.from(`${pkt(`# service=${route.service}\n`)}0000${pkt(`ERR ${sentence}`)}`, "utf8");
+    down.end(Buffer.concat([
+        Buffer.from(`HTTP/1.1 200 OK\r\nContent-Type: application/x-${route.service}-advertisement\r\nCache-Control: no-cache\r\nContent-Length: ${body.length}\r\nConnection: close\r\n\r\n`, "latin1"),
+        body,
+    ]));
+}
+export function rewriteLocation(location, upstreamUrl, origin, i) {
+    if (location.includes("%") || !URL.canParse(location, upstreamUrl))
+        return undefined;
+    const u = new URL(location, upstreamUrl);
+    if (u.origin !== origin || u.username !== "" || u.password !== "" || u.hash !== "")
+        return undefined;
+    const m = UPSTREAM_PATH.exec(u.pathname);
+    if (!m)
+        return undefined;
+    const endpoint = m[3];
+    const query = u.search === "" ? undefined : u.search.slice(1);
+    if (endpoint === "info/refs" ? query === undefined || !Object.hasOwn(INFO_REFS_QUERIES, query) : query !== undefined)
+        return undefined;
+    return `/o/${i}/${m[1]}/${m[2]}/${endpoint}${query !== undefined ? `?${query}` : ""}`;
+}
+export async function runBroker(opts) {
+    const book = new LeaseBook({ clock: opts.clock ?? systemMonotonicClock, log: opts.log });
+    let last;
+    const poll = () => {
+        let text;
+        try {
+            text = readFileSync(opts.leasePath, "utf8");
+        }
+        catch (e) {
+            text = "";
+            if (last !== "")
+                opts.log({ event: "lease_file_unreadable", problem: e.code ?? "read failed" });
+        }
+        if (text === last)
+            return;
+        last = text;
+        book.load(text);
+    };
+    poll();
+    const timer = setInterval(poll, opts.pollMs);
+    const server = createBrokerServer({ book, connect: opts.connect ?? createUpstreamConnector(), log: opts.log });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port, opts.host, () => resolve());
+    });
+    const port = server.address().port;
+    opts.log({ event: "listening", host: opts.host, port });
+    return {
+        port,
+        book,
+        close: () => new Promise((resolve) => {
+            clearInterval(timer);
+            server.close(() => resolve());
+        }),
+    };
+}
+export function probeBroker(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        const req = http.get({ host, port, path: BROKER_READY_PATH, timeout: timeoutMs, agent: false }, (res) => {
+            res.resume();
+            resolve(res.statusCode === 200);
+        });
+        req.on("timeout", () => req.destroy());
+        req.on("error", () => resolve(false));
+    });
+}
+//# sourceMappingURL=broker.js.map

package/dist/broker/constants.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The member git-credential broker's fixed coordinates — the ONE place they are spelled. Both sides read this module: the k8s adapter
+ * (which builds the broker container, its lease volume and the agent container's `insteadOf` routes) and the broker program itself (which
+ * listens on the port and reads the lease file). Nothing here is a knob: a pod's broker is the same program at the same place on every pod.
+ *
+ * The program runs from the engine image (`K8S_SANDBOX_BROKER_IMAGE`, recommended = this engine's own image), whose layout is the repo's
+ * `Dockerfile`: Bun at `/app`, the TypeScript sources at `/app/src`, no build step — hence the command below. A broker image other than the
+ * engine's own must carry the same program at the same path.
+ */
+/** The broker's loopback port inside the pod's network namespace (the agent container reaches it at `127.0.0.1`; nothing outside the pod does). */
+export declare const BROKER_PORT = 47311;
+/** The broker listens on the pod loopback only. */
+export declare const BROKER_HOST = "127.0.0.1";
+/** The broker container's name (`containers[1]`). */
+export declare const BROKER_CONTAINER_NAME = "sema-broker";
+/** The pod volume that projects the lease Secret into the broker container (a reserved name: a deployment patch cannot use it). */
+export declare const BROKER_VOLUME_NAME = "sema-broker-lease";
+/** Where the lease volume is mounted in the broker container (read-only). */
+export declare const BROKER_LEASE_DIR = "/var/run/sema-broker";
+/** The lease Secret's one data key, and the file name in the mounted volume. */
+export declare const BROKER_LEASE_KEY = "broker.json";
+/** The lease file the broker reads. */
+export declare const BROKER_LEASE_PATH = "/var/run/sema-broker/broker.json";
+/** The broker program inside the engine image. */
+export declare const BROKER_ENTRY_PATH = "/app/src/broker/main.ts";
+/** The broker container's fixed command. */
+export declare const BROKER_COMMAND: readonly ["bun", "/app/src/broker/main.ts"];
+/** The argument that turns the same program into its own readiness probe (asks `BROKER_READY_PATH` on the loopback, exits 0 ⇔ 200). */
+export declare const BROKER_PROBE_ARG = "--probe";
+/** The broker's local readiness route (answered by the broker itself, never forwarded). */
+export declare const BROKER_READY_PATH = "/_ready";
+/** How often the broker re-reads the lease file (the kubelet swaps the projected file atomically; a changed text is loaded). */
+export declare const BROKER_LEASE_POLL_MS = 1000;
+/** Every upstream wait is bounded. The connection — TCP, and for https the TLS handshake — must take the request head within this long. */
+export declare const BROKER_UPSTREAM_CONNECT_MS = 10000;
+/** The upstream's response head must arrive within this long after the request was fully sent (a body still uploading is not cut by it:
+ *  the body has no total bound of its own — an authenticated one is bounded by its lease, `lease-book.ts`). */
+export declare const BROKER_UPSTREAM_HEADERS_MS = 30000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/broker/constants.js

@@ -0,0 +1,15 @@
+export const BROKER_PORT = 47311;
+export const BROKER_HOST = "127.0.0.1";
+export const BROKER_CONTAINER_NAME = "sema-broker";
+export const BROKER_VOLUME_NAME = "sema-broker-lease";
+export const BROKER_LEASE_DIR = "/var/run/sema-broker";
+export const BROKER_LEASE_KEY = "broker.json";
+export const BROKER_LEASE_PATH = `${BROKER_LEASE_DIR}/${BROKER_LEASE_KEY}`;
+export const BROKER_ENTRY_PATH = "/app/src/broker/main.ts";
+export const BROKER_COMMAND = ["bun", BROKER_ENTRY_PATH];
+export const BROKER_PROBE_ARG = "--probe";
+export const BROKER_READY_PATH = "/_ready";
+export const BROKER_LEASE_POLL_MS = 1_000;
+export const BROKER_UPSTREAM_CONNECT_MS = 10_000;
+export const BROKER_UPSTREAM_HEADERS_MS = 30_000;
+//# sourceMappingURL=constants.js.map

package/dist/broker/http1.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The broker's own HTTP/1.1 reading — strict, small, and the same under Node and Bun (it runs on plain sockets, not on a runtime's HTTP
+ * server, so no runtime's leniency decides what the boundary accepts). One request per downstream connection: the broker answers and
+ * closes, so bytes after a request's declared body are never parsed as a second request at all.
+ *
+ * What is judged here (the rest of the boundary is in `broker.ts`):
+ *  · the request head: request line (origin-form target, HTTP/1.1), header lines (token names, no obs-fold, no bare CR / LF, no control
+ *    characters in values) — {@link parseRequestHead};
+ *  · the request against the route table — target form, path, method + query, Content-Type, framing, Expect, Content-Encoding —
+ *    {@link judgeRequest};
+ *  · the response head and its framing (RFC 9112 §6.3) — {@link parseResponseHead}, {@link judgeResponseFraming};
+ *  · chunked bodies, both directions — {@link readChunked}.
+ */
+import type { Duplex } from "node:stream";
+/** A request / response head larger than this is refused. */
+export declare const MAX_HEAD_BYTES: number;
+/** A wire-level failure: `status` is what the client is told when nothing was answered yet. */
+export declare class WireError extends Error {
+    readonly status: number;
+    readonly rule: string;
+    constructor(status: number, rule: string);
+}
+/** Pull-reader over one socket: buffers what arrives, pauses the socket past a high-water mark, hands out exact amounts. */
+export declare class ByteReader {
+    private readonly stream;
+    private bufs;
+    private len;
+    private ended;
+    private failure?;
+    private wake?;
+    constructor(stream: Duplex);
+    private notify;
+    private wait;
+    private take;
+    /** Bytes up to and including `delim`; `undefined` = the stream ended first; throws once more than `max` bytes arrive without it. */
+    readUntil(delim: string, max: number): Promise<Buffer | undefined>;
+    /** Up to `max` bytes as soon as any are there; `undefined` = the stream ended. */
+    readSome(max: number): Promise<Buffer | undefined>;
+    /** Exactly `n` bytes; throws when the stream ends first. */
+    readExact(n: number): Promise<Buffer>;
+}
+export type Headers = ReadonlyArray<readonly [name: string, value: string]>;
+export interface RequestHead {
+    readonly method: string;
+    readonly target: string;
+    /** Header lines in order, names lower-cased, values with surrounding blanks removed. */
+    readonly headers: Headers;
+}
+export interface ResponseHead {
+    readonly status: number;
+    readonly reason: string;
+    readonly headers: Headers;
+}
+export declare function parseRequestHead(buf: Buffer): RequestHead;
+export declare function parseResponseHead(buf: Buffer): ResponseHead;
+export declare const valuesOf: (headers: Headers, name: string) => string[];
+/** The three git smart-HTTP endpoints — the only things behind the route. */
+export type GitEndpoint = "info/refs" | "git-upload-pack" | "git-receive-pack";
+export type GitService = "git-upload-pack" | "git-receive-pack";
+export interface Route {
+    readonly i: number;
+    readonly owner: string;
+    readonly repo: string;
+    readonly endpoint: GitEndpoint;
+    /** info/refs only: the advertised service. */
+    readonly service?: GitService;
+}
+/** How a body is framed: none, a declared length, chunked — and, for a response only, delimited by the connection closing. */
+export type Framing = {
+    readonly kind: "none";
+} | {
+    readonly kind: "length";
+    readonly n: number;
+} | {
+    readonly kind: "chunked";
+} | {
+    readonly kind: "close";
+};
+/** The broker's route, matched on the RAW path (never decoded): `/o/<i>/<owner>/<repo>/<endpoint>`. */
+export declare const ROUTE_PATH: RegExp;
+/** The same namespace on the upstream (a redirect's Location must land in it). */
+export declare const UPSTREAM_PATH: RegExp;
+/** The only two info/refs queries. */
+export declare const INFO_REFS_QUERIES: Readonly<Record<string, GitService>>;
+/** Request headers that cross to the origin as they came (framing is re-stated by the broker; Host / Authorization are the broker's own). */
+export declare const FORWARDED_REQUEST_HEADERS: ReadonlySet<string>;
+/** Response headers that cross back to the agent as they came (framing re-stated; Location only rewritten on a 3xx). */
+export declare const FORWARDED_RESPONSE_HEADERS: ReadonlySet<string>;
+export type RequestVerdict = {
+    readonly ok: true;
+    readonly route: Route;
+    readonly framing: Framing;
+    readonly expectContinue: boolean;
+} | {
+    readonly ok: false;
+    readonly status: 400 | 417;
+    readonly rule: string;
+};
+/** Judge one request head against the route (`hasEntry` = the pinned origin table has that index). Pure. */
+export declare function judgeRequest(head: RequestHead, hasEntry: (i: number) => boolean): RequestVerdict;
+/** RFC 9112 §6.3 for an upstream response to a GET / POST. Conflicting or repeated framing headers ⇒ a problem (the response is not forwarded). */
+export declare function judgeResponseFraming(head: ResponseHead): Framing | {
+    readonly problem: string;
+};
+/**
+ * The data of one chunked body, piece by piece (each ≤ 64 KiB), validated as it goes: chunk-size lines are 1–8 hex digits with no
+ * extension; the body ends with a zero chunk and an empty trailer section — any trailer field is a {@link WireError} when
+ * `trailers` is `"refuse"` (a request: a Trailer header is refused, so trailer fields are too) and is dropped when `"drop"` (a response).
+ */
+export declare function readChunked(reader: ByteReader, trailers: "refuse" | "drop", failStatus: number): AsyncGenerator<Buffer>;
+//# sourceMappingURL=http1.d.ts.map