@sequenceholdings/artifact-studio 0.6.3 → 0.6.6

package/dist/server/runtime-config.js

@@ -22,6 +22,16 @@ export const artifactRuntimeConfigSchema = z.object({
     devSessionId: z.string().min(1).max(255).optional(),
     deploymentId: z.string().min(1).max(255).optional(),
 }).strict().refine(value => !(value.devSessionId && value.deploymentId), 'Runtime cannot be both local and hosted');
+/**
+ * Marks a lease file's configuration. Non-enumerable, so the strict schema still accepts the
+ * object if a caller hands it back as an explicit `runtime` (which then drops the marker).
+ */
+function developmentLease(config) {
+    // A lease belongs to exactly one development session; anything else is not a development lease.
+    if (!config.devSessionId || config.deploymentId)
+        return config;
+    return Object.defineProperty(config, 'development', { value: true, enumerable: false, writable: false, configurable: false });
+}
 /** Credentials are platform-provided and rotated by the CLI, never inferred from ambient cloud auth. */
 export async function readArtifactRuntimeConfig({ file = process.env.SEQUENCE_ARTIFACT_RUNTIME_FILE } = {}) {
     if (!file) {
@@ -42,7 +52,7 @@ export async function readArtifactRuntimeConfig({ file = process.env.SEQUENCE_AR
         const stat = await handle.stat();
         if (!stat.isFile() || stat.size > 65536 || (process.platform !== 'win32' && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())))
             throw new Error('Artifact runtime credential file must be owner-readable only, regular, and no larger than 64 KiB');
-        return artifactRuntimeConfigSchema.parse(JSON.parse(await handle.readFile('utf8')));
+        return developmentLease(artifactRuntimeConfigSchema.parse(JSON.parse(await handle.readFile('utf8'))));
     }
     finally {
         await handle.close();

package/dist/server/testing.d.ts

@@ -19,7 +19,7 @@ export interface SignTestExternalContextInput {
     /** Overrides on a verified-borrower default principal. */
     principal?: Partial<Omit<ExternalPrincipalClaims, 'kind'>>;
     serviceAccountId: string;
-    /** Defaults to `published`. Verifiers refuse `development` until development leases admit it. */
+    /** Defaults to `published`. Verifiers accept `development` only under a development lease, for its session. */
     mode?: RequestContextV2External['mode'];
     deploymentId?: string | null;
     devSessionId?: string | null;

package/dist/server.d.ts

@@ -2,8 +2,8 @@ import 'server-only';
 export { createArtifactServerClient } from './server/client.js';
 export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './server/errors.js';
 export type { ArtifactAtlasRefusal } from './server/errors.js';
-export type { ArtifactAuditEvent, ArtifactOrmOperations, ArtifactOrmOptions, ArtifactProcessAdvance, ArtifactProcessAdvanceResult, ArtifactProcessArtifactRef, ArtifactProcessAssign, ArtifactProcessAssignResult, ArtifactProcessDefinition, ArtifactProcessDescribeQuery, ArtifactProcessEdge, ArtifactProcessHumanNode, ArtifactProcessNode, ArtifactProcessNodeBase, ArtifactProcessNodeState, ArtifactProcessPrincipal, ArtifactProcessPrincipalSearch, ArtifactProcessPrincipals, ArtifactProcessRun, ArtifactProcessRunRecord, ArtifactProcessRunSnapshot, ArtifactProcessRunsQuery, ArtifactProcessRunViewerChange, ArtifactProcessRunViewers, ArtifactProcessStart, ArtifactProcessStepRecord, ArtifactProcessTask, ArtifactProcessTasksQuery, ArtifactServerAudit, ArtifactServerClient, ArtifactServerClientOptions, ArtifactServerContext, ArtifactServerFetchOptions, ArtifactServerFlags, ArtifactServerProcesses, } from './server/client.js';
-export { ARTIFACT_AUDIT_ACTIONS, ARTIFACT_AUDIT_RESOURCES_PER_EVENT, ARTIFACT_FLAGS_PER_REQUEST, ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT, ARTIFACT_PROCESS_PRINCIPAL_TYPES, ARTIFACT_PROCESS_PRINCIPALS_PER_CALL, ARTIFACT_PROCESS_RUN_STATUSES, ARTIFACT_PROCESS_RUNS_LIMIT, ARTIFACT_PROCESS_TASK_VIEWS, ARTIFACT_PROCESS_TASKS_LIMIT, } from './server/broker-contract.js';
+export type { ArtifactAuditEvent, ArtifactOrmOperations, ArtifactOrmOptions, ArtifactProcessAdvance, ArtifactProcessAdvanceResult, ArtifactProcessArtifactRef, ArtifactProcessAssign, ArtifactProcessAssignResult, ArtifactProcessDefinition, ArtifactProcessDescribeQuery, ArtifactProcessEdge, ArtifactProcessHumanNode, ArtifactProcessNode, ArtifactProcessNodeBase, ArtifactProcessNodeState, ArtifactProcessPrincipal, ArtifactProcessPrincipalSearch, ArtifactProcessPrincipals, ArtifactProcessRun, ArtifactProcessRunRecord, ArtifactProcessRunSnapshot, ArtifactProcessRunSummary, ArtifactProcessRunsPage, ArtifactProcessRunsPageQuery, ArtifactProcessRunsQuery, ArtifactProcessRunViewerChange, ArtifactProcessRunViewers, ArtifactProcessStart, ArtifactProcessStepRecord, ArtifactProcessShareRun, ArtifactProcessShareRunResult, ArtifactProcessRunSharingAuthoritiesQuery, ArtifactProcessRunSharingAuthoritiesPage, ArtifactProcessRunSharingAuthority, ArtifactProcessRunSharingDelegate, ArtifactProcessRevokeRunSharingAuthority, ArtifactProcessRevokeRunSharingAuthorityResult, ArtifactProcessTask, ArtifactProcessTasksQuery, ArtifactServerAudit, ArtifactServerClient, ArtifactServerClientOptions, ArtifactServerContext, ArtifactServerFetchOptions, ArtifactServerFlags, ArtifactServerProcesses, } from './server/client.js';
+export { ARTIFACT_AUDIT_ACTIONS, ARTIFACT_AUDIT_RESOURCES_PER_EVENT, ARTIFACT_FLAGS_PER_REQUEST, ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT, ARTIFACT_PROCESS_PRINCIPAL_TYPES, ARTIFACT_PROCESS_PRINCIPALS_PER_CALL, ARTIFACT_PROCESS_RUN_STATUSES, ARTIFACT_PROCESS_RUNS_LIMIT, ARTIFACT_PROCESS_RUN_ENTITIES_LIMIT, ARTIFACT_PROCESS_SHARE_NODES_LIMIT, ARTIFACT_PROCESS_SHARING_AUTHORITIES_LIMIT, ARTIFACT_PROCESS_TASK_VIEWS, ARTIFACT_PROCESS_TASKS_LIMIT, } from './server/broker-contract.js';
 export type { ArtifactAuditAction, ArtifactProcessPrincipalType, ArtifactProcessRunStatus, ArtifactProcessTaskView, } from './server/broker-contract.js';
 export { getArtifactRequestContext, readArtifactRuntimeConfig } from './server/runtime-config.js';
 export type { ArtifactRuntimeConfig, ArtifactRequestHeaders } from './server/runtime-config.js';

package/dist/server.js

@@ -1,7 +1,7 @@
 import 'server-only';
 export { createArtifactServerClient } from './server/client.js';
 export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './server/errors.js';
-export { ARTIFACT_AUDIT_ACTIONS, ARTIFACT_AUDIT_RESOURCES_PER_EVENT, ARTIFACT_FLAGS_PER_REQUEST, ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT, ARTIFACT_PROCESS_PRINCIPAL_TYPES, ARTIFACT_PROCESS_PRINCIPALS_PER_CALL, ARTIFACT_PROCESS_RUN_STATUSES, ARTIFACT_PROCESS_RUNS_LIMIT, ARTIFACT_PROCESS_TASK_VIEWS, ARTIFACT_PROCESS_TASKS_LIMIT, } from './server/broker-contract.js';
+export { ARTIFACT_AUDIT_ACTIONS, ARTIFACT_AUDIT_RESOURCES_PER_EVENT, ARTIFACT_FLAGS_PER_REQUEST, ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT, ARTIFACT_PROCESS_PRINCIPAL_TYPES, ARTIFACT_PROCESS_PRINCIPALS_PER_CALL, ARTIFACT_PROCESS_RUN_STATUSES, ARTIFACT_PROCESS_RUNS_LIMIT, ARTIFACT_PROCESS_RUN_ENTITIES_LIMIT, ARTIFACT_PROCESS_SHARE_NODES_LIMIT, ARTIFACT_PROCESS_SHARING_AUTHORITIES_LIMIT, ARTIFACT_PROCESS_TASK_VIEWS, ARTIFACT_PROCESS_TASKS_LIMIT, } from './server/broker-contract.js';
 export { getArtifactRequestContext, readArtifactRuntimeConfig } from './server/runtime-config.js';
 export { ArtifactContextError, getArtifactBrowserBootstrap } from './server/request-context.js';
 export { verifyArtifactExternalContext } from './server/external-context.js';

package/dist/tunnel/broker.d.ts

@@ -2,6 +2,8 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Duplex } from 'node:stream';
 import { type TunnelLimits } from './peer.js';
 import type { TunnelRelay } from './transport.js';
+import { type TunnelExternalRequest } from './external.js';
+export type { TunnelExternalFailure, TunnelExternalRequest } from './external.js';
 export interface TunnelLease {
     sessionId: string;
     epoch: number;
@@ -53,12 +55,28 @@ export declare class ArtifactTunnelBroker {
     constructor(options: TunnelBrokerOptions);
     handleTunnelUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
     handleHttp(request: IncomingMessage, response: ServerResponse, sessionId: string): Promise<void>;
+    /** Proxies an admitted external ingress request over the session's tunnel. Never throws. */
+    handleExternalHttp(input: TunnelExternalRequest): Promise<void>;
     handleWebSocketUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, sessionId: string): Promise<void>;
     private authorize;
+    /**
+     * The live tunnel for an external request: the session's current lease, for the granted project
+     * and environment, still valid. Null otherwise. No browser owner is compared: Atlas's grant
+     * already checked the session and its owner's grant on the ingress service account.
+     */
+    private externalConnection;
     private valid;
     private remoteConnection;
     private attach;
     private receive;
+    private receiveHead;
+    private receiveBody;
+    /**
+     * Backpressure from an external caller abandons the request after the idle timeout instead of
+     * holding its stream (and the caller's admission permit) until the request timeout. A write the
+     * abort interrupted is not a tunnel failure, so the session's other streams carry on.
+     */
+    private writeExternalChunk;
     private finish;
     private abort;
     /** Immediate revocation and graceful service shutdown hook. */

package/dist/tunnel/broker.js

@@ -2,6 +2,7 @@ import { WebSocketServer } from 'ws';
 import { TunnelPeer, tunnelLimits } from './peer.js';
 import { assertSafeRequest, encodeTunnelFrame, isSharedCacheDirective, normalizePublicOrigin, sanitizeRequestHeaders, sanitizeResponseHeaders, SHARED_CACHE_REFUSAL, TUNNEL_PROTOCOL } from './protocol.js';
 import { forwardWebSocketMessages, MessageBudget, permittedCloseCode, sendWebSocket, WebSocketMessage, writeChunk } from './io.js';
+import { declaredLength, isExternalFailure } from './external.js';
 const UPGRADE_REASONS = { 403: 'Forbidden', 429: 'Too Many Requests', 503: 'Service Unavailable' };
 function rejectUpgrade(socket, status) {
     socket.end(`HTTP/1.1 ${status} ${UPGRADE_REASONS[status] ?? 'Service Unavailable'}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
@@ -194,6 +195,91 @@ export class ArtifactTunnelBroker {
                 rejectHttp(response, 403);
         }
     }
+    /** Proxies an admitted external ingress request over the session's tunnel. Never throws. */
+    async handleExternalHttp(input) {
+        const { request, response, sessionId } = input;
+        const method = request.method ?? 'GET';
+        const maxRequestBytes = Math.min(input.maxRequestBytes, this.limits.maxBodyBytes);
+        try {
+            assertSafeRequest(method, request.url ?? '/');
+            if (!input.requestContext || /[\r\n]/.test(input.requestContext))
+                throw new Error('Invalid request context');
+        }
+        catch {
+            input.fail(400);
+            return;
+        }
+        const length = request.headers['content-length'];
+        if (length !== undefined && (!/^(0|[1-9][0-9]*)$/.test(length) || Number(length) > maxRequestBytes)) {
+            input.fail(413);
+            return;
+        }
+        let connection;
+        try {
+            connection = await this.externalConnection(input);
+        }
+        catch {
+            connection = null;
+        }
+        // No tunnel, or one for another project: the session ended or never connected.
+        if (!connection) {
+            input.fail(503);
+            return;
+        }
+        let headers;
+        try {
+            headers = sanitizeRequestHeaders(request.headers, input.publicOrigin, { mode: 'ingress', appHeaders: input.appHeaders });
+        }
+        catch {
+            input.fail(400);
+            return;
+        }
+        headers['x-sequence-artifact-context'] = input.requestContext;
+        let id;
+        try {
+            id = connection.peer.open();
+        }
+        catch {
+            input.fail(503);
+            return;
+        }
+        const active = connection;
+        const streamId = id;
+        const timer = setTimeout(() => this.abort(active, streamId, 504), Math.min(input.timeoutMs, this.limits.requestTimeoutMs));
+        timer.unref();
+        connection.streams.set(id, {
+            request, response, timer, bytes: 0, receivedHeaders: false,
+            message: new WebSocketMessage(this.limits.maxWebSocketMessageBytes, connection.messageBudget),
+            external: {
+                writeHead: input.writeHead, fail: input.fail, idleWriteTimeoutMs: input.idleWriteTimeoutMs,
+                maxResponseBytes: Math.min(input.maxResponseBytes, this.limits.maxBodyBytes),
+            },
+        });
+        // Even a response the gateway finished itself (its admission timeout's 504) stops the stream;
+        // a stream that completed normally is already gone, so this is a no-op for it.
+        response.once('close', () => this.abort(active, streamId));
+        request.once('aborted', () => this.abort(active, streamId));
+        try {
+            await connection.peer.send({ type: 'request', id, method, path: request.url ?? '/', headers, websocket: false });
+            let total = 0;
+            for await (const chunk of input.body ?? request) {
+                if (!connection.streams.has(id))
+                    return;
+                const bytes = Buffer.from(chunk);
+                total += bytes.length;
+                if (total > maxRequestBytes) {
+                    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 {
+            this.abort(connection, id, 503);
+        }
+    }
     async handleWebSocketUpgrade(request, socket, head, sessionId) {
         socket.pause();
         try {
@@ -255,6 +341,29 @@ export class ArtifactTunnelBroker {
             return null;
         return { connection, headers };
     }
+    /**
+     * The live tunnel for an external request: the session's current lease, for the granted project
+     * and environment, still valid. Null otherwise. No browser owner is compared: Atlas's grant
+     * already checked the session and its owner's grant on the ingress service account.
+     */
+    async externalConnection({ sessionId, projectId, environment }) {
+        if (this.closing)
+            return null;
+        const granted = (lease) => lease.sessionId === sessionId && lease.projectId === projectId && lease.environment === environment;
+        let connection = this.connections.get(sessionId);
+        if (this.options.relay && this.options.resolveLease) {
+            const lease = await this.options.resolveLease(sessionId);
+            if (!lease || !granted(lease) || !(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 || !granted(connection.lease) || !(await this.valid(connection)))
+            return null;
+        return connection;
+    }
     async valid(connection) {
         const owner = await this.options.routing.lookup(connection.lease.sessionId);
         if (this.options.resolveLease) {
@@ -330,10 +439,7 @@ export class ArtifactTunnelBroker {
         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;
-            stream.response.writeHead(frame.status, developmentResponseHeaders({ response: stream.response, headers: sanitizeResponseHeaders(frame.headers) }));
+            this.receiveHead(connection, stream, frame);
             return;
         }
         if (frame.type === 'data') {
@@ -348,17 +454,8 @@ export class ArtifactTunnelBroker {
                     }
                 }
             }
-            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);
-            }
+            else
+                await this.receiveBody(connection, stream, frame);
             return;
         }
         if (frame.type === 'end') {
@@ -399,6 +496,62 @@ export class ArtifactTunnelBroker {
             upgrade.socket.resume();
         }
     }
+    receiveHead(connection, stream, frame) {
+        if (!stream.response || stream.receivedHeaders)
+            throw new Error('Unexpected response');
+        const headers = sanitizeResponseHeaders(frame.headers);
+        if (stream.external) {
+            // Decided on the head, before any body byte. The tunnel client carries the app's validated
+            // content-length on the frame; sanitising has already removed it from what the caller gets.
+            const declared = declaredLength(frame.headers['content-length']);
+            if (!stream.external.writeHead({ status: frame.status, headers, declaredLength: declared })) {
+                this.abort(connection, frame.id, 502);
+                return;
+            }
+            // The body may not outgrow the length the head was judged on.
+            stream.external.declaredLength = declared;
+            stream.receivedHeaders = true;
+            return;
+        }
+        stream.receivedHeaders = true;
+        stream.response.writeHead(frame.status, developmentResponseHeaders({ response: stream.response, headers }));
+    }
+    async receiveBody(connection, stream, frame) {
+        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;
+        const cap = stream.external
+            ? Math.min(stream.external.maxResponseBytes, stream.external.declaredLength ?? Number.POSITIVE_INFINITY)
+            : this.limits.maxBodyBytes;
+        if (stream.bytes > cap) {
+            this.abort(connection, frame.id, 502);
+            return;
+        }
+        if (stream.external)
+            await this.writeExternalChunk(connection, frame.id, stream.response, bytes, stream.external.idleWriteTimeoutMs);
+        else
+            await writeChunk(stream.response, bytes);
+    }
+    /**
+     * Backpressure from an external caller abandons the request after the idle timeout instead of
+     * holding its stream (and the caller's admission permit) until the request timeout. A write the
+     * abort interrupted is not a tunnel failure, so the session's other streams carry on.
+     */
+    async writeExternalChunk(connection, id, response, bytes, idleWriteTimeoutMs) {
+        const timer = setTimeout(() => this.abort(connection, id, 504), idleWriteTimeoutMs);
+        timer.unref();
+        try {
+            await writeChunk(response, bytes);
+        }
+        catch (error) {
+            if (connection.streams.has(id))
+                throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     finish(connection, id, status) {
         const stream = connection.streams.get(id);
         if (!stream)
@@ -408,8 +561,13 @@ export class ArtifactTunnelBroker {
         clearTimeout(stream.timer);
         stream.message.reset();
         if (stream.response) {
-            if (status || !stream.receivedHeaders)
-                rejectHttp(stream.response, status ?? 502);
+            if (status || !stream.receivedHeaders) {
+                const failure = status ?? 502;
+                if (stream.external)
+                    stream.external.fail(isExternalFailure(failure) ? failure : 502);
+                else
+                    rejectHttp(stream.response, failure);
+            }
             else
                 stream.response.end();
         }

package/dist/tunnel/client.d.ts

@@ -1,4 +1,5 @@
 import { type TunnelLimits } from './peer.js';
+import { type TunnelFrame } from './protocol.js';
 export interface LocalTunnelOptions {
     url: string;
     token: string;
@@ -20,3 +21,15 @@ export interface LocalTunnelConnection {
 /** 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>;
+/**
+ * The origin a forwarded request is pinned to. An external ingress request (its context signed
+ * by an `external-` kid, which only the gateway puts on a frame) keeps the ingress origin the
+ * broker set, so the app sees the same host as on a hosted release. Everything else is pinned to
+ * this session's own origin.
+ */
+export declare function tunnelFrameOrigin({ headers, sessionOrigin }: {
+    headers: Extract<TunnelFrame, {
+        type: 'request';
+    }>['headers'];
+    sessionOrigin: string;
+}): string;

package/dist/tunnel/client.js

@@ -3,7 +3,9 @@ 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';
+import { declaredLength } from './external.js';
 import { isLoopbackHostname } from '../loopback.js';
+import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX } from '../server/internal/signed-token.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) {
@@ -52,7 +54,7 @@ export async function connectLocalTunnel(options) {
     const handle = async (frame) => {
         if (frame.type === 'request') {
             assertSafeRequest(frame.method, frame.path);
-            const headers = sanitizeRequestHeaders(frame.headers, publicOrigin);
+            const headers = sanitizeRequestHeaders(frame.headers, tunnelFrameOrigin({ headers: frame.headers, sessionOrigin: publicOrigin }));
             // Only the already authenticated gateway may mint this signed context.
             const context = frame.headers['x-sequence-artifact-context'];
             if (typeof context === 'string')
@@ -91,7 +93,14 @@ export async function connectLocalTunnel(options) {
                 local.once('response', (response) => {
                     void (async () => {
                         try {
-                            await peer.send({ type: 'response', id: frame.id, status: response.statusCode ?? 502, headers: sanitizeResponseHeaders(response.headers) });
+                            // Sanitising drops content-length as a hop header. The validated length the app declared
+                            // rides on the frame so the gateway can decide an external response on its head as hosted
+                            // ingress does (an empty 200 needs no content type); the broker never passes it on.
+                            const declared = declaredLength(response.headers['content-length']);
+                            const headers = sanitizeResponseHeaders(response.headers);
+                            if (declared !== null)
+                                headers['content-length'] = String(declared);
+                            await peer.send({ type: 'response', id: frame.id, status: response.statusCode ?? 502, headers });
                             let total = 0;
                             for await (const chunk of response) {
                                 const bytes = Buffer.from(chunk);
@@ -182,3 +191,32 @@ export async function connectLocalTunnel(options) {
     });
     return { closed, close: abort };
 }
+/**
+ * The origin a forwarded request is pinned to. An external ingress request (its context signed
+ * by an `external-` kid, which only the gateway puts on a frame) keeps the ingress origin the
+ * broker set, so the app sees the same host as on a hosted release. Everything else is pinned to
+ * this session's own origin.
+ */
+export function tunnelFrameOrigin({ headers, sessionOrigin }) {
+    const context = headers['x-sequence-artifact-context'];
+    const host = headers['x-forwarded-host'];
+    const proto = headers['x-forwarded-proto'];
+    if (typeof context !== 'string' || typeof host !== 'string' || typeof proto !== 'string' || !signedByExternalKid(context))
+        return sessionOrigin;
+    try {
+        return normalizePublicOrigin(`${proto}://${host}`);
+    }
+    catch {
+        return sessionOrigin;
+    }
+}
+function signedByExternalKid(token) {
+    try {
+        const header = JSON.parse(Buffer.from(token.split('.')[0] ?? '', 'base64url').toString('utf8'));
+        return typeof header === 'object' && header !== null && 'kid' in header && typeof header.kid === 'string' &&
+            header.kid.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/tunnel/external.d.ts

@@ -0,0 +1,51 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** The failures an external request's writer answers itself (the gateway's error contract). */
+export type TunnelExternalFailure = 400 | 413 | 502 | 503 | 504;
+/**
+ * An external ingress request proxied over a development session's tunnel (local development
+ * only, design §(j.3) step 3). No browser session or cookie is involved: the gateway admitted the
+ * caller and signed the context. The broker only checks that the session's tunnel belongs to the
+ * granted project and environment, forwards ingress-sanitised headers, and leaves every response
+ * decision to the caller's `writeHead` and every failure to its `fail`.
+ */
+export interface TunnelExternalRequest {
+    request: IncomingMessage;
+    response: ServerResponse;
+    sessionId: string;
+    projectId: string;
+    environment: string;
+    /**
+     * The ingress host's canonical origin. The app sees it as `host` / `x-forwarded-host`, as it sees
+     * the ingress origin on a hosted release, not the development session's own origin.
+     */
+    publicOrigin: string;
+    /** The signed external context, forwarded as the only platform header. */
+    requestContext: string;
+    /** Declared request headers forwarded on top of the fixed ingress allowlist. */
+    appHeaders: readonly string[];
+    /** The request body, when the caller buffered it; otherwise the request stream is forwarded. */
+    body?: AsyncIterable<Uint8Array>;
+    maxRequestBytes: number;
+    maxResponseBytes: number;
+    timeoutMs: number;
+    /** A response whose writes stay blocked this long is abandoned (504). */
+    idleWriteTimeoutMs: number;
+    /** Applies the response policy to the head and sets it; false refuses the response (502, no body byte sent). */
+    writeHead(input: {
+        status: number;
+        headers: Record<string, string | string[]>;
+        declaredLength: number | null;
+    }): boolean;
+    /** Writes a broker-decided failure; destroys the response when its head was already sent. */
+    fail(status: TunnelExternalFailure): void;
+}
+export type ExternalStream = Pick<TunnelExternalRequest, 'writeHead' | 'fail' | 'maxResponseBytes' | 'idleWriteTimeoutMs'> & {
+    /** The content-length the accepted head declared; the body is cut off once it passes it. */
+    declaredLength?: number | null;
+};
+export declare function isExternalFailure(status: number): status is TunnelExternalFailure;
+/**
+ * A declared body length as a plain decimal, else null. Read from a raw head: the shared
+ * sanitising removes `content-length` as a hop header.
+ */
+export declare function declaredLength(value: string | string[] | undefined): number | null;

package/dist/tunnel/external.js

@@ -0,0 +1,10 @@
+export function isExternalFailure(status) {
+    return status === 400 || status === 413 || status === 502 || status === 503 || status === 504;
+}
+/**
+ * A declared body length as a plain decimal, else null. Read from a raw head: the shared
+ * sanitising removes `content-length` as a hop header.
+ */
+export function declaredLength(value) {
+    return typeof value === 'string' && /^(0|[1-9][0-9]*)$/.test(value) ? Number(value) : null;
+}

package/dist/tunnel/index.d.ts

@@ -1,5 +1,5 @@
 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 { ArtifactTunnelBroker, SingleProcessTunnelOwnership, type TunnelBrokerOptions, type TunnelLease, type TunnelOwner, type TunnelOwnershipStore, type GatewayAuthorization, type TunnelExternalFailure, type TunnelExternalRequest, } 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';

package/dist/tunnel/protocol.d.ts

@@ -63,8 +63,26 @@ export type TunnelFrame = z.infer<typeof tunnelFrameSchema>;
 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;
+/**
+ * The request headers an external ingress forwards (design §(e) "Request sanitising"): a short
+ * fixed set plus the `x-` headers the ingress declared in its manifest. Everything else is
+ * dropped, so a cross-origin caller cannot reach framework-internal, routing-override,
+ * conditional or client-address headers the app might trust.
+ */
+export declare const INGRESS_FORWARDED_REQUEST_HEADERS: readonly string[];
+/** `session`: same-origin iframe traffic. `ingress`: an external caller; `appHeaders` are the ingress's declared headers. */
+export type RequestHeaderMode = {
+    mode?: 'session';
+} | {
+    mode: 'ingress';
+    appHeaders: readonly string[];
+};
+/**
+ * Rebuild trusted routing headers; no Atlas bearer/session crosses into app code. A session
+ * request must come from its own origin; an `ingress` request is cross-origin by design, so it
+ * keeps only its allowlisted headers and its `Origin` is dropped instead.
+ */
+export declare function sanitizeRequestHeaders(headers: HeaderInput, publicOrigin: string, mode?: RequestHeaderMode): 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. */

package/dist/tunnel/protocol.js

@@ -1,7 +1,7 @@
 import { Buffer } from 'node:buffer';
 import { z } from 'zod';
 import { isLoopbackHostname } from '../loopback.js';
-import { isPrivateRequestHeader } from './reserved-headers.js';
+import { INGRESS_CLIENT_ADDRESS_HEADERS, isPrivateRequestHeader } from './reserved-headers.js';
 /** 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({
@@ -148,13 +148,49 @@ function removePrivateHeaders(headers) {
             headers.delete(name);
     }
 }
-/** Rebuild trusted routing headers; no Atlas bearer/session crosses into app code. */
-export function sanitizeRequestHeaders(headers, publicOrigin) {
+/**
+ * The request headers an external ingress forwards (design §(e) "Request sanitising"): a short
+ * fixed set plus the `x-` headers the ingress declared in its manifest. Everything else is
+ * dropped, so a cross-origin caller cannot reach framework-internal, routing-override,
+ * conditional or client-address headers the app might trust.
+ */
+export const INGRESS_FORWARDED_REQUEST_HEADERS = Object.freeze([
+    // Content-Length is a hop header the proxy re-frames, so it is not listed.
+    'content-type', 'accept', 'accept-encoding', 'user-agent',
+]);
+/**
+ * Dropped on an ingress even if an ingress declared one (the manifest already refuses them):
+ * browser credentials and the caller's `Origin` (the gateway matched it against the binding),
+ * the edge secret, and every client-address header. The client address an app sees comes only
+ * from the signed context, never from a header the caller or another Cloudflare zone could set.
+ */
+const INGRESS_DROPPED_REQUEST_HEADERS = new Set([
+    'cookie', 'origin', 'authorization', 'x-sequence-edge', ...INGRESS_CLIENT_ADDRESS_HEADERS,
+]);
+function isIngressForwardedRequestHeader(name, declared) {
+    if (INGRESS_DROPPED_REQUEST_HEADERS.has(name) || name.startsWith('cf-'))
+        return false;
+    return INGRESS_FORWARDED_REQUEST_HEADERS.includes(name) || declared.has(name);
+}
+/**
+ * Rebuild trusted routing headers; no Atlas bearer/session crosses into app code. A session
+ * request must come from its own origin; an `ingress` request is cross-origin by design, so it
+ * keeps only its allowlisted headers and its `Origin` is dropped instead.
+ */
+export function sanitizeRequestHeaders(headers, publicOrigin, mode = {}) {
     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');
+    if (mode.mode === 'ingress') {
+        const declared = new Set(mode.appHeaders);
+        for (const name of [...normalized.keys()])
+            if (!isIngressForwardedRequestHeader(name, declared))
+                normalized.delete(name);
+    }
+    else {
+        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) {

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.6.3",
+  "version": "0.6.6",
   "description": "SDK types and CLI library for building Artifact Studio apps. Driven via `seq-studio artifact <sub>` (@sequenceholdings/studio-cli), which runs the `./cli` runCli export.",
   "type": "module",
   "exports": {
@@ -148,7 +148,7 @@
     "VERSION-PIN.md"
   ],
   "dependencies": {
-    "@sequenceholdings/atlas-ui": "3.3.0",
+    "@sequenceholdings/atlas-ui": "3.4.1",
     "@tailwindcss/postcss": "^4.1.8",
     "@tailwindcss/vite": "^4.1.8",
     "@tanstack/react-query": "^4.36.1",
@@ -167,8 +167,8 @@
     "server-only": "0.0.1",
     "parse5": "7.3.0",
     "@sequenceholdings/lattice-form-renderer": "0.2.0",
-    "@sequenceholdings/storage": "0.1.0",
-    "@sequenceholdings/orm": "2.3.0"
+    "@sequenceholdings/orm": "2.5.0",
+    "@sequenceholdings/storage": "0.1.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",