agentgather 0.1.0

package/dist/src/tunnel/forwarding.js

@@ -0,0 +1,176 @@
+// Broker forwarding core.
+//
+// Forwards a participant request from the broker to the host room server and
+// streams the response back. The host room server stays the only authority for
+// participant tokens and sender identity: this module never injects a `from`
+// field and never inspects or stores request/response bodies. Long-poll `/wait`
+// responses are streamed, not buffered to completion. Request and forwarded
+// response sizes are capped per the broker resource limits.
+import { once } from "node:events";
+import { Readable } from "node:stream";
+import { URL } from "node:url";
+import { normalizeBaseUrl } from "../protocol/index.js";
+import { TunnelError } from "./protocol.js";
+// Request headers passed through to the host. The Authorization header carries
+// the participant token the host uses to derive sender identity. Origin and
+// Referer are translated to the host origin so the host's same-origin checks
+// stay correct for remote POSTs. Hop-by-hop and host-identifying headers are
+// dropped.
+const FORWARDED_REQUEST_HEADERS = new Set(["authorization", "content-type", "accept"]);
+/**
+ * Forward a single participant request to the host room server. Throws a
+ * TunnelError (before any response is written) when the host is unreachable or
+ * the request body is too large; once the response stream begins, transport
+ * failures or an over-limit response just close the socket.
+ */
+export async function forwardToHost(options) {
+    const targetBase = normalizeBaseUrl(options.target);
+    const targetUrl = `${targetBase}${options.path.startsWith("/") ? options.path : `/${options.path}`}`;
+    const method = options.req.method ?? "GET";
+    const headers = selectRequestHeaders(options.req, new URL(targetBase).origin);
+    const body = await readRequestBody(options.req, method, options.requestBodyBytes);
+    const bytesIn = body?.length ?? 0;
+    const init = { method, headers, redirect: "manual" };
+    if (body !== undefined)
+        init.body = new Uint8Array(body);
+    let response;
+    try {
+        response = await fetch(targetUrl, init);
+    }
+    catch {
+        throw new TunnelError("internal_error", 502, "could not reach the host room server");
+    }
+    // When the host declares an over-limit content-length we can still reject
+    // cleanly with a stable error before committing any upstream headers.
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > options.responseBodyBytes) {
+        throw new TunnelError("response_too_large", 502, "forwarded response exceeds the broker limit");
+    }
+    const responseHeaders = {};
+    const contentType = response.headers.get("content-type");
+    if (contentType !== null)
+        responseHeaders["content-type"] = contentType;
+    options.res.writeHead(response.status, responseHeaders);
+    const bytesOut = await streamResponse(response, options.res, options.responseBodyBytes);
+    return { status: response.status, bytesIn, bytesOut };
+}
+async function streamResponse(response, res, responseBodyBytes) {
+    if (response.body === null) {
+        res.end();
+        return 0;
+    }
+    // Stream the body through without buffering it to completion, so held /wait
+    // responses are released as soon as the host responds. If a body with no (or
+    // an understated) content-length grows past the cap, headers are already
+    // committed, so we destroy the socket and throw response_too_large — the
+    // caller logs it as a limit failure rather than a successful forward.
+    const source = Readable.fromWeb(response.body);
+    let bytesOut = 0;
+    let overflow = false;
+    try {
+        for await (const chunk of source) {
+            const buffer = chunk;
+            bytesOut += buffer.length;
+            if (bytesOut > responseBodyBytes) {
+                overflow = true;
+                source.destroy();
+                break;
+            }
+            if (!res.write(buffer))
+                await once(res, "drain");
+        }
+    }
+    catch {
+        res.destroy();
+        return bytesOut;
+    }
+    if (overflow) {
+        res.destroy();
+        throw new TunnelError("response_too_large", 502, "forwarded response exceeds the broker limit");
+    }
+    res.end();
+    return bytesOut;
+}
+/**
+ * Host-side relay step: apply a claimed forwarded request to the local room
+ * server and build a response envelope. Used by the host tunnel client (and by
+ * relay tests). Origin/Referer are translated to the host origin so same-origin
+ * checks pass; the response body is buffered (capped) into base64 for return.
+ */
+export async function relayToLocalServer(target, request, responseBodyBytes) {
+    const targetBase = normalizeBaseUrl(target);
+    const targetUrl = `${targetBase}${request.path.startsWith("/") ? request.path : `/${request.path}`}`;
+    const headers = translateEnvelopeHeaders(request.headers, new URL(targetBase).origin);
+    const init = { method: request.method, headers, redirect: "manual" };
+    if (request.body_base64 !== undefined && request.method !== "GET" && request.method !== "HEAD") {
+        init.body = new Uint8Array(Buffer.from(request.body_base64, "base64"));
+    }
+    let response;
+    try {
+        response = await fetch(targetUrl, init);
+    }
+    catch {
+        throw new TunnelError("host_unavailable", 502, "host room server is unreachable");
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.length > responseBodyBytes) {
+        throw new TunnelError("response_too_large", 502, "host response exceeds the broker limit");
+    }
+    const responseHeaders = {};
+    const contentType = response.headers.get("content-type");
+    if (contentType !== null)
+        responseHeaders["content-type"] = contentType;
+    const result = { status: response.status, headers: responseHeaders };
+    if (buffer.length > 0)
+        result.body_base64 = buffer.toString("base64");
+    return result;
+}
+function translateEnvelopeHeaders(headers, targetOrigin) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        if (lower === "origin") {
+            result.origin = targetOrigin;
+        }
+        else if (lower === "referer") {
+            result.referer = `${targetOrigin}/`;
+        }
+        else if (FORWARDED_REQUEST_HEADERS.has(lower)) {
+            result[lower] = value;
+        }
+    }
+    return result;
+}
+function selectRequestHeaders(req, targetOrigin) {
+    const headers = {};
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        const lower = name.toLowerCase();
+        if (FORWARDED_REQUEST_HEADERS.has(lower)) {
+            headers[lower] = Array.isArray(value) ? value.join(", ") : value;
+        }
+    }
+    // Translate browser-supplied origin/referer to the host origin so same-origin
+    // protections pass through the tunnel without trusting a client-supplied from.
+    if (req.headers.origin !== undefined)
+        headers.origin = targetOrigin;
+    if (req.headers.referer !== undefined)
+        headers.referer = `${targetOrigin}/`;
+    return headers;
+}
+async function readRequestBody(req, method, limitBytes) {
+    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/host-session.js

@@ -0,0 +1,133 @@
+// Foreground host tunnel session.
+//
+// Keeps a local room attached to the managed broker: a heartbeat loop holds the
+// route, and a single poll loop claims relay requests and dispatches them to a
+// bounded number of concurrent handlers. Bounded concurrency matters because a
+// claimed `/wait` can hold for ~25s; a serial loop would starve normal card,
+// message, and asset requests behind it.
+import { TunnelError } from "./protocol.js";
+const DEFAULT_CONCURRENCY = 16;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 10_000;
+const DEFAULT_POLL_INTERVAL_MS = 50;
+// A poll failure with one of these codes means the route is gone for good.
+const FATAL_POLL_CODES = new Set(["route_closed", "route_expired", "route_not_found"]);
+export class HostTunnelSession {
+    client;
+    routeId;
+    hostConnectionId;
+    target;
+    concurrency;
+    heartbeatIntervalMs;
+    pollIntervalMs;
+    onError;
+    controller = new AbortController();
+    handlers = new Set();
+    heartbeatTimer;
+    pollLoop;
+    stopped = false;
+    failureError;
+    constructor(client, options) {
+        this.client = client;
+        this.routeId = options.routeId;
+        this.hostConnectionId = options.hostConnectionId;
+        this.target = options.target;
+        this.concurrency = Math.max(2, options.concurrency ?? DEFAULT_CONCURRENCY);
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.onError = options.onError;
+    }
+    /** The first fatal error that shut the session down, if any. */
+    get failure() {
+        return this.failureError;
+    }
+    start() {
+        this.heartbeatTimer = setInterval(() => void this.beat(), this.heartbeatIntervalMs);
+        this.pollLoop = this.runPollLoop();
+    }
+    async stop(options = {}) {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.controller.abort();
+        if (this.heartbeatTimer !== undefined)
+            clearInterval(this.heartbeatTimer);
+        if (this.pollLoop !== undefined)
+            await this.pollLoop;
+        await Promise.allSettled([...this.handlers]);
+        if (options.closeRoute === true) {
+            try {
+                await this.client.close(this.routeId, this.hostConnectionId);
+            }
+            catch {
+                // Best effort: the route may already be closed or expired.
+            }
+        }
+    }
+    async runPollLoop() {
+        while (!this.controller.signal.aborted) {
+            if (this.handlers.size >= this.concurrency) {
+                await this.idle(this.pollIntervalMs);
+                continue;
+            }
+            let request;
+            try {
+                request = await this.client.poll(this.routeId, this.hostConnectionId);
+            }
+            catch (error) {
+                if (error instanceof TunnelError && FATAL_POLL_CODES.has(error.code)) {
+                    this.fail(error);
+                    return;
+                }
+                await this.idle(this.pollIntervalMs);
+                continue;
+            }
+            if (request === null) {
+                await this.idle(this.pollIntervalMs);
+                continue;
+            }
+            const handler = this.handle(request);
+            this.handlers.add(handler);
+            void handler.finally(() => this.handlers.delete(handler));
+        }
+    }
+    async handle(request) {
+        try {
+            await this.client.handleClaim(this.routeId, this.hostConnectionId, request, this.target);
+        }
+        catch {
+            // The request may have already settled (closed/timed out); nothing to do.
+        }
+    }
+    async beat() {
+        if (this.controller.signal.aborted)
+            return;
+        try {
+            await this.client.heartbeat(this.routeId, this.hostConnectionId);
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    fail(error) {
+        if (this.failureError === undefined)
+            this.failureError = error;
+        this.controller.abort();
+        this.onError?.(error);
+    }
+    idle(ms) {
+        return new Promise((resolve) => {
+            const signal = this.controller.signal;
+            if (signal.aborted) {
+                resolve();
+                return;
+            }
+            const done = () => {
+                clearTimeout(timer);
+                signal.removeEventListener("abort", done);
+                resolve();
+            };
+            const timer = setTimeout(done, ms);
+            signal.addEventListener("abort", done, { once: true });
+        });
+    }
+}

package/dist/src/tunnel/index.js

@@ -0,0 +1,8 @@
+export * from "./protocol.js";
+export * from "./broker.js";
+export * from "./client.js";
+export * from "./forwarding.js";
+export * from "./limits.js";
+export * from "./logging.js";
+export * from "./relay.js";
+export * from "./host-session.js";

package/dist/src/tunnel/limits.js

@@ -0,0 +1,81 @@
+// Prototype broker resource limits and abuse controls.
+//
+// These are local prototype guards, not a production WAF. They cap concurrency,
+// request/response size, route lifetime, and request rate so managed tunnel
+// routing can be exercised without runaway resource use. Limit errors carry
+// stable codes and generic messages — never raw request details.
+import { TunnelError } from "./protocol.js";
+export const BROKER_LIMITS = {
+    hostConnectionsPerRoute: 1,
+    concurrentRequestsPerRoute: 64,
+    concurrentWaitsPerRoute: 32,
+    requestBodyBytes: 64 * 1024,
+    responseBodyBytes: 1024 * 1024,
+    idleTimeoutMs: 15 * 60_000,
+    maxRouteLifetimeMs: 8 * 60 * 60_000,
+    unauthenticatedPerIpPerMinute: 60,
+    requestsPerRoutePerMinute: 600
+};
+const RATE_WINDOW_MS = 60_000;
+/**
+ * Tracks per-route concurrency and per-route / per-IP request rate. `enter`
+ * admits a request or throws a stable limit error; it returns a release handle
+ * that the caller must invoke when the request completes.
+ */
+export class BrokerGuards {
+    now;
+    limits;
+    inflight = new Map();
+    routeRate = new Map();
+    ipRate = new Map();
+    constructor(now, limits = BROKER_LIMITS) {
+        this.now = now;
+        this.limits = limits;
+    }
+    enter(input) {
+        this.admitRate(this.routeRate, input.routeSlug, this.limits.requestsPerRoutePerMinute, "rate_limited");
+        if (!input.authenticated) {
+            this.admitRate(this.ipRate, input.clientIp, this.limits.unauthenticatedPerIpPerMinute, "rate_limited");
+        }
+        const counts = this.inflight.get(input.routeSlug) ?? { total: 0, waits: 0 };
+        if (counts.total >= this.limits.concurrentRequestsPerRoute) {
+            throw limitError("route_request_limit", "too many concurrent requests for this route");
+        }
+        if (input.isWait && counts.waits >= this.limits.concurrentWaitsPerRoute) {
+            throw limitError("wait_limit", "too many concurrent wait requests for this route");
+        }
+        counts.total += 1;
+        if (input.isWait)
+            counts.waits += 1;
+        this.inflight.set(input.routeSlug, counts);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const current = this.inflight.get(input.routeSlug);
+            if (current === undefined)
+                return;
+            current.total = Math.max(0, current.total - 1);
+            if (input.isWait)
+                current.waits = Math.max(0, current.waits - 1);
+            if (current.total === 0 && current.waits === 0)
+                this.inflight.delete(input.routeSlug);
+        };
+    }
+    admitRate(windows, key, perMinute, code) {
+        const nowMs = this.now();
+        const window = windows.get(key);
+        if (window === undefined || nowMs >= window.resetAt) {
+            windows.set(key, { resetAt: nowMs + RATE_WINDOW_MS, count: 1 });
+            return;
+        }
+        if (window.count >= perMinute) {
+            throw limitError(code, "request rate limit exceeded");
+        }
+        window.count += 1;
+    }
+}
+export function limitError(code, message) {
+    return new TunnelError(code, code === "request_too_large" ? 413 : 429, message);
+}

package/dist/src/tunnel/logging.js

@@ -0,0 +1,70 @@
+// Broker structured logging with deny-by-default redaction.
+//
+// The broker must never log secrets or room content. This module emits only a
+// fixed allowlist of coarse, safe fields. It never accepts headers, bodies,
+// tokens, query strings, or full paths: callers pass a derived path class and a
+// route hash, and the emitter copies only known-safe keys onto the record.
+import { createHash } from "node:crypto";
+// Only these keys are ever emitted. Anything else a caller attaches is dropped.
+const ALLOWED_FIELDS = [
+    "event",
+    "route_hash",
+    "method",
+    "path_class",
+    "status",
+    "duration_ms",
+    "bytes_in",
+    "bytes_out",
+    "wait_held_ms",
+    "error"
+];
+/** Default sink: structured JSON line to stderr. */
+export const stderrLogSink = (record) => {
+    process.stderr.write(`${JSON.stringify(record)}\n`);
+};
+export class BrokerLogger {
+    sink;
+    constructor(sink = stderrLogSink) {
+        this.sink = sink;
+    }
+    log(fields) {
+        const record = {};
+        for (const key of ALLOWED_FIELDS) {
+            const value = fields[key];
+            if (value !== undefined)
+                record[key] = value;
+        }
+        this.sink(record);
+    }
+}
+/** Stable, non-reversible identifier for a route slug, safe to log. */
+export function routeHash(slug) {
+    return createHash("sha256").update(slug).digest("hex").slice(0, 12);
+}
+const PATH_CLASSES = new Set([
+    "room.css",
+    "room.js",
+    "brief",
+    "attendance",
+    "status",
+    "messages",
+    "wait",
+    "card",
+    "profile",
+    "join",
+    "leave",
+    "close"
+]);
+/**
+ * Reduce a forwarded path to a coarse class with no query string, parameters,
+ * or identifiers. Unknown paths collapse to "other" so nothing sensitive leaks.
+ */
+export function classifyPath(pathname) {
+    const withoutQuery = pathname.split("?", 1)[0] ?? "/";
+    const first = withoutQuery.split("/").filter(Boolean)[0];
+    if (first === undefined)
+        return "shell";
+    if (first === "room.css" || first === "room.js")
+        return "asset";
+    return PATH_CLASSES.has(first) ? first : "other";
+}

package/dist/src/tunnel/protocol.js

@@ -0,0 +1,46 @@
+// Local tunnel protocol for managed agentgather.dev routing.
+//
+// This module defines the wire shapes exchanged between a host tunnel client,
+// the routing broker, and remote participants. It is transport-agnostic and
+// local-only: later tickets (#35 host client, #36 forwarding core) implement
+// real forwarding against these types. Nothing here opens a public network
+// connection or requires credentials.
+/**
+ * Error raised by broker operations. Carries a stable code and the HTTP status
+ * the participant listener should return. Messages are intentionally generic so
+ * they never leak raw request URLs or tokens.
+ */
+export class TunnelError extends Error {
+    code;
+    status;
+    constructor(code, status, message) {
+        super(message);
+        this.name = "TunnelError";
+        this.code = code;
+        this.status = status;
+    }
+    body() {
+        return { ok: false, error: this.code, message: this.message };
+    }
+}
+/** Header names stripped before any tunnel-layer logging or metrics. */
+const SENSITIVE_HEADERS = new Set([
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "proxy-authorization"
+]);
+/**
+ * Remove credential-bearing headers from a forwarded header map so tunnel logs
+ * and metrics can never capture participant tokens. Pure; returns a new map and
+ * does not mutate the input.
+ */
+export function redactHeaders(headers) {
+    const safe = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (SENSITIVE_HEADERS.has(name.toLowerCase()))
+            continue;
+        safe[name] = value;
+    }
+    return safe;
+}

package/dist/src/tunnel/relay.js

@@ -0,0 +1,106 @@
+// Host-connected relay queue.
+//
+// In managed mode the broker cannot reach the host's private room server. A
+// participant request becomes a bounded in-flight forwarded request: the broker
+// holds it in memory, the host tunnel client claims it over an outbound poll,
+// forwards it to its local room server, and posts the response back. Bodies live
+// only in memory while in flight and are never persisted or logged here.
+import { TunnelError } from "./protocol.js";
+/**
+ * Tracks in-flight participant requests waiting for a host relay response. One
+ * hub serves all routes; requests are keyed by a broker-minted request id.
+ */
+export class RelayHub {
+    options;
+    mintId;
+    pending = new Map();
+    inflight = new Map();
+    constructor(options, mintId) {
+        this.options = options;
+        this.mintId = mintId;
+    }
+    /** Enqueue a participant request and resolve once the host responds. */
+    enqueue(slug, envelope) {
+        const requestId = this.mintId();
+        const full = { ...envelope, request_id: requestId };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.fail(requestId, new TunnelError("host_unavailable", 504, "host tunnel did not attend the request"));
+            }, this.options.claimTimeoutMs);
+            timer.unref();
+            this.inflight.set(requestId, { envelope: full, slug, resolve, reject, claimed: false, timer });
+            const queue = this.pending.get(slug) ?? [];
+            queue.push(requestId);
+            this.pending.set(slug, queue);
+        });
+    }
+    /** Host claims the next pending request for a route, or null if none. */
+    claim(slug) {
+        const queue = this.pending.get(slug);
+        while (queue !== undefined && queue.length > 0) {
+            const requestId = queue.shift();
+            if (requestId === undefined)
+                break;
+            const item = this.inflight.get(requestId);
+            if (item === undefined || item.claimed)
+                continue;
+            item.claimed = true;
+            clearTimeout(item.timer);
+            item.timer = setTimeout(() => {
+                this.fail(requestId, new TunnelError("host_unavailable", 504, "host tunnel did not respond in time"));
+            }, this.options.responseTimeoutMs);
+            item.timer.unref();
+            if (queue.length === 0)
+                this.pending.delete(slug);
+            return item.envelope;
+        }
+        if (queue !== undefined && queue.length === 0)
+            this.pending.delete(slug);
+        return null;
+    }
+    /** Host posts the response for exactly one in-flight request id. */
+    respond(requestId, response) {
+        const item = this.inflight.get(requestId);
+        if (item === undefined) {
+            throw new TunnelError("unknown_request", 404, "no in-flight request for this id");
+        }
+        const bodyBytes = typeof response.body_base64 === "string" ? Buffer.byteLength(response.body_base64, "base64") : 0;
+        if (bodyBytes > this.options.responseBodyBytes) {
+            this.fail(requestId, new TunnelError("response_too_large", 502, "forwarded response exceeds the broker limit"));
+            throw new TunnelError("response_too_large", 502, "forwarded response exceeds the broker limit");
+        }
+        clearTimeout(item.timer);
+        this.remove(requestId);
+        item.resolve(response);
+    }
+    /** Reject every in-flight request for a closed route. */
+    closeRoute(slug) {
+        for (const [requestId, item] of [...this.inflight]) {
+            if (item.slug === slug) {
+                this.fail(requestId, new TunnelError("route_closed", 410, "this route has been closed"));
+            }
+        }
+    }
+    fail(requestId, error) {
+        const item = this.inflight.get(requestId);
+        if (item === undefined)
+            return;
+        clearTimeout(item.timer);
+        this.remove(requestId);
+        item.reject(error);
+    }
+    remove(requestId) {
+        const item = this.inflight.get(requestId);
+        this.inflight.delete(requestId);
+        if (item === undefined)
+            return;
+        const queue = this.pending.get(item.slug);
+        if (queue === undefined)
+            return;
+        const index = queue.indexOf(requestId);
+        if (index >= 0)
+            queue.splice(index, 1);
+        if (queue.length === 0)
+            this.pending.delete(item.slug);
+    }
+}