@sequenceholdings/artifact-studio 0.6.4 → 0.6.6

package/dist/gateway/ingress-audit.js

@@ -0,0 +1,84 @@
+import { INGRESS_AUDIT_BATCH_MAX_EVENTS } from '../server/ingress-control-contract.js';
+export const INGRESS_AUDIT_FLUSH_INTERVAL_MS = 5_000;
+/** Refusals buffered between flushes; past this they are dropped and counted, never queued without bound. */
+export const INGRESS_AUDIT_CAPACITY = 5_000;
+/** Shutdown spends at most this on the final batch, so audit delivery never holds up tunnel cleanup. */
+export const INGRESS_AUDIT_CLOSE_BUDGET_MS = 2_000;
+/**
+ * Batches the refusals the gateway decided itself (edge, client address, CORS, a refused authentic
+ * pass, freshness) to `control/ingress-audit` every 5 s, at most 500 per call. Garbage and
+ * admission refusals are counted elsewhere and never reach it. Refusals an Atlas control
+ * route returned are never recorded here: Atlas already audited them. Best effort and bounded: a
+ * refusal flood can cost Atlas at most one batch per interval per gateway process, and a failed
+ * delivery is counted, not retried into a backlog.
+ */
+export class IngressDenialAuditor {
+    options;
+    buffer = [];
+    dropped = 0;
+    timer;
+    flushing;
+    intervalMs;
+    capacity;
+    constructor(options) {
+        this.options = options;
+        this.intervalMs = options.intervalMs ?? INGRESS_AUDIT_FLUSH_INTERVAL_MS;
+        this.capacity = options.capacity ?? INGRESS_AUDIT_CAPACITY;
+    }
+    record(event) {
+        if (this.buffer.length >= this.capacity) {
+            this.dropped++;
+            return;
+        }
+        this.buffer.push(event);
+    }
+    /** Flushes every interval; the timer never keeps the process alive. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => { void this.flush(); }, this.intervalMs);
+        this.timer.unref();
+    }
+    /** One batch of at most 500 refusals, single-flight. Never rejects. */
+    flush() {
+        this.flushing ??= this.deliver().finally(() => { this.flushing = undefined; });
+        return this.flushing;
+    }
+    /**
+     * Stops the timer and makes one final delivery attempt within the close budget: a slow or failing
+     * Atlas costs shutdown at most that long. Whatever is still buffered is dropped and counted.
+     */
+    async close() {
+        clearInterval(this.timer);
+        this.timer = undefined;
+        let expire;
+        const budget = new Promise((resolve) => { expire = setTimeout(resolve, this.options.closeBudgetMs ?? INGRESS_AUDIT_CLOSE_BUDGET_MS); });
+        try {
+            await Promise.race([(this.flushing ?? Promise.resolve()).then(() => this.flush()), budget]);
+        }
+        finally {
+            clearTimeout(expire);
+        }
+        this.dropped += this.buffer.length;
+        this.buffer = [];
+        this.reportDropped();
+    }
+    async deliver() {
+        this.reportDropped();
+        const events = this.buffer.splice(0, INGRESS_AUDIT_BATCH_MAX_EVENTS);
+        if (events.length === 0)
+            return;
+        try {
+            await this.options.send({ events });
+        }
+        catch {
+            this.options.onFailure?.({ kind: 'ingress_audit_delivery_failed', count: events.length });
+        }
+    }
+    reportDropped() {
+        if (!this.dropped)
+            return;
+        this.options.onFailure?.({ kind: 'ingress_audit_dropped', count: this.dropped });
+        this.dropped = 0;
+    }
+}

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

@@ -0,0 +1,57 @@
+import type { IngressPassPayload } from './ingress-pass.js';
+/** What the gateway records of a caller's `User-Agent` (design §(f)): ≤ 512 characters, no control characters. */
+export declare const OBSERVED_USER_AGENT_MAX_LENGTH = 512;
+/**
+ * The user agent as the context carries it: control characters stripped, then truncated. The
+ * SHA-256 is of the header exactly as sent, so a truncated value still fingerprints the caller.
+ */
+export declare function observeUserAgent(raw: string | undefined): {
+    userAgent: string;
+    userAgentSha256: string;
+};
+/** The namespaced subject an external context and usage carry; ≤ 255 characters or refused at exchange. */
+export declare function externalSubject({ provider, subject }: {
+    provider: string;
+    subject: string;
+}): string;
+/**
+ * What an external context runs against: a published deployment, or (local development only,
+ * design §(j.3) step 5) the development session whose tunnel the gateway proxies over.
+ */
+export type ExternalContextRelease = {
+    mode: 'published';
+    deploymentId: string;
+} | {
+    mode: 'development';
+    devSessionId: string;
+};
+/**
+ * Signs the external (v2) context for one admitted ingress request (design §(f), "Steady state"
+ * step 8), with the gateway's external key, never the browser one. Lifetime ≤ 60 s. Validated
+ * against the strict v2 schema before signing, so the gateway never emits a context the SDK,
+ * sidecar or broker would refuse.
+ */
+export declare function signExternalGatewayContext({ privateKey, keyId, projectId, environment, release, requestId, method, path, serviceAccountId, pass, passKid, client, now, ttlSeconds, }: {
+    privateKey: string;
+    keyId: string;
+    projectId: string;
+    environment: string;
+    release: ExternalContextRelease;
+    /** Gateway-generated, never client-supplied. */
+    requestId: string;
+    method: string;
+    /** The canonical path plus raw query, as matched. */
+    path: string;
+    /** The grant's ingress service account. */
+    serviceAccountId: string;
+    pass: IngressPassPayload;
+    passKid: string;
+    client: {
+        ip: string;
+        userAgent: string;
+        userAgentSha256: string;
+        origin: string | null;
+    };
+    now?: number;
+    ttlSeconds?: number;
+}): string;

package/dist/gateway/ingress-context.js

@@ -0,0 +1,57 @@
+import { createHash, createPrivateKey, randomUUID, sign } from 'node:crypto';
+import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX, ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS, requestContextV2ExternalSchema, } from '../server/request-context.js';
+/** What the gateway records of a caller's `User-Agent` (design §(f)): ≤ 512 characters, no control characters. */
+export const OBSERVED_USER_AGENT_MAX_LENGTH = 512;
+/**
+ * The user agent as the context carries it: control characters stripped, then truncated. The
+ * SHA-256 is of the header exactly as sent, so a truncated value still fingerprints the caller.
+ */
+export function observeUserAgent(raw) {
+    const value = raw ?? '';
+    const stripped = value.replace(/[\u0000-\u001f\u007f]/g, '');
+    // Truncate on a code point boundary, never splitting a surrogate pair.
+    let userAgent = '';
+    for (const character of stripped) {
+        if (userAgent.length + character.length > OBSERVED_USER_AGENT_MAX_LENGTH)
+            break;
+        userAgent += character;
+    }
+    return { userAgent, userAgentSha256: createHash('sha256').update(value).digest('hex') };
+}
+/** The namespaced subject an external context and usage carry; ≤ 255 characters or refused at exchange. */
+export function externalSubject({ provider, subject }) {
+    return `ext|${provider}|${subject}`;
+}
+/**
+ * Signs the external (v2) context for one admitted ingress request (design §(f), "Steady state"
+ * step 8), with the gateway's external key, never the browser one. Lifetime ≤ 60 s. Validated
+ * against the strict v2 schema before signing, so the gateway never emits a context the SDK,
+ * sidecar or broker would refuse.
+ */
+export function signExternalGatewayContext({ privateKey, keyId, projectId, environment, release, requestId, method, path, serviceAccountId, pass, passKid, client, now = Math.floor(Date.now() / 1000), ttlSeconds = ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS, }) {
+    if (!keyId.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX))
+        throw new Error('External contexts are signed only with an external- key');
+    const context = requestContextV2ExternalSchema.parse({
+        v: 2, iss: 'atlas-artifact-gateway', aud: `artifact:${projectId}`,
+        sub: externalSubject({ provider: pass.provider, subject: pass.subject }),
+        projectId, environment, mode: release.mode,
+        deploymentId: release.mode === 'published' ? release.deploymentId : null,
+        devSessionId: release.mode === 'development' ? release.devSessionId : null,
+        requestId, jti: randomUUID(), method, path, iat: now, exp: now + ttlSeconds, serviceAccountId,
+        principal: {
+            kind: 'external', ingress: pass.ingress, provider: pass.provider, issuer: pass.issuer, subject: pass.subject,
+            clientId: pass.clientId, email: pass.email, emailVerified: pass.emailVerified, authTime: pass.authTime, amr: pass.amr,
+            tokenIssuedAt: pass.tokenIssuedAt,
+            pass: { id: pass.jti, kid: passKid, issuedAt: pass.iat, exchangeIp: pass.exchangeIp },
+            client,
+        },
+        crit: [], ext: {},
+    });
+    const key = createPrivateKey(privateKey);
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new Error('External context key must be Ed25519');
+    const header = Buffer.from(JSON.stringify({ alg: 'EdDSA', typ: 'JWT', kid: keyId })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify(context)).toString('base64url');
+    const signed = `${header}.${payload}`;
+    return `${signed}.${sign(null, Buffer.from(signed), key).toString('base64url')}`;
+}

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

@@ -0,0 +1,12 @@
+import type { ArtifactTunnelBroker } from '../tunnel/index.js';
+import type { IngressDevelopmentProxy } from './ingress.js';
+/**
+ * The ingress proxy for a development target (design §(j.3) step 3): the admitted request goes
+ * over the development session's tunnel instead of to a hosted deployment, under the hosted
+ * ingress proxy's rules: ingress request sanitising, the route's response policy decided on the
+ * head, the request and response caps, the idle-write timeout and the error-contract writer.
+ * The gateway wires it only when its own APP_ENV is `development`.
+ */
+export declare function createDevelopmentIngressProxy({ broker }: {
+    broker: Pick<ArtifactTunnelBroker, 'handleExternalHttp'>;
+}): IngressDevelopmentProxy;

package/dist/gateway/ingress-development.js

@@ -0,0 +1,23 @@
+import { INGRESS_PROXY_ERROR_CODES, INGRESS_PROXY_LIMITS, writeIngressResponseHead } from './ingress-response.js';
+/**
+ * The ingress proxy for a development target (design §(j.3) step 3): the admitted request goes
+ * over the development session's tunnel instead of to a hosted deployment, under the hosted
+ * ingress proxy's rules: ingress request sanitising, the route's response policy decided on the
+ * head, the request and response caps, the idle-write timeout and the error-contract writer.
+ * The gateway wires it only when its own APP_ENV is `development`.
+ */
+export function createDevelopmentIngressProxy({ broker }) {
+    return ({ request, response, target, publicOrigin, requestContext, body, limits, ingress }) => broker.handleExternalHttp({
+        request, response, requestContext, body, publicOrigin,
+        sessionId: target.sessionId, projectId: target.projectId, environment: target.environment,
+        appHeaders: ingress.requestHeaders,
+        maxRequestBytes: limits.maxRequestBytes,
+        maxResponseBytes: limits.maxResponseBytes,
+        timeoutMs: Math.min(limits.timeoutMs, INGRESS_PROXY_LIMITS.maxTimeoutMs),
+        idleWriteTimeoutMs: ingress.idleWriteTimeoutMs ?? INGRESS_PROXY_LIMITS.idleWriteTimeoutMs,
+        writeHead: ({ status, headers, declaredLength }) => writeIngressResponseHead({
+            response, status, method: request.method ?? 'GET', headers, declaredLength, responses: ingress.responses, maxResponseBytes: limits.maxResponseBytes,
+        }),
+        fail: (status) => ingress.errorWriter({ status, code: INGRESS_PROXY_ERROR_CODES[status] }),
+    });
+}

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

@@ -0,0 +1,44 @@
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { type ArtifactGatewayIngressOptions, type IngressDevelopmentProxy } from './ingress.js';
+import type { GatewayUsageReporter } from './usage.js';
+/**
+ * The ingress request pipeline (design §(e), "Steady state" steps 1-3 and 9). Order matters:
+ * canonical host, edge header, snapshot, client address, canonical path, declared route and
+ * CORS are all local, so nothing unauthenticated reaches Redis or Atlas before `handlers.admit`.
+ */
+export declare function createIngressHandler({ options, runtimeDomain, protocol, isDraining, onError, usage, proxyDevelopment }: {
+    /** Absent: the ingress branch is disabled and every ingress host answers 404. */
+    options: ArtifactGatewayIngressOptions | undefined;
+    runtimeDomain: string;
+    /** `https:` in every deployed environment; `http:` only for a loopback development gateway. */
+    protocol: string;
+    isDraining: () => boolean;
+    /** Counts refusal metrics and failures that are not a decided refusal (the gateway's own onError). */
+    onError?: (event: {
+        kind: string;
+    }) => void;
+    /** Records one observation per proxied ingress request, attributed to the external principal. */
+    usage?: Pick<GatewayUsageReporter, 'record'>;
+    /**
+     * Proxies over a development session's tunnel. Used only when `options.appEnv` is `development`
+     * (design §(j.3) step 3); anywhere else a development target is never proxied.
+     */
+    proxyDevelopment?: IngressDevelopmentProxy;
+}): {
+    handle: (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+    clientError: ({ error, socket }: {
+        error: NodeJS.ErrnoException & {
+            rawPacket?: Buffer;
+        };
+        socket: Duplex;
+    }) => boolean;
+};
+/**
+ * Installs `clientError` on the gateway server: an attributable ingress request gets the ingress
+ * reply, everything else Node's own. Tracks the response in flight on each socket for the check.
+ */
+export declare function handleClientErrors({ server, ingress }: {
+    server: Server;
+    ingress: Pick<ReturnType<typeof createIngressHandler>, 'clientError'>;
+}): void;

package/dist/gateway/ingress-handler.js

@@ -0,0 +1,320 @@
+import { randomUUID } from 'node:crypto';
+import { canonicalizeIngressPath, signedIngressPath } from '../server/ingress-routes.js';
+import { ArtifactAdmissionError } from './admission.js';
+import { proxyHostedArtifact } from './hosted-proxy.js';
+import { BASE_ALLOWED_REQUEST_HEADERS, callerOrigin, corsFor, edgeClientIp, edgeValuesMatch, hasAcceptableAuthorization, hasValidEdgeHeader, hostOrigins, INGRESS_LIMITS, INGRESS_LOGOUT_PATH, INGRESS_TOKEN_PATH, ingressCorsHeaders, IngressError, isIngressHost, requestedHeaders, requestLineHeaders, resolveIngressRoute, writeIngressError, writeIngressRefusal, } from './ingress.js';
+import { INGRESS_RESPONSE_SECURITY_HEADERS } from './ingress-response.js';
+/**
+ * The ingress request pipeline (design §(e), "Steady state" steps 1-3 and 9). Order matters:
+ * canonical host, edge header, snapshot, client address, canonical path, declared route and
+ * CORS are all local, so nothing unauthenticated reaches Redis or Atlas before `handlers.admit`.
+ */
+export function createIngressHandler({ options, runtimeDomain, protocol, isDraining, onError, usage, proxyDevelopment }) {
+    /**
+     * The snapshot entry for a canonical host. A development target outside development is unknown
+     * whether the snapshot is fresh or stale, so a stale one never lends its loopback origins to CORS.
+     */
+    function knownEntry(host) {
+        if (!options)
+            return { state: 'unknown' };
+        const found = options.snapshot.lookup(host);
+        if (found.state !== 'unknown' && found.entry?.target.kind === 'development' && options.appEnv !== 'development')
+            return { state: 'unknown' };
+        return found;
+    }
+    // What `clientError` needs to answer a request timeout on a request already being handled.
+    const inFlight = new WeakMap();
+    function track(request, response) {
+        const socket = request.socket;
+        inFlight.set(socket, { request, response });
+        const forget = () => { if (inFlight.get(socket)?.response === response)
+            inFlight.delete(socket); };
+        response.once('finish', forget);
+        response.once('close', forget);
+    }
+    /** Every check that needs no credential, in the design's order. Throws IngressError. */
+    function checkLocally({ request, response, requestId, cors }) {
+        const host = request.headers.host;
+        // Non-canonical spellings are refused before any lookup.
+        if (!options || host === undefined || !isIngressHost({ rawHost: host, runtimeDomain }))
+            throw new IngressError(404, 'not_found');
+        if (isDraining())
+            throw new IngressError(503, 'temporarily_unavailable');
+        if (!hasValidEdgeHeader({ request, secrets: options.edgeSecrets }))
+            throw new IngressError(404, 'not_found', { audit: { reason: 'edge_header_invalid' }, metric: 'ingress_edge_header_invalid' });
+        cors.edgeVerified = true;
+        const origin = callerOrigin(request);
+        const found = knownEntry(host);
+        if (found.state === 'unknown')
+            throw new IngressError(404, 'not_found');
+        cors.origin = corsFor(origin, hostOrigins(found.entry));
+        if (found.state === 'stale')
+            throw new IngressError(503, 'temporarily_unavailable');
+        const clientIp = edgeClientIp(request);
+        if (clientIp === null)
+            throw new IngressError(400, 'bad_request', { audit: { reason: 'client_ip_invalid' }, metric: 'ingress_client_ip_invalid' });
+        const canonical = canonicalizeIngressPath(request.url ?? '');
+        if (!canonical)
+            throw new IngressError(404, 'not_found');
+        return { request, response, host, publicOrigin: `${protocol}//${host}`, entry: found.entry, clientIp, origin, requestId, canonical, method: request.method ?? 'GET' };
+    }
+    /** Only token and logout exist under /_sequence/ on an ingress host; no session-path endpoint is reachable. */
+    async function sequenceEndpoint(checked) {
+        const { canonical, method, origin, entry, request, response } = checked;
+        const handler = canonical.path === INGRESS_TOKEN_PATH ? options?.handlers?.exchange
+            : canonical.path === INGRESS_LOGOUT_PATH ? options?.handlers?.logout : null;
+        if (handler === null)
+            throw new IngressError(404, 'not_found');
+        const allowed = hostOrigins(entry);
+        if (method === 'OPTIONS') {
+            await options?.handlers?.preflight?.(checked);
+            preflight({ request, response, origin, allowed, methods: ['POST'], headers: BASE_ALLOWED_REQUEST_HEADERS });
+            return;
+        }
+        if (method !== 'POST')
+            throw new IngressError(404, 'not_found');
+        if (origin !== null && !allowed.has(origin))
+            throw forbidden('origin_not_allowed');
+        // The exchange carries the identity provider's token (≤ 8 KiB), logout a pass (≤ 4 KiB); a
+        // repeated header is refused, so no handler ever reads Node's first value of several.
+        const exchange = canonical.path === INGRESS_TOKEN_PATH;
+        const maxBytes = exchange ? INGRESS_LIMITS.maxExchangeAuthorizationBytes : INGRESS_LIMITS.maxApiAuthorizationBytes;
+        if (!hasAcceptableAuthorization({ request, maxBytes }))
+            throw new IngressError(401, 'invalid_token', { metric: exchange ? 'ingress_token_rejected' : 'ingress_pass_rejected' });
+        if (!handler)
+            throw new IngressError(503, 'temporarily_unavailable');
+        await handler(checked);
+    }
+    async function routePreflight(checked) {
+        const { request, response, entry, canonical, origin } = checked;
+        await options?.handlers?.preflight?.(checked);
+        const requested = request.headers['access-control-request-method'];
+        const resolved = typeof requested === 'string' ? resolveIngressRoute({ entry, method: requested, path: canonical.path }) : null;
+        if (!resolved)
+            throw forbidden('preflight_refused');
+        preflight({
+            request, response, origin, allowed: new Set(resolved.ingress.allowedOrigins), methods: resolved.match.route.methods,
+            headers: [...BASE_ALLOWED_REQUEST_HEADERS, ...resolved.ingress.headers],
+        });
+    }
+    async function routeRequest(checked, cors) {
+        const { request, response, entry, canonical, method, origin } = checked;
+        const resolved = resolveIngressRoute({ entry, method, path: canonical.path });
+        if (!resolved)
+            throw new IngressError(404, 'not_found');
+        // From here CORS follows the matched ingress's own origins.
+        cors.origin = corsFor(origin, new Set(resolved.ingress.allowedOrigins));
+        if (origin !== null && cors.origin === null)
+            throw forbidden('origin_not_allowed', resolved.ingress.id);
+        // At most one Authorization header, at most 4 KiB: refused unread, before any Redis or Atlas call.
+        if (!hasAcceptableAuthorization({ request, maxBytes: INGRESS_LIMITS.maxApiAuthorizationBytes }))
+            throw new IngressError(401, 'invalid_token', { metric: 'ingress_pass_rejected' });
+        if (!options?.handlers?.admit)
+            throw new IngressError(503, 'temporarily_unavailable');
+        const admitted = await options.handlers.admit({ ...checked, ingress: resolved.ingress, match: resolved.match, signedPath: signedIngressPath(canonical) });
+        const corsOrigin = cors.origin;
+        if (corsOrigin)
+            for (const [name, value] of Object.entries(ingressCorsHeaders(corsOrigin)))
+                response.setHeader(name, value);
+        observe({ response, admitted, requestId: checked.requestId });
+        admitted.bind?.(response, () => timeOutAdmitted({ response, corsOrigin }));
+        if (response.destroyed)
+            return;
+        await forwardAdmitted({ options, proxyDevelopment, checked, resolved, admitted, corsOrigin });
+    }
+    /** Handles one request on a host `resemblesIngressHost` matched. */
+    async function handle(request, response) {
+        const requestId = randomUUID();
+        response.setHeader('x-request-id', requestId);
+        track(request, response);
+        const cors = { origin: null, edgeVerified: false };
+        try {
+            const checked = checkLocally({ request, response, requestId, cors });
+            if (checked.canonical.path.startsWith('/_sequence/'))
+                await sequenceEndpoint(checked);
+            else if (checked.method === 'OPTIONS')
+                await routePreflight(checked);
+            else
+                await routeRequest(checked, cors);
+        }
+        catch (error) {
+            if (error instanceof ArtifactAdmissionError)
+                onError?.({ kind: 'admission_rejected' });
+            else if (error instanceof IngressError) {
+                if (error.extra.metric)
+                    onError?.({ kind: error.extra.metric });
+            }
+            else
+                onError?.({ kind: 'ingress_request_failed' });
+            recordDenial({ request, error, edgeVerified: cors.edgeVerified });
+            // A refused origin or preflight never carries CORS headers (design §(e)).
+            writeIngressRefusal({ response, error, corsOrigin: error instanceof IngressError && error.code === 'forbidden' ? null : cors.origin });
+        }
+    }
+    /**
+     * Reports a refusal the gateway decided itself to the denial audit, only on a canonical host in
+     * the snapshot: random hostnames never become audit records. The client address is recorded only
+     * when the edge header verified: otherwise `CF-Connecting-IP` is whatever the caller chose.
+     */
+    function recordDenial({ request, error, edgeVerified }) {
+        if (!options?.onDenial || !(error instanceof IngressError) || !error.extra.audit)
+            return;
+        const host = request.headers.host;
+        if (host === undefined || !isIngressHost({ rawHost: host, runtimeDomain }) || knownEntry(host).state === 'unknown')
+            return;
+        const { reason, ingress = null, subjectHash, passId } = error.extra.audit;
+        options.onDenial({
+            ts: Date.now(), host, ingress, reason, status: error.status, clientIp: edgeVerified ? edgeClientIp(request) : null,
+            ...(subjectHash ? { subjectHash } : {}), ...(passId ? { passId } : {}),
+        });
+    }
+    /** One usage observation per proxied request, attributed to the external principal (`ext|…`). */
+    function observe({ response, admitted, requestId }) {
+        const attribution = admitted.usage;
+        if (!usage || !attribution)
+            return;
+        const startedAt = new Date().toISOString(), started = performance.now();
+        let reported = false;
+        const report = () => {
+            if (reported)
+                return;
+            reported = true;
+            usage.record({
+                eventId: `gateway:${requestId}`, requestId, actorId: attribution.actorId, principalKind: 'external', ingressId: attribution.ingressId,
+                projectId: attribution.projectId, environment: attribution.environment,
+                ...('devSessionId' in attribution ? { devSessionId: attribution.devSessionId } : { deploymentId: attribution.deploymentId }),
+                startedAt, endedAt: new Date().toISOString(),
+                measurements: { requestCount: 1, durationMs: Math.max(0, Math.round(performance.now() - started)) },
+                outcome: !response.writableFinished ? 'cancelled' : response.statusCode >= 400 ? 'error' : 'success',
+                httpStatus: response.statusCode,
+            });
+        };
+        response.once('finish', report);
+        response.once('close', report);
+    }
+    /** Preflights are answered locally and never forwarded; a refusal carries no CORS headers. */
+    function preflight({ request, response, origin, allowed, methods, headers }) {
+        const method = request.headers['access-control-request-method'];
+        if (origin === null || !allowed.has(origin) || typeof method !== 'string' || !methods.includes(method) ||
+            !requestedHeaders(request).every((name) => headers.includes(name)))
+            throw forbidden('preflight_refused');
+        response.writeHead(204, {
+            ...INGRESS_RESPONSE_SECURITY_HEADERS,
+            'access-control-allow-origin': origin,
+            'access-control-allow-methods': methods.join(', '),
+            'access-control-allow-headers': headers.join(', '),
+            'access-control-max-age': String(INGRESS_LIMITS.preflightMaxAgeSeconds),
+            vary: 'Origin, Access-Control-Request-Method, Access-Control-Request-Headers',
+        });
+        response.end();
+    }
+    function forbidden(reason, ingress) {
+        return new IngressError(403, 'forbidden', { audit: { reason, ...(ingress ? { ingress } : {}) } });
+    }
+    /** Host, Origin and edge validity of the request a Node-level error belongs to. */
+    function attribute({ socket, rawPacket, secrets }) {
+        const current = inFlight.get(socket);
+        if (current) {
+            const { request, response } = current;
+            return { host: request.headers.host, origin: callerOrigin(request), edge: hasValidEdgeHeader({ request, secrets }), response };
+        }
+        const parsed = requestLineHeaders(rawPacket);
+        return { host: parsed.host, origin: parsed.origin ?? null, edge: edgeValuesMatch({ values: parsed.edge, secrets }), response: undefined };
+    }
+    /**
+     * `clientError` for a canonical ingress host: a CORS-bearing JSON 408 or 431 instead of Node's
+     * bare status line, so the caller can read it. Like every other ingress response it requires the
+     * edge header, so a request that bypassed the zone learns nothing about hosts or origins. Returns
+     * false when the socket is not an ingress request this handler can attribute, so the caller
+     * writes Node's default.
+     */
+    function clientError({ error, socket }) {
+        const status = error.code === 'HPE_HEADER_OVERFLOW' ? 431 : error.code === 'ERR_HTTP_REQUEST_TIMEOUT' ? 408 : undefined;
+        if (!options || status === undefined || !socket.writable)
+            return false;
+        const parsed = attribute({ socket, rawPacket: error.rawPacket, secrets: options.edgeSecrets });
+        if (parsed.host === undefined || !isIngressHost({ rawHost: parsed.host, runtimeDomain }) || !parsed.edge)
+            return false;
+        if (parsed.response?.headersSent) {
+            socket.destroy();
+            return true;
+        }
+        const found = knownEntry(parsed.host);
+        const entry = found.state === 'unknown' ? undefined : found.entry;
+        const cors = corsFor(parsed.origin, hostOrigins(entry));
+        const code = status === 431 ? 'request_header_fields_too_large' : 'request_timeout';
+        const body = JSON.stringify({ error: code });
+        const headers = {
+            ...INGRESS_RESPONSE_SECURITY_HEADERS, 'content-type': 'application/json', 'content-length': String(Buffer.byteLength(body)),
+            connection: 'close', ...(cors ? ingressCorsHeaders(cors) : {}),
+        };
+        const reason = status === 431 ? 'Request Header Fields Too Large' : 'Request Timeout';
+        socket.end(`HTTP/1.1 ${status} ${reason}\r\n${Object.entries(headers).map(([name, value]) => `${name}: ${value}`).join('\r\n')}\r\n\r\n${body}`);
+        return true;
+    }
+    return { handle, clientError };
+}
+/**
+ * The admitted request's budget ran out (the admission timer starts before the proxy's, so it
+ * fires first). Before any response byte the caller gets the error contract's 504, which it can
+ * read; after the head the response is destroyed. Either way the response closes, and both
+ * proxies stop the upstream on close.
+ */
+function timeOutAdmitted({ response, corsOrigin }) {
+    // writeIngressError destroys a response whose head was already sent.
+    writeIngressError({ response, status: 504, code: 'upstream_timeout', corsOrigin });
+}
+/**
+ * Proxies an admitted request under the matched route's limits and response policy: to the
+ * active deployment, or for a development target over its session tunnel. Only a development
+ * gateway does the latter (design §(j.3) step 3); the stage refused it first, and the permit is
+ * already bound, so a refusal here releases it with the response.
+ */
+async function forwardAdmitted({ options, proxyDevelopment, checked, resolved, admitted, corsOrigin }) {
+    const { request, response } = checked;
+    const limits = { maxRequestBytes: resolved.match.route.max_body_bytes, maxResponseBytes: options.maxResponseBytes ?? INGRESS_LIMITS.maxResponseBytes, timeoutMs: admitted.timeoutMs };
+    const ingress = {
+        responses: resolved.match.route.responses,
+        requestHeaders: resolved.ingress.headers,
+        idleWriteTimeoutMs: options.idleWriteTimeoutMs,
+        errorWriter: ({ status, code }) => writeIngressError({ response, status, code, corsOrigin }),
+    };
+    const { target, requestContext, body } = admitted;
+    if (target.kind === 'development') {
+        if (options.appEnv !== 'development' || !proxyDevelopment)
+            throw new IngressError(503, 'temporarily_unavailable');
+        await proxyDevelopment({ request, response, target, publicOrigin: checked.publicOrigin, requestContext, body, limits, ingress });
+        return;
+    }
+    await (options.proxy ?? proxyHostedArtifact)({ request, response, requestContext, body, target: { ...target, publicOrigin: checked.publicOrigin }, limits, ingress });
+}
+/**
+ * Node's own `clientError` replies, kept for every request the ingress handler does not answer.
+ * Like Node, nothing is written once the in-flight response has started.
+ */
+function defaultClientError({ error, socket, inFlight }) {
+    if (socket.writable && !inFlight?.headersSent) {
+        const line = error.code === 'HPE_HEADER_OVERFLOW' ? '431 Request Header Fields Too Large'
+            : error.code === 'HPE_CHUNK_EXTENSIONS_OVERFLOW' ? '413 Payload Too Large'
+                : error.code === 'ERR_HTTP_REQUEST_TIMEOUT' ? '408 Request Timeout' : '400 Bad Request';
+        socket.write(`HTTP/1.1 ${line}\r\nConnection: close\r\n\r\n`);
+    }
+    socket.destroy(error);
+}
+/**
+ * Installs `clientError` on the gateway server: an attributable ingress request gets the ingress
+ * reply, everything else Node's own. Tracks the response in flight on each socket for the check.
+ */
+export function handleClientErrors({ server, ingress }) {
+    const inFlight = new WeakMap();
+    server.on('request', (request, response) => {
+        const socket = request.socket;
+        inFlight.set(socket, response);
+        response.once('finish', () => { if (inFlight.get(socket) === response)
+            inFlight.delete(socket); });
+    });
+    server.on('clientError', (error, socket) => {
+        if (!ingress.clientError({ error, socket }))
+            defaultClientError({ error, socket, inFlight: inFlight.get(socket) });
+    });
+}