@sequenceholdings/artifact-studio 0.6.4 → 0.6.7

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) });
+    });
+}

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

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+/**
+ * The ingress pass (design §(d)): `sqx1.<kid>.<b64url(payload)>.<b64url(mac)>`, minted by the
+ * gateway after Atlas verified an identity provider's token, and verified locally on every API
+ * call with no Redis and no Atlas. Its MAC key is derived from the gateway-only pass keyring with
+ * a salt of its own, so neither the control token (Atlas holds it) nor the session key (it signs
+ * iframe cookies raw) can produce or verify a pass.
+ */
+export declare const INGRESS_PASS_PREFIX = "sqx1";
+export declare const INGRESS_PASS_MAX_BYTES = 2048;
+/** Never `atlas-artifact-next`, the control-token salt Atlas derives with (design §(b.1) item 5). */
+export declare const INGRESS_PASS_HKDF_SALT = "artifact-next-gateway-ingress-pass";
+export declare const INGRESS_PASS_HKDF_INFO = "sqx1";
+/** A pass issued up to this many seconds in the future (gateway replicas' clock skew) still verifies. */
+export declare const INGRESS_PASS_IAT_SKEW_SECONDS = 5;
+export declare const INGRESS_PASS_KEYRING_MAX_KEYS = 3;
+/** At least 32 random bytes, base64-encoded. */
+export declare const INGRESS_PASS_KEY_MIN_LENGTH = 43;
+/** `ARTIFACT_NEXT_INGRESS_PASS_KEYS`: `{"current":"k2","keys":{"k1":"…","k2":"…"}}`. */
+export declare const ingressPassKeyringSchema: z.ZodObject<{
+    current: z.ZodString;
+    keys: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+export type IngressPassKeyring = z.infer<typeof ingressPassKeyringSchema>;
+/** Strict: a pass carrying any other key is refused. */
+export declare const ingressPassPayloadSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    typ: z.ZodLiteral<"artifact-ingress-pass">;
+    env: z.ZodString;
+    origin: z.ZodString;
+    projectId: z.ZodString;
+    ingress: z.ZodString;
+    provider: z.ZodString;
+    bep: z.ZodNumber;
+    issuer: z.ZodString;
+    subject: z.ZodString;
+    clientId: z.ZodString;
+    email: z.ZodString;
+    emailVerified: z.ZodLiteral<true>;
+    authTime: z.ZodNullable<z.ZodNumber>;
+    amr: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    tokenIssuedAt: z.ZodNumber;
+    exchangeIp: z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>;
+    jti: z.ZodUUID;
+    iat: z.ZodNumber;
+    exp: z.ZodNumber;
+}, z.core.$strict>;
+export type IngressPassPayload = z.infer<typeof ingressPassPayloadSchema>;
+/** `K_kid = HKDF-SHA256(keyring[kid], salt, info, 32)`; never the raw keyring value. */
+export declare function derivePassKey(secret: string): Buffer;
+/** A valid payload whose pass would exceed INGRESS_PASS_MAX_BYTES: a refusal, never retryable. */
+export declare class IngressPassTooLargeError extends Error {
+    constructor();
+}
+/** Mints a pass with the keyring's current key. The payload is validated first; `exp` is the caller's. */
+export declare function mintPass({ keyring, payload }: {
+    keyring: IngressPassKeyring;
+    payload: IngressPassPayload;
+}): string;
+export type IngressPassRefusal = 'malformed' | 'unknown_kid' | 'bad_mac' | 'invalid_payload' | 'expired' | 'not_yet_valid' | 'wrong_origin' | 'wrong_environment';
+export type IngressPassVerification = {
+    ok: true;
+    payload: IngressPassPayload;
+    kid: string;
+} | {
+    ok: false;
+    reason: IngressPassRefusal;
+};
+/**
+ * Verifies a pass locally: format and size, a keyring kid, a constant-time MAC, then the strict
+ * payload, `exp > now`, `iat ≤ now + 5`, the minting host's origin and this gateway's APP_ENV.
+ * The payload is parsed only after the MAC holds. Checking the ingress and provider against the
+ * matched route is the caller's.
+ */
+export declare function verifyPass({ keyring, token, now, origin, env }: {
+    keyring: IngressPassKeyring;
+    token: string;
+    /** Epoch seconds. */
+    now: number;
+    /** The public origin of the host the request arrived on. */
+    origin: string;
+    env: string;
+}): IngressPassVerification;

package/dist/gateway/ingress-pass.js

@@ -0,0 +1,143 @@
+import { createHmac, hkdfSync, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+import { artifactNextIngressIdSchema, artifactNextIngressProviderRefSchema } from '../manifest-next-ingress.js';
+import { INGRESS_MAX_PASS_SECONDS } from '../server/ingress-control-contract.js';
+import { artifactExternalPrincipalSchema, artifactIpAddressSchema } from '../server/request-context.js';
+/**
+ * The ingress pass (design §(d)): `sqx1.<kid>.<b64url(payload)>.<b64url(mac)>`, minted by the
+ * gateway after Atlas verified an identity provider's token, and verified locally on every API
+ * call with no Redis and no Atlas. Its MAC key is derived from the gateway-only pass keyring with
+ * a salt of its own, so neither the control token (Atlas holds it) nor the session key (it signs
+ * iframe cookies raw) can produce or verify a pass.
+ */
+export const INGRESS_PASS_PREFIX = 'sqx1';
+export const INGRESS_PASS_MAX_BYTES = 2048;
+/** Never `atlas-artifact-next`, the control-token salt Atlas derives with (design §(b.1) item 5). */
+export const INGRESS_PASS_HKDF_SALT = 'artifact-next-gateway-ingress-pass';
+export const INGRESS_PASS_HKDF_INFO = 'sqx1';
+/** A pass issued up to this many seconds in the future (gateway replicas' clock skew) still verifies. */
+export const INGRESS_PASS_IAT_SKEW_SECONDS = 5;
+export const INGRESS_PASS_KEYRING_MAX_KEYS = 3;
+/** At least 32 random bytes, base64-encoded. */
+export const INGRESS_PASS_KEY_MIN_LENGTH = 43;
+const passKidSchema = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/, 'Expected a pass key id of letters, digits, _ or -');
+const passKeySchema = z.string().min(INGRESS_PASS_KEY_MIN_LENGTH).max(1024);
+/** `ARTIFACT_NEXT_INGRESS_PASS_KEYS`: `{"current":"k2","keys":{"k1":"…","k2":"…"}}`. */
+export const ingressPassKeyringSchema = z.strictObject({
+    current: passKidSchema,
+    keys: z.record(passKidSchema, passKeySchema),
+}).superRefine((keyring, ctx) => {
+    const kids = Object.keys(keyring.keys);
+    if (kids.length < 1 || kids.length > INGRESS_PASS_KEYRING_MAX_KEYS)
+        ctx.addIssue({ code: 'custom', path: ['keys'], message: `Expected 1-${INGRESS_PASS_KEYRING_MAX_KEYS} pass keys` });
+    if (!Object.hasOwn(keyring.keys, keyring.current))
+        ctx.addIssue({ code: 'custom', path: ['current'], message: 'The current pass key id must name a key' });
+});
+const principal = artifactExternalPrincipalSchema.shape;
+const epochSeconds = z.number().int().nonnegative();
+/** Strict: a pass carrying any other key is refused. */
+export const ingressPassPayloadSchema = z.strictObject({
+    v: z.literal(1),
+    typ: z.literal('artifact-ingress-pass'),
+    env: z.string().min(1).max(64),
+    /** The ingress host's public origin; a pass verifies only on the host that minted it. */
+    origin: z.string().min(1).max(300),
+    projectId: z.string().min(1).max(255),
+    ingress: artifactNextIngressIdSchema,
+    provider: artifactNextIngressProviderRefSchema,
+    /** The binding epoch at exchange; informational only. */
+    bep: z.number().int().nonnegative(),
+    issuer: principal.issuer,
+    subject: principal.subject,
+    clientId: principal.clientId,
+    email: principal.email,
+    emailVerified: principal.emailVerified,
+    authTime: principal.authTime,
+    amr: principal.amr,
+    /** The identity provider's `iat`, which Atlas verified; revocation compares it, never the pass `iat`. */
+    tokenIssuedAt: principal.tokenIssuedAt,
+    exchangeIp: artifactIpAddressSchema,
+    jti: z.uuid(),
+    iat: epochSeconds,
+    exp: epochSeconds,
+}).refine((payload) => payload.exp > payload.iat && payload.exp - payload.iat <= INGRESS_MAX_PASS_SECONDS, 'Invalid pass lifetime');
+/** `K_kid = HKDF-SHA256(keyring[kid], salt, info, 32)`; never the raw keyring value. */
+export function derivePassKey(secret) {
+    return Buffer.from(hkdfSync('sha256', Buffer.from(secret, 'utf8'), INGRESS_PASS_HKDF_SALT, INGRESS_PASS_HKDF_INFO, 32));
+}
+function mac({ key, kid, payload }) {
+    return createHmac('sha256', key).update(`${INGRESS_PASS_PREFIX}.${kid}.${payload}`).digest();
+}
+/** Derived keys per keyring, so every verification costs one HMAC and no HKDF. */
+const derivedKeys = new WeakMap();
+function keysOf(keyring) {
+    let keys = derivedKeys.get(keyring);
+    if (!keys) {
+        keys = new Map(Object.entries(keyring.keys).map(([kid, secret]) => [kid, derivePassKey(secret)]));
+        derivedKeys.set(keyring, keys);
+    }
+    return keys;
+}
+/** A valid payload whose pass would exceed INGRESS_PASS_MAX_BYTES: a refusal, never retryable. */
+export class IngressPassTooLargeError extends Error {
+    constructor() {
+        super('Ingress pass exceeds its size limit');
+        this.name = 'IngressPassTooLargeError';
+    }
+}
+/** Mints a pass with the keyring's current key. The payload is validated first; `exp` is the caller's. */
+export function mintPass({ keyring, payload }) {
+    const parsed = ingressPassPayloadSchema.parse(payload);
+    const kid = keyring.current;
+    const key = keysOf(keyring).get(kid);
+    if (!key)
+        throw new Error('The current pass key is missing');
+    const encoded = Buffer.from(JSON.stringify(parsed)).toString('base64url');
+    const token = `${INGRESS_PASS_PREFIX}.${kid}.${encoded}.${mac({ key, kid, payload: encoded }).toString('base64url')}`;
+    if (Buffer.byteLength(token) > INGRESS_PASS_MAX_BYTES)
+        throw new IngressPassTooLargeError();
+    return token;
+}
+const SEGMENT = /^[A-Za-z0-9_-]+$/;
+/**
+ * Verifies a pass locally: format and size, a keyring kid, a constant-time MAC, then the strict
+ * payload, `exp > now`, `iat ≤ now + 5`, the minting host's origin and this gateway's APP_ENV.
+ * The payload is parsed only after the MAC holds. Checking the ingress and provider against the
+ * matched route is the caller's.
+ */
+export function verifyPass({ keyring, token, now, origin, env }) {
+    if (Buffer.byteLength(token) > INGRESS_PASS_MAX_BYTES)
+        return { ok: false, reason: 'malformed' };
+    const parts = token.split('.');
+    if (parts.length !== 4 || parts[0] !== INGRESS_PASS_PREFIX)
+        return { ok: false, reason: 'malformed' };
+    const [, kid, payload, presented] = parts;
+    if (!passKidSchema.safeParse(kid).success || !SEGMENT.test(payload) || !SEGMENT.test(presented))
+        return { ok: false, reason: 'malformed' };
+    const key = keysOf(keyring).get(kid);
+    if (!key)
+        return { ok: false, reason: 'unknown_kid' };
+    const expected = mac({ key, kid, payload });
+    const actual = Buffer.from(presented, 'base64url');
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+        return { ok: false, reason: 'bad_mac' };
+    let decoded;
+    try {
+        decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    }
+    catch {
+        return { ok: false, reason: 'invalid_payload' };
+    }
+    const parsed = ingressPassPayloadSchema.safeParse(decoded);
+    if (!parsed.success)
+        return { ok: false, reason: 'invalid_payload' };
+    if (parsed.data.exp <= now)
+        return { ok: false, reason: 'expired' };
+    if (parsed.data.iat > now + INGRESS_PASS_IAT_SKEW_SECONDS)
+        return { ok: false, reason: 'not_yet_valid' };
+    if (parsed.data.origin !== origin)
+        return { ok: false, reason: 'wrong_origin' };
+    if (parsed.data.env !== env)
+        return { ok: false, reason: 'wrong_environment' };
+    return { ok: true, payload: parsed.data, kid };
+}

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

@@ -0,0 +1,74 @@
+import type { ServerResponse } from 'node:http';
+/**
+ * Response policy for an external ingress (design §(e) "Response policy"). An ingress answers a
+ * cross-origin caller that is not an Atlas user, so nothing it returns may become a document, a
+ * redirect, a stream, a cookie or a cache entry: the only output is data of a type the route
+ * declared. The decision is taken on the status line and headers, before any body byte is sent.
+ */
+/**
+ * Set on every ingress response, the gateway's own errors included. The shared-cache refusal is
+ * the one every protected session response carries, so no zone cache rule can hold borrower data.
+ */
+export declare const INGRESS_RESPONSE_SECURITY_HEADERS: Readonly<Record<string, string>>;
+export type IngressResponseRefusal = 'redirect' | 'event_stream' | 'content_type' | 'missing_content_type';
+export type IngressResponseDecision = {
+    allowed: true;
+    headers: Record<string, string | string[]>;
+} | {
+    allowed: false;
+    reason: IngressResponseRefusal;
+};
+/**
+ * The upstream's declared body length, read from the raw head: the shared sanitising removes
+ * `content-length` as a hop header, so the policy must be handed it explicitly. The same parser
+ * the development tunnel uses, so hosted and development ingress judge a head alike.
+ */
+export { declaredLength as declaredContentLength } from '../tunnel/external.js';
+/**
+ * Decides an upstream response on an ingress route. `headers` are the app's headers after the
+ * shared private-header sanitising (no `content-length`); `declaredLength` is the upstream's own
+ * `Content-Length`; `responses` are the matched route's declared content types.
+ */
+export declare function applyIngressResponsePolicy({ status, method, headers, declaredLength, responses }: {
+    status: number;
+    method: string;
+    headers: Readonly<Record<string, string | string[]>>;
+    declaredLength: number | null;
+    responses: readonly string[];
+}): IngressResponseDecision;
+/**
+ * Applies the policy to an upstream head and writes the allowed status and headers onto the
+ * gateway response. False when the response is refused (502 before any body byte), including a
+ * declared length above the ingress response cap.
+ */
+export declare function writeIngressResponseHead({ response, status, method, headers, declaredLength, responses, maxResponseBytes }: {
+    response: ServerResponse;
+    status: number;
+    method: string;
+    headers: Readonly<Record<string, string | string[]>>;
+    declaredLength: number | null;
+    responses: readonly string[];
+    maxResponseBytes: number;
+}): boolean;
+/** An ingress caller gets a deterministic 504 before its 60 s context expires (design §(e) "Limits"). */
+export declare const INGRESS_PROXY_LIMITS: Readonly<{
+    maxTimeoutMs: 55000;
+    idleWriteTimeoutMs: 10000;
+}>;
+export type IngressProxyErrorStatus = 400 | 413 | 502 | 503 | 504;
+/** Error contract codes (design §(i)) for the failures the proxy itself decides. */
+export declare const INGRESS_PROXY_ERROR_CODES: Readonly<Record<IngressProxyErrorStatus, string>>;
+/** External ingress mode (design §(e)): cross-origin data only, under the matched route's policy. */
+export interface HostedArtifactIngressMode {
+    /** The matched route's declared response content types. */
+    responses: readonly string[];
+    /** The matched ingress's declared request headers, forwarded on top of the fixed allowlist. */
+    requestHeaders: readonly string[];
+    /** Writes the gateway's error-contract JSON with the caller's CORS headers. */
+    errorWriter: (input: {
+        status: IngressProxyErrorStatus;
+        code: string;
+    }) => void;
+    /** Destroys a response whose writes stay blocked this long (default INGRESS_PROXY_LIMITS.idleWriteTimeoutMs). */
+    idleWriteTimeoutMs?: number;
+}