@sequenceholdings/artifact-studio 0.8.0 → 0.9.0

package/dist/server/client.js

@@ -11,6 +11,7 @@ import { ARTIFACT_REQUEST_CONTEXT_HEADER, ARTIFACT_RUNTIME_TOKEN_HEADER, ARTIFAC
 import { verifyArtifactExternalContext } from './external-context.js';
 import { isExternalContextToken } from './internal/signed-token.js';
 import { createApiClient } from './api-client.js';
+import { createArtifactAgentsClient } from './agent-responses.js';
 import { pause, transientConnectionCode } from './connection-retry.js';
 import { principalFromContext } from './principal.js';
 import { artifactRuntimeConfigSchema, readArtifactRuntimeConfig } from './runtime-config.js';
@@ -52,7 +53,12 @@ export async function createArtifactServerClient({ headers, runtime, fetch: fetc
             throw new ArtifactServerError(401, 'runtime_changed', 'Artifact runtime disconnected or changed; reload the preview');
         return current;
     };
-    return buildClient({ context, principal: principalFromContext(context), token, getRuntime, fetcher, mode: 'user', logSink });
+    // Opaque proof of the gateway's actual browser authentication. Atlas verifies it
+    // against this exact signed context; it grants nothing when copied to another request.
+    const authenticationToken = headers.get('x-sequence-artifact-authentication') ?? undefined;
+    if (authenticationToken !== undefined && authenticationToken.length > 4096)
+        throw new ArtifactServerError(401, 'invalid_request_context', 'Artifact gateway authentication proof exceeds its header limit');
+    return buildClient({ context, principal: principalFromContext(context), token, authenticationToken, getRuntime, fetcher, mode: 'user', logSink });
 }
 function buildClient(args) {
     const { context, principal, mode, logSink } = args;
@@ -89,6 +95,7 @@ function buildClient(args) {
         mode,
         log,
         api: createApiClient({ mode, request, json }),
+        agents: createArtifactAgentsClient({ mode, json }),
         storage: storageClient({ request: (method, path, body) => storageJson(artifactServerRequestSchema.parse({ operation: 'storage', mode, method, path, body })) }),
         functions: {
             invoke: async (id, params) => {
@@ -213,7 +220,7 @@ function isReadOperation(operation) {
             return false;
     }
 }
-function createBrokerTransport({ context, principal, token, getRuntime, fetcher, log }) {
+function createBrokerTransport({ context, principal, token, authenticationToken, getRuntime, fetcher, log }) {
     const send = async (input, signal, stream = false) => {
         // The one choke point for every broker operation: an external caller never acts as a user.
         if (input.mode === 'user' && principal.kind === 'external')
@@ -241,6 +248,7 @@ function createBrokerTransport({ context, principal, token, getRuntime, fetcher,
                     'Content-Type': 'application/json',
                     [ARTIFACT_RUNTIME_TOKEN_HEADER]: runtime.sessionToken,
                     [ARTIFACT_REQUEST_CONTEXT_HEADER]: token,
+                    ...(authenticationToken !== undefined ? { 'x-sequence-artifact-authentication': authenticationToken } : {}),
                 },
                 body,
                 cache: 'no-store',

package/dist/server/processes.d.ts

@@ -7,6 +7,17 @@ export type { ArtifactProcessRunSharingAuthoritiesQuery, ArtifactProcessRunShari
 /** A run of a process declared under `server.capabilities.processes.start`. */
 export interface ArtifactProcessStart {
     process: string;
+    /** Select a registered immutable version. Omit to start the process's current active version. */
+    version?: string;
+    /**
+     * Require the resolved immutable target to match this version and bundle hash before Atlas
+     * creates the run. Drift returns 409 PROCESS_IDENTITY_MISMATCH; this assertion does not select
+     * a version. Use `version` separately to start a captured target after active-version promotion.
+     */
+    expectedProcess?: {
+        version: string;
+        bundleHash: string;
+    };
     /** Idempotency key: starting the same run id again returns the existing run. */
     runId?: string;
     /**

package/dist/server/request-authentication.d.ts

@@ -0,0 +1,42 @@
+import { type ArtifactGatewayPublicKeys, type ArtifactRequestContext } from './request-context.js';
+export declare const ARTIFACT_REQUEST_AUTHENTICATION_HEADER = "x-sequence-artifact-authentication";
+export declare const ARTIFACT_REQUEST_AUTHENTICATION_MAX_LENGTH = 4096;
+export declare class ArtifactRequestHeaderError extends Error {
+    constructor();
+}
+/** Internal forwarding validation; the signed proof is verified by the receiving broker. */
+export declare function validatedArtifactAuthenticationHeader({ token, contextToken, external }: {
+    token: unknown;
+    contextToken: unknown;
+    external?: boolean;
+}): string | undefined;
+/** Internal transport guard: trusted appended headers share the same 32 KiB transport budget. */
+export declare function assertArtifactRequestHeaderBudget({ headers }: {
+    headers: Readonly<Record<string, string | string[]>>;
+}): void;
+/** Add only the gateway-controlled value after all browser-owned private headers were stripped. */
+export declare function appendArtifactAuthenticationHeader({ headers, token, contextToken }: {
+    headers: Record<string, string | string[]>;
+    token: unknown;
+    contextToken: unknown;
+}): void;
+/** Cloud transport identity headers may come only from the platform's own credential provider. */
+export declare function stripArtifactCloudHeaders({ headers }: {
+    headers: Record<string, string | string[]>;
+}): void;
+/**
+ * Verifies actual authentication separately from actor attribution. An absent proof keeps legacy
+ * contexts usable, but supplies no human authority. A present invalid proof always fails closed.
+ * The exact signed context bytes bind even bridge, deployment and service-account fields that
+ * are not repeated in this small proof. No application-authored context can supply this evidence.
+ */
+export declare function verifyArtifactRequestAuthentication({ token, requestContextToken, context, publicKeys, now }: {
+    token: string | null | undefined;
+    requestContextToken: string;
+    context: ArtifactRequestContext;
+    publicKeys: ArtifactGatewayPublicKeys;
+    now?: number;
+}): Readonly<{
+    authenticationMethod: 'auth0_user';
+    sub: string;
+}> | undefined;

package/dist/server/request-authentication.js

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import { validateHeaderValue } from 'node:http';
+import { z } from 'zod';
+import { ArtifactContextError, artifactRequestContextSchema, verifyArtifactRequestContext } from './request-context.js';
+import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX, verifySignedContext } from './internal/signed-token.js';
+export const ARTIFACT_REQUEST_AUTHENTICATION_HEADER = 'x-sequence-artifact-authentication';
+export const ARTIFACT_REQUEST_AUTHENTICATION_MAX_LENGTH = 4096;
+export class ArtifactRequestHeaderError extends Error {
+    constructor() { super('Artifact request headers exceed the transport limit'); this.name = 'ArtifactRequestHeaderError'; }
+}
+/** Internal forwarding validation; the signed proof is verified by the receiving broker. */
+export function validatedArtifactAuthenticationHeader({ token, contextToken, external = false }) {
+    if (token === undefined)
+        return undefined;
+    if (typeof token !== 'string' || !token || token.length > ARTIFACT_REQUEST_AUTHENTICATION_MAX_LENGTH ||
+        typeof contextToken !== 'string' || !contextToken || external)
+        throw new Error('Invalid Artifact request authentication');
+    validateHeaderValue(ARTIFACT_REQUEST_AUTHENTICATION_HEADER, token);
+    return token;
+}
+/** Internal transport guard: trusted appended headers share the same 32 KiB transport budget. */
+export function assertArtifactRequestHeaderBudget({ headers }) {
+    let bytes = 0;
+    const entries = Object.entries(headers);
+    if (entries.length > 128)
+        throw new ArtifactRequestHeaderError();
+    for (const [name, value] of entries) {
+        // Node may emit array values as repeated lines. Counting each name/CRLF is conservative
+        // even for cookie values, which Node joins instead of repeating.
+        for (const item of Array.isArray(value) ? value : [value]) {
+            bytes += Buffer.byteLength(name) + Buffer.byteLength(item) + 4;
+            if (bytes > 32 * 1024)
+                throw new ArtifactRequestHeaderError();
+        }
+    }
+}
+/** Add only the gateway-controlled value after all browser-owned private headers were stripped. */
+export function appendArtifactAuthenticationHeader({ headers, token, contextToken }) {
+    const authentication = validatedArtifactAuthenticationHeader({ token, contextToken });
+    if (authentication !== undefined)
+        headers[ARTIFACT_REQUEST_AUTHENTICATION_HEADER] = authentication;
+    assertArtifactRequestHeaderBudget({ headers });
+}
+/** Cloud transport identity headers may come only from the platform's own credential provider. */
+export function stripArtifactCloudHeaders({ headers }) {
+    for (const name of Object.keys(headers)) {
+        if (name === 'x-serverless-authorization' || name.startsWith('x-goog-'))
+            delete headers[name];
+    }
+}
+/** Internal signed format. Authentication is deliberately absent from the public v1 context. */
+const authenticationProofSchema = z.object({
+    purpose: z.literal('artifact-request-authentication'), v: z.literal(1),
+    iss: z.literal('atlas-artifact-gateway'), aud: z.string().min(1).max(300),
+    authenticationMethod: z.literal('auth0_user'), sub: z.string().min(1).max(255),
+    contextJti: z.uuid(), contextSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    projectId: z.string().min(1).max(255), environment: z.string().min(1).max(255),
+    method: z.enum(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']), pathSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    iat: z.number().int().nonnegative(), exp: z.number().int().positive(),
+}).strict();
+/**
+ * Verifies actual authentication separately from actor attribution. An absent proof keeps legacy
+ * contexts usable, but supplies no human authority. A present invalid proof always fails closed.
+ * The exact signed context bytes bind even bridge, deployment and service-account fields that
+ * are not repeated in this small proof. No application-authored context can supply this evidence.
+ */
+export function verifyArtifactRequestAuthentication({ token, requestContextToken, context, publicKeys, now = Math.floor(Date.now() / 1000) }) {
+    if (token === null || token === undefined)
+        return undefined;
+    try {
+        if (!token || token.length > ARTIFACT_REQUEST_AUTHENTICATION_MAX_LENGTH)
+            throw new ArtifactContextError();
+        const signedContext = verifyArtifactRequestContext({ token: requestContextToken, publicKeys,
+            projectId: context.projectId, environment: context.environment, method: context.method, path: context.path, now });
+        if (JSON.stringify(signedContext) !== JSON.stringify(artifactRequestContextSchema.parse(context)))
+            throw new ArtifactContextError();
+        const contextSignature = verifySignedContext({ token: requestContextToken, publicKeys });
+        const verified = verifySignedContext({ token, publicKeys });
+        if (verified.kid.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX) || verified.kid !== contextSignature.kid)
+            throw new ArtifactContextError();
+        const proof = authenticationProofSchema.parse(verified.payload);
+        if (proof.contextSha256 !== createHash('sha256').update(requestContextToken).digest('hex') ||
+            proof.contextJti !== signedContext.jti || proof.sub !== signedContext.sub || proof.aud !== signedContext.aud ||
+            proof.projectId !== signedContext.projectId || proof.environment !== signedContext.environment ||
+            proof.method !== signedContext.method || proof.pathSha256 !== createHash('sha256').update(signedContext.path).digest('hex') ||
+            proof.iat !== signedContext.iat || proof.exp !== signedContext.exp)
+            throw new ArtifactContextError();
+        return Object.freeze({ authenticationMethod: proof.authenticationMethod, sub: proof.sub });
+    }
+    catch {
+        throw new ArtifactContextError();
+    }
+}

package/dist/server/request-context.d.ts

@@ -195,3 +195,4 @@ export declare function verifyArtifactRequestContext({ token, publicKeys, projec
 export declare function getArtifactBrowserBootstrap(context: ArtifactRequestContext | RequestContextV2External): NextArtifactBridgeBootstrap & {
     initialContext: NextArtifactInitialContext;
 };
+export { ARTIFACT_REQUEST_AUTHENTICATION_HEADER, verifyArtifactRequestAuthentication } from './request-authentication.js';

package/dist/server/request-context.js

@@ -193,3 +193,4 @@ export function getArtifactBrowserBootstrap(context) {
         },
     };
 }
+export { ARTIFACT_REQUEST_AUTHENTICATION_HEADER, verifyArtifactRequestAuthentication } from './request-authentication.js';

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import 'server-only';
 export { createArtifactServerClient } from './server/client.js';
+export type { ArtifactServerAgents, ArtifactCompletedAgentRun, ArtifactCompletedAgentSourceCapture, ArtifactCompletedAgentConversationCapture, ArtifactAgentConversationSourceCapture, ArtifactExecutionIdentity, ArtifactCreateAgentJob, ArtifactCreateWorkflowJob, ArtifactCreatedAgentJob, ArtifactCreatedWorkflowJob, ArtifactCompletedWorkflowSourceCapture } from './server/agent-responses.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, ArtifactProcessRunSummary, ArtifactProcessRunsPage, ArtifactProcessRunsPageQuery, ArtifactProcessRunsQuery, ArtifactProcessRunViewerChange, ArtifactProcessRunViewers, ArtifactProcessStart, ArtifactProcessStepRecord, ArtifactProcessShareRun, ArtifactProcessShareRunResult, ArtifactProcessRunSharingAuthoritiesQuery, ArtifactProcessRunSharingAuthoritiesPage, ArtifactProcessRunSharingAuthority, ArtifactProcessRunSharingDelegate, ArtifactProcessRevokeRunSharingAuthority, ArtifactProcessRevokeRunSharingAuthorityResult, ArtifactProcessTask, ArtifactProcessTasksQuery, ArtifactServerAudit, ArtifactServerClient, ArtifactServerClientOptions, ArtifactServerContext, ArtifactServerFetchOptions, ArtifactServerFlags, ArtifactServerGroups, ArtifactServerProcesses, ArtifactGroupMembership, ArtifactGroupMembershipsPage, ArtifactGroupMembershipsQuery, } from './server/client.js';
@@ -7,7 +8,7 @@ export { ARTIFACT_AUDIT_ACTIONS, ARTIFACT_AUDIT_RESOURCES_PER_EVENT, ARTIFACT_FL
 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';
-export { ArtifactContextError, getArtifactBrowserBootstrap } from './server/request-context.js';
+export { ArtifactContextError, getArtifactBrowserBootstrap, ARTIFACT_REQUEST_AUTHENTICATION_HEADER, verifyArtifactRequestAuthentication } from './server/request-context.js';
 export type { ArtifactContextErrorReason, ArtifactRequestContext, RequestContextV2External } from './server/request-context.js';
 export { verifyArtifactExternalContext } from './server/external-context.js';
 export type { ArtifactExternalAccept } from './server/external-context.js';

package/dist/server.js

@@ -3,6 +3,6 @@ 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_GROUP_MEMBERSHIPS_LIMIT, ARTIFACT_GROUP_MEMBERSHIPS_MAX_PAGE, 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 { ArtifactContextError, getArtifactBrowserBootstrap, ARTIFACT_REQUEST_AUTHENTICATION_HEADER, verifyArtifactRequestAuthentication } from './server/request-context.js';
 export { verifyArtifactExternalContext } from './server/external-context.js';
 export { externalEvidence } from './server/principal.js';

package/dist/templates/react-vite/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@sequenceholdings/artifact-studio": "^0.8.0",
+    "@sequenceholdings/artifact-studio": "^0.9.0",
     "@sequenceholdings/atlas-ui": "^3.1.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",

package/dist/tunnel/broker.d.ts

@@ -30,6 +30,8 @@ export interface GatewayAuthorization {
     publicOrigin: string;
     /** Signed, audience-scoped context minted by Atlas, never a user bearer. */
     requestContext?: string;
+    /** Generated from the authenticated gateway session, never forwarded from a browser. */
+    requestAuthentication?: string;
 }
 export interface TunnelBrokerOptions {
     nodeId: string;
@@ -52,6 +54,10 @@ export declare class ArtifactTunnelBroker {
     private readonly pendingConnections;
     private readonly ownerTimers;
     private closing;
+    private draining;
+    private readonly drainWaiters;
+    private readonly pendingReceipts;
+    private relayClosed?;
     constructor(options: TunnelBrokerOptions);
     handleTunnelUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
     handleHttp(request: IncomingMessage, response: ServerResponse, sessionId: string): Promise<void>;
@@ -59,6 +65,7 @@ export declare class ArtifactTunnelBroker {
     handleExternalHttp(input: TunnelExternalRequest): Promise<void>;
     handleWebSocketUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, sessionId: string): Promise<void>;
     private authorize;
+    private requestHeaders;
     /**
      * 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
@@ -79,7 +86,13 @@ export declare class ArtifactTunnelBroker {
     private writeExternalChunk;
     private finish;
     private abort;
-    /** Immediate revocation and graceful service shutdown hook. */
+    /** Stop new upgrades and remote-owner admission while admitted HTTP handlers finish. */
+    beginDrain(): void;
+    private notifyDrained;
+    /** The gateway first joins admitted handlers and response accounting. Its outer deadline
+     * bounds finite streams; lease validation and revocation remain active until cleanup. */
+    drain(): Promise<void>;
+    /** Immediate security revocation, never a graceful drain. */
     disconnect(sessionId: string): void;
     close(): void;
 }

package/dist/tunnel/broker.js

@@ -1,6 +1,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 { appendArtifactAuthenticationHeader } from '../server/request-authentication.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' };
@@ -65,6 +66,10 @@ export class ArtifactTunnelBroker {
     pendingConnections = new Map();
     ownerTimers = new Set();
     closing = false;
+    draining = false;
+    drainWaiters = new Set();
+    pendingReceipts = new Set();
+    relayClosed;
     constructor(options) {
         this.options = options;
         if (!options.nodeId || !options.routing || !options.authorizeTunnel || !options.authorizeRequest || !options.validateLease) {
@@ -80,7 +85,7 @@ export class ArtifactTunnelBroker {
         let lease = null;
         let claimed = false;
         try {
-            if (this.closing) {
+            if (this.draining || this.closing) {
                 rejectUpgrade(socket, 503);
                 return;
             }
@@ -99,19 +104,28 @@ export class ArtifactTunnelBroker {
                 rejectUpgrade(socket, 403);
                 return;
             }
+            if (this.draining || this.closing) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
             claimed = await this.options.routing.claim(lease, this.options.nodeId);
             const owner = await this.options.routing.lookup(lease.sessionId);
             if (!claimed || owner?.nodeId !== this.options.nodeId || owner.epoch !== lease.epoch || socket.destroyed) {
                 rejectUpgrade(socket, 403);
                 return;
             }
+            if (this.draining || this.closing) {
+                await this.options.routing.release(lease.sessionId, lease.epoch, this.options.nodeId).catch(() => undefined);
+                rejectUpgrade(socket, 503);
+                return;
+            }
             const authorizedLease = lease;
             this.tunnels.handleUpgrade(request, socket, head, (websocket) => {
                 const ready = () => websocket.send(encodeTunnelFrame({ type: 'ready', id: authorizedLease.sessionId, epoch: authorizedLease.epoch }));
                 websocket.once('close', () => this.options.onTunnelClosed?.(authorizedLease));
                 if (this.options.relay) {
                     void this.options.relay.attach(authorizedLease, websocket).then(() => {
-                        if (this.closing) {
+                        if (this.draining || this.closing) {
                             websocket.terminate();
                             return;
                         }
@@ -283,7 +297,15 @@ export class ArtifactTunnelBroker {
     async handleWebSocketUpgrade(request, socket, head, sessionId) {
         socket.pause();
         try {
+            if (this.draining || this.closing) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
             const authorized = await this.authorize(request, sessionId);
+            if (this.draining || this.closing) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
             if (!authorized) {
                 rejectUpgrade(socket, 403);
                 return;
@@ -317,12 +339,9 @@ export class ArtifactTunnelBroker {
             return null;
         if (!['GET', 'HEAD', 'OPTIONS'].includes(request.method ?? 'GET') && request.headers.origin !== origin)
             return null;
-        const headers = sanitizeRequestHeaders(request.headers, origin);
-        if (authorization.requestContext) {
-            if (/[\r\n]/.test(authorization.requestContext))
-                return null;
-            headers['x-sequence-artifact-context'] = authorization.requestContext;
-        }
+        const headers = this.requestHeaders({ request, origin, authorization });
+        if (!headers)
+            return null;
         let connection = this.connections.get(sessionId);
         if (this.options.relay && this.options.resolveLease) {
             const lease = await this.options.resolveLease(sessionId);
@@ -341,6 +360,21 @@ export class ArtifactTunnelBroker {
             return null;
         return { connection, headers };
     }
+    requestHeaders({ request, origin, authorization }) {
+        const headers = sanitizeRequestHeaders(request.headers, origin);
+        if (authorization.requestContext) {
+            if (/[\r\n]/.test(authorization.requestContext))
+                return null;
+            headers['x-sequence-artifact-context'] = authorization.requestContext;
+        }
+        try {
+            appendArtifactAuthenticationHeader({ headers, token: authorization.requestAuthentication, contextToken: authorization.requestContext });
+        }
+        catch {
+            return null;
+        }
+        return 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
@@ -459,7 +493,22 @@ export class ArtifactTunnelBroker {
             return;
         }
         if (frame.type === 'end') {
+            if (!this.options.relay) {
+                this.finish(connection, frame.id);
+                return;
+            }
+            // The existing cancel frame releases an already-completed stream. Redis owners that
+            // negotiated receipts retain the route until this proves the final response was consumed.
+            const receipt = connection.peer.send({ type: 'cancel', id: frame.id }).catch(() => connection.peer.close());
+            this.pendingReceipts.add(receipt);
             this.finish(connection, frame.id);
+            try {
+                await receipt;
+            }
+            finally {
+                this.pendingReceipts.delete(receipt);
+                this.notifyDrained();
+            }
             return;
         }
         if (frame.type === 'cancel') {
@@ -575,6 +624,7 @@ export class ArtifactTunnelBroker {
             stream.socket.close(status ? 1011 : 1000);
         else if (stream.upgrade)
             rejectUpgrade(stream.upgrade.socket, status ?? 503);
+        this.notifyDrained();
     }
     abort(connection, id, status = 502) {
         if (!connection.streams.has(id))
@@ -582,20 +632,54 @@ export class ArtifactTunnelBroker {
         this.finish(connection, id, status);
         void connection.peer.send({ type: 'cancel', id }).catch(() => undefined);
     }
-    /** Immediate revocation and graceful service shutdown hook. */
+    /** Stop new upgrades and remote-owner admission while admitted HTTP handlers finish. */
+    beginDrain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        this.options.relay?.beginDrain?.();
+        for (const connection of this.connections.values()) {
+            for (const [id, stream] of connection.streams)
+                if (stream.upgrade)
+                    this.abort(connection, id, 503);
+        }
+    }
+    notifyDrained() {
+        if (!this.drainWaiters.size || this.pendingReceipts.size)
+            return;
+        for (const connection of this.connections.values())
+            if (connection.streams.size)
+                return;
+        for (const resolve of this.drainWaiters)
+            resolve();
+        this.drainWaiters.clear();
+    }
+    /** The gateway first joins admitted handlers and response accounting. Its outer deadline
+     * bounds finite streams; lease validation and revocation remain active until cleanup. */
+    async drain() {
+        this.beginDrain();
+        await new Promise((resolve) => { this.drainWaiters.add(resolve); this.notifyDrained(); });
+        await this.options.relay?.drain?.();
+        this.close();
+        await this.relayClosed;
+    }
+    /** Immediate security revocation, never a graceful drain. */
     disconnect(sessionId) {
         this.connections.get(sessionId)?.peer.close();
         this.options.relay?.disconnect(sessionId);
     }
     close() {
+        if (this.closing)
+            return;
         this.closing = true;
+        this.draining = true;
         for (const timer of this.ownerTimers)
             clearInterval(timer);
         this.ownerTimers.clear();
         for (const connection of this.connections.values())
             connection.peer.close();
         this.tunnels.close();
-        void this.options.relay?.close().catch(() => undefined);
+        this.relayClosed = this.options.relay?.close().catch(() => undefined);
     }
 }
 /** For one-process local development/tests only. Production must provide a shared

package/dist/tunnel/client.js

@@ -6,6 +6,7 @@ import { forwardWebSocketMessages, MessageBudget, permittedCloseCode, sendWebSoc
 import { declaredLength } from './external.js';
 import { isLoopbackHostname } from '../loopback.js';
 import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX } from '../server/internal/signed-token.js';
+import { ARTIFACT_REQUEST_AUTHENTICATION_HEADER, assertArtifactRequestHeaderBudget, validatedArtifactAuthenticationHeader } from '../server/request-authentication.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) {
@@ -59,6 +60,11 @@ export async function connectLocalTunnel(options) {
             const context = frame.headers['x-sequence-artifact-context'];
             if (typeof context === 'string')
                 headers['x-sequence-artifact-context'] = context;
+            // This frame came from the authenticated gateway connection, not a browser header map.
+            const authentication = validatedArtifactAuthenticationHeader({ token: frame.headers[ARTIFACT_REQUEST_AUTHENTICATION_HEADER], contextToken: context });
+            if (authentication !== undefined)
+                headers[ARTIFACT_REQUEST_AUTHENTICATION_HEADER] = authentication;
+            assertArtifactRequestHeaderBudget({ headers });
             const timer = setTimeout(() => { void fail(frame.id); }, limits.requestTimeoutMs);
             timer.unref();
             const forward = { message: new WebSocketMessage(limits.maxWebSocketMessageBytes, messageBudget), bytes: 0, timer };

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

@@ -40,12 +40,16 @@ export type Remote = {
     nodeId: string;
     connection: string;
     lastSeen: number;
+    receipts?: boolean;
 };
 export type Attached = {
     lease: TunnelLease;
     socket: TunnelSocket;
     remotes: Map<string, Remote>;
-    streams: Map<string, Remote>;
+    streams: Map<string, Remote & {
+        websocket: boolean;
+        ended: boolean;
+    }>;
     timer: NodeJS.Timeout;
     queuedBytes: number;
     receiving: Promise<void>;

package/dist/tunnel/redis.d.ts

@@ -12,6 +12,10 @@ export declare class RedisTunnelRelay implements TunnelRelay {
     private readonly options;
     private started;
     private closed;
+    private draining;
+    private drainSealed;
+    private drainWork;
+    private readonly drainWaiters;
     private readonly attached;
     private readonly connected;
     private readonly frames;
@@ -52,5 +56,13 @@ export declare class RedisTunnelRelay implements TunnelRelay {
     private closeOwner;
     private closeConnection;
     disconnect(sessionId: string): void;
+    /** Reject new remote requests, but allow same-node work already admitted by the HTTP
+     * gateway until drain() seals it. Security checks and ownership timers stay live. */
+    beginDrain(): void;
+    private notifyDrained;
+    /** Updated requesters acknowledge consumed final responses with cancel. Keep those bounded
+     * routes even before drain starts to cover an end-vs-shutdown race. Legacy requesters retain
+     * the previous publish-only completion behavior; they never acquire a new receipt wait. */
+    drain(): Promise<void>;
     close(): Promise<void>;
 }