@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/dist/tunnel/io.d.ts

@@ -0,0 +1,33 @@
+import type { Writable } from 'node:stream';
+import WebSocket, { type RawData } from 'ws';
+import type { TunnelFrame } from './protocol.js';
+export declare function writeChunk(target: Writable, bytes: Buffer): Promise<void>;
+export declare function rawBuffer(data: RawData): Buffer;
+export declare function sendWebSocket(socket: WebSocket, bytes: Buffer, binary: boolean): Promise<void>;
+/** pause() alone does not stop messages already decoded from a single TCP read.
+ * Serialize those messages so fragments from two HMR messages cannot interleave. */
+export declare function forwardWebSocketMessages(socket: WebSocket, forward: (bytes: Buffer, binary: boolean) => Promise<void>, maximumQueuedBytes: number, failed: () => void, budget: MessageBudget): void;
+export declare class MessageBudget {
+    private readonly maximum;
+    private bytes;
+    constructor(maximum: number);
+    add(bytes: number): void;
+    release(bytes: number): void;
+}
+/** Reassembles only one bounded message, preserving HMR message boundaries. */
+export declare class WebSocketMessage {
+    private readonly maximum;
+    private readonly budget;
+    private parts;
+    private size;
+    private binary;
+    constructor(maximum: number, budget: MessageBudget);
+    accept(frame: Extract<TunnelFrame, {
+        type: 'data';
+    }>): {
+        bytes: Buffer;
+        binary: boolean;
+    } | undefined;
+    reset(): void;
+}
+export declare function permittedCloseCode(code: number): number;

package/dist/tunnel/io.js

@@ -0,0 +1,108 @@
+import WebSocket from 'ws';
+export async function writeChunk(target, bytes) {
+    if (target.destroyed)
+        throw new Error('Destination disconnected');
+    if (!target.write(bytes)) {
+        // A destroyed HTTP destination may emit close without drain or error.
+        await new Promise((resolve, reject) => {
+            const cleanup = () => { target.off('drain', done); target.off('close', closed); target.off('error', failed); };
+            const done = () => { cleanup(); resolve(); };
+            const closed = () => { cleanup(); reject(new Error('Destination disconnected')); };
+            const failed = (error) => { cleanup(); reject(error); };
+            target.once('drain', done);
+            target.once('close', closed);
+            target.once('error', failed);
+        });
+    }
+}
+export function rawBuffer(data) {
+    return Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+}
+export async function sendWebSocket(socket, bytes, binary) {
+    if (socket.readyState !== WebSocket.OPEN)
+        throw new Error('WebSocket disconnected');
+    await new Promise((resolve, reject) => {
+        socket.send(bytes, { binary }, (error) => error ? reject(error) : resolve());
+    });
+}
+/** pause() alone does not stop messages already decoded from a single TCP read.
+ * Serialize those messages so fragments from two HMR messages cannot interleave. */
+export function forwardWebSocketMessages(socket, forward, maximumQueuedBytes, failed, budget) {
+    let queued = 0;
+    let pending = Promise.resolve();
+    socket.on('message', (data, binary) => {
+        const bytes = rawBuffer(data);
+        try {
+            budget.add(bytes.length);
+        }
+        catch {
+            failed();
+            return;
+        }
+        queued += bytes.length;
+        socket.pause();
+        if (queued > maximumQueuedBytes) {
+            budget.release(bytes.length);
+            failed();
+            return;
+        }
+        pending = pending.then(() => forward(bytes, binary)).finally(() => {
+            budget.release(bytes.length);
+            queued -= bytes.length;
+            if (queued === 0 && socket.readyState === WebSocket.OPEN)
+                socket.resume();
+        }).catch(failed);
+    });
+}
+export class MessageBudget {
+    maximum;
+    bytes = 0;
+    constructor(maximum) {
+        this.maximum = maximum;
+    }
+    add(bytes) {
+        if (this.bytes + bytes > this.maximum)
+            throw new Error('WebSocket buffer exceeded');
+        this.bytes += bytes;
+    }
+    release(bytes) { this.bytes -= bytes; }
+}
+/** Reassembles only one bounded message, preserving HMR message boundaries. */
+export class WebSocketMessage {
+    maximum;
+    budget;
+    parts = [];
+    size = 0;
+    binary;
+    constructor(maximum, budget) {
+        this.maximum = maximum;
+        this.budget = budget;
+    }
+    accept(frame) {
+        const bytes = Buffer.from(frame.data, 'base64');
+        if (typeof frame.binary !== 'boolean' || typeof frame.final !== 'boolean')
+            throw new Error('Missing WebSocket framing');
+        if (this.binary !== undefined && this.binary !== frame.binary)
+            throw new Error('Changed message encoding');
+        this.binary = frame.binary;
+        if (this.size + bytes.length > this.maximum)
+            throw new Error('WebSocket message too large');
+        this.budget.add(bytes.length);
+        this.size += bytes.length;
+        this.parts.push(bytes);
+        if (!frame.final)
+            return;
+        const result = { bytes: Buffer.concat(this.parts, this.size), binary: this.binary };
+        return result;
+    }
+    reset() {
+        this.budget.release(this.size);
+        this.parts = [];
+        this.size = 0;
+        this.binary = undefined;
+    }
+}
+export function permittedCloseCode(code) {
+    return code === 1000 || (code >= 1001 && code <= 1014 && ![1004, 1005, 1006].includes(code)) || (code >= 3000 && code <= 4999)
+        ? code : 1000;
+}

package/dist/tunnel/peer.d.ts

@@ -0,0 +1,25 @@
+import type { TunnelSocket } from './transport.js';
+import { DEFAULT_TUNNEL_LIMITS, type TunnelFrame } from './protocol.js';
+export type TunnelLimits = typeof DEFAULT_TUNNEL_LIMITS;
+/** Flow control is per direction and per stream. ACK means the receiving
+ * application consumed the bytes, not merely that the WebSocket received them. */
+export declare class TunnelPeer {
+    readonly socket: TunnelSocket;
+    readonly limits: TunnelLimits;
+    private readonly receive;
+    private readonly disconnected;
+    private readonly acceptsRequests;
+    private readonly streams;
+    private queuedBytes;
+    private stopped;
+    constructor(socket: TunnelSocket, limits: TunnelLimits, receive: (frame: TunnelFrame) => Promise<void>, disconnected: () => void, acceptsRequests?: boolean);
+    open(id?: string): string;
+    forget(id: string): void;
+    send(frame: TunnelFrame): Promise<void>;
+    data(id: string, data: Buffer, websocket?: {
+        binary: boolean;
+    }): Promise<void>;
+    private credit;
+    close(): void;
+}
+export declare function tunnelLimits(overrides?: Partial<TunnelLimits>): TunnelLimits;

package/dist/tunnel/peer.js

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import WebSocket from 'ws';
+import { DEFAULT_TUNNEL_LIMITS, encodeTunnelFrame, parseTunnelFrame, } from './protocol.js';
+/** Flow control is per direction and per stream. ACK means the receiving
+ * application consumed the bytes, not merely that the WebSocket received them. */
+export class TunnelPeer {
+    socket;
+    limits;
+    receive;
+    disconnected;
+    acceptsRequests;
+    streams = new Map();
+    queuedBytes = 0;
+    stopped = false;
+    constructor(socket, limits, receive, disconnected, acceptsRequests = false) {
+        this.socket = socket;
+        this.limits = limits;
+        this.receive = receive;
+        this.disconnected = disconnected;
+        this.acceptsRequests = acceptsRequests;
+        socket.on('message', (data, binary) => {
+            try {
+                if (binary)
+                    throw new Error('Binary protocol frame');
+                const frame = parseTunnelFrame(data);
+                if (frame.type === 'ack') {
+                    const stream = this.streams.get(frame.id);
+                    if (!stream)
+                        return; // A cancelled stream may have an ACK in flight.
+                    if (frame.bytes > stream.outstanding)
+                        throw new Error('Invalid credit');
+                    stream.outstanding -= frame.bytes;
+                    for (const wake of stream.waiters)
+                        wake();
+                    return;
+                }
+                if (frame.type === 'request') {
+                    if (!this.acceptsRequests || this.streams.has(frame.id))
+                        throw new Error('Unexpected request frame');
+                    this.open(frame.id);
+                }
+                const stream = this.streams.get(frame.id);
+                if (!stream)
+                    return; // Frames from an already cancelled request are discarded.
+                if (frame.type === 'cancel') {
+                    void this.receive(frame).catch(() => this.close());
+                    return;
+                }
+                const bytes = frame.type === 'data' ? Buffer.from(frame.data, 'base64').length : 0;
+                this.queuedBytes += bytes;
+                if (this.queuedBytes > limits.maxBufferedBytes)
+                    throw new Error('Receive buffer exceeded');
+                stream.receive = stream.receive.then(async () => {
+                    try {
+                        if (!this.streams.has(frame.id))
+                            return;
+                        await this.receive(frame);
+                        if (bytes > 0)
+                            await this.send({ type: 'ack', id: frame.id, bytes });
+                    }
+                    finally {
+                        this.queuedBytes -= bytes;
+                    }
+                }).catch(() => this.close());
+            }
+            catch {
+                this.close();
+            }
+        });
+        socket.on('error', () => this.close());
+        socket.once('close', () => this.close());
+    }
+    open(id = randomUUID()) {
+        if (this.stopped || this.streams.has(id) || this.streams.size >= this.limits.maxStreams) {
+            throw new Error('Tunnel stream limit or duplicate stream');
+        }
+        this.streams.set(id, { outstanding: 0, waiters: new Set(), receive: Promise.resolve() });
+        return id;
+    }
+    forget(id) {
+        const stream = this.streams.get(id);
+        this.streams.delete(id);
+        if (stream)
+            for (const wake of stream.waiters)
+                wake();
+    }
+    async send(frame) {
+        if (this.stopped || this.socket.readyState !== WebSocket.OPEN)
+            throw new Error('Tunnel disconnected');
+        const payload = encodeTunnelFrame(frame);
+        if (this.socket.bufferedAmount + Buffer.byteLength(payload) > this.limits.maxBufferedBytes) {
+            this.close();
+            throw new Error('Tunnel send buffer exceeded');
+        }
+        await new Promise((resolve, reject) => {
+            this.socket.send(payload, (error) => error ? reject(error) : resolve());
+        });
+    }
+    async data(id, data, websocket) {
+        // An empty WebSocket message is meaningful; HTTP empty chunks are not.
+        for (let offset = 0; offset < Math.max(data.length, websocket ? 1 : 0); offset += this.limits.maxChunkBytes) {
+            const chunk = data.subarray(offset, offset + this.limits.maxChunkBytes);
+            await this.credit(id, chunk.length);
+            const stream = this.streams.get(id);
+            if (!stream)
+                throw new Error('Tunnel stream closed');
+            stream.outstanding += chunk.length;
+            await this.send({
+                type: 'data', id, data: chunk.toString('base64'),
+                ...(websocket ? { binary: websocket.binary, final: offset + chunk.length >= data.length } : {}),
+            });
+        }
+    }
+    async credit(id, bytes) {
+        while (true) {
+            const stream = this.streams.get(id);
+            if (!stream || this.stopped)
+                throw new Error('Tunnel stream closed');
+            if (stream.outstanding + bytes <= this.limits.maxInFlightBytes)
+                return;
+            await new Promise((resolve) => {
+                const wake = () => { stream.waiters.delete(wake); resolve(); };
+                stream.waiters.add(wake);
+            });
+        }
+    }
+    close() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        for (const id of this.streams.keys())
+            this.forget(id);
+        this.socket.terminate();
+        this.disconnected();
+    }
+}
+export function tunnelLimits(overrides) {
+    const limits = { ...DEFAULT_TUNNEL_LIMITS, ...overrides };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value <= 0 || value > DEFAULT_TUNNEL_LIMITS[name]) {
+            throw new Error(`Invalid tunnel limit ${name}`);
+        }
+    }
+    if (limits.maxChunkBytes > limits.maxInFlightBytes)
+        throw new Error('Chunk exceeds stream window');
+    return limits;
+}

package/dist/tunnel/protocol.d.ts

@@ -0,0 +1,78 @@
+import { Buffer } from 'node:buffer';
+import { z } from 'zod';
+/** Version 1 is negotiated by the tunnel connection, not by individual streams. */
+export declare const TUNNEL_PROTOCOL = "artifact-tunnel.v1";
+export declare const DEFAULT_TUNNEL_LIMITS: Readonly<{
+    maxFrameBytes: number;
+    maxChunkBytes: number;
+    maxStreams: 32;
+    maxBodyBytes: number;
+    maxInFlightBytes: number;
+    maxWebSocketMessageBytes: number;
+    maxBufferedBytes: number;
+    requestTimeoutMs: 60000;
+}>;
+export type TunnelHeaders = Record<string, string | string[]>;
+type HeaderInput = Record<string, string | string[] | undefined>;
+/** Enforce origin-form paths before a URL parser can reinterpret a destination. */
+export declare function assertSafeRequest(method: string, path: string): void;
+export declare const tunnelFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"ready">;
+    id: z.ZodString;
+    epoch: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"request">;
+    id: z.ZodString;
+    method: z.ZodString;
+    path: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    websocket: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"response">;
+    id: z.ZodString;
+    status: z.ZodNumber;
+    headers: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"data">;
+    id: z.ZodString;
+    data: z.ZodString;
+    binary: z.ZodOptional<z.ZodBoolean>;
+    final: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"end">;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"cancel">;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"ws-open">;
+    id: z.ZodString;
+    protocol: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"ws-close">;
+    id: z.ZodString;
+    code: z.ZodNumber;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"ack">;
+    id: z.ZodString;
+    bytes: z.ZodNumber;
+}, z.core.$strict>], "type">;
+export type TunnelFrame = z.infer<typeof tunnelFrameSchema>;
+/** Compatible with ws RawData without introducing a websocket dependency here. */
+export declare function parseTunnelFrame(input: string | Buffer | ArrayBuffer | Buffer[]): TunnelFrame;
+export declare function encodeTunnelFrame(frame: TunnelFrame): string;
+export declare function normalizePublicOrigin(value: string): string;
+/** Rebuild trusted routing headers; no Atlas bearer/session crosses into app code. */
+export declare function sanitizeRequestHeaders(headers: HeaderInput, publicOrigin: string): TunnelHeaders;
+/** Response headers through which application output could opt into CDN or proxy reuse. */
+export declare function isSharedCacheDirective(name: string): boolean;
+/** Sent in their place on every protected response, so each reuse must pass gateway authorization again. */
+export declare const SHARED_CACHE_REFUSAL: Readonly<{
+    'cdn-cache-control': "no-store";
+    'surrogate-control': "no-store";
+    pragma: "no-cache";
+    expires: "0";
+}>;
+export declare function sanitizeResponseHeaders(headers: HeaderInput): TunnelHeaders;
+export {};

package/dist/tunnel/protocol.js

@@ -0,0 +1,210 @@
+import { Buffer } from 'node:buffer';
+import { z } from 'zod';
+/** Version 1 is negotiated by the tunnel connection, not by individual streams. */
+export const TUNNEL_PROTOCOL = 'artifact-tunnel.v1';
+export const DEFAULT_TUNNEL_LIMITS = Object.freeze({
+    maxFrameBytes: 64 * 1024,
+    maxChunkBytes: 32 * 1024,
+    maxStreams: 32,
+    maxBodyBytes: 32 * 1024 * 1024,
+    maxInFlightBytes: 256 * 1024,
+    maxWebSocketMessageBytes: 4 * 1024 * 1024,
+    maxBufferedBytes: 8 * 1024 * 1024,
+    requestTimeoutMs: 60_000,
+});
+const HEADER_TOKEN = /^[!#$%&'*+.^_`|~0-9a-z-]+$/i;
+const HEADER_VALUE = /^[\t\x20-\x7e\x80-\xff]*$/;
+const METHODS = new Set(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']);
+const PLATFORM_COOKIE = '__Host-atlas-artifact-session';
+function isPlatformCookie(name) {
+    const normalized = name.toLowerCase();
+    const reserved = PLATFORM_COOKIE.toLowerCase();
+    return normalized === reserved || normalized.startsWith(`${reserved}-`);
+}
+const HOP_HEADERS = new Set([
+    'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+    'proxy-connection', 'te', 'trailer', 'transfer-encoding', 'upgrade',
+    'content-length', 'expect',
+]);
+const MAX_HEADER_BYTES = 32 * 1024;
+function headerMapSchema({ maxValueLength }) {
+    const value = z.string().max(maxValueLength).regex(HEADER_VALUE);
+    return z.record(z.string().max(256).regex(HEADER_TOKEN), z.union([value, z.array(value).min(1).max(32)])).superRefine((headers, context) => {
+        const names = new Set();
+        let bytes = 0;
+        for (const [name, value] of Object.entries(headers)) {
+            if (names.has(name.toLowerCase())) {
+                context.addIssue({ code: 'custom', message: 'Duplicate case-insensitive header' });
+            }
+            names.add(name.toLowerCase());
+            bytes += Buffer.byteLength(name) + Buffer.byteLength(Array.isArray(value) ? value.join(',') : value);
+        }
+        if (names.size > 128 || bytes > MAX_HEADER_BYTES) {
+            context.addIssue({ code: 'custom', message: 'Tunnel headers exceed their size limit' });
+        }
+    });
+}
+// A frame carries the gateway's signed request context, which the hosted proxy accepts up to 16 KiB.
+const headersSchema = headerMapSchema({ maxValueLength: 16 * 1024 });
+// A browser request still holds the gateway's own session cookies, which are removed before any
+// frame is built, so they must not use up the application's per-value allowance.
+const browserRequestHeadersSchema = headerMapSchema({ maxValueLength: MAX_HEADER_BYTES });
+/** Enforce origin-form paths before a URL parser can reinterpret a destination. */
+export function assertSafeRequest(method, path) {
+    if (!METHODS.has(method))
+        throw new Error('Unsupported tunnel request method');
+    if (path.length > 16 * 1024 || !path.startsWith('/') || path.startsWith('//') ||
+        !/^[\x21-\x7e]+$/.test(path) || /[\\#]/.test(path) ||
+        /%(?![a-f0-9]{2})/i.test(path) || /%(?:0[0-9a-f]|1[0-9a-f]|7f|5c)/i.test(path)) {
+        throw new Error('Tunnel request requires a safe origin-form path');
+    }
+}
+const requestPathSchema = z.string().refine((path) => {
+    try {
+        assertSafeRequest('GET', path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, 'Tunnel request requires a safe origin-form path');
+const streamIdSchema = z.string().min(1).max(128).regex(/^[a-zA-Z0-9_-]+$/);
+const dataSchema = z.string()
+    .max(4 * Math.ceil(DEFAULT_TUNNEL_LIMITS.maxChunkBytes / 3))
+    .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/)
+    .refine((data) => {
+    const decoded = Buffer.from(data, 'base64');
+    return decoded.length <= DEFAULT_TUNNEL_LIMITS.maxChunkBytes && decoded.toString('base64') === data;
+}, 'Tunnel data must be canonical, bounded base64');
+export const tunnelFrameSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('ready'), id: streamIdSchema, epoch: z.number().int().positive() }).strict(),
+    z.object({
+        type: z.literal('request'), id: streamIdSchema,
+        method: z.string().refine((method) => METHODS.has(method)),
+        path: requestPathSchema, headers: headersSchema, websocket: z.boolean(),
+    }).strict(),
+    z.object({
+        type: z.literal('response'), id: streamIdSchema,
+        status: z.number().int().min(200).max(599), headers: headersSchema,
+    }).strict(),
+    z.object({
+        type: z.literal('data'), id: streamIdSchema, data: dataSchema,
+        binary: z.boolean().optional(), final: z.boolean().optional(),
+    }).strict(),
+    z.object({ type: z.literal('end'), id: streamIdSchema }).strict(),
+    z.object({ type: z.literal('cancel'), id: streamIdSchema }).strict(),
+    z.object({
+        type: z.literal('ws-open'), id: streamIdSchema,
+        protocol: z.string().max(256).refine((protocol) => protocol === '' || HEADER_TOKEN.test(protocol)),
+    }).strict(),
+    z.object({
+        type: z.literal('ws-close'), id: streamIdSchema,
+        code: z.number().int().refine((code) => (code >= 1000 && code <= 1014 && ![1004, 1005, 1006].includes(code)) ||
+            (code >= 3000 && code <= 4999)),
+        reason: z.string().refine((reason) => Buffer.byteLength(reason) <= 123),
+    }).strict(),
+    z.object({
+        type: z.literal('ack'), id: streamIdSchema,
+        bytes: z.number().int().min(1).max(DEFAULT_TUNNEL_LIMITS.maxInFlightBytes),
+    }).strict(),
+]);
+/** Compatible with ws RawData without introducing a websocket dependency here. */
+export function parseTunnelFrame(input) {
+    const bytes = typeof input === 'string' ? Buffer.byteLength(input)
+        : Array.isArray(input) ? input.reduce((total, part) => total + part.byteLength, 0)
+            : input.byteLength;
+    if (bytes > DEFAULT_TUNNEL_LIMITS.maxFrameBytes)
+        throw new Error('Tunnel frame exceeds its size limit');
+    const source = typeof input === 'string' ? input : new TextDecoder('utf-8', { fatal: true }).decode(Array.isArray(input) ? Buffer.concat(input) : input);
+    return tunnelFrameSchema.parse(JSON.parse(source));
+}
+export function encodeTunnelFrame(frame) {
+    const source = JSON.stringify(tunnelFrameSchema.parse(frame));
+    if (Buffer.byteLength(source) > DEFAULT_TUNNEL_LIMITS.maxFrameBytes) {
+        throw new Error('Tunnel frame exceeds its size limit');
+    }
+    return source;
+}
+export function normalizePublicOrigin(value) {
+    const url = new URL(value);
+    const isLoopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (!/^https?:\/\/[^/?#@\\\s]+\/?$/i.test(value) || url.username || url.password || url.search || url.hash ||
+        url.pathname !== '/' || (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopback)))
+        throw new Error('Tunnel public origin must be an HTTPS origin or HTTP loopback origin');
+    return url.origin;
+}
+function normalizedHeaders(headers, schema = headersSchema) {
+    const present = Object.fromEntries(Object.entries(headers).filter(([, value]) => value !== undefined));
+    return new Map(Object.entries(schema.parse(present)).map(([name, value]) => [name.toLowerCase(), value]));
+}
+function removePrivateHeaders(headers) {
+    const connection = headers.get('connection');
+    const nominated = new Set((Array.isArray(connection) ? connection.join(',') : connection ?? '')
+        .split(',').map((name) => name.trim().toLowerCase()));
+    for (const name of headers.keys()) {
+        if (HOP_HEADERS.has(name) || nominated.has(name) || name === 'forwarded' ||
+            name === 'authorization' || name === 'remote-user' || name === 'x-remote-user' ||
+            name === 'x-serverless-authorization' || name === 'x-goog-iap-jwt-assertion' ||
+            /^(?:x-forwarded-|x-sequence-|x-artifact-|x-atlas-|x-user-|x-auth-|x-authenticated-|x-goog-authenticated-|proxy-)/.test(name))
+            headers.delete(name);
+    }
+}
+/** Rebuild trusted routing headers; no Atlas bearer/session crosses into app code. */
+export function sanitizeRequestHeaders(headers, publicOrigin) {
+    const origin = normalizePublicOrigin(publicOrigin);
+    const normalized = normalizedHeaders(headers, browserRequestHeadersSchema);
+    const suppliedOrigin = normalized.get('origin');
+    if (suppliedOrigin !== undefined && suppliedOrigin !== origin)
+        throw new Error('Tunnel request origin mismatch');
+    removePrivateHeaders(normalized);
+    const cookie = normalized.get('cookie');
+    if (cookie !== undefined) {
+        const remaining = (Array.isArray(cookie) ? cookie.join(';') : cookie).split(';')
+            .map((part) => part.trim()).filter((part) => {
+            const separator = part.indexOf('=');
+            return separator > 0 && !isPlatformCookie(part.slice(0, separator).trim());
+        }).join('; ');
+        if (remaining)
+            normalized.set('cookie', remaining);
+        else
+            normalized.delete('cookie');
+    }
+    const url = new URL(origin);
+    normalized.set('host', url.host);
+    normalized.set('x-forwarded-host', url.host);
+    normalized.set('x-forwarded-proto', url.protocol.slice(0, -1));
+    return Object.fromEntries(normalized);
+}
+function constrainCookie(cookie) {
+    const [assignment, ...attributes] = cookie.split(';');
+    const separator = assignment.indexOf('=');
+    if (separator <= 0)
+        throw new Error('Invalid application Set-Cookie header');
+    const name = assignment.slice(0, separator).trim();
+    if (!HEADER_TOKEN.test(name))
+        throw new Error('Invalid application cookie name');
+    if (isPlatformCookie(name))
+        return undefined;
+    return [assignment.trim(), ...attributes.map((attribute) => attribute.trim())
+            .filter((attribute) => attribute && attribute.split('=', 1)[0].trim().toLowerCase() !== 'domain')].join('; ');
+}
+/** Response headers through which application output could opt into CDN or proxy reuse. */
+export function isSharedCacheDirective(name) {
+    return /(?:^|-)cdn-cache-control$/.test(name) || ['surrogate-control', 'x-accel-expires', 'expires', 'age'].includes(name);
+}
+/** Sent in their place on every protected response, so each reuse must pass gateway authorization again. */
+export const SHARED_CACHE_REFUSAL = Object.freeze({ 'cdn-cache-control': 'no-store', 'surrogate-control': 'no-store', pragma: 'no-cache', expires: '0' });
+export function sanitizeResponseHeaders(headers) {
+    const normalized = normalizedHeaders(headers);
+    removePrivateHeaders(normalized);
+    const cookies = normalized.get('set-cookie');
+    if (cookies !== undefined) {
+        const constrained = (Array.isArray(cookies) ? cookies : [cookies])
+            .map(constrainCookie).filter((cookie) => cookie !== undefined);
+        if (constrained.length)
+            normalized.set('set-cookie', constrained);
+        else
+            normalized.delete('set-cookie');
+    }
+    return Object.fromEntries(normalized);
+}

package/dist/tunnel/redis-auth.d.ts

@@ -0,0 +1,37 @@
+import { type Envelope } from './redis-types.js';
+/** Frames older (or further in the future) than this are replays or come from a stalled node. */
+export declare const RELAY_FRAME_MAX_AGE_MS = 30000;
+/** An envelope quotes a frame as a JSON string: at most double its size, plus fixed fields and the MAC. */
+export declare const RELAY_MESSAGE_MAX_BYTES: number;
+/**
+ * The relay's frame key: an HKDF-SHA256 subkey of the gateway-only session key, bound to one
+ * environment. Atlas and every other Redis client lack that key, so they cannot forge frames, and
+ * the session key itself is never used as a MAC key for anything but cookies.
+ */
+export declare function deriveRelayFrameKey({ secret, namespace }: {
+    secret: string;
+    namespace: string;
+}): Buffer;
+/**
+ * Authenticates relay messages: the MAC binds the destination channel, so a captured frame cannot be
+ * redirected to another node, and each source's strictly increasing sequence plus a freshness window
+ * rejects replays. A single publisher connection per node keeps Redis delivery in sequence order.
+ */
+export declare class RelayFrameAuthenticator {
+    private readonly key;
+    private readonly now;
+    private sequence;
+    private readonly peers;
+    constructor(key: Buffer, now?: () => number);
+    seal({ channel, envelope }: {
+        channel: string;
+        envelope: Envelope;
+    }): string;
+    /** Null for any frame that is oversized, unauthenticated, stale, replayed or malformed. */
+    open({ channel, message }: {
+        channel: string;
+        message: string;
+    }): Envelope | null;
+    /** Forgotten peers can only send frames newer than the freshness window, which rejects replays. */
+    private forgetIdlePeers;
+}