@sequenceholdings/artifact-studio 0.2.5 → 0.3.0

package/dist/gateway/release-admission.js

@@ -0,0 +1,259 @@
+import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+const RELEASE_FIELD = '__sequence_release';
+const RELEASE_HEADER = 'x-sequence-artifact-release';
+const FRAMEWORK_BUILD_HEADER = 'x-deployment-id';
+const MAX_PREFIX_BYTES = 64 * 1024;
+const MAX_RELEASE_BYTES = 255;
+const RELEASE_ID = /^[a-zA-Z0-9_-]{1,255}$/;
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+export class ReleaseAdmissionError extends Error {
+    reason;
+    status = 409;
+    code = 'update-required';
+    constructor(reason = 'missing-release') {
+        super('Reload the application before submitting this request. The request was not executed.');
+        this.reason = reason;
+        this.name = 'ReleaseAdmissionError';
+    }
+}
+function parseUrlEncoded({ prefix, ended }) {
+    const separator = prefix.indexOf(0x26);
+    if (separator < 0 && !ended)
+        return undefined;
+    const first = prefix.subarray(0, separator < 0 ? prefix.length : separator).toString('utf8');
+    const equals = first.indexOf('=');
+    if (equals < 0)
+        throw new ReleaseAdmissionError('invalid-form');
+    try {
+        const name = decodeURIComponent(first.slice(0, equals).replace(/\+/g, ' '));
+        const release = decodeURIComponent(first.slice(equals + 1).replace(/\+/g, ' '));
+        if (name !== RELEASE_FIELD || Buffer.byteLength(release) > MAX_RELEASE_BYTES || !RELEASE_ID.test(release)) {
+            throw new ReleaseAdmissionError('invalid-form');
+        }
+        return release;
+    }
+    catch {
+        throw new ReleaseAdmissionError('invalid-form');
+    }
+}
+function multipartParser({ boundary }) {
+    const opening = Buffer.from(`--${boundary}\r\n`);
+    const delimiter = Buffer.from(`\r\n--${boundary}`);
+    return ({ prefix, ended }) => {
+        if (!prefix.subarray(0, Math.min(prefix.length, opening.length)).equals(opening.subarray(0, Math.min(prefix.length, opening.length)))) {
+            throw new ReleaseAdmissionError('invalid-form');
+        }
+        if (prefix.length < opening.length) {
+            if (ended)
+                throw new ReleaseAdmissionError('invalid-form');
+            return undefined;
+        }
+        const headerEnd = prefix.indexOf('\r\n\r\n', opening.length);
+        if (headerEnd < 0) {
+            if (ended)
+                throw new ReleaseAdmissionError('invalid-form');
+            return undefined;
+        }
+        const headers = new Map();
+        for (const line of prefix.subarray(opening.length, headerEnd).toString('latin1').split('\r\n')) {
+            const colon = line.indexOf(':');
+            if (colon <= 0)
+                throw new ReleaseAdmissionError('invalid-form');
+            const name = line.slice(0, colon).toLowerCase();
+            const value = line.slice(colon + 1).trim();
+            if (!['content-disposition', 'content-type'].includes(name) || headers.has(name)) {
+                throw new ReleaseAdmissionError('invalid-form');
+            }
+            headers.set(name, value);
+        }
+        const disposition = headers.get('content-disposition')?.split(';').map((part) => part.trim());
+        if (!disposition || disposition.length !== 2 || disposition[0].toLowerCase() !== 'form-data') {
+            throw new ReleaseAdmissionError('invalid-form');
+        }
+        const field = disposition[1];
+        const equals = field.indexOf('=');
+        if (equals < 0 || field.slice(0, equals).toLowerCase() !== 'name' ||
+            ![RELEASE_FIELD, `"${RELEASE_FIELD}"`].includes(field.slice(equals + 1))) {
+            throw new ReleaseAdmissionError('invalid-form');
+        }
+        const contentType = headers.get('content-type');
+        if (contentType && !/^text\/plain(?:\s*;\s*charset=(?:utf-8|"utf-8"))?$/i.test(contentType)) {
+            throw new ReleaseAdmissionError('invalid-form');
+        }
+        const valueStart = headerEnd + 4;
+        const valueEnd = prefix.indexOf(delimiter, valueStart);
+        if (valueEnd < 0) {
+            if (ended || prefix.length - valueStart > MAX_RELEASE_BYTES + delimiter.length - 1) {
+                throw new ReleaseAdmissionError('invalid-form');
+            }
+            return undefined;
+        }
+        if (valueEnd - valueStart > MAX_RELEASE_BYTES)
+            throw new ReleaseAdmissionError('invalid-form');
+        const suffixOffset = valueEnd + delimiter.length;
+        if (prefix.length < suffixOffset + 2) {
+            if (ended)
+                throw new ReleaseAdmissionError('invalid-form');
+            return undefined;
+        }
+        const suffix = prefix.subarray(suffixOffset, suffixOffset + 2).toString('ascii');
+        if (suffix !== '\r\n' && suffix !== '--')
+            throw new ReleaseAdmissionError('invalid-form');
+        if (suffix === '--') {
+            const closingEnd = suffixOffset + 2;
+            if (prefix.length < closingEnd + 2) {
+                if (!ended)
+                    return undefined;
+                if (prefix.length !== closingEnd)
+                    throw new ReleaseAdmissionError('invalid-form');
+            }
+            else if (!prefix.subarray(closingEnd, closingEnd + 2).equals(Buffer.from('\r\n'))) {
+                throw new ReleaseAdmissionError('invalid-form');
+            }
+        }
+        const release = prefix.subarray(valueStart, valueEnd).toString('utf8');
+        if (!RELEASE_ID.test(release))
+            throw new ReleaseAdmissionError('invalid-form');
+        return release;
+    };
+}
+function getFormParser({ contentType }) {
+    if (typeof contentType !== 'string')
+        throw new ReleaseAdmissionError('missing-release');
+    const [mediaType, ...parameters] = contentType.split(';').map((part) => part.trim());
+    if (mediaType.toLowerCase() === 'application/x-www-form-urlencoded')
+        return parseUrlEncoded;
+    if (mediaType.toLowerCase() !== 'multipart/form-data')
+        throw new ReleaseAdmissionError('missing-release');
+    const boundaries = parameters.filter((parameter) => parameter.slice(0, parameter.indexOf('=')).toLowerCase() === 'boundary');
+    if (boundaries.length !== 1)
+        throw new ReleaseAdmissionError('invalid-form');
+    const raw = boundaries[0].slice(boundaries[0].indexOf('=') + 1);
+    const boundary = raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1) : raw;
+    if (!/^[0-9A-Za-z'()+_,./:=? -]{1,70}$/.test(boundary) || boundary.endsWith(' ') ||
+        (!raw.startsWith('"') && boundary.includes(' '))) {
+        throw new ReleaseAdmissionError('invalid-form');
+    }
+    return multipartParser({ boundary });
+}
+function checkRelease({ release, expectedDeploymentId }) {
+    if (!RELEASE_ID.test(release) || release !== expectedDeploymentId)
+        throw new ReleaseAdmissionError('stale-release');
+}
+function readReleaseHeader({ request, name }) {
+    const value = request.headers[name];
+    // Inspect raw headers too: Node may discard rather than join duplicate values.
+    const count = request.rawHeaders.filter((_, index) => index % 2 === 0 && request.rawHeaders[index].toLowerCase() === name).length;
+    if (count > 1)
+        throw new ReleaseAdmissionError('conflicting-release');
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !RELEASE_ID.test(value))
+        throw new ReleaseAdmissionError('conflicting-release');
+    return value;
+}
+/** Framework hints identify compiled assets, never the Atlas activation authorizing a mutation. */
+function validateFrameworkHints({ request, expectedFrameworkBuildId }) {
+    const header = readReleaseHeader({ request, name: FRAMEWORK_BUILD_HEADER });
+    let query;
+    try {
+        query = new URL(request.url ?? '/', 'http://release.invalid').searchParams.getAll('dpl');
+    }
+    catch {
+        throw new ReleaseAdmissionError('conflicting-release');
+    }
+    if (!artifactNextFrameworkBuildIdSchema.safeParse(expectedFrameworkBuildId).success ||
+        (header !== undefined && !artifactNextFrameworkBuildIdSchema.safeParse(header).success) ||
+        query.length > 1 || (query.length === 1 && !artifactNextFrameworkBuildIdSchema.safeParse(query[0]).success)) {
+        throw new ReleaseAdmissionError('conflicting-release');
+    }
+    if (header !== undefined && query.length === 1 && header !== query[0]) {
+        throw new ReleaseAdmissionError('conflicting-release');
+    }
+    const frameworkBuildId = header ?? query[0];
+    if (frameworkBuildId !== undefined && frameworkBuildId !== expectedFrameworkBuildId) {
+        throw new ReleaseAdmissionError('stale-release');
+    }
+}
+function bytes({ value }) {
+    if (!(value instanceof Uint8Array))
+        throw new ReleaseAdmissionError('invalid-form');
+    return value;
+}
+/**
+ * Admit a mutation against the release that rendered its document. No request is
+ * forwarded until admission succeeds. An admitted form exposes one continuation
+ * over the original iterator, including every byte inspected here.
+ */
+export async function admitHostedMutation({ request, expectedDeploymentId, expectedFrameworkBuildId, active, published }) {
+    const method = (request.method ?? 'GET').toUpperCase();
+    validateFrameworkHints({ request, expectedFrameworkBuildId });
+    if (READ_METHODS.has(method))
+        return {};
+    if (published && !active)
+        throw new ReleaseAdmissionError('inactive-release');
+    const release = readReleaseHeader({ request, name: RELEASE_HEADER });
+    if (release !== undefined) {
+        checkRelease({ release, expectedDeploymentId });
+        return {};
+    }
+    if (method !== 'POST')
+        throw new ReleaseAdmissionError('missing-release');
+    const parse = getFormParser({ contentType: request.headers['content-type'] });
+    // A normal for-await break destroys IncomingMessage. Retain this one iterator
+    // while peeking, then hand its continuation to the proxy without a second read.
+    const iterator = request.iterator({ destroyOnReturn: false });
+    const buffered = [];
+    const prefixBuffer = Buffer.alloc(MAX_PREFIX_BYTES);
+    let prefixLength = 0;
+    let ended = false;
+    try {
+        while (true) {
+            const release = parse({ prefix: prefixBuffer.subarray(0, prefixLength), ended });
+            if (release !== undefined) {
+                checkRelease({ release, expectedDeploymentId });
+                break;
+            }
+            if (ended)
+                throw new ReleaseAdmissionError('invalid-form');
+            if (prefixLength >= MAX_PREFIX_BYTES)
+                throw new ReleaseAdmissionError('prefix-limit');
+            const next = await iterator.next();
+            ended = next.done === true;
+            if (!ended) {
+                const chunk = bytes({ value: next.value });
+                buffered.push(chunk);
+                // Inspect at most 64 KiB even when a transport read returns a larger
+                // chunk. Keep that original chunk for lossless, zero-copy forwarding.
+                const inspected = chunk.subarray(0, MAX_PREFIX_BYTES - prefixLength);
+                prefixBuffer.set(inspected, prefixLength);
+                prefixLength += inspected.length;
+            }
+        }
+    }
+    catch (error) {
+        await iterator.return?.();
+        throw error;
+    }
+    async function* continuation() {
+        try {
+            for (const chunk of buffered)
+                yield chunk;
+            if (ended)
+                return;
+            while (true) {
+                const next = await iterator.next();
+                if (next.done)
+                    return;
+                yield bytes({ value: next.value });
+            }
+        }
+        finally {
+            // The transport owns abort/connection-close behavior. Returning this
+            // non-destructive iterator releases its listeners without losing a 409
+            // or upstream-error response by prematurely destroying the client socket.
+            await iterator.return?.();
+        }
+    }
+    return { body: continuation() };
+}

package/dist/gateway/server.d.ts

@@ -0,0 +1,29 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type TunnelLease, type TunnelBrokerOptions } from '../tunnel/index.js';
+import { ArtifactGatewayControl } from './control.js';
+import { type ArtifactRequestAdmission } from './admission.js';
+export interface ArtifactGatewayOptions {
+    control: ArtifactGatewayControl;
+    runtimeDomain: string;
+    parentOrigin: string;
+    gatewayOrigin: string;
+    sessionKey: string;
+    contextPrivateKey: string;
+    contextKeyId: string;
+    /** Unique per process, never a shared Cloud Run revision name. */
+    nodeId: string;
+    routing: TunnelBrokerOptions['routing'];
+    relay?: TunnelBrokerOptions['relay'];
+    resolveLease?: TunnelBrokerOptions['resolveLease'];
+    renewLease?: (lease: TunnelLease) => Promise<boolean>;
+    ready?: () => boolean;
+    admission?: Pick<ArtifactRequestAdmission, 'acquire'>;
+    onError?: (event: {
+        kind: string;
+        requestId?: string;
+    }) => void;
+}
+export declare function createArtifactGateway(options: ArtifactGatewayOptions): {
+    server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
+    drain(): Promise<void>;
+};

package/dist/gateway/server.js

@@ -0,0 +1,298 @@
+import { createPrivateKey, randomBytes, randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { z } from 'zod';
+import { ArtifactTunnelBroker } from '../tunnel/index.js';
+import { assertSafeRequest, normalizePublicOrigin } from '../tunnel/protocol.js';
+import { GatewayControlError } from './control.js';
+import { decodeGatewaySession, gatewaySessionCookies, renewGatewaySession, signGatewayContext } from './session.js';
+import { proxyHostedArtifact } from './hosted-proxy.js';
+import { admitHostedMutation, ReleaseAdmissionError } from './release-admission.js';
+import { ArtifactAdmissionError } from './admission.js';
+import { GatewayUsageReporter } from './usage.js';
+import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+function json(response, status, error) {
+    if (response.headersSent) {
+        response.destroy();
+        return;
+    }
+    if (status >= 400)
+        response.setHeader('connection', 'close');
+    response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+    response.end(JSON.stringify({ error }));
+}
+function rejectUpgrade(socket, status = 403) {
+    socket.end(`HTTP/1.1 ${status} Rejected\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+}
+function header(request, key) {
+    const value = request.headers[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function releaseHints(request) {
+    function uniqueHeader(name) {
+        const value = request.headers[name];
+        if (value === undefined)
+            return undefined;
+        const count = request.rawHeaders.filter((_, index) => index % 2 === 0 && request.rawHeaders[index].toLowerCase() === name).length;
+        if (typeof value !== 'string' || count !== 1 || !artifactNextFrameworkBuildIdSchema.safeParse(value).success)
+            throw new ReleaseAdmissionError('conflicting-release');
+        return value;
+    }
+    const deploymentId = uniqueHeader('x-sequence-artifact-release');
+    const frameworkHeader = uniqueHeader('x-deployment-id');
+    const query = new URL(request.url ?? '/', 'https://gateway.invalid').searchParams.getAll('dpl');
+    if (query.length > 1 || (query.length === 1 && !artifactNextFrameworkBuildIdSchema.safeParse(query[0]).success) ||
+        (frameworkHeader && query.length === 1 && frameworkHeader !== query[0]))
+        throw new ReleaseAdmissionError('conflicting-release');
+    return { deploymentId, frameworkBuildId: frameworkHeader ?? query[0] };
+}
+async function boundedJson(request) {
+    if (header(request, 'content-type')?.split(';', 1)[0] !== 'application/json')
+        throw new GatewayControlError(400);
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.from(chunk);
+        length += bytes.length;
+        if (length > 2048)
+            throw new GatewayControlError(413);
+        chunks.push(bytes);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+/** The bootstrap ticket travels in a fragment and a POST body, never a request URL or log. The page
+ * exchanges it only inside the Atlas frame; browsers without Fetch Metadata are covered by the script check. */
+function bootstrapPage({ response, parentOrigin }) {
+    const nonce = randomBytes(24).toString('base64');
+    response.writeHead(200, {
+        'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer',
+        'x-content-type-options': 'nosniff',
+        'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; connect-src 'self'; frame-ancestors ${parentOrigin}; base-uri 'none'; form-action 'none'`,
+    });
+    response.end(`<!doctype html><meta charset="utf-8"><title>Connecting application</title><p id="status">Connecting application…</p><script nonce="${nonce}">(() => {const ticket=new URLSearchParams(location.hash.slice(1)).get('ticket');history.replaceState(null,'',location.pathname);if(!ticket||window.top===window){document.getElementById('status').textContent='Open this application from Atlas.';return;}fetch('/_sequence/session',{method:'POST',credentials:'same-origin',headers:{'content-type':'application/json'},body:JSON.stringify({ticket})}).then(r=>{if(!r.ok)throw new Error();location.replace('/');}).catch(()=>{document.getElementById('status').textContent='This preview expired. Open it again from Atlas.';});})();</script>`);
+}
+export function createArtifactGateway(options) {
+    const parentOrigin = normalizePublicOrigin(options.parentOrigin);
+    const gatewayOrigin = normalizePublicOrigin(options.gatewayOrigin);
+    if (!/^[a-z0-9.-]+$/.test(options.runtimeDomain) || options.runtimeDomain.includes('..'))
+        throw new Error('Invalid Artifact runtime domain');
+    // Validate signing and cookie keys before accepting traffic.
+    if (Buffer.byteLength(options.sessionKey) < 32)
+        throw new Error('Artifact gateway session key is too short');
+    if (createPrivateKey(options.contextPrivateKey).asymmetricKeyType !== 'ed25519')
+        throw new Error('Artifact context key must be Ed25519');
+    const activeRequests = new WeakMap();
+    const leases = new Map();
+    const usage = new GatewayUsageReporter({ send: event => options.control.usage(event), onFailure: event => options.onError?.(event) });
+    let draining = false;
+    function requestOrigin(request) {
+        const host = header(request, 'host');
+        if (!host || /[\s/@\\?#]/.test(host))
+            throw new GatewayControlError(403);
+        const origin = `${new URL(gatewayOrigin).protocol}//${host}`;
+        const url = new URL(origin);
+        // One DNS label per application/session prevents suffix tricks and parent-domain cookies.
+        const suffix = `.${options.runtimeDomain}`;
+        if (url.hostname !== new URL(gatewayOrigin).hostname &&
+            (!url.hostname.endsWith(suffix) || !/^[a-z0-9-]+$/.test(url.hostname.slice(0, -suffix.length))))
+            throw new GatewayControlError(403);
+        if (url.port !== new URL(gatewayOrigin).port)
+            throw new GatewayControlError(403);
+        return origin;
+    }
+    async function authorize(request) {
+        const cached = activeRequests.get(request);
+        if (cached)
+            return cached;
+        const origin = requestOrigin(request);
+        assertSafeRequest(request.method ?? 'GET', request.url ?? '/');
+        const hints = releaseHints(request);
+        // Retained releases must belong to the valid main session's actor and scope.
+        const session = decodeGatewaySession({ cookie: header(request, 'cookie'), key: options.sessionKey, origin, ...hints });
+        if (!session || session.bridge.parentOrigin !== parentOrigin)
+            throw new GatewayControlError(403);
+        const method = request.method ?? 'GET';
+        if ((!['GET', 'HEAD', 'OPTIONS'].includes(method) || header(request, 'upgrade')) && header(request, 'origin') !== origin)
+            throw new GatewayControlError(403);
+        const target = await options.control.authorize(session);
+        const requestId = randomUUID();
+        const result = { session, target, requestId, requestContext: signGatewayContext({
+                session: { ...session, lattice: target.lattice, taskRoutes: target.taskRoutes }, method, path: request.url ?? '/', privateKey: options.contextPrivateKey, keyId: options.contextKeyId,
+                capabilities: target.capabilities, serviceAccountId: target.serviceAccountId, requestId,
+            }) };
+        activeRequests.set(request, result);
+        return result;
+    }
+    const broker = new ArtifactTunnelBroker({
+        nodeId: options.nodeId, routing: options.routing, relay: options.relay, resolveLease: options.resolveLease,
+        authorizeTunnel: async (request) => {
+            if (draining || requestOrigin(request) !== gatewayOrigin || header(request, 'origin'))
+                return null;
+            const authorization = header(request, 'authorization'), sessionId = header(request, 'x-artifact-session-id');
+            const epoch = Number(header(request, 'x-artifact-tunnel-epoch'));
+            if (!authorization?.startsWith('Bearer ') || !sessionId || !Number.isSafeInteger(epoch) || epoch < 1)
+                return null;
+            const token = authorization.slice(7);
+            const lease = await options.control.tunnel({ token, sessionId, epoch });
+            leases.set(sessionId, { token, lease });
+            return lease;
+        },
+        authorizeRequest: async (request, sessionId) => {
+            const authorized = await authorize(request);
+            if (authorized.target.kind !== 'development' || authorized.target.sessionId !== sessionId)
+                return null;
+            return { ownerId: authorized.session.ownerId, publicOrigin: authorized.session.publicOrigin, requestContext: authorized.requestContext };
+        },
+        validateLease: async (lease) => {
+            const credential = leases.get(lease.sessionId);
+            // Remote browser nodes use the control-plane session check above; only the owner holds the tunnel credential.
+            if (!credential) {
+                const owner = await options.routing.lookup(lease.sessionId);
+                return Boolean(options.relay && owner && owner.nodeId !== options.nodeId && owner.epoch === lease.epoch);
+            }
+            if (credential.lease.epoch !== lease.epoch)
+                return false;
+            try {
+                const current = await options.control.tunnel({ token: credential.token, sessionId: lease.sessionId, epoch: lease.epoch });
+                lease.expiresAt = current.expiresAt;
+                credential.lease = current;
+                const owner = await options.routing.lookup(lease.sessionId);
+                // Before the claim, an authorized newer epoch must reach routing.claim, which atomically fences
+                // the older owner, including a record a dead node left behind. Only a current owner is checked and renewed.
+                if (!owner || owner.epoch < lease.epoch)
+                    return true;
+                if (owner.nodeId !== options.nodeId || owner.epoch !== lease.epoch)
+                    return false;
+                if (options.renewLease && !await options.renewLease(lease))
+                    return false;
+                return true;
+            }
+            catch {
+                if (leases.get(lease.sessionId) === credential)
+                    leases.delete(lease.sessionId);
+                return false;
+            }
+        },
+        onTunnelClosed: lease => { if (leases.get(lease.sessionId)?.lease.epoch === lease.epoch)
+            leases.delete(lease.sessionId); },
+    });
+    const server = createServer({ maxHeaderSize: 32 * 1024, requestTimeout: 60_000, headersTimeout: 15_000 }, (request, response) => {
+        const startedAt = new Date().toISOString(), started = performance.now();
+        void (async () => {
+            if ((request.url === '/_sequence/health' || request.url === '/health') && request.method === 'GET') {
+                const ready = !draining && (options.ready?.() ?? true);
+                json(response, ready ? 200 : 503, ready ? 'ready' : 'unavailable');
+                return;
+            }
+            if (draining) {
+                response.setHeader('connection', 'close');
+                json(response, 503, 'gateway_draining');
+                return;
+            }
+            const origin = requestOrigin(request);
+            if (request.url === '/_sequence/bootstrap' && request.method === 'GET') {
+                // Atlas only embeds this page (see frame-ancestors). Refusing top-level loads keeps a crafted
+                // link from exchanging someone else's ticket in the victim's browser (login CSRF).
+                const destination = header(request, 'sec-fetch-dest');
+                if (destination !== undefined && destination !== 'iframe')
+                    throw new GatewayControlError(403);
+                bootstrapPage({ response, parentOrigin });
+                return;
+            }
+            if (request.url === '/_sequence/session' && request.method === 'POST') {
+                if (header(request, 'origin') !== origin)
+                    throw new GatewayControlError(403);
+                const { ticket } = z.object({ ticket: z.string().regex(/^[A-Za-z0-9_-]{43}$/) }).strict().parse(await boundedJson(request));
+                const { session } = await options.control.bootstrap(ticket);
+                if (session.publicOrigin !== origin || session.bridge.parentOrigin !== parentOrigin)
+                    throw new GatewayControlError(403);
+                response.setHeader('set-cookie', gatewaySessionCookies({ session, key: options.sessionKey, cookie: header(request, 'cookie') }));
+                json(response, 200, 'connected');
+                return;
+            }
+            if (request.url?.startsWith('/_sequence/')) {
+                json(response, 404, 'not_found');
+                return;
+            }
+            if (['GET', 'HEAD'].includes(request.method ?? 'GET')) {
+                const url = new URL(request.url ?? '/', origin);
+                if (url.searchParams.has('__sequence_release')) {
+                    url.searchParams.delete('__sequence_release');
+                    request.url = url.pathname + url.search;
+                }
+            }
+            const { session, target, requestContext, requestId } = await authorize(request);
+            let reported = false;
+            const report = () => {
+                if (reported)
+                    return;
+                reported = true;
+                usage.record({
+                    eventId: `gateway:${requestId}`, requestId, projectId: target.projectId, environment: target.environment,
+                    ...(target.kind === 'development' ? { devSessionId: target.sessionId } : { deploymentId: target.deploymentId }),
+                    startedAt, endedAt: new Date().toISOString(),
+                    measurements: { requestCount: 1, durationMs: Math.max(0, Math.round(performance.now() - started)) },
+                    outcome: !response.writableFinished ? 'cancelled' : response.statusCode >= 400 ? 'error' : 'success',
+                    httpStatus: response.statusCode,
+                });
+            };
+            response.once('finish', report);
+            response.once('close', report);
+            if (response.destroyed) {
+                report();
+                return;
+            }
+            const renewed = renewGatewaySession({ session, authorizedExpiresAt: target.expiresAt });
+            if (renewed)
+                response.setHeader('set-cookie', gatewaySessionCookies({ session: renewed, key: options.sessionKey, cookie: header(request, 'cookie'), renewal: true }));
+            // Authorization precedes every response, including Next static assets and cached pages.
+            response.setHeader('content-security-policy', `frame-ancestors ${session.bridge.parentOrigin}`);
+            response.setHeader('referrer-policy', 'same-origin');
+            response.setHeader('x-content-type-options', 'nosniff');
+            if (target.kind === 'development') {
+                await broker.handleHttp(request, response, target.sessionId);
+                return;
+            }
+            if (!options.admission)
+                throw new ArtifactAdmissionError(503, 'admission_unavailable');
+            const admitted = await options.admission.acquire({ environment: target.environment, projectId: target.projectId, deploymentId: target.deploymentId, resources: target.manifest?.server.resources });
+            admitted.bind(response, () => response.destroy());
+            if (response.destroyed)
+                return;
+            const { body } = await admitHostedMutation({ request, expectedDeploymentId: target.deploymentId, expectedFrameworkBuildId: target.frameworkBuildId, active: target.active, published: session.published });
+            await proxyHostedArtifact({ request, response, target, requestContext, body, limits: { timeoutMs: admitted.timeoutMs } });
+        })().catch(error => {
+            options.onError?.({ kind: error instanceof ReleaseAdmissionError ? 'release_mismatch' : error instanceof GatewayControlError ? 'authorization_denied' : 'request_failed' });
+            const status = error instanceof ReleaseAdmissionError || error instanceof GatewayControlError || error instanceof ArtifactAdmissionError ? error.status : 400;
+            json(response, status === 401 || status === 404 ? 403 : status, error instanceof ReleaseAdmissionError ? 'update_required' : 'artifact_request_failed');
+        });
+    });
+    server.on('upgrade', (request, socket, head) => {
+        void (async () => {
+            if (draining) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
+            if (request.url === '/_sequence/tunnel') {
+                await broker.handleTunnelUpgrade(request, socket, head);
+                return;
+            }
+            const authorized = await authorize(request);
+            if (authorized.target.kind !== 'development') {
+                rejectUpgrade(socket);
+                return;
+            }
+            await broker.handleWebSocketUpgrade(request, socket, head, authorized.target.sessionId);
+        })().catch(() => rejectUpgrade(socket));
+    });
+    return {
+        server,
+        async drain() {
+            draining = true;
+            server.closeIdleConnections();
+            broker.close();
+            leases.clear();
+            await new Promise(resolve => server.close(() => resolve()));
+            await usage.flush();
+        },
+    };
+}

package/dist/gateway/session.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+export declare const GATEWAY_SESSION_COOKIE = "__Host-atlas-artifact-session";
+export declare function gatewayReleaseCookieName(deploymentId: string): string;
+declare const sessionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    kind: z.ZodEnum<{
+        development: "development";
+        hosted: "hosted";
+    }>;
+    sessionId: z.ZodNullable<z.ZodString>;
+    deploymentId: z.ZodNullable<z.ZodString>;
+    frameworkBuildId: z.ZodNullable<z.ZodString>;
+    projectId: z.ZodString;
+    ownerId: z.ZodString;
+    environment: z.ZodString;
+    publicOrigin: z.ZodString;
+    expiresAt: z.ZodNumber;
+    maxExpiresAt: z.ZodOptional<z.ZodNumber>;
+    published: z.ZodBoolean;
+    bridge: z.ZodObject<{
+        parentOrigin: z.ZodString;
+        channelId: z.ZodString;
+        nonce: z.ZodString;
+    }, z.core.$strict>;
+    lattice: z.ZodOptional<z.ZodObject<{
+        runId: z.ZodNullable<z.ZodString>;
+        nodeId: z.ZodNullable<z.ZodString>;
+        stepId: z.ZodNullable<z.ZodString>;
+        processId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type GatewaySession = z.infer<typeof sessionSchema>;
+/** Active use renews the idle window, but never extends the original admission's eight-hour bound. */
+export declare function renewGatewaySession({ session, authorizedExpiresAt, now }: {
+    session: GatewaySession;
+    authorizedExpiresAt: number;
+    now?: number;
+}): GatewaySession | null;
+export declare function gatewaySessionCookies({ session, key, cookie, renewal, now }: {
+    session: GatewaySession;
+    key: string;
+    cookie?: string;
+    renewal?: boolean;
+    now?: number;
+}): string[];
+export declare function encodeGatewaySession({ session, key }: {
+    session: GatewaySession;
+    key: string;
+}): string;
+/** Retained releases preserve tabs, never a different login or runtime scope. */
+export declare function decodeGatewaySession(input: {
+    cookie: string | undefined;
+    key: string;
+    origin: string;
+    now?: number;
+    deploymentId?: string;
+    frameworkBuildId?: string;
+}): GatewaySession | null;
+export declare function signGatewayContext({ session, method, path, privateKey, keyId, now, capabilities, serviceAccountId, requestId }: {
+    session: GatewaySession;
+    method: string;
+    path: string;
+    privateKey: string;
+    keyId: string;
+    now?: number;
+    capabilities?: string[];
+    serviceAccountId?: string | null;
+    requestId?: string;
+}): string;
+export {};