@sequenceholdings/artifact-studio 0.2.6 → 0.3.0

package/dist/tunnel/broker.js

@@ -0,0 +1,451 @@
+import { WebSocketServer } from 'ws';
+import { TunnelPeer, tunnelLimits } from './peer.js';
+import { assertSafeRequest, encodeTunnelFrame, normalizePublicOrigin, sanitizeRequestHeaders, sanitizeResponseHeaders, TUNNEL_PROTOCOL } from './protocol.js';
+import { forwardWebSocketMessages, MessageBudget, permittedCloseCode, sendWebSocket, WebSocketMessage, writeChunk } from './io.js';
+function rejectUpgrade(socket, status) {
+    socket.end(`HTTP/1.1 ${status} ${status === 403 ? 'Forbidden' : 'Service Unavailable'}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+}
+function rejectHttp(response, status) {
+    if (response.headersSent) {
+        response.destroy();
+        return;
+    }
+    response.writeHead(status, { 'cache-control': 'no-store', 'content-type': 'application/json' });
+    response.end(JSON.stringify({ error: status === 403 ? 'Preview access denied' : 'Development server unavailable' }));
+}
+function preserveGatewayCookies({ response, headers }) {
+    const gateway = response.getHeader('set-cookie');
+    const application = headers['set-cookie'];
+    if (gateway === undefined || application === undefined)
+        return;
+    // Reserved names were removed from application cookies by the sanitizer.
+    // Use a new array: appendHeader mutates the gateway's existing cookie array.
+    headers['set-cookie'] = [
+        ...(Array.isArray(gateway) ? gateway : [String(gateway)]),
+        ...(Array.isArray(application) ? application : [application]),
+    ];
+}
+/** Transport only: all identity, cookie bootstrap and FGA checks belong to the
+ * mandatory Atlas callbacks. An unconfigured broker cannot accept connections. */
+export class ArtifactTunnelBroker {
+    options;
+    connections = new Map();
+    limits;
+    tunnels;
+    pendingConnections = new Map();
+    ownerTimers = new Set();
+    closing = false;
+    constructor(options) {
+        this.options = options;
+        if (!options.nodeId || !options.routing || !options.authorizeTunnel || !options.authorizeRequest || !options.validateLease) {
+            throw new Error('Atlas authorization and ownership routing are required');
+        }
+        this.limits = tunnelLimits(options.limits);
+        if (Boolean(options.relay) !== Boolean(options.resolveLease))
+            throw new Error('Distributed relay requires lease resolution');
+        this.tunnels = new WebSocketServer({ noServer: true, maxPayload: this.limits.maxFrameBytes, perMessageDeflate: false });
+    }
+    async handleTunnelUpgrade(request, socket, head) {
+        socket.pause();
+        let lease = null;
+        let claimed = false;
+        try {
+            if (this.closing) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
+            if (request.headers['sec-websocket-protocol'] !== TUNNEL_PROTOCOL) {
+                rejectUpgrade(socket, 403);
+                return;
+            }
+            lease = await this.options.authorizeTunnel(request);
+            if (!lease || !Number.isSafeInteger(lease.epoch) || lease.epoch < 1 || lease.expiresAt <= Date.now() ||
+                !lease.ownerId || !lease.projectId || !lease.environment || !lease.sessionId || !(await this.options.validateLease(lease))) {
+                rejectUpgrade(socket, 403);
+                return;
+            }
+            lease.publicOrigin = normalizePublicOrigin(lease.publicOrigin);
+            if (request.headers['x-artifact-session-id'] !== lease.sessionId || request.headers['x-artifact-tunnel-epoch'] !== String(lease.epoch)) {
+                rejectUpgrade(socket, 403);
+                return;
+            }
+            claimed = await this.options.routing.claim(lease, this.options.nodeId);
+            const owner = await this.options.routing.lookup(lease.sessionId);
+            if (!claimed || owner?.nodeId !== this.options.nodeId || owner.epoch !== lease.epoch || socket.destroyed) {
+                rejectUpgrade(socket, 403);
+                return;
+            }
+            const authorizedLease = lease;
+            this.tunnels.handleUpgrade(request, socket, head, (websocket) => {
+                const ready = () => websocket.send(encodeTunnelFrame({ type: 'ready', id: authorizedLease.sessionId, epoch: authorizedLease.epoch }));
+                websocket.once('close', () => this.options.onTunnelClosed?.(authorizedLease));
+                if (this.options.relay) {
+                    void this.options.relay.attach(authorizedLease, websocket).then(() => {
+                        if (this.closing) {
+                            websocket.terminate();
+                            return;
+                        }
+                        let checking = false;
+                        const timer = setInterval(() => {
+                            if (authorizedLease.expiresAt <= Date.now()) {
+                                websocket.terminate();
+                                return;
+                            }
+                            if (checking)
+                                return;
+                            checking = true;
+                            void this.options.validateLease(authorizedLease).then((valid) => {
+                                if (!valid)
+                                    websocket.terminate();
+                            }).catch(() => websocket.terminate()).finally(() => { checking = false; });
+                        }, Math.min(5_000, Math.max(1, authorizedLease.expiresAt - Date.now())));
+                        timer.unref();
+                        this.ownerTimers.add(timer);
+                        websocket.once('close', () => { clearInterval(timer); this.ownerTimers.delete(timer); });
+                        ready();
+                    }).catch(() => websocket.terminate());
+                }
+                else {
+                    this.attach(authorizedLease, websocket);
+                    ready();
+                }
+            });
+            socket.resume();
+        }
+        catch {
+            rejectUpgrade(socket, 403);
+            if (claimed && lease)
+                await this.options.routing.release(lease.sessionId, lease.epoch, this.options.nodeId).catch(() => undefined);
+        }
+    }
+    async handleHttp(request, response, sessionId) {
+        let connection;
+        let id;
+        try {
+            const authorized = await this.authorize(request, sessionId);
+            if (!authorized) {
+                rejectHttp(response, 403);
+                return;
+            }
+            connection = authorized.connection;
+            if (!connection) {
+                rejectHttp(response, 503);
+                return;
+            }
+            id = connection.peer.open();
+            const streamId = id;
+            const active = connection;
+            const timer = setTimeout(() => this.abort(active, streamId, 504), this.limits.requestTimeoutMs);
+            timer.unref();
+            connection.streams.set(id, {
+                request, response, timer, bytes: 0, receivedHeaders: false,
+                message: new WebSocketMessage(this.limits.maxWebSocketMessageBytes, connection.messageBudget),
+            });
+            response.once('close', () => { if (!response.writableFinished)
+                this.abort(active, streamId); });
+            request.once('aborted', () => this.abort(active, streamId));
+            await connection.peer.send({ type: 'request', id, method: request.method ?? 'GET', path: request.url ?? '/', headers: authorized.headers, websocket: false });
+            let total = 0;
+            for await (const chunk of request) {
+                const bytes = Buffer.from(chunk);
+                total += bytes.length;
+                if (total > this.limits.maxBodyBytes) {
+                    this.abort(connection, id, 413);
+                    return;
+                }
+                await connection.peer.data(id, bytes);
+            }
+            if (connection.streams.has(id))
+                await connection.peer.send({ type: 'end', id });
+        }
+        catch {
+            if (connection && id)
+                this.abort(connection, id);
+            else
+                rejectHttp(response, 403);
+        }
+    }
+    async handleWebSocketUpgrade(request, socket, head, sessionId) {
+        socket.pause();
+        try {
+            const authorized = await this.authorize(request, sessionId);
+            if (!authorized) {
+                rejectUpgrade(socket, 403);
+                return;
+            }
+            const connection = authorized.connection;
+            if (!connection) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
+            const id = connection.peer.open();
+            const timer = setTimeout(() => this.abort(connection, id), this.limits.requestTimeoutMs);
+            timer.unref();
+            connection.streams.set(id, {
+                request, upgrade: { socket, head }, timer, bytes: 0, receivedHeaders: false,
+                message: new WebSocketMessage(this.limits.maxWebSocketMessageBytes, connection.messageBudget),
+            });
+            socket.once('close', () => this.abort(connection, id));
+            await connection.peer.send({ type: 'request', id, method: 'GET', path: request.url ?? '/', headers: authorized.headers, websocket: true });
+        }
+        catch {
+            rejectUpgrade(socket, 403);
+        }
+    }
+    async authorize(request, sessionId) {
+        assertSafeRequest(request.method ?? 'GET', request.url ?? '/');
+        const authorization = await this.options.authorizeRequest(request, sessionId);
+        if (!authorization)
+            return null;
+        const origin = normalizePublicOrigin(authorization.publicOrigin);
+        if (request.headers.host !== new URL(origin).host)
+            return null;
+        if (!['GET', 'HEAD', 'OPTIONS'].includes(request.method ?? 'GET') && request.headers.origin !== origin)
+            return null;
+        const headers = sanitizeRequestHeaders(request.headers, origin);
+        if (authorization.requestContext) {
+            if (/[\r\n]/.test(authorization.requestContext))
+                return null;
+            headers['x-sequence-artifact-context'] = authorization.requestContext;
+        }
+        let connection = this.connections.get(sessionId);
+        if (this.options.relay && this.options.resolveLease) {
+            const lease = await this.options.resolveLease(sessionId);
+            if (!lease)
+                return { headers };
+            if (lease.ownerId !== authorization.ownerId || normalizePublicOrigin(lease.publicOrigin) !== origin || !(await this.options.validateLease(lease)))
+                return null;
+            if (!connection || connection.lease.epoch !== lease.epoch)
+                connection = await this.remoteConnection(lease);
+            else
+                connection.lease.expiresAt = lease.expiresAt;
+        }
+        if (!connection)
+            return { headers };
+        if (connection.lease.ownerId !== authorization.ownerId || connection.lease.publicOrigin !== origin || !(await this.valid(connection)))
+            return null;
+        return { connection, headers };
+    }
+    async valid(connection) {
+        const owner = await this.options.routing.lookup(connection.lease.sessionId);
+        if (this.options.resolveLease) {
+            const lease = await this.options.resolveLease(connection.lease.sessionId);
+            if (lease?.epoch === connection.lease.epoch)
+                connection.lease.expiresAt = lease.expiresAt;
+        }
+        return connection.lease.expiresAt > Date.now() && Boolean(owner) && (Boolean(this.options.relay) || owner?.nodeId === this.options.nodeId) && owner?.epoch === connection.lease.epoch &&
+            await this.options.validateLease(connection.lease);
+    }
+    async remoteConnection(lease) {
+        const key = `${lease.sessionId}:${lease.epoch}`;
+        const pending = this.pendingConnections.get(key);
+        if (pending)
+            return pending;
+        const connecting = (async () => {
+            const socket = await this.options.relay.connect(lease);
+            if (this.closing) {
+                socket.terminate();
+                throw new Error('Gateway shutting down');
+            }
+            const connection = this.attach(lease, socket);
+            if (!connection)
+                throw new Error('Tunnel lease superseded');
+            return connection;
+        })();
+        this.pendingConnections.set(key, connecting);
+        try {
+            return await connecting;
+        }
+        finally {
+            this.pendingConnections.delete(key);
+        }
+    }
+    attach(lease, socket) {
+        const existing = this.connections.get(lease.sessionId);
+        if (existing && existing.lease.epoch >= lease.epoch) {
+            socket.terminate();
+            return;
+        }
+        existing?.peer.close();
+        const streams = new Map();
+        const peer = new TunnelPeer(socket, this.limits, (frame) => this.receive(connection, frame), () => {
+            clearInterval(connection.timer);
+            for (const id of streams.keys())
+                this.finish(connection, id, 502);
+            if (this.connections.get(lease.sessionId) === connection)
+                this.connections.delete(lease.sessionId);
+            if (!this.options.relay)
+                void this.options.routing.release(lease.sessionId, lease.epoch, this.options.nodeId).catch(() => undefined);
+        });
+        let checking = false;
+        const timer = setInterval(() => {
+            if (connection.lease.expiresAt <= Date.now()) {
+                peer.close();
+                return;
+            }
+            if (checking)
+                return;
+            checking = true;
+            void this.valid(connection).then((valid) => { if (!valid)
+                peer.close(); }).catch(() => peer.close()).finally(() => { checking = false; });
+        }, Math.min(5_000, Math.max(1, lease.expiresAt - Date.now())));
+        timer.unref();
+        const connection = { lease, peer, streams, timer, messageBudget: new MessageBudget(this.limits.maxBufferedBytes) };
+        this.connections.set(lease.sessionId, connection);
+        return connection;
+    }
+    async receive(connection, frame) {
+        const stream = connection.streams.get(frame.id);
+        if (!stream)
+            return;
+        if (frame.type === 'request')
+            throw new Error('Developer cannot initiate gateway requests');
+        if (frame.type === 'response') {
+            if (!stream.response || stream.receivedHeaders)
+                throw new Error('Unexpected response');
+            stream.receivedHeaders = true;
+            const headers = sanitizeResponseHeaders(frame.headers);
+            // A development process cannot relax the gateway's embedding policy.
+            // Multiple CSP policies are intersected by browsers, preserving app CSP.
+            const platformCsp = stream.response.getHeader('content-security-policy');
+            const applicationCsp = headers['content-security-policy'];
+            if (platformCsp)
+                headers['content-security-policy'] = [
+                    ...(Array.isArray(platformCsp) ? platformCsp : [String(platformCsp)]),
+                    ...(applicationCsp === undefined ? [] : Array.isArray(applicationCsp) ? applicationCsp : [applicationCsp]),
+                ];
+            for (const name of ['x-content-type-options', 'referrer-policy']) {
+                const value = stream.response.getHeader(name);
+                if (value !== undefined)
+                    headers[name] = String(value);
+            }
+            headers['cache-control'] = 'no-store';
+            preserveGatewayCookies({ response: stream.response, headers });
+            stream.response.writeHead(frame.status, headers);
+            return;
+        }
+        if (frame.type === 'data') {
+            if (stream.socket) {
+                const message = stream.message.accept(frame);
+                if (message) {
+                    try {
+                        await sendWebSocket(stream.socket, message.bytes, message.binary);
+                    }
+                    finally {
+                        stream.message.reset();
+                    }
+                }
+            }
+            else {
+                if (!stream.response || !stream.receivedHeaders || stream.request.method === 'HEAD')
+                    throw new Error('Unexpected response body');
+                const bytes = Buffer.from(frame.data, 'base64');
+                stream.bytes += bytes.length;
+                if (stream.bytes > this.limits.maxBodyBytes) {
+                    this.abort(connection, frame.id, 502);
+                    return;
+                }
+                await writeChunk(stream.response, bytes);
+            }
+            return;
+        }
+        if (frame.type === 'end') {
+            this.finish(connection, frame.id);
+            return;
+        }
+        if (frame.type === 'cancel') {
+            this.finish(connection, frame.id, 502);
+            return;
+        }
+        if (frame.type === 'ws-close') {
+            stream.socket?.close(permittedCloseCode(frame.code), frame.reason);
+            this.finish(connection, frame.id);
+            return;
+        }
+        if (frame.type === 'ws-open') {
+            const upgrade = stream.upgrade;
+            if (!upgrade || stream.socket)
+                throw new Error('Unexpected websocket upgrade');
+            const requested = stream.request.headers['sec-websocket-protocol']?.split(',').map((protocol) => protocol.trim()) ?? [];
+            if (frame.protocol && !requested.includes(frame.protocol))
+                throw new Error('Unexpected websocket subprotocol');
+            const server = new WebSocketServer({
+                noServer: true, perMessageDeflate: false, maxPayload: this.limits.maxWebSocketMessageBytes,
+                handleProtocols: () => frame.protocol || false,
+            });
+            server.handleUpgrade(stream.request, upgrade.socket, upgrade.head, (browser) => {
+                clearTimeout(stream.timer);
+                stream.socket = browser;
+                browser.on('error', () => this.abort(connection, frame.id));
+                forwardWebSocketMessages(browser, (bytes, binary) => connection.peer.data(frame.id, bytes, { binary }), this.limits.maxBufferedBytes, () => this.abort(connection, frame.id), connection.messageBudget);
+                browser.once('close', (code, reason) => {
+                    void connection.peer.send({ type: 'ws-close', id: frame.id, code: permittedCloseCode(code), reason: reason.toString().slice(0, 100) }).catch(() => undefined);
+                    this.finish(connection, frame.id);
+                    server.close();
+                });
+            });
+            upgrade.socket.resume();
+        }
+    }
+    finish(connection, id, status) {
+        const stream = connection.streams.get(id);
+        if (!stream)
+            return;
+        connection.streams.delete(id);
+        connection.peer.forget(id);
+        clearTimeout(stream.timer);
+        stream.message.reset();
+        if (stream.response) {
+            if (status || !stream.receivedHeaders)
+                rejectHttp(stream.response, status ?? 502);
+            else
+                stream.response.end();
+        }
+        if (stream.socket)
+            stream.socket.close(status ? 1011 : 1000);
+        else if (stream.upgrade)
+            rejectUpgrade(stream.upgrade.socket, status ?? 503);
+    }
+    abort(connection, id, status = 502) {
+        if (!connection.streams.has(id))
+            return;
+        this.finish(connection, id, status);
+        void connection.peer.send({ type: 'cancel', id }).catch(() => undefined);
+    }
+    /** Immediate revocation and graceful service shutdown hook. */
+    disconnect(sessionId) {
+        this.connections.get(sessionId)?.peer.close();
+        this.options.relay?.disconnect(sessionId);
+    }
+    close() {
+        this.closing = true;
+        for (const timer of this.ownerTimers)
+            clearInterval(timer);
+        this.ownerTimers.clear();
+        for (const connection of this.connections.values())
+            connection.peer.close();
+        this.tunnels.close();
+        void this.options.relay?.close().catch(() => undefined);
+    }
+}
+/** For one-process local development/tests only. Production must provide a shared
+ * compare-and-swap store and route ingress to the claimed owner. */
+export class SingleProcessTunnelOwnership {
+    owners = new Map();
+    async claim(lease, nodeId) {
+        const current = this.owners.get(lease.sessionId);
+        if (current && current.epoch >= lease.epoch)
+            return false;
+        this.owners.set(lease.sessionId, { nodeId, epoch: lease.epoch, expiresAt: lease.expiresAt, active: true });
+        return true;
+    }
+    async lookup(sessionId) {
+        const current = this.owners.get(sessionId);
+        return current?.active && current.expiresAt > Date.now() ? current : null;
+    }
+    async release(sessionId, epoch, nodeId) {
+        const current = this.owners.get(sessionId);
+        if (current?.epoch === epoch && current.nodeId === nodeId)
+            current.active = false;
+    }
+}

package/dist/tunnel/client.d.ts

@@ -0,0 +1,22 @@
+import { type TunnelLimits } from './peer.js';
+export interface LocalTunnelOptions {
+    url: string;
+    token: string;
+    sessionId: string;
+    epoch: number;
+    localPort: number;
+    publicOrigin: string;
+    signal?: AbortSignal;
+    allowInsecureLoopback?: boolean;
+    limits?: Partial<TunnelLimits>;
+}
+export interface LocalTunnelConnection {
+    closed: Promise<{
+        code: number;
+        reason: string;
+    }>;
+    close(): void;
+}
+/** One connection/epoch only. The caller obtains a fresh lease to reconnect;
+ * no HTTP request or mutation is ever retained or replayed. */
+export declare function connectLocalTunnel(options: LocalTunnelOptions): Promise<LocalTunnelConnection>;

package/dist/tunnel/client.js

@@ -0,0 +1,177 @@
+import { request } from 'node:http';
+import WebSocket from 'ws';
+import { TunnelPeer, tunnelLimits } from './peer.js';
+import { assertSafeRequest, normalizePublicOrigin, parseTunnelFrame, sanitizeRequestHeaders, sanitizeResponseHeaders, TUNNEL_PROTOCOL } from './protocol.js';
+import { forwardWebSocketMessages, MessageBudget, permittedCloseCode, sendWebSocket, WebSocketMessage, writeChunk } from './io.js';
+/** One connection/epoch only. The caller obtains a fresh lease to reconnect;
+ * no HTTP request or mutation is ever retained or replayed. */
+export async function connectLocalTunnel(options) {
+    const endpoint = new URL(options.url);
+    const insecureLocal = endpoint.protocol === 'ws:' && ['127.0.0.1', '[::1]', 'localhost'].includes(endpoint.hostname) && options.allowInsecureLoopback;
+    if ((endpoint.protocol !== 'wss:' && !insecureLocal) || endpoint.username || endpoint.password || endpoint.hash) {
+        throw new Error('Tunnel endpoint must use authenticated WSS');
+    }
+    if (!Number.isSafeInteger(options.localPort) || options.localPort < 1 || options.localPort > 65535)
+        throw new Error('Invalid loopback port');
+    if (!Number.isSafeInteger(options.epoch) || options.epoch < 1 || !options.sessionId || !options.token || /[\r\n]/.test(options.token))
+        throw new Error('Invalid tunnel lease');
+    const publicOrigin = normalizePublicOrigin(options.publicOrigin);
+    const limits = tunnelLimits(options.limits);
+    options.signal?.throwIfAborted();
+    const socket = new WebSocket(endpoint, [TUNNEL_PROTOCOL], {
+        headers: { authorization: `Bearer ${options.token}`, 'x-artifact-session-id': options.sessionId, 'x-artifact-tunnel-epoch': String(options.epoch) },
+        maxPayload: limits.maxFrameBytes,
+        perMessageDeflate: false,
+        followRedirects: false,
+        handshakeTimeout: limits.requestTimeoutMs,
+    });
+    const forwards = new Map();
+    const messageBudget = new MessageBudget(limits.maxBufferedBytes);
+    const dispose = (id) => {
+        const forward = forwards.get(id);
+        if (!forward)
+            return;
+        forwards.delete(id);
+        clearTimeout(forward.timer);
+        forward.message.reset();
+        forward.request?.destroy();
+        forward.socket?.terminate();
+        peer.forget(id);
+    };
+    const fail = async (id) => {
+        dispose(id);
+        await peer.send({ type: 'cancel', id }).catch(() => undefined);
+    };
+    const handle = async (frame) => {
+        if (frame.type === 'request') {
+            assertSafeRequest(frame.method, frame.path);
+            const headers = sanitizeRequestHeaders(frame.headers, publicOrigin);
+            // Only the already authenticated gateway may mint this signed context.
+            const context = frame.headers['x-sequence-artifact-context'];
+            if (typeof context === 'string')
+                headers['x-sequence-artifact-context'] = context;
+            const timer = setTimeout(() => { void fail(frame.id); }, limits.requestTimeoutMs);
+            timer.unref();
+            const forward = { message: new WebSocketMessage(limits.maxWebSocketMessageBytes, messageBudget), bytes: 0, timer };
+            forwards.set(frame.id, forward);
+            if (frame.websocket) {
+                clearTimeout(timer); // HMR is long lived; tunnel lease owns its lifetime.
+                const protocolHeader = frame.headers['sec-websocket-protocol'];
+                const protocols = typeof protocolHeader === 'string' ? protocolHeader.split(',').map((value) => value.trim()) : [];
+                for (const name of Object.keys(headers))
+                    if (name.startsWith('sec-websocket-'))
+                        delete headers[name];
+                const local = new WebSocket(`ws://127.0.0.1:${options.localPort}${frame.path}`, protocols, {
+                    headers, maxPayload: limits.maxWebSocketMessageBytes, perMessageDeflate: false,
+                    followRedirects: false, handshakeTimeout: limits.requestTimeoutMs,
+                });
+                forward.socket = local;
+                local.on('error', () => { void fail(frame.id); });
+                local.once('open', () => {
+                    void peer.send({ type: 'ws-open', id: frame.id, protocol: local.protocol }).catch(() => fail(frame.id));
+                });
+                forwardWebSocketMessages(local, (bytes, binary) => peer.data(frame.id, bytes, { binary }), limits.maxBufferedBytes, () => { void fail(frame.id); }, messageBudget);
+                local.once('close', (code, reason) => {
+                    if (!forwards.has(frame.id))
+                        return;
+                    void peer.send({ type: 'ws-close', id: frame.id, code: permittedCloseCode(code), reason: reason.toString().slice(0, 100) }).finally(() => dispose(frame.id)).catch(() => undefined);
+                });
+            }
+            else {
+                const local = request({ hostname: '127.0.0.1', port: options.localPort, method: frame.method, path: frame.path, headers, agent: false });
+                forward.request = local;
+                local.on('error', () => { void fail(frame.id); });
+                local.once('response', (response) => {
+                    void (async () => {
+                        try {
+                            await peer.send({ type: 'response', id: frame.id, status: response.statusCode ?? 502, headers: sanitizeResponseHeaders(response.headers) });
+                            let total = 0;
+                            for await (const chunk of response) {
+                                const bytes = Buffer.from(chunk);
+                                total += bytes.length;
+                                if (total > limits.maxBodyBytes)
+                                    throw new Error('Response too large');
+                                await peer.data(frame.id, bytes);
+                            }
+                            await peer.send({ type: 'end', id: frame.id });
+                            dispose(frame.id);
+                        }
+                        catch {
+                            await fail(frame.id);
+                        }
+                    })();
+                });
+            }
+            return;
+        }
+        const forward = forwards.get(frame.id);
+        if (!forward)
+            return;
+        if (frame.type === 'cancel') {
+            dispose(frame.id);
+            return;
+        }
+        if (frame.type === 'end') {
+            forward.request?.end();
+            return;
+        }
+        if (frame.type === 'ws-close') {
+            forward.socket?.close(permittedCloseCode(frame.code), frame.reason);
+            return;
+        }
+        if (frame.type === 'data') {
+            if (forward.socket) {
+                const message = forward.message.accept(frame);
+                if (message) {
+                    try {
+                        await sendWebSocket(forward.socket, message.bytes, message.binary);
+                    }
+                    finally {
+                        forward.message.reset();
+                    }
+                }
+            }
+            else if (forward.request) {
+                const bytes = Buffer.from(frame.data, 'base64');
+                forward.bytes += bytes.length;
+                if (forward.bytes > limits.maxBodyBytes) {
+                    await fail(frame.id);
+                    return;
+                }
+                await writeChunk(forward.request, bytes);
+            }
+        }
+    };
+    const peer = new TunnelPeer(socket, limits, handle, () => { for (const id of forwards.keys())
+        dispose(id); }, true);
+    const abort = () => peer.close();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const closed = new Promise((resolve) => {
+        socket.once('close', (code, reason) => {
+            options.signal?.removeEventListener('abort', abort);
+            resolve({ code, reason: reason.toString() });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        const ready = (raw) => {
+            try {
+                const frame = parseTunnelFrame(raw);
+                if (frame.type !== 'ready' || frame.id !== options.sessionId || frame.epoch !== options.epoch)
+                    return;
+                cleanup();
+                resolve();
+            }
+            catch {
+                failed();
+            }
+        };
+        const failed = () => { cleanup(); reject(new Error('Tunnel connection failed')); };
+        const timer = setTimeout(() => { failed(); peer.close(); }, limits.requestTimeoutMs);
+        timer.unref();
+        const cleanup = () => { clearTimeout(timer); socket.off('message', ready); socket.off('error', failed); socket.off('close', failed); };
+        socket.on('message', ready);
+        socket.once('error', failed);
+        socket.once('close', failed);
+    });
+    return { closed, close: abort };
+}

package/dist/tunnel/index.d.ts

@@ -0,0 +1,6 @@
+export { connectLocalTunnel, type LocalTunnelOptions, type LocalTunnelConnection } from './client.js';
+export { ArtifactTunnelBroker, SingleProcessTunnelOwnership, type TunnelBrokerOptions, type TunnelLease, type TunnelOwner, type TunnelOwnershipStore, type GatewayAuthorization, } from './broker.js';
+export { DEFAULT_TUNNEL_LIMITS, TUNNEL_PROTOCOL, type TunnelFrame } from './protocol.js';
+export type { TunnelLimits } from './peer.js';
+export type { TunnelRelay, TunnelSocket } from './transport.js';
+export { RedisTunnelOwnership, RedisTunnelRelay, type RedisTunnelCommands, type RedisTunnelPublisher, type RedisTunnelSubscriber, type RedisTunnelRelayOptions, } from './redis.js';

package/dist/tunnel/index.js

@@ -0,0 +1,4 @@
+export { connectLocalTunnel } from './client.js';
+export { ArtifactTunnelBroker, SingleProcessTunnelOwnership, } from './broker.js';
+export { DEFAULT_TUNNEL_LIMITS, TUNNEL_PROTOCOL } from './protocol.js';
+export { RedisTunnelOwnership, RedisTunnelRelay, } from './redis.js';