agentgather 0.1.0

package/dist/src/tunnel/broker.js

@@ -0,0 +1,440 @@
+// Local tunnel broker harness.
+//
+// The broker registers a single host route per slug and exposes a local HTTP
+// listener that resolves participant requests to route status. It does not
+// forward real room endpoints yet (that is ticket #36) and never opens a public
+// network connection. The only state it keeps is ephemeral RouteMetadata.
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { URL } from "node:url";
+import { TunnelError } from "./protocol.js";
+import { forwardToHost } from "./forwarding.js";
+import { BROKER_LIMITS, BrokerGuards } from "./limits.js";
+import { BrokerLogger, classifyPath, routeHash } from "./logging.js";
+import { RelayHub } from "./relay.js";
+const DEFAULT_CLAIM_TIMEOUT_MS = 10_000;
+const DEFAULT_RESPONSE_TIMEOUT_MS = 35_000;
+const DEFAULT_ROUTE_TTL_MS = BROKER_LIMITS.idleTimeoutMs;
+const SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const LOCAL_TARGET_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+/**
+ * Validate a forwarding target before the broker will store and fetch it. This
+ * ticket is local-only, so the target must be a loopback http(s) URL. Rejecting
+ * non-local hosts blocks server-side request forgery to internal-network or
+ * cloud-metadata addresses through the unauthenticated register endpoint.
+ * Authenticated host registration and egress allowlists for non-local targets
+ * are deferred to the #37 hardening ticket.
+ */
+function assertLocalTarget(target) {
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        throw new TunnelError("invalid_registration", 400, "target is not a valid URL");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new TunnelError("invalid_registration", 400, "target must use http or https");
+    }
+    if (!LOCAL_TARGET_HOSTS.has(url.hostname)) {
+        throw new TunnelError("invalid_registration", 400, "target must be a local address");
+    }
+}
+/**
+ * In-memory tunnel broker. One active route per slug; routes expire after a TTL
+ * unless refreshed by a heartbeat, and can be closed explicitly by the host.
+ */
+export class TunnelBroker {
+    now;
+    routeTtlMs;
+    maxRouteLifetimeMs;
+    limits;
+    guards;
+    logger;
+    relay;
+    routes = new Map();
+    // Optional local room server URL per slug for direct-fetch mode (local tests).
+    // Managed relay mode registers no target and never stores one.
+    targets = new Map();
+    constructor(options = {}) {
+        this.now = options.now ?? (() => Date.now());
+        this.limits = { ...BROKER_LIMITS, ...options.limits };
+        this.routeTtlMs = options.routeTtlMs ?? this.limits.idleTimeoutMs;
+        this.maxRouteLifetimeMs = options.maxRouteLifetimeMs ?? this.limits.maxRouteLifetimeMs;
+        this.guards = new BrokerGuards(this.now, this.limits);
+        this.logger = new BrokerLogger(options.logSink);
+        this.relay = new RelayHub({
+            claimTimeoutMs: options.claimTimeoutMs ?? DEFAULT_CLAIM_TIMEOUT_MS,
+            responseTimeoutMs: options.responseTimeoutMs ?? DEFAULT_RESPONSE_TIMEOUT_MS,
+            responseBodyBytes: this.limits.responseBodyBytes
+        }, () => mintId("req"));
+    }
+    /** Register a route for a slug. Rejects a duplicate active slug. */
+    register(registration) {
+        const slug = registration.route_slug;
+        if (typeof slug !== "string" || !SLUG_PATTERN.test(slug)) {
+            throw new TunnelError("invalid_registration", 400, "route slug is missing or malformed");
+        }
+        if (registration.target !== undefined)
+            assertLocalTarget(registration.target);
+        const existing = this.currentRoute(slug);
+        if (existing && existing.status === "active") {
+            throw new TunnelError("route_slug_taken", 409, "an active route already exists for this slug");
+        }
+        const nowMs = this.now();
+        const route = {
+            route_slug: slug,
+            route_id: mintId("rte"),
+            host_connection_id: mintId("conn"),
+            created_at: isoFrom(nowMs),
+            last_seen_at: isoFrom(nowMs),
+            expires_at: isoFrom(nowMs + this.routeTtlMs),
+            status: "active"
+        };
+        this.routes.set(slug, route);
+        // Always re-sync the target so a re-registration without a target cannot
+        // inherit a previous route's forwarding host.
+        if (registration.target !== undefined) {
+            this.targets.set(slug, registration.target);
+        }
+        else {
+            this.targets.delete(slug);
+        }
+        return { ...route };
+    }
+    /** Local room server URL a slug forwards to, if one was registered. */
+    target(slug) {
+        return this.targets.get(slug);
+    }
+    /** Refresh an active route's last-seen and expiry timestamps. */
+    heartbeat(beat) {
+        if (typeof beat.route_id !== "string" || typeof beat.host_connection_id !== "string") {
+            throw new TunnelError("invalid_heartbeat", 400, "heartbeat is missing route identifiers");
+        }
+        const route = this.findByConnection(beat.route_id, beat.host_connection_id);
+        if (route.status === "closed") {
+            throw new TunnelError("route_closed", 410, "this route has been closed");
+        }
+        if (route.status === "expired") {
+            throw new TunnelError("route_expired", 410, "this route has expired");
+        }
+        const nowMs = this.now();
+        route.last_seen_at = isoFrom(nowMs);
+        route.expires_at = isoFrom(nowMs + this.routeTtlMs);
+        return { ...route };
+    }
+    /** Close a route. Idempotent identifiers must match the registered route. */
+    closeRoute(request) {
+        const route = this.findByConnection(request.route_id, request.host_connection_id);
+        route.status = "closed";
+        this.targets.delete(route.route_slug);
+        this.relay.closeRoute(route.route_slug);
+        return { ok: true, route_slug: route.route_slug, status: "closed" };
+    }
+    /**
+     * Resolve a participant-facing slug to its active route, or throw a stable
+     * tunnel error. Returns a copy so callers cannot mutate stored metadata.
+     */
+    resolve(slug) {
+        const route = this.currentRoute(slug);
+        if (!route) {
+            throw new TunnelError("route_not_found", 404, "no route is registered for this slug");
+        }
+        if (route.status === "closed") {
+            throw new TunnelError("route_closed", 410, "this route has been closed");
+        }
+        if (route.status === "expired") {
+            throw new TunnelError("route_expired", 410, "this route has expired");
+        }
+        return { ...route };
+    }
+    /** Copy of all stored route metadata, with lazy expiry applied. */
+    snapshot() {
+        return [...this.routes.values()].map((route) => ({ ...this.refresh(route) }));
+    }
+    /** Host claims the next pending relay request for its route, or null. */
+    claimRelay(routeId, hostConnectionId) {
+        const route = this.findByConnection(routeId, hostConnectionId);
+        if (route.status !== "active") {
+            throw new TunnelError(route.status === "closed" ? "route_closed" : "route_expired", 410, "route is not active");
+        }
+        this.touch(route.route_slug);
+        return this.relay.claim(route.route_slug);
+    }
+    /** Host posts the response for exactly one in-flight relay request id. */
+    respondRelay(routeId, hostConnectionId, requestId, response) {
+        this.findByConnection(routeId, hostConnectionId);
+        this.relay.respond(requestId, response);
+    }
+    /**
+     * Forward a participant request under `/<slug>/`, applying concurrency and
+     * rate guards and emitting a redaction-safe access log. A route registered
+     * with a local target is fetched directly (local tests); otherwise the
+     * request is held for the host tunnel client to claim and answer. The caller
+     * must have resolved the slug as an active route first.
+     */
+    async forward(slug, url, req, res) {
+        const forwardPath = url.pathname.slice(`/${slug}`.length) || "/";
+        const pathClass = classifyPath(forwardPath);
+        const isWait = pathClass === "wait";
+        const method = req.method ?? "GET";
+        const startedAt = this.now();
+        let release;
+        try {
+            release = this.guards.enter({
+                routeSlug: slug,
+                clientIp: req.socket.remoteAddress ?? "unknown",
+                isWait,
+                authenticated: typeof req.headers.authorization === "string"
+            });
+        }
+        catch (error) {
+            this.logger.log({ event: "limit_rejected", route_hash: routeHash(slug), method, path_class: pathClass, error: errorCode(error) });
+            throw error;
+        }
+        this.touch(slug);
+        try {
+            const target = this.targets.get(slug);
+            const result = target !== undefined
+                ? await this.forwardDirect(target, forwardPath, url, req, res)
+                : await this.forwardViaRelay(slug, forwardPath, url, req, res);
+            this.logger.log({
+                event: "forward",
+                route_hash: routeHash(slug),
+                method,
+                path_class: pathClass,
+                status: result.status,
+                duration_ms: this.now() - startedAt,
+                bytes_in: result.bytesIn,
+                bytes_out: result.bytesOut,
+                ...(isWait ? { wait_held_ms: this.now() - startedAt } : {})
+            });
+        }
+        catch (error) {
+            this.logger.log({ event: "forward_error", route_hash: routeHash(slug), method, path_class: pathClass, error: errorCode(error) });
+            throw error;
+        }
+        finally {
+            release();
+        }
+    }
+    async forwardDirect(target, forwardPath, url, req, res) {
+        return forwardToHost({
+            target,
+            path: `${forwardPath}${url.search}`,
+            req,
+            res,
+            requestBodyBytes: this.limits.requestBodyBytes,
+            responseBodyBytes: this.limits.responseBodyBytes
+        });
+    }
+    async forwardViaRelay(slug, forwardPath, url, req, res) {
+        const body = await readBody(req, this.limits.requestBodyBytes);
+        const response = await this.relay.enqueue(slug, {
+            route_slug: slug,
+            method: req.method ?? "GET",
+            path: `${forwardPath}${url.search}`,
+            headers: selectEnvelopeHeaders(req),
+            ...(body !== undefined ? { body_base64: body.toString("base64") } : {})
+        });
+        const responseBody = typeof response.body_base64 === "string" ? Buffer.from(response.body_base64, "base64") : Buffer.alloc(0);
+        const responseHeaders = {};
+        const contentType = response.headers["content-type"] ?? response.headers["Content-Type"];
+        if (typeof contentType === "string")
+            responseHeaders["content-type"] = contentType;
+        res.writeHead(response.status, responseHeaders);
+        res.end(responseBody);
+        return { status: response.status, bytesIn: body?.length ?? 0, bytesOut: responseBody.length };
+    }
+    touch(slug) {
+        const route = this.routes.get(slug);
+        if (route && route.status === "active") {
+            const nowMs = this.now();
+            route.last_seen_at = isoFrom(nowMs);
+            route.expires_at = isoFrom(nowMs + this.routeTtlMs);
+        }
+    }
+    currentRoute(slug) {
+        const route = this.routes.get(slug);
+        return route ? this.refresh(route) : undefined;
+    }
+    refresh(route) {
+        if (route.status === "active") {
+            const nowMs = this.now();
+            const idleExpired = Date.parse(route.expires_at) <= nowMs;
+            const lifetimeExceeded = Date.parse(route.created_at) + this.maxRouteLifetimeMs <= nowMs;
+            if (idleExpired || lifetimeExceeded)
+                route.status = "expired";
+        }
+        return route;
+    }
+    findByConnection(routeId, connectionId) {
+        for (const route of this.routes.values()) {
+            if (route.route_id === routeId && route.host_connection_id === connectionId) {
+                return this.refresh(route);
+            }
+        }
+        throw new TunnelError("route_not_found", 404, "no route matches these identifiers");
+    }
+}
+// Reserved path prefix for host control requests. The slug pattern forbids the
+// underscore, so this prefix can never collide with a participant route slug.
+const HOST_PREFIX = "_host";
+const MAX_HOST_CONTROL_BODY_BYTES = 16_000;
+const MAX_HOST_RESPOND_BODY_BYTES = Math.ceil((BROKER_LIMITS.responseBodyBytes * 4) / 3) + 16_000;
+/**
+ * Create a local HTTP listener for the broker. Host control requests use the
+ * reserved `/_host/<action>` prefix (register, heartbeat, close); every other
+ * path is treated as a participant request whose first segment is the route
+ * slug. Active slugs return route status; unknown, expired, or closed slugs
+ * return a stable tunnel error. The listener never forwards to a host room
+ * server in this ticket (forwarding lands with #36).
+ */
+export function createBrokerHttpServer(broker) {
+    return createServer((req, res) => {
+        void routeBrokerRequest(broker, req, res);
+    });
+}
+async function routeBrokerRequest(broker, req, res) {
+    try {
+        const url = new URL(req.url ?? "/", "http://broker.local");
+        const segments = url.pathname.split("/").filter(Boolean);
+        if (segments[0] === HOST_PREFIX) {
+            await handleHostRequest(broker, segments[1], req, res);
+            return;
+        }
+        await handleParticipantRequest(broker, url, req, res);
+    }
+    catch (error) {
+        sendTunnelError(res, error);
+    }
+}
+async function handleParticipantRequest(broker, url, req, res) {
+    const slug = url.pathname.split("/").filter(Boolean)[0];
+    if (slug === undefined) {
+        throw new TunnelError("unsupported_route", 404, "request path does not name a route");
+    }
+    const route = broker.resolve(slug);
+    // A bare `/<slug>` with no trailing slash is a route-status probe; anything
+    // under `/<slug>/` is forwarded to the host room server.
+    if (url.pathname === `/${slug}`) {
+        sendJson(res, 200, { ok: true, route_slug: route.route_slug, status: route.status });
+        return;
+    }
+    await broker.forward(slug, url, req, res);
+}
+async function handleHostRequest(broker, action, req, res) {
+    if (req.method !== "POST") {
+        throw new TunnelError("unsupported_route", 405, "host control requires POST");
+    }
+    const body = await readJsonBody(req, action === "respond" ? MAX_HOST_RESPOND_BODY_BYTES : MAX_HOST_CONTROL_BODY_BYTES);
+    if (action === "register") {
+        const route = broker.register({
+            route_slug: body.route_slug,
+            ...(typeof body.target === "string" ? { target: body.target } : {})
+        });
+        sendJson(res, 200, { ok: true, route });
+        return;
+    }
+    if (action === "heartbeat") {
+        const route = broker.heartbeat({
+            route_id: body.route_id,
+            host_connection_id: body.host_connection_id
+        });
+        sendJson(res, 200, { ok: true, route });
+        return;
+    }
+    if (action === "close") {
+        const result = broker.closeRoute({
+            route_id: body.route_id,
+            host_connection_id: body.host_connection_id
+        });
+        sendJson(res, 200, result);
+        return;
+    }
+    if (action === "poll") {
+        const request = broker.claimRelay(body.route_id, body.host_connection_id);
+        sendJson(res, 200, { ok: true, request });
+        return;
+    }
+    if (action === "respond") {
+        broker.respondRelay(body.route_id, body.host_connection_id, body.request_id, body.response);
+        sendJson(res, 200, { ok: true });
+        return;
+    }
+    throw new TunnelError("unsupported_route", 404, "unknown host control action");
+}
+async function readJsonBody(req, limitBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        total += buffer.length;
+        if (total > limitBytes) {
+            throw new TunnelError("invalid_registration", 413, "host control body is too large");
+        }
+        chunks.push(buffer);
+    }
+    if (total === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function sendTunnelError(res, error) {
+    if (res.headersSent) {
+        res.destroy();
+        return;
+    }
+    if (error instanceof TunnelError) {
+        sendJson(res, error.status, error.body());
+        return;
+    }
+    sendJson(res, 500, { ok: false, error: "internal_error", message: "internal tunnel error" });
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(payload);
+}
+function mintId(prefix) {
+    return `${prefix}_${randomBytes(12).toString("base64url")}`;
+}
+function isoFrom(ms) {
+    return new Date(ms).toISOString();
+}
+function errorCode(error) {
+    return error instanceof TunnelError ? error.code : "internal_error";
+}
+const ENVELOPE_HEADERS = new Set(["authorization", "content-type", "accept", "origin", "referer"]);
+function selectEnvelopeHeaders(req) {
+    const headers = {};
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        const lower = name.toLowerCase();
+        if (ENVELOPE_HEADERS.has(lower))
+            headers[lower] = Array.isArray(value) ? value.join(", ") : value;
+    }
+    return headers;
+}
+async function readBody(req, limitBytes) {
+    const method = req.method ?? "GET";
+    if (method === "GET" || method === "HEAD")
+        return undefined;
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        total += buffer.length;
+        if (total > limitBytes) {
+            throw new TunnelError("request_too_large", 413, "request body exceeds the broker limit");
+        }
+        chunks.push(buffer);
+    }
+    return chunks.length === 0 ? undefined : Buffer.concat(chunks);
+}

package/dist/src/tunnel/client.js

@@ -0,0 +1,144 @@
+// Host tunnel client.
+//
+// Connects a host to a local tunnel broker over HTTP, registers a route for a
+// room slug, and records the resulting public base URL on disk so the running
+// room server and the CLI can advertise it. The host tunnel session is kept
+// distinct from participant tokens: the broker-minted host_connection_id is a
+// routing credential, never a participant bearer token.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { ensureSecureDir, writeSecureFile } from "../storage/index.js";
+import { normalizeBaseUrl, roomUrl } from "../protocol/index.js";
+import { relayToLocalServer } from "./forwarding.js";
+import { TunnelError } from "./protocol.js";
+const RELAY_RESPONSE_BODY_BYTES = 1024 * 1024;
+/** HTTP client for a local tunnel broker's host control endpoints. */
+export class TunnelClient {
+    brokerBaseUrl;
+    constructor(brokerBaseUrl) {
+        this.brokerBaseUrl = normalizeBaseUrl(brokerBaseUrl);
+    }
+    /** Register a route for a slug and compute its public base URL. */
+    async register(slug, target) {
+        const payload = await this.post("/_host/register", {
+            route_slug: slug,
+            ...(target === undefined ? {} : { target })
+        });
+        const route = payload.route;
+        return { route, publicBaseUrl: this.publicBaseUrlFor(route.route_slug) };
+    }
+    /** Refresh a route to keep the host session alive. */
+    async heartbeat(routeId, hostConnectionId) {
+        const payload = await this.post("/_host/heartbeat", {
+            route_id: routeId,
+            host_connection_id: hostConnectionId
+        });
+        return payload.route;
+    }
+    /** Close a route the host owns. */
+    async close(routeId, hostConnectionId) {
+        const payload = await this.post("/_host/close", {
+            route_id: routeId,
+            host_connection_id: hostConnectionId
+        });
+        return payload;
+    }
+    /** Claim the next pending relay request for the route, or null if none. */
+    async poll(routeId, hostConnectionId) {
+        const payload = await this.post("/_host/poll", { route_id: routeId, host_connection_id: hostConnectionId });
+        return payload.request ?? null;
+    }
+    /** Post the response for exactly one in-flight relay request id. */
+    async respond(routeId, hostConnectionId, requestId, response) {
+        await this.post("/_host/respond", {
+            route_id: routeId,
+            host_connection_id: hostConnectionId,
+            request_id: requestId,
+            response
+        });
+    }
+    /**
+     * Attend the route once: claim a pending request, forward it to the local
+     * room server, and post the response back. Returns true if a request was
+     * handled, false if none were pending. This is the host outbound relay step;
+     * the broker never reaches the local server itself.
+     */
+    async attendOnce(routeId, hostConnectionId, target) {
+        const request = await this.poll(routeId, hostConnectionId);
+        if (request === null)
+            return false;
+        await this.handleClaim(routeId, hostConnectionId, request, target);
+        return true;
+    }
+    /**
+     * Forward an already-claimed request to the local room server and post the
+     * response. Failures become a stable error response so the participant never
+     * hangs. Used by the foreground run loop to process claims concurrently.
+     */
+    async handleClaim(routeId, hostConnectionId, request, target) {
+        let response;
+        try {
+            response = await relayToLocalServer(target, request, RELAY_RESPONSE_BODY_BYTES);
+        }
+        catch (error) {
+            response = {
+                status: error instanceof TunnelError ? error.status : 502,
+                headers: { "content-type": "application/json; charset=utf-8" },
+                body_base64: Buffer.from(JSON.stringify({ ok: false, error: error instanceof TunnelError ? error.code : "host_unavailable" })).toString("base64")
+            };
+        }
+        await this.respond(routeId, hostConnectionId, request.request_id, response);
+    }
+    publicBaseUrlFor(slug) {
+        return normalizeBaseUrl(roomUrl(this.brokerBaseUrl, slug));
+    }
+    async post(action, body) {
+        let response;
+        try {
+            response = await fetch(new URL(action, `${this.brokerBaseUrl}/`), {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body)
+            });
+        }
+        catch {
+            throw new TunnelError("route_not_found", 502, "could not reach the tunnel broker");
+        }
+        const payload = await readJson(response);
+        if (!response.ok || payload.ok === false) {
+            const error = payload;
+            throw new TunnelError(error.error ?? "internal_error", response.status, typeof error.message === "string" ? error.message : "tunnel broker rejected the request");
+        }
+        return payload;
+    }
+}
+async function readJson(response) {
+    try {
+        const parsed = JSON.parse(await response.text());
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function tunnelStatePath(home, roomId) {
+    return path.join(home, "rooms", roomId, "tunnel.json");
+}
+export async function writeHostTunnelState(home, roomId, state) {
+    const file = tunnelStatePath(home, roomId);
+    await ensureSecureDir(path.dirname(file));
+    await writeSecureFile(file, `${JSON.stringify(state, null, 2)}\n`);
+}
+/**
+ * Read the published public base URL for a room, or undefined if no tunnel has
+ * been started. Synchronous so the room server can resolve it per request.
+ */
+export function readPublicBaseUrl(home, roomId) {
+    try {
+        const state = JSON.parse(readFileSync(tunnelStatePath(home, roomId), "utf8"));
+        return typeof state.public_base_url === "string" ? state.public_base_url : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}