@sequenceholdings/artifact-studio 0.8.0 → 0.8.1

package/README.md

@@ -163,6 +163,25 @@ workspace source awaiting a matching SDK release and platform deployment;
 they are not a newly supported public SDK or direct HTTP contract. See
 [VERSION-PIN.md](./VERSION-PIN.md) for compatibility requirements.
 
+Human completion receipts require a genuine Auth0 browser authentication carried
+by the platform. The gateway signs a separate, optional authentication proof
+bound to the exact request context; the server SDK forwards it unchanged.
+Legacy contexts continue to work without producing human receipts. Service mode,
+external ingress, impersonation and an authored `assertedBy` never supply human
+authentication. This proof requires the matching platform and gateway release.
+
+`client.processes.start` accepts an optional `version` selector for a registered
+immutable process version. Omitting it selects the active version. In the
+upcoming SDK 0.8.1, use this selector to start a retained release after the
+active process has been promoted.
+
+The separate `expectedProcess: { version, bundleHash }` option asserts the
+resolved target; it does not select a version. Atlas returns
+`409 PROCESS_IDENTITY_MISMATCH` before creating a run with a different
+definition. Retrying a known run ID compares its persisted definition, so a
+lost response can recover the original run after a process promotion. Current
+process admission and manifest capability checks still apply.
+
 On the request-scoped client returned by `createArtifactServerClient`, declare
 the exact process IDs the application reads or acts on:
 
@@ -350,15 +369,80 @@ until the host rollout completes. Host/session replacement closes the preview.
 
 ## Calling agents from a Next.js server
 
+The upcoming SDK **0.8.1** adds typed, user-mode job admission. Obtain the
+reviewed source tuple with `client.agents.getCurrentIdentity({ kind, id })` and
+pass it as `expectedIdentity` to `createJob` or `createWorkflowJob`, together
+with a stable `idempotencyKey`. An application should retain its reviewed tuple
+and execution intent rather than silently replace a mismatched source with the
+latest definition. The current user's permissions are checked at admission and
+recovery; neither the tuple nor the key grants access.
+
+Declare the exact read routes for current identity and these strict write
+routes in the server manifest:
+
+- `POST /api/agents/jobs/create-idempotent` for `createJob`.
+- `POST /api/agents/workflows/*/jobs` for `createWorkflowJob`.
+
+Keep the same key and semantic request when recovering an uncertain outcome.
+Changed input or source pins under an existing key are refused. A matching
+replay returns the original admission response without resolving a newer source
+head; read the Job separately for its current execution status. These methods use distinct
+strict endpoints so an older host fails before creating a legacy job that
+ignores the idempotency contract. Do not fall back to the legacy create route
+or generate another key merely because an acknowledgement was lost.
+
+`client.agents.getCompletedRun({ agent, runId })` reads a completed response as
+the current user. Declare its `GET /api/agents/jobs/*/completed-response` route
+in `server.capabilities.api.read`. Both the run and private thread must belong
+to that user, and current Agent, Job and Thread read grants remain enforced.
+The bounded response carries JSON output, assistant text and citation resources;
+it omits reasoning, tool inputs and arbitrary tool results. Reused or changed
+conversations, incomplete runs and results over 1,000 messages or 8 MiB fail
+explicitly. Service mode and machine credentials cannot use this method.
+
+`client.agents.captureCompletedRun({ agent, runId })` returns the neutral response
+with a historical `responseHash` and `sourceReceipt`. Explicit
+`client.agents.captureCompletedConversation({ agent, runId })` additionally
+captures permitted user/assistant text and tool inputs/results in
+`response.context`. Declare the respective `completed-source` and
+`completed-conversation` GET routes. Atlas requires current Agent, Job and Thread
+read grants for the actual private source. These user-only captures reject changed
+or unfinished history, recognizable credentials, unverified compaction context
+and responses over 512 KiB. A receipt proves the captured bytes and actual actor;
+receiving functions verify it under their own live evidence capability, and the
+application separately validates its protected source/release association.
+
+`client.agents.captureConversation({ agent, threadId })` explicitly captures a
+sidebar transcript through `GET /api/agents/threads/*/conversation-source`.
+Its response binds a durable settled `revision` and `cutoffAt`, with the same
+permitted `context` and neutral `conversation` metrics. It has no invented agent
+run ID. Active, interrupted or legacy conversations without proven settlement
+are refused. The receiver uses `verifyConversationEvidence` and checks the
+application's protected sidebar/source association before persisting it.
+
+`client.agents.captureCompletedWorkflow({ workflow, runId })` explicitly
+captures a completed standalone Workflow source as an authenticated human with
+current access. The capturing user remains distinct from the original source
+owner recorded in the evidence.
+Declare `GET /api/agents/jobs/*/completed-workflow-source`. The typed response
+contains the persisted merged root output and historical source evidence,
+including real branch outcomes and the original job-admission association;
+it is not an Agent conversation. Current Workflow Invoker and root/child Job
+visibility remain required. Incomplete or changed sources and captures over
+512 KiB fail explicitly. A receiver verifies the historical bytes with its
+separate Workflow evidence capability and checks the application's current
+protected intent; a source receipt grants no current task or write authority.
+
 An application that declares `/api/agents/` in `server.capabilities.api.read`
 and `write` can reach a fixed set of agents API routes as the signed-in user:
 
 | Area | Routes |
 | --- | --- |
 | Chat | `POST chat`, `POST chat/abort`, `GET chat/resume` |
-| Agents | `GET agents`, `GET agents/:id` |
-| Threads | `GET threads`, `POST threads`, `GET threads/:id`, `GET threads/:id/messages`, `PATCH threads/:id/messages/:messageId` |
-| Jobs | `POST jobs`, `GET jobs/:id`, `DELETE jobs/:id` |
+| Agents | `GET agents`, `GET agents/:id`, `GET agents/:id/current-identity` |
+| Threads | `GET threads`, `POST threads`, `GET threads/:id`, `GET threads/:id/messages`, `GET threads/:id/conversation-source`, `PATCH threads/:id/messages/:messageId` |
+| Jobs | `POST jobs`, `POST jobs/create-idempotent`, `GET jobs/:id`, `GET jobs/:id/completed-response`, `GET jobs/:id/completed-source`, `GET jobs/:id/completed-conversation`, `GET jobs/:id/completed-workflow-source`, `DELETE jobs/:id` |
+| Workflows | `GET workflows/:id/current-identity`, `POST workflows/:id/jobs` |
 | Files | `POST files`, `GET files/:id`, `DELETE files/:id`, `GET files/:id/url` |
 
 Atlas answers them with the agents API's own handlers, so agent `can_invoke`,

package/dist/gateway/authorization-cache.js

@@ -121,7 +121,7 @@ function digest(parts) {
  * bridge values and the cookie's own expiry do not change the decision. */
 export function gatewayAuthorizationKey(session) {
     return digest(['session-v1', session.kind, session.projectId, session.ownerId, session.environment, session.publicOrigin,
-        session.sessionId, session.deploymentId, session.frameworkBuildId, session.published, session.lattice ?? null, session.taskRoutes ?? null]);
+        session.sessionId, session.deploymentId, session.frameworkBuildId, session.published, session.lattice ?? null, session.taskRoutes ?? null, session.authentication ?? null]);
 }
 /** A tunnel credential is keyed by its hash, never retained in the key itself. */
 export function tunnelAuthorizationKey({ token, sessionId, epoch }) {

package/dist/gateway/control.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { TunnelLease } from '../tunnel/index.js';
-import type { GatewaySession } from './session.js';
+import { type GatewaySession } from './session.js';
 import type { GatewayUsageEvent } from './usage.js';
 import { type IngressAuditBatch, type IngressExchangeRequest, type IngressExchangeResponse, type IngressGrantRequest, type IngressGrantResponse, type IngressRevokeRequest, type IngressSnapshot } from '../server/ingress-control-contract.js';
 export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -22,6 +22,10 @@ export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         processId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authentication: z.ZodOptional<z.ZodObject<{
+        method: z.ZodLiteral<"auth0_user">;
+        sub: z.ZodString;
+    }, z.core.$strict>>;
     manifest: z.ZodOptional<z.ZodObject<{
         server: z.ZodObject<{
             resources: z.ZodObject<{
@@ -58,6 +62,10 @@ export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         processId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authentication: z.ZodOptional<z.ZodObject<{
+        method: z.ZodLiteral<"auth0_user">;
+        sub: z.ZodString;
+    }, z.core.$strict>>;
     manifest: z.ZodOptional<z.ZodObject<{
         server: z.ZodObject<{
             resources: z.ZodObject<{
@@ -88,6 +96,10 @@ export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         processId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authentication: z.ZodOptional<z.ZodObject<{
+        method: z.ZodLiteral<"auth0_user">;
+        sub: z.ZodString;
+    }, z.core.$strict>>;
     manifest: z.ZodOptional<z.ZodObject<{
         server: z.ZodObject<{
             resources: z.ZodObject<{

package/dist/gateway/control.js

@@ -1,6 +1,7 @@
 import { createHash, timingSafeEqual } from 'node:crypto';
 import { z } from 'zod';
 import { normalizePublicOrigin } from '../tunnel/protocol.js';
+import { gatewayAuthenticationSchema } from './session.js';
 import { artifactRequestContextSchema } from '../server/request-context.js';
 import { ARTIFACT_NEXT_CONTROL_PATH, artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
 import { untilAborted } from './abort.js';
@@ -13,6 +14,7 @@ const base = {
     capabilities: z.array(id).max(256).default([]), serviceAccountId: id.nullable().default(null),
     lattice: artifactRequestContextSchema.shape.lattice.optional(),
     taskRoutes: artifactRequestContextSchema.shape.taskRoutes,
+    authentication: gatewayAuthenticationSchema.optional(),
     manifest: z.object({ server: z.object({ resources: z.object({
                 concurrency: z.number().int().min(1).max(80), max_instances: z.number().int().min(1).max(100), timeout_seconds: z.number().int().min(1).max(300),
             }) }) }).optional(),
@@ -228,6 +230,7 @@ export class ArtifactGatewayControl {
             published: target.kind !== 'development' && (target.published ?? target.active), bridge,
             ...(target.lattice ? { lattice: target.lattice } : {}),
             ...(target.taskRoutes ? { taskRoutes: target.taskRoutes } : {}),
+            ...(target.authentication ? { authentication: target.authentication } : {}),
         };
         return { session, target };
     }

package/dist/gateway/datadog-startup.d.ts

@@ -0,0 +1,13 @@
+/** Messages contain configuration names, never supplied values or connection errors. */
+export declare class DatadogStartupError extends Error {
+}
+/**
+ * Replaces the sidecar's TCP startup probe only in the opt-in image mode.
+ * The app remains serverless-init's direct child, so its existing signal and
+ * drain handlers still own shutdown. This checks collector startup, not remote
+ * telemetry delivery; the app's /health probe continues to check its own readiness.
+ */
+export declare function waitForDatadogStartup({ env, timeoutMs, }: {
+    env: Record<string, string | undefined>;
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/gateway/datadog-startup.js

@@ -0,0 +1,51 @@
+import { createConnection } from 'node:net';
+import { setTimeout as delay } from 'node:timers/promises';
+/** Messages contain configuration names, never supplied values or connection errors. */
+export class DatadogStartupError extends Error {
+}
+function collectorListening({ port, timeoutMs }) {
+    return new Promise(resolve => {
+        const socket = createConnection({ host: '127.0.0.1', port });
+        let finished = false;
+        const finish = (ready) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(ready);
+        };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+    });
+}
+/**
+ * Replaces the sidecar's TCP startup probe only in the opt-in image mode.
+ * The app remains serverless-init's direct child, so its existing signal and
+ * drain handlers still own shutdown. This checks collector startup, not remote
+ * telemetry delivery; the app's /health probe continues to check its own readiness.
+ */
+export async function waitForDatadogStartup({ env, timeoutMs = 30_000, }) {
+    const mode = env.ARTIFACT_NEXT_DATADOG_IN_CONTAINER;
+    if (mode === undefined || mode === 'false')
+        return;
+    if (mode !== 'true')
+        throw new DatadogStartupError('Invalid ARTIFACT_NEXT_DATADOG_IN_CONTAINER: expected true or false');
+    const configuredPort = env.DD_HEALTH_PORT ?? '5555';
+    const port = Number(configuredPort);
+    if (!/^\d+$/.test(configuredPort) || !Number.isSafeInteger(port) || port < 1 || port > 65535)
+        throw new DatadogStartupError('Invalid DD_HEALTH_PORT: expected an integer from 1 to 65535');
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 30_000)
+        throw new DatadogStartupError('Invalid Datadog startup budget: expected at most 30000 milliseconds');
+    // A monotonic deadline includes both connection attempts and retry delays.
+    const deadline = performance.now() + timeoutMs;
+    while (performance.now() < deadline) {
+        if (await collectorListening({ port, timeoutMs: Math.min(1_000, deadline - performance.now()) }))
+            return;
+        const remaining = deadline - performance.now();
+        if (remaining > 0)
+            await delay(Math.min(100, remaining));
+    }
+    throw new DatadogStartupError('Datadog collector did not become ready within the startup budget');
+}

package/dist/gateway/hosted-proxy.d.ts

@@ -18,6 +18,8 @@ export interface HostedArtifactProxyOptions {
         deploymentId: string;
     };
     requestContext: string;
+    /** Optional actual-human proof generated alongside this exact request context by the gateway. */
+    requestAuthentication?: string;
     /** Admission may inspect a native form prefix and replay it without buffering the body. */
     body?: AsyncIterable<Uint8Array>;
     identityTokenProvider?: (input: {

package/dist/gateway/hosted-proxy.js

@@ -9,6 +9,7 @@ import { createReleaseFormTransform } from '../server/release-forms.js';
 import { declaredContentLength, INGRESS_PROXY_ERROR_CODES, INGRESS_PROXY_LIMITS, writeIngressResponseHead } from './ingress-response.js';
 import { resolveHostedTarget } from './runtime-transport.js';
 import { gatewayElapsedMs } from './usage.js';
+import { ArtifactRequestHeaderError, appendArtifactAuthenticationHeader, assertArtifactRequestHeaderBudget, stripArtifactCloudHeaders, validatedArtifactAuthenticationHeader } from '../server/request-authentication.js';
 export { cloudRunOrigin, resolveHostedTarget } from './runtime-transport.js';
 export const HOSTED_ARTIFACT_PROXY_LIMITS = Object.freeze({ maxRequestBytes: 32 * 1024 * 1024, maxResponseBytes: 32 * 1024 * 1024, timeoutMs: 60_000, maxTimeoutMs: 300_000 });
 const googleAuth = new GoogleAuth();
@@ -40,12 +41,6 @@ async function defaultIdentityTokenProvider({ audience }) {
 export function hostedIdentityToken(input) {
     return defaultIdentityTokenProvider(input);
 }
-function stripCloudHeaders(headers) {
-    for (const name of Object.keys(headers)) {
-        if (name === 'x-serverless-authorization' || name.startsWith('x-goog-'))
-            delete headers[name];
-    }
-}
 /** HTTP-only streaming hop. Authentication, CSRF and release admission happen before calling this. */
 export function proxyHostedArtifact(options) {
     return new HostedExchange(options).run();
@@ -92,11 +87,11 @@ class HostedExchange {
             request.once('error', this.finish);
             this.timer = setTimeout(() => this.fail(504), this.timeoutMs);
             this.timer.unref();
-            void this.prepare().catch(() => this.fail(this.unavailableStatus));
+            void this.prepare().catch(error => this.fail(error instanceof ArtifactRequestHeaderError ? 400 : this.unavailableStatus));
         });
     }
     async prepare() {
-        const { request, response, target, requestContext } = this.options;
+        const { request, response, target, requestContext, requestAuthentication } = this.options;
         const { upstream, audience } = resolveHostedTarget({ target });
         // Cloud Run revision tags select immutable transport destinations, but IAM
         // requires the canonical service audience. Both are control-plane owned;
@@ -107,6 +102,7 @@ class HostedExchange {
             validateHeaderValue('x-sequence-artifact-context', requestContext);
             if (!requestContext || requestContext.length > 16384)
                 throw new Error('Invalid request context');
+            validatedArtifactAuthenticationHeader({ token: requestAuthentication, contextToken: requestContext, external: Boolean(this.options.ingress) });
         }
         catch {
             this.fail(400);
@@ -127,7 +123,9 @@ class HostedExchange {
             this.fail(this.options.ingress ? 400 : 502);
             return;
         }
-        stripCloudHeaders(headers);
+        stripArtifactCloudHeaders({ headers });
+        headers['x-sequence-artifact-context'] = requestContext;
+        appendArtifactAuthenticationHeader({ headers, token: requestAuthentication, contextToken: requestContext });
         if (audience) {
             const provider = this.options.identityTokenProvider ?? defaultIdentityTokenProvider;
             const identityStarted = performance.now();
@@ -147,7 +145,7 @@ class HostedExchange {
         // HTML forms receive release markers. Avoid compression when possible;
         // runtimes that still compress HTML are decoded as a bounded stream below.
         headers['accept-encoding'] = 'identity';
-        headers['x-sequence-artifact-context'] = requestContext;
+        assertArtifactRequestHeaderBudget({ headers });
         const destination = this.resolveDestination(upstream);
         const transport = destination.protocol === 'https:' ? httpsRequest : httpRequest;
         const upstreamStarted = performance.now();
@@ -204,7 +202,7 @@ class HostedExchange {
             // Read before sanitising, which removes content-length as a hop header.
             const declaredLength = declaredContentLength(incoming.headers['content-length']);
             const headers = sanitizeResponseHeaders(incoming.headers);
-            stripCloudHeaders(headers);
+            stripArtifactCloudHeaders({ headers });
             const response = this.options.response;
             if (this.options.ingress) {
                 // Decided on the head, before any body byte; never the HTML release-marker path.

package/dist/gateway/ingress-handler.js

@@ -191,6 +191,8 @@ export function createIngressHandler({ options, runtimeDomain, protocol, isDrain
         };
         response.once('finish', report);
         response.once('close', report);
+        if (response.destroyed)
+            report();
     }
     /** Preflights are answered locally and never forwarded; a refusal carries no CORS headers. */
     function preflight({ request, response, origin, allowed, methods, headers }) {

package/dist/gateway/server.d.ts

@@ -41,7 +41,7 @@ export interface ArtifactGatewayOptions {
 }
 export declare function createArtifactGateway(options: ArtifactGatewayOptions): {
     server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
-    /** Observations recorded but not yet confirmed by Atlas: what a forced exit would lose. */
+    /** Recorded observations not yet confirmed by Atlas; excludes responses still in flight. */
     readonly pendingUsage: number;
     drain(): Promise<void>;
 };

package/dist/gateway/server.js

@@ -4,7 +4,7 @@ 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 { decodeGatewaySession, gatewaySessionCookies, renewGatewaySession, signGatewayRequest } from './session.js';
 import { proxyHostedArtifact } from './hosted-proxy.js';
 import { bootstrapPage } from './bootstrap-page.js';
 import { routeSequenceRequest } from './lattice-invoke.js';
@@ -95,7 +95,9 @@ export function createArtifactGateway(options) {
     const authorizations = new PositiveDecisionCache({ ttlMs: options.authorizationCacheTtlMs });
     const tunnelAuthorizations = new PositiveDecisionCache({ ttlMs: options.authorizationCacheTtlMs });
     const usage = new GatewayUsageReporter({ send: events => options.control.usage(events), onFailure: failure => options.onError?.(failure) });
+    const requests = new Set();
     let draining = false;
+    let drainPromise;
     const isIngressRequest = (request) => resemblesIngressHost({ rawHost: header(request, 'host'), runtimeDomain: options.runtimeDomain });
     const staticFiles = options.staticFiles ?? new StaticArtifactFiles({ fetch: ({ deploymentId, path }) => options.control.staticFile({ deploymentId, path, parentOrigin }) });
     /** Admission for the unauthenticated endpoints; the release frees the in-flight permit. */
@@ -173,10 +175,11 @@ export function createArtifactGateway(options) {
         const target = await decision.promise;
         const requestId = randomUUID();
         // A static deployment has no server of its own to read a request context.
-        const result = { session, target, requestId, authorizationCache: decision.source, requestContext: target.kind === 'static' ? '' : 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,
-            }) };
+        const signed = target.kind === 'static' ? { requestContext: '' } : signGatewayRequest({
+            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,
+        });
+        const result = { session, target, requestId, authorizationCache: decision.source, ...signed };
         activeRequests.set(request, result);
         return result;
     }
@@ -206,7 +209,8 @@ export function createArtifactGateway(options) {
             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 };
+            return { ownerId: authorized.session.ownerId, publicOrigin: authorized.session.publicOrigin, requestContext: authorized.requestContext,
+                ...(authorized.requestAuthentication ? { requestAuthentication: authorized.requestAuthentication } : {}) };
         },
         validateLease: async (lease) => {
             const credential = leases.get(lease.sessionId);
@@ -247,14 +251,24 @@ export function createArtifactGateway(options) {
     const proxyDevelopment = options.ingress?.appEnv === 'development' ? createDevelopmentIngressProxy({ broker }) : undefined;
     const ingress = createIngressHandler({ options: options.ingress, runtimeDomain: options.runtimeDomain, protocol: new URL(gatewayOrigin).protocol, isDraining: () => draining, onError: options.onError, usage, proxyDevelopment });
     const server = createServer({ maxHeaderSize: 32 * 1024, requestTimeout: 60_000, headersTimeout: 15_000 }, (request, response) => {
+        // server.close() can run before a destroyed response emits close. Join that event's
+        // usage finalizer AND the handler: authorization may finish after the browser disconnects.
+        const finished = new Promise(resolve => {
+            response.once('finish', resolve);
+            response.once('close', resolve);
+        });
+        const track = (handler) => {
+            const settled = Promise.allSettled([handler, finished]).then(() => { requests.delete(settled); });
+            requests.add(settled);
+        };
         // Before readiness, bootstrap and requestOrigin(): an ingress host, canonical or not, never
         // reaches a session-path handler or the 401/404→403 remap below (design §(e) "Branch placement").
         if (isIngressRequest(request)) {
-            void ingress.handle(request, response);
+            track(ingress.handle(request, response));
             return;
         }
         const startedAt = new Date().toISOString(), started = performance.now();
-        void (async () => {
+        track((async () => {
             if (isReadinessRequest({ request, gatewayOrigin, runtimeDomain: options.runtimeDomain })) {
                 const ready = !draining && (options.ready?.() ?? true);
                 json(response, ready ? 200 : 503, ready ? 'ready' : 'unavailable');
@@ -294,7 +308,7 @@ export function createArtifactGateway(options) {
                 }
             }
             const authorizationStarted = performance.now();
-            const { session, target, requestContext, requestId, authorizationCache } = await authorize(request);
+            const { session, target, requestContext, requestAuthentication, requestId, authorizationCache } = await authorize(request);
             // Immutable files Atlas already authorized this session for: no admission, context or usage.
             if (target.kind === 'static') {
                 await serveStaticTarget({ request, response, target, files: staticFiles, renew: () => renewCookie({ options, request, response, session, target }), parentOrigin: session.bridge.parentOrigin });
@@ -340,7 +354,7 @@ export function createArtifactGateway(options) {
             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 }, gatewayTimings });
+            await proxyHostedArtifact({ request, response, target, requestContext, requestAuthentication, body, limits: { timeoutMs: admitted.timeoutMs }, gatewayTimings });
         })().catch(error => {
             options.onError?.({ kind: error instanceof ReleaseAdmissionError ? 'release_mismatch' : error instanceof GatewayControlError ? 'authorization_denied'
                     : error instanceof ArtifactAdmissionError ? 'admission_rejected' : 'request_failed' });
@@ -348,7 +362,7 @@ export function createArtifactGateway(options) {
             if (error instanceof ArtifactAdmissionError && error.retryAfterSeconds && !response.headersSent)
                 response.setHeader('retry-after', String(error.retryAfterSeconds));
             json(response, status === 401 || status === 404 ? 403 : status, error instanceof ReleaseAdmissionError ? 'update_required' : 'artifact_request_failed');
-        });
+        }));
     });
     server.on('upgrade', (request, socket, head) => {
         void (async () => {
@@ -366,6 +380,10 @@ export function createArtifactGateway(options) {
                 return;
             }
             const authorized = await authorize(request);
+            if (draining) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
             if (authorized.target.kind !== 'development') {
                 rejectUpgrade(socket);
                 return;
@@ -378,18 +396,31 @@ export function createArtifactGateway(options) {
         handleClientErrors({ server, ingress });
     return {
         server,
-        /** Observations recorded but not yet confirmed by Atlas: what a forced exit would lose. */
+        /** Recorded observations not yet confirmed by Atlas; excludes responses still in flight. */
         get pendingUsage() { return usage.pending; },
-        async drain() {
+        drain() {
+            if (drainPromise)
+                return drainPromise;
             draining = true;
+            broker.beginDrain();
+            const closed = new Promise(resolve => server.close(() => resolve()));
             server.closeIdleConnections();
-            broker.close();
-            leases.clear();
-            authorizations.clear();
-            tunnelAuthorizations.clear();
-            // The usage timer keeps flushing while in-flight requests finish.
-            await new Promise(resolve => server.close(() => resolve()));
-            await usage.close();
+            drainPromise = (async () => {
+                while (requests.size)
+                    await Promise.all(requests);
+                // Active responses may have become idle since close() first stopped admission.
+                server.closeIdleConnections();
+                // Keep lease checks and revocation live until local and remote HTTP streams finish.
+                await broker.drain();
+                await closed;
+                while (requests.size)
+                    await Promise.all(requests);
+                leases.clear();
+                authorizations.clear();
+                tunnelAuthorizations.clear();
+                await usage.close();
+            })();
+            return drainPromise;
         },
     };
 }

package/dist/gateway/session.d.ts

@@ -1,6 +1,11 @@
 import { z } from 'zod';
 export declare const GATEWAY_SESSION_COOKIE = "__Host-atlas-artifact-session";
 export declare function gatewayReleaseCookieName(deploymentId: string): string;
+/** Only the authenticated Atlas bootstrap control reply supplies this private cookie member. */
+export declare const gatewayAuthenticationSchema: z.ZodObject<{
+    method: z.ZodLiteral<"auth0_user">;
+    sub: z.ZodString;
+}, z.core.$strict>;
 declare const sessionSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     kind: z.ZodEnum<{
@@ -30,6 +35,10 @@ declare const sessionSchema: z.ZodObject<{
         processId: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
     taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authentication: z.ZodOptional<z.ZodObject<{
+        method: z.ZodLiteral<"auth0_user">;
+        sub: z.ZodString;
+    }, z.core.$strict>>;
 }, 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. */
@@ -85,4 +94,9 @@ export declare function signGatewayContext({ session, method, path, privateKey,
     /** Seconds until exp. Browser requests stay at 60; a Lattice run may last up to 300. */
     ttlSeconds?: number;
 }): string;
+/** Signs a proof only for the exact context this call just minted from its authenticated session. */
+export declare function signGatewayRequest(input: Parameters<typeof signGatewayContext>[0]): {
+    requestContext: string;
+    requestAuthentication?: string;
+};
 export {};

package/dist/gateway/session.js

@@ -1,8 +1,9 @@
-import { createHmac, createPrivateKey, randomUUID, sign, timingSafeEqual } from 'node:crypto';
+import { createHash, createHmac, createPrivateKey, randomUUID, sign, timingSafeEqual } from 'node:crypto';
 import { z } from 'zod';
 import { ARTIFACT_CONTEXT_MAX_AGE_SECONDS, ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS, artifactRequestContextSchema } from '../server/request-context.js';
 import { normalizePublicOrigin } from '../tunnel/protocol.js';
 import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+import { ARTIFACT_REQUEST_AUTHENTICATION_MAX_LENGTH } from '../server/request-authentication.js';
 export const GATEWAY_SESSION_COOKIE = '__Host-atlas-artifact-session';
 export function gatewayReleaseCookieName(deploymentId) {
     if (!/^[a-zA-Z0-9_-]{1,128}$/.test(deploymentId))
@@ -16,6 +17,8 @@ catch {
     return false;
 } });
 const id = z.string().min(1).max(255);
+/** Only the authenticated Atlas bootstrap control reply supplies this private cookie member. */
+export const gatewayAuthenticationSchema = z.object({ method: z.literal('auth0_user'), sub: id }).strict();
 const sessionSchema = z.object({
     version: z.literal(1), kind: z.enum(['development', 'hosted', 'static']),
     sessionId: id.nullable(), deploymentId: id.nullable(),
@@ -24,6 +27,7 @@ const sessionSchema = z.object({
     bridge: artifactRequestContextSchema.shape.bridge,
     lattice: artifactRequestContextSchema.shape.lattice.optional(),
     taskRoutes: artifactRequestContextSchema.shape.taskRoutes,
+    authentication: gatewayAuthenticationSchema.optional(),
 }).strict().refine(value => value.kind === 'development'
     ? value.sessionId !== null && value.deploymentId === null && value.frameworkBuildId === null && !value.published
     // A static deployment has no Next build: its assets are named by the deployment itself.
@@ -33,7 +37,8 @@ const sessionSchema = z.object({
 function sameSessionScope(left, right) {
     return left.ownerId === right.ownerId && left.projectId === right.projectId &&
         left.environment === right.environment && left.publicOrigin === right.publicOrigin &&
-        left.kind === right.kind && left.published === right.published;
+        left.kind === right.kind && left.published === right.published &&
+        left.authentication?.method === right.authentication?.method && left.authentication?.sub === right.authentication?.sub;
 }
 /** Active use renews the idle window, but never extends the original admission's eight-hour bound. */
 export function renewGatewaySession({ session, authorizedExpiresAt, now = Date.now() }) {
@@ -161,3 +166,27 @@ export function signGatewayContext({ session, method, path, privateKey, keyId, n
     const signed = `${header}.${payload}`;
     return `${signed}.${sign(null, Buffer.from(signed), key).toString('base64url')}`;
 }
+/** Signs a proof only for the exact context this call just minted from its authenticated session. */
+export function signGatewayRequest(input) {
+    const requestContext = signGatewayContext(input);
+    const authentication = input.session.authentication;
+    if (!authentication || authentication.method !== 'auth0_user' || authentication.sub !== input.session.ownerId) {
+        return { requestContext };
+    }
+    // This is our own just-signed payload, never a caller-supplied context token.
+    const context = artifactRequestContextSchema.parse(JSON.parse(Buffer.from(requestContext.split('.')[1], 'base64url').toString('utf8')));
+    const header = Buffer.from(JSON.stringify({ alg: 'EdDSA', typ: 'JWT', kid: input.keyId })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify({
+        purpose: 'artifact-request-authentication', v: 1, iss: context.iss, aud: context.aud,
+        authenticationMethod: authentication.method, sub: authentication.sub,
+        contextJti: context.jti, contextSha256: createHash('sha256').update(requestContext).digest('hex'),
+        projectId: context.projectId, environment: context.environment, method: context.method,
+        pathSha256: createHash('sha256').update(context.path).digest('hex'),
+        iat: context.iat, exp: context.exp,
+    })).toString('base64url');
+    const unsigned = `${header}.${payload}`;
+    const requestAuthentication = `${unsigned}.${sign(null, Buffer.from(unsigned), createPrivateKey(input.privateKey)).toString('base64url')}`;
+    if (requestAuthentication.length > ARTIFACT_REQUEST_AUTHENTICATION_MAX_LENGTH)
+        throw new Error('Artifact authentication proof exceeds the header limit');
+    return { requestContext, requestAuthentication };
+}

package/dist/gateway-main.js

@@ -10,6 +10,7 @@ import { RedisTunnelOwnership, RedisTunnelRelay } from './tunnel/redis.js';
 import { ArtifactRequestAdmission } from './gateway/admission.js';
 import { GatewayControlAdmission } from './gateway/control-admission.js';
 import { createIngressRuntime, IngressSecretsError } from './gateway/ingress-runtime.js';
+import { DatadogStartupError, waitForDatadogStartup } from './gateway/datadog-startup.js';
 function required(name) {
     const value = process.env[name];
     if (!value)
@@ -20,6 +21,7 @@ function required(name) {
 async function main() {
     if (process.env.ARTIFACT_NEXT_ENABLED !== 'true')
         throw new Error('Artifact Next gateway is disabled');
+    await waitForDatadogStartup({ env: process.env });
     const redisUrl = required('ARTIFACT_NEXT_REDIS_URL');
     if (new URL(redisUrl).protocol !== 'rediss:')
         throw new Error('Artifact tunnel routing requires private Redis with TLS');
@@ -135,9 +137,9 @@ async function main() {
     process.once('SIGINT', () => { void stop(); });
 }
 void main().catch((error) => {
-    // Only an ingress-secrets refusal is described: its message names variables, never values, by
-    // construction. Other errors (Redis, URLs) may carry connection strings.
-    const reason = error instanceof IngressSecretsError ? error.message : undefined;
+    // These startup refusals contain only fixed descriptions and configuration names.
+    // Other errors (Redis, URLs) may carry connection strings.
+    const reason = error instanceof IngressSecretsError || error instanceof DatadogStartupError ? error.message : undefined;
     process.stderr.write(`${JSON.stringify({ event: 'artifact_gateway.start_failed', ...(reason ? { reason } : {}) })}\n`);
     process.exit(1);
 });