@sequenceholdings/artifact-studio 0.6.4 → 0.6.7

package/dist/gateway/control.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { normalizePublicOrigin } from '../tunnel/protocol.js';
 import { artifactRequestContextSchema } from '../server/request-context.js';
 import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+import { INGRESS_SNAPSHOT_MAX_BYTES, ingressExchangeResponseSchema, ingressGrantResponseSchema, ingressSnapshotSchema, } from '../server/ingress-control-contract.js';
 const id = z.string().min(1).max(255);
 const base = {
     projectId: id, ownerId: id, environment: id, publicOrigin: z.string().transform(normalizePublicOrigin),
@@ -17,7 +18,7 @@ const base = {
 };
 export const gatewayTargetSchema = z.discriminatedUnion('kind', [
     z.object({ ...base, kind: z.literal('development'), sessionId: id, epoch: z.number().int().positive() }),
-    z.object({ ...base, kind: z.literal('hosted'), deploymentId: id, frameworkBuildId: artifactNextFrameworkBuildIdSchema, upstreamUrl: z.string().url(), upstreamAudience: z.string().url().optional(), active: z.boolean(), published: z.boolean().optional() }),
+    z.object({ ...base, kind: z.literal('hosted'), deploymentId: id, frameworkBuildId: artifactNextFrameworkBuildIdSchema, upstreamUrl: z.string().url(), upstreamAudience: z.string().url().optional(), runtimeTransport: z.enum(['cloud-run', 'local-docker']).optional(), active: z.boolean(), published: z.boolean().optional() }),
 ]);
 const bootstrapSchema = z.object({ parentOrigin: z.string().transform(normalizePublicOrigin), channelId: id, nonce: z.string().min(16).max(255) });
 const usageResultSchema = z.object({ rejected: z.number().int().nonnegative() });
@@ -27,6 +28,7 @@ const latticeInvokeGrantSchema = z.object({
     frameworkBuildId: artifactNextFrameworkBuildIdSchema,
     upstreamUrl: z.string().url(),
     upstreamAudience: z.string().url().optional(),
+    runtimeTransport: z.enum(['cloud-run', 'local-docker']).optional(),
     publicOrigin: z.string().min(1).max(2048),
     environment: id,
     principalSub: id,
@@ -46,6 +48,49 @@ export class GatewayControlError extends Error {
         this.name = 'GatewayControlError';
     }
 }
+/** Codes an ingress control route may answer with (design §(i)), and the status each one carries. */
+const INGRESS_CONTROL_CODES = { invalid_token: 401, exchange_denied: 403, not_found: 404, rate_limited: 429, temporarily_unavailable: 503 };
+const INGRESS_ERROR_BODY_MAX_BYTES = 4096;
+function isIngressControlCode(value) {
+    return Object.hasOwn(INGRESS_CONTROL_CODES, value);
+}
+/**
+ * A refusal an ingress control route decided: its contract code and Atlas's `Retry-After`, so the
+ * gateway answers the caller with Atlas's decision instead of inventing one. `code` is null when the
+ * response named no contract code matching its status (a misconfigured control token, a bare 500):
+ * the gateway then answers 503, never a code that would send the client into a sign-in loop.
+ */
+export class IngressControlError extends GatewayControlError {
+    code;
+    retryAfterSeconds;
+    constructor(status, code, retryAfterSeconds) {
+        super(status);
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'IngressControlError';
+    }
+}
+/** The contract code of a refused control response, read from at most 4 KiB of its JSON body. */
+async function ingressRefusal(response) {
+    const retryAfter = Number(response.headers.get('retry-after'));
+    const retryAfterSeconds = Number.isSafeInteger(retryAfter) && retryAfter > 0 && retryAfter <= 3600 ? retryAfter : undefined;
+    let code = null;
+    try {
+        const length = Number(response.headers.get('content-length'));
+        const text = length > INGRESS_ERROR_BODY_MAX_BYTES ? '' : (await response.text()).slice(0, INGRESS_ERROR_BODY_MAX_BYTES);
+        const parsed = z.object({ error: z.string() }).safeParse(JSON.parse(text));
+        const named = parsed.success && isIngressControlCode(parsed.data.error) ? parsed.data.error : null;
+        // A code is believed only with the status the contract gives it.
+        code = named !== null && INGRESS_CONTROL_CODES[named] === response.status ? named : null;
+    }
+    catch {
+        code = null;
+    }
+    finally {
+        await response.body?.cancel().catch(() => undefined);
+    }
+    return new IngressControlError(response.status, code, retryAfterSeconds);
+}
 export class ArtifactGatewayControl {
     options;
     origin;
@@ -55,15 +100,19 @@ export class ArtifactGatewayControl {
         if (options.token.length < 32)
             throw new Error('Artifact control plane token requires at least 32 characters');
     }
-    async call(path, body, timeoutMs = 10_000) {
+    call(path, body, timeoutMs = 10_000) {
+        return this.send({ path, body, timeoutMs, maxBytes: 128 * 1024 });
+    }
+    async send({ path, body, timeoutMs, maxBytes, ingress = false }) {
         const response = await (this.options.fetch ?? fetch)(`${this.origin}/api/artifact-studio/next/control/${path}`, {
-            method: 'POST', headers: { authorization: `Bearer ${this.options.token}`, 'content-type': 'application/json' },
-            body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs), redirect: 'error',
+            method: body === undefined ? 'GET' : 'POST',
+            headers: { authorization: `Bearer ${this.options.token}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(timeoutMs), redirect: 'error',
         });
         if (!response.ok)
-            throw new GatewayControlError(response.status);
+            throw ingress ? await ingressRefusal(response) : new GatewayControlError(response.status);
         const contentLength = Number(response.headers.get('content-length'));
-        if (contentLength > 128 * 1024) {
+        if (contentLength > maxBytes) {
             await response.body?.cancel();
             throw new GatewayControlError(502);
         }
@@ -78,7 +127,7 @@ export class ArtifactGatewayControl {
                 if (done)
                     break;
                 length += value.length;
-                if (length > 128 * 1024)
+                if (length > maxBytes)
                     throw new GatewayControlError(502);
                 chunks.push(value);
             }
@@ -88,6 +137,26 @@ export class ArtifactGatewayControl {
             await reader.cancel().catch(() => undefined);
         }
     }
+    /** Every enabled ingress host (GET, at most 1 MiB); the gateway pulls it on a timer, never per request. */
+    async ingressSnapshot() {
+        return ingressSnapshotSchema.parse(await this.send({ path: 'ingress-snapshot', timeoutMs: 10_000, maxBytes: INGRESS_SNAPSHOT_MAX_BYTES }));
+    }
+    /** Verifies an identity provider's token for an ingress; refusals carry Atlas's contract code. */
+    async ingressExchange(body) {
+        return ingressExchangeResponseSchema.parse(await this.send({ path: 'ingress-exchange', body, timeoutMs: 10_000, maxBytes: 16 * 1024, ingress: true }));
+    }
+    /** Re-checks one ingress request against the active deployment and returns where to proxy it. */
+    async ingressGrant(body) {
+        return ingressGrantResponseSchema.parse(await this.send({ path: 'ingress-grant', body, timeoutMs: 10_000, maxBytes: 16 * 1024, ingress: true }));
+    }
+    /** Logout: revokes every identity provider token the subject was issued up to Atlas's now. */
+    async ingressRevoke(body) {
+        await this.send({ path: 'ingress-revoke', body, timeoutMs: 10_000, maxBytes: 16 * 1024, ingress: true });
+    }
+    /** One batch of refusals the gateway decided locally (Atlas audits the ones it decided itself). */
+    async ingressAudit(body) {
+        await this.send({ path: 'ingress-audit', body, timeoutMs: 5_000, maxBytes: 16 * 1024, ingress: true });
+    }
     /** One idempotent batch; Atlas reports events it refused (for example, a retired target). */
     async usage(events) {
         const value = await this.call('usage', { events }, 5_000);

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

@@ -1,16 +1,17 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type HostedArtifactIngressMode } from './ingress-response.js';
+import { type HostedRuntimeTarget } from './runtime-transport.js';
+export { cloudRunOrigin, resolveHostedTarget, type HostedRuntimeTarget } from './runtime-transport.js';
 export declare const HOSTED_ARTIFACT_PROXY_LIMITS: Readonly<{
-    maxBodyBytes: number;
+    maxRequestBytes: number;
+    maxResponseBytes: number;
     timeoutMs: 60000;
     maxTimeoutMs: 300000;
 }>;
 export interface HostedArtifactProxyOptions {
     request: IncomingMessage;
     response: ServerResponse;
-    target: {
-        upstreamUrl: string;
-        /** Canonical service URL from the same provider record as the revision URL. */
-        upstreamAudience?: string;
+    target: HostedRuntimeTarget & {
         publicOrigin: string;
         projectId: string;
         deploymentId: string;
@@ -26,16 +27,18 @@ export interface HostedArtifactProxyOptions {
     resolveUpstream?: (input: {
         url: URL;
     }) => URL;
-    /** Approved request timeouts may exceed the default up to the platform cap. */
+    /** Approved request timeouts may exceed the default up to the platform cap (55 s on an ingress). */
     limits?: {
-        maxBodyBytes?: number;
+        maxRequestBytes?: number;
+        maxResponseBytes?: number;
         timeoutMs?: number;
     };
+    /** Present only for an external ingress request. */
+    ingress?: HostedArtifactIngressMode;
 }
 export declare function hostedIdentityToken(input: {
     audience: string;
     signal: AbortSignal;
 }): Promise<string>;
-export declare function cloudRunOrigin(value: string): URL;
 /** HTTP-only streaming hop. Authentication, CSRF and release admission happen before calling this. */
 export declare function proxyHostedArtifact(options: HostedArtifactProxyOptions): Promise<void>;

package/dist/gateway/hosted-proxy.js

@@ -3,9 +3,13 @@ import { request as httpsRequest } from 'node:https';
 import { Duplex, Readable, Transform } from 'node:stream';
 import { createBrotliDecompress, createGunzip, createInflate } from 'node:zlib';
 import { GoogleAuth } from 'google-auth-library';
-import { assertSafeRequest, isSharedCacheDirective, normalizePublicOrigin, sanitizeRequestHeaders, sanitizeResponseHeaders, SHARED_CACHE_REFUSAL } from '../tunnel/protocol.js';
+import { assertSafeRequest, normalizePublicOrigin, sanitizeRequestHeaders, sanitizeResponseHeaders } from '../tunnel/protocol.js';
+import { enforceBrowserCachePolicy, mergeFramePolicy, rewriteLocation } from './session-response.js';
 import { createReleaseFormTransform } from '../server/release-forms.js';
-export const HOSTED_ARTIFACT_PROXY_LIMITS = Object.freeze({ maxBodyBytes: 32 * 1024 * 1024, timeoutMs: 60_000, maxTimeoutMs: 300_000 });
+import { declaredContentLength, INGRESS_PROXY_ERROR_CODES, INGRESS_PROXY_LIMITS, writeIngressResponseHead } from './ingress-response.js';
+import { resolveHostedTarget } from './runtime-transport.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();
 const identityClients = new Map();
 async function defaultIdentityTokenProvider({ audience }) {
@@ -35,58 +39,12 @@ async function defaultIdentityTokenProvider({ audience }) {
 export function hostedIdentityToken(input) {
     return defaultIdentityTokenProvider(input);
 }
-export function cloudRunOrigin(value) {
-    const url = new URL(value);
-    if (!/^https:\/\/[a-z0-9.-]+\.run\.app\/?$/.test(value) || url.protocol !== 'https:' ||
-        url.username || url.password || url.port || url.pathname !== '/' || url.search || url.hash ||
-        !url.hostname.split('.').every((part) => /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(part)))
-        throw new Error('Invalid hosted deployment origin');
-    return url;
-}
 function stripCloudHeaders(headers) {
     for (const name of Object.keys(headers)) {
         if (name === 'x-serverless-authorization' || name.startsWith('x-goog-'))
             delete headers[name];
     }
 }
-function rewriteLocation({ location, upstream, publicOrigin }) {
-    if (!/^(?:https?:)?\/\//i.test(location))
-        return location;
-    const url = new URL(location, upstream);
-    return url.origin === upstream.origin ? `${publicOrigin}${url.pathname}${url.search}${url.hash}` : location;
-}
-function mergeFramePolicy({ application, trusted }) {
-    const policies = Array.isArray(application) ? application : [application];
-    const frames = Array.isArray(trusted) ? trusted : [trusted];
-    return [...policies.map((policy) => policy.split(';')
-            .filter((directive) => directive.trim().split(/\s/, 1)[0].toLowerCase() !== 'frame-ancestors')
-            .map((directive) => directive.trim()).filter(Boolean).join('; ')).filter(Boolean), ...frames];
-}
-function enforceBrowserCachePolicy({ request, response }) {
-    const path = (request.url ?? '/').split('?', 1)[0];
-    let staticAsset = false;
-    try {
-        const segments = path.slice(1).split('/').map((segment) => decodeURIComponent(segment));
-        staticAsset = path.startsWith('/_next/static/') && /\.(?:js|css)$/.test(path) &&
-            segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..' && !/[\\/]/.test(segment));
-    }
-    catch { /* Malformed or ambiguous asset paths retain the default no-store policy. */ }
-    const contentType = response.getHeader('content-type');
-    const mediaType = typeof contentType === 'string' ? contentType.split(';', 1)[0].trim().toLowerCase() : undefined;
-    const assetType = path.endsWith('.css') ? mediaType === 'text/css' : mediaType === 'text/javascript' || mediaType === 'application/javascript';
-    const revalidateAsset = staticAsset && ['GET', 'HEAD'].includes(request.method ?? 'GET') &&
-        (response.statusCode === 200 || response.statusCode === 304) &&
-        (assetType || (response.statusCode === 304 && contentType === undefined));
-    // Every protected reuse must reach authorization. Retain only private static
-    // JS/CSS bytes and validators; app output may never opt into browser/CDN TTLs.
-    for (const name of response.getHeaderNames()) {
-        if (isSharedCacheDirective(name))
-            response.removeHeader(name);
-    }
-    response.setHeader('cache-control', revalidateAsset ? 'private, no-cache' : 'private, no-store');
-    for (const [name, value] of Object.entries(SHARED_CACHE_REFUSAL))
-        response.setHeader(name, value);
-}
 /** HTTP-only streaming hop. Authentication, CSRF and release admission happen before calling this. */
 export function proxyHostedArtifact(options) {
     return new HostedExchange(options).run();
@@ -94,9 +52,11 @@ export function proxyHostedArtifact(options) {
 class HostedExchange {
     options;
     controller = new AbortController();
-    maximum;
+    requestMaximum;
+    responseMaximum;
     timeoutMs;
     timer;
+    idleWriteTimer;
     upload;
     outgoing;
     incoming;
@@ -108,8 +68,10 @@ class HostedExchange {
     resolve;
     constructor(options) {
         this.options = options;
-        this.maximum = this.boundLimit(options.limits?.maxBodyBytes, HOSTED_ARTIFACT_PROXY_LIMITS.maxBodyBytes);
-        this.timeoutMs = this.boundLimit(options.limits?.timeoutMs, HOSTED_ARTIFACT_PROXY_LIMITS.maxTimeoutMs, HOSTED_ARTIFACT_PROXY_LIMITS.timeoutMs);
+        this.requestMaximum = this.boundLimit(options.limits?.maxRequestBytes, HOSTED_ARTIFACT_PROXY_LIMITS.maxRequestBytes);
+        this.responseMaximum = this.boundLimit(options.limits?.maxResponseBytes, HOSTED_ARTIFACT_PROXY_LIMITS.maxResponseBytes);
+        const maxTimeoutMs = options.ingress ? INGRESS_PROXY_LIMITS.maxTimeoutMs : HOSTED_ARTIFACT_PROXY_LIMITS.maxTimeoutMs;
+        this.timeoutMs = this.boundLimit(options.limits?.timeoutMs, maxTimeoutMs, Math.min(HOSTED_ARTIFACT_PROXY_LIMITS.timeoutMs, maxTimeoutMs));
     }
     boundLimit(value, maximum, fallback = maximum) {
         return Number.isSafeInteger(value) && value !== undefined && value > 0 ? Math.min(value, maximum) : fallback;
@@ -129,16 +91,15 @@ class HostedExchange {
             request.once('error', this.finish);
             this.timer = setTimeout(() => this.fail(504), this.timeoutMs);
             this.timer.unref();
-            void this.prepare().catch(() => this.fail(502));
+            void this.prepare().catch(() => this.fail(this.unavailableStatus));
         });
     }
     async prepare() {
         const { request, response, target, requestContext } = this.options;
-        const upstream = cloudRunOrigin(target.upstreamUrl);
+        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;
         // never derive this from a browser host, header or query parameter.
-        const audience = target.upstreamAudience === undefined ? upstream : cloudRunOrigin(target.upstreamAudience);
         const publicOrigin = normalizePublicOrigin(target.publicOrigin);
         try {
             assertSafeRequest(request.method ?? 'GET', request.url ?? '/');
@@ -151,30 +112,41 @@ class HostedExchange {
             return;
         }
         const length = request.headers['content-length'];
-        if (length !== undefined && (!/^(0|[1-9][0-9]*)$/.test(length) || Number(length) > this.maximum)) {
+        if (length !== undefined && (!/^(0|[1-9][0-9]*)$/.test(length) || Number(length) > this.requestMaximum)) {
             this.fail(413);
             return;
         }
-        const headers = sanitizeRequestHeaders(request.headers, publicOrigin);
-        stripCloudHeaders(headers);
-        const provider = this.options.identityTokenProvider ?? defaultIdentityTokenProvider;
-        const token = await provider({ audience: audience.origin, signal: this.controller.signal });
-        if (this.stopped)
+        let headers;
+        try {
+            headers = sanitizeRequestHeaders(request.headers, publicOrigin, this.options.ingress ? { mode: 'ingress', appHeaders: this.options.ingress.requestHeaders } : {});
+        }
+        catch {
+            // A header map the schema refuses is the caller's malformed request: an ingress caller must
+            // not retry it as an outage (§(i) `bad_request`); a session keeps its 502.
+            this.fail(this.options.ingress ? 400 : 502);
             return;
-        if (!/^[A-Za-z0-9._~-]+$/.test(token) || token.length > 16384)
-            throw new Error('Invalid platform token');
+        }
+        stripCloudHeaders(headers);
+        if (audience) {
+            const provider = this.options.identityTokenProvider ?? defaultIdentityTokenProvider;
+            const token = await provider({ audience: audience.origin, signal: this.controller.signal });
+            if (this.stopped)
+                return;
+            if (!/^[A-Za-z0-9._~-]+$/.test(token) || token.length > 16384)
+                throw new Error('Invalid platform token');
+            // Cloud Run removes this token's signature before passing it to user code.
+            // https://cloud.google.com/run/docs/authenticating/service-to-service
+            headers['x-serverless-authorization'] = `Bearer ${token}`;
+        }
         headers.host = upstream.host;
         // 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';
-        // Cloud Run removes this token's signature before passing it to user code.
-        // https://cloud.google.com/run/docs/authenticating/service-to-service
-        headers['x-serverless-authorization'] = `Bearer ${token}`;
         headers['x-sequence-artifact-context'] = requestContext;
         const destination = this.resolveDestination(upstream);
         const transport = destination.protocol === 'https:' ? httpsRequest : httpRequest;
         this.outgoing = transport(destination, { method: request.method, path: request.url, headers, maxHeaderSize: 32 * 1024 }, (incoming) => this.receive({ incoming, upstream, publicOrigin }));
-        this.outgoing.on('error', () => this.fail(502));
+        this.outgoing.on('error', () => this.fail(this.unavailableStatus));
         this.outgoing.once('upgrade', (_incoming, socket) => { socket.destroy(); this.fail(502); });
         this.outgoing.on('drain', () => { if (!this.stopped)
             this.upload?.resume(); });
@@ -182,8 +154,16 @@ class HostedExchange {
         this.upload.on('data', this.sendChunk);
         this.upload.once('end', () => this.outgoing?.end());
         this.upload.once('error', () => this.fail(502));
-        response.on('drain', () => { if (!this.stopped)
-            this.responseSource?.resume(); });
+        response.on('drain', () => {
+            clearTimeout(this.idleWriteTimer);
+            this.idleWriteTimer = undefined;
+            if (!this.stopped)
+                this.responseSource?.resume();
+        });
+    }
+    /** An unreachable app is an outage an ingress caller retries; a session keeps its 502. */
+    get unavailableStatus() {
+        return this.options.ingress ? 503 : 502;
     }
     resolveDestination(upstream) {
         const destination = this.options.resolveUpstream?.({ url: upstream }) ?? upstream;
@@ -197,7 +177,7 @@ class HostedExchange {
         if (this.stopped)
             return;
         this.sentBytes += chunk.byteLength;
-        if (this.sentBytes > this.maximum) {
+        if (this.sentBytes > this.requestMaximum) {
             this.fail(413);
             return;
         }
@@ -211,29 +191,24 @@ class HostedExchange {
             return;
         }
         try {
+            // 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);
-            delete headers['x-frame-options'];
-            if (typeof headers.location === 'string')
-                headers.location = rewriteLocation({ location: headers.location, upstream, publicOrigin });
             const response = this.options.response;
-            this.responseSource = this.prepareResponseSource({ incoming, headers, publicOrigin });
-            const framePolicy = response.getHeader('content-security-policy');
-            if (headers['content-security-policy'] && (typeof framePolicy === 'string' || Array.isArray(framePolicy))) {
-                headers['content-security-policy'] = mergeFramePolicy({ application: headers['content-security-policy'], trusted: framePolicy });
-            }
-            response.statusCode = incoming.statusCode ?? 502;
-            for (const [name, value] of Object.entries(headers)) {
-                const existing = name === 'set-cookie' ? response.getHeader(name) : undefined;
-                if (typeof existing === 'string' || Array.isArray(existing)) {
-                    // Rolling gateway leases and application cookies share the response,
-                    // but application cookies were stripped of reserved names above.
-                    response.setHeader(name, [...(Array.isArray(existing) ? existing : [existing]), ...(Array.isArray(value) ? value : [value])]);
+            if (this.options.ingress) {
+                // Decided on the head, before any body byte; never the HTML release-marker path.
+                if (!writeIngressResponseHead({
+                    response, status: incoming.statusCode ?? 502, method: this.options.request.method ?? 'GET', headers, declaredLength,
+                    responses: this.options.ingress.responses, maxResponseBytes: this.responseMaximum,
+                })) {
+                    this.fail(502);
+                    return;
                 }
-                else
-                    response.setHeader(name, value);
+                this.responseSource = incoming;
             }
-            enforceBrowserCachePolicy({ request: this.options.request, response });
+            else
+                this.responseSource = this.writeSessionResponseHead({ incoming, headers, upstream, publicOrigin });
             this.responseSource.on('data', this.receiveChunk);
             this.responseSource.once('end', () => response.end());
             this.responseSource.once('error', () => this.fail(502));
@@ -244,6 +219,30 @@ class HostedExchange {
             this.fail(502);
         }
     }
+    writeSessionResponseHead({ incoming, headers, upstream, publicOrigin }) {
+        delete headers['x-frame-options'];
+        if (typeof headers.location === 'string')
+            headers.location = rewriteLocation({ location: headers.location, upstream, publicOrigin });
+        const response = this.options.response;
+        const source = this.prepareResponseSource({ incoming, headers, publicOrigin });
+        const framePolicy = response.getHeader('content-security-policy');
+        if (headers['content-security-policy'] && (typeof framePolicy === 'string' || Array.isArray(framePolicy))) {
+            headers['content-security-policy'] = mergeFramePolicy({ application: headers['content-security-policy'], trusted: framePolicy });
+        }
+        response.statusCode = incoming.statusCode ?? 502;
+        for (const [name, value] of Object.entries(headers)) {
+            const existing = name === 'set-cookie' ? response.getHeader(name) : undefined;
+            if (typeof existing === 'string' || Array.isArray(existing)) {
+                // Rolling gateway leases and application cookies share the response,
+                // but application cookies were stripped of reserved names above.
+                response.setHeader(name, [...(Array.isArray(existing) ? existing : [existing]), ...(Array.isArray(value) ? value : [value])]);
+            }
+            else
+                response.setHeader(name, value);
+        }
+        enforceBrowserCachePolicy({ request: this.options.request, response });
+        return source;
+    }
     prepareResponseSource({ incoming, headers, publicOrigin }) {
         const contentType = headers['content-type'];
         if (typeof contentType !== 'string' || contentType.split(';', 1)[0].trim().toLowerCase() !== 'text/html')
@@ -269,7 +268,7 @@ class HostedExchange {
             source = source.pipe(decoder);
         }
         let decodedBytes = 0;
-        const maximum = this.maximum;
+        const maximum = this.responseMaximum;
         const limit = new Transform({ transform(chunk, _encoding, callback) {
                 decodedBytes += chunk.byteLength;
                 if (decodedBytes > maximum)
@@ -287,12 +286,18 @@ class HostedExchange {
         if (this.stopped)
             return;
         this.receivedBytes += chunk.byteLength;
-        if (this.receivedBytes > this.maximum) {
+        if (this.receivedBytes > this.responseMaximum) {
             this.fail(502);
             return;
         }
-        if (!this.options.response.write(chunk))
-            this.responseSource?.pause();
+        if (this.options.response.write(chunk))
+            return;
+        this.responseSource?.pause();
+        // Backpressure would otherwise hold the admission permit until the request timeout.
+        if (this.options.ingress && !this.idleWriteTimer) {
+            this.idleWriteTimer = setTimeout(() => this.fail(504), this.options.ingress.idleWriteTimeoutMs ?? INGRESS_PROXY_LIMITS.idleWriteTimeoutMs);
+            this.idleWriteTimer.unref();
+        }
     };
     fail(status) {
         if (this.stopped)
@@ -303,6 +308,8 @@ class HostedExchange {
         const response = this.options.response;
         if (response.headersSent)
             response.destroy();
+        else if (this.options.ingress)
+            this.options.ingress.errorWriter({ status, code: INGRESS_PROXY_ERROR_CODES[status] });
         else {
             // Do not send application cookies, encodings or redirects with a gateway error.
             for (const name of response.getHeaderNames()) {
@@ -321,6 +328,7 @@ class HostedExchange {
             return;
         this.stopped = true;
         clearTimeout(this.timer);
+        clearTimeout(this.idleWriteTimer);
         this.controller.abort();
         this.upload?.off('data', this.sendChunk);
         this.incoming?.off('data', this.receiveChunk);

package/dist/gateway/ingress-admission.d.ts

@@ -0,0 +1,77 @@
+import { type AdmissionRedis } from './admission.js';
+/**
+ * Rate limiting and in-flight pools for the external ingress (design §(e) "Rate limiting and
+ * admission"). A separate instance from `GatewayControlAdmission`, with its own in-flight pools,
+ * so a flood of borrower exchanges can never return 503 on an Atlas user's `/_sequence/session`.
+ * The same fail-closed fixed-window counters: when Redis cannot answer, nothing is admitted.
+ */
+export type IngressInFlightPool = 'ingress-public' | 'ingress-grant';
+export interface IngressAdmissionLimits {
+    /** Fixed Redis-clock window shared by every class. */
+    windowMs: number;
+    preflight: {
+        perClient: number;
+    };
+    exchange: {
+        perClient: number;
+        perHost: number;
+        environment: number;
+    };
+    logout: {
+        perSubject: number;
+        perClient: number;
+    };
+    subject: {
+        perSubject: number;
+    };
+    app: {
+        perApp: number;
+    };
+    /** Outstanding Atlas calls one gateway process may hold per pool. */
+    pools: Record<IngressInFlightPool, number>;
+}
+/** The design's defaults; bindings may lower them in Atlas, never raise them here. */
+export declare const INGRESS_ADMISSION_LIMITS: Readonly<IngressAdmissionLimits>;
+/**
+ * The address an ingress caller is budgeted against: an IPv4 address as is, an IPv6 address as its
+ * /48 (design §(e)), since one IPv6 customer commonly controls a /48 or a /56.
+ */
+export declare function ingressClientBucket(address: string): string;
+export declare class IngressAdmission {
+    private readonly options;
+    private readonly namespace;
+    private readonly limits;
+    private readonly inFlight;
+    constructor(options: {
+        redis: AdmissionRedis;
+        namespace: string;
+        limits?: IngressAdmissionLimits;
+    });
+    /** `ingress-preflight`: per client address only, no in-flight permit (no Atlas call follows). */
+    preflight({ clientIp }: {
+        clientIp: string;
+    }): Promise<void>;
+    /** `ingress-exchange`: per client, per host and environment-wide; holds an `ingress-public` permit. */
+    exchange({ clientIp, host }: {
+        clientIp: string;
+        host: string;
+    }): Promise<() => void>;
+    /** `ingress-logout`: per subject and per client, after the pass verified; holds an `ingress-public` permit. */
+    logout({ provider, subjectHash, clientIp }: {
+        provider: string;
+        subjectHash: string;
+        clientIp: string;
+    }): Promise<() => void>;
+    /** `ingress-subject` and `ingress-app`, on verified pass fields; plain counters, no in-flight permit. */
+    request({ provider, subjectHash, projectId, ingressId }: {
+        provider: string;
+        subjectHash: string;
+        projectId: string;
+        ingressId: string;
+    }): Promise<void>;
+    /** Runs one Atlas call under a permit from `pool`; a full pool is 503, never a queue. */
+    withPool<T>(pool: IngressInFlightPool, work: () => Promise<T>): Promise<T>;
+    private withPermit;
+    private take;
+    private count;
+}