@sequenceholdings/artifact-studio 0.6.4 → 0.6.7

package/dist/gateway/ingress.js

@@ -0,0 +1,204 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { BlockList } from 'node:net';
+import { matchIngressRoute } from '../server/ingress-routes.js';
+import { artifactIpAddressSchema } from '../server/request-context.js';
+import { ArtifactAdmissionError } from './admission.js';
+import { INGRESS_RESPONSE_SECURITY_HEADERS } from './ingress-response.js';
+/**
+ * The external ingress branch of the gateway (design §(e)): the front door for callers that are
+ * not Atlas users, on hosts `ingress-<24 hex>.<runtime domain>`. It shares nothing with the
+ * iframe session path: no bootstrap, no session cookie, no `authorize()`, and no 401/404→403 remap.
+ * Every check before authentication is local: canonical host, edge header, snapshot lookup,
+ * client address, canonical path, declared route and CORS. The pass, admission and grant
+ * (`handlers.admit`) come after them, so nothing unauthenticated reaches Redis or Atlas.
+ */
+export const INGRESS_TOKEN_PATH = '/_sequence/ingress/token';
+export const INGRESS_LOGOUT_PATH = '/_sequence/ingress/logout';
+export const INGRESS_LIMITS = Object.freeze({
+    /** A pass is at most 2 KiB; an API (and logout) `Authorization` header above this is refused unread. */
+    maxApiAuthorizationBytes: 4 * 1024,
+    /** The exchange carries the identity provider's token, which may be larger than a pass. */
+    maxExchangeAuthorizationBytes: 8 * 1024,
+    maxResponseBytes: 32 * 1024 * 1024,
+    preflightMaxAgeSeconds: 600,
+});
+export const INGRESS_EXPOSED_HEADERS = 'retry-after, x-request-id, www-authenticate, content-disposition';
+export const BASE_ALLOWED_REQUEST_HEADERS = ['authorization', 'content-type'];
+/** Thrown by an ingress handler; written through the ingress writer, never the session remap. */
+export class IngressError extends Error {
+    status;
+    code;
+    extra;
+    constructor(status, code, extra = {}) {
+        super(`Ingress request refused: ${code}`);
+        this.status = status;
+        this.code = code;
+        this.extra = extra;
+        this.name = 'IngressError';
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Every ingress host's first label starts with this. */
+export const INGRESS_HOST_PREFIX = 'ingress-';
+/** The raw `Host` exactly as an ingress host must arrive: lowercase, no port, no trailing dot. */
+export function isIngressHost({ rawHost, runtimeDomain }) {
+    return rawHost !== undefined && new RegExp(`^ingress-[a-f0-9]{24}\\.${escapeRegExp(runtimeDomain)}$`).test(rawHost);
+}
+/**
+ * Every host the ingress branch owns: any spelling (any case, a port, a trailing dot) of any
+ * `ingress-*` name under the runtime domain, canonical or not. Edge allowlists exempt `ingress-*`
+ * hosts, so a non-canonical one (`ingress-x.<domain>`, `ingress-<24 hex>.foo.<domain>`) must get the
+ * ingress branch's local 404 and never fall into the iframe path: session ticket exchange,
+ * bootstrap, authorize and WebSocket upgrades. No application or preview host starts `ingress-`.
+ */
+export function resemblesIngressHost({ rawHost, runtimeDomain }) {
+    if (rawHost === undefined)
+        return false;
+    const hostname = rawHost.toLowerCase().replace(/:[0-9]*$/, '').replace(/\.$/, '');
+    return hostname.startsWith(INGRESS_HOST_PREFIX) && hostname.endsWith(`.${runtimeDomain}`);
+}
+/** Every value of a header as sent, so a repeated header is seen (Node keeps only the first of some). */
+export function rawHeaderValues(request, name) {
+    const values = [];
+    for (let index = 0; index + 1 < request.rawHeaders.length; index += 2) {
+        if (request.rawHeaders[index].toLowerCase() === name)
+            values.push(request.rawHeaders[index + 1]);
+    }
+    return values;
+}
+/**
+ * At least this many characters. Shorter configured secrets are ignored, so a misconfigured empty
+ * value (`current,` split on commas) can never match an empty header and open the edge check.
+ */
+export const MIN_EDGE_SECRET_LENGTH = 32;
+/** Every `Authorization` value at most `maxBytes`, and at most one of them: none is ever picked. */
+export function hasAcceptableAuthorization({ request, maxBytes }) {
+    const values = rawHeaderValues(request, 'authorization');
+    return values.length <= 1 && values.every((value) => Buffer.byteLength(value) <= maxBytes);
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest();
+}
+/** The presented `x-sequence-edge` values match: exactly one, equal in constant time to a usable secret. */
+export function edgeValuesMatch({ values, secrets }) {
+    // Only a usable secret can match, so the presented value is at least as long too.
+    const usable = secrets.filter((secret) => secret.length >= MIN_EDGE_SECRET_LENGTH);
+    if (values.length !== 1)
+        return false;
+    const presented = digest(values[0]);
+    let matched = false;
+    // Every secret is compared, so timing does not reveal which one matched.
+    for (const secret of usable)
+        matched = timingSafeEqual(presented, digest(secret)) || matched;
+    return matched;
+}
+/**
+ * Exactly one `x-sequence-edge`, equal in constant time to one of the configured secrets (current
+ * and next). Only our Cloudflare zone's transform rule injects it, so a request that reached the
+ * gateway another way, or through another Cloudflare zone, is refused (threat T17).
+ */
+export function hasValidEdgeHeader({ request, secrets }) {
+    return edgeValuesMatch({ values: rawHeaderValues(request, 'x-sequence-edge'), secrets });
+}
+// Cloudflare's Pseudo IPv4 range: an address Cloudflare invents for an IPv6 client, never a real one.
+const PSEUDO_IPV4 = new BlockList();
+PSEUDO_IPV4.addSubnet('240.0.0.0', 4, 'ipv4');
+PSEUDO_IPV4.addSubnet('::ffff:f000:0', 100, 'ipv6');
+/**
+ * The client address: exactly one `CF-Connecting-IP` that parses and is not a Pseudo IPv4
+ * address, else null (400). Never X-Forwarded-For or the socket address.
+ */
+export function edgeClientIp(request) {
+    const values = rawHeaderValues(request, 'cf-connecting-ip');
+    if (values.length !== 1)
+        return null;
+    const value = values[0];
+    if (!artifactIpAddressSchema.safeParse(value).success)
+        return null;
+    const family = value.includes(':') ? 'ipv6' : 'ipv4';
+    return PSEUDO_IPV4.check(value, family) ? null : value;
+}
+/** Exactly one ingress on the host may declare the matched (method, path); ambiguity is no match. */
+export function resolveIngressRoute({ entry, method, path }) {
+    let found = null;
+    for (const ingress of entry.ingresses) {
+        const match = matchIngressRoute(ingress.routes, method, path);
+        if (!match)
+            continue;
+        if (found)
+            return null;
+        found = { ingress, match };
+    }
+    return found;
+}
+/** The caller's `Origin`, or null when absent. Several `Origin` headers never match an allowed origin. */
+export function callerOrigin(request) {
+    const values = rawHeaderValues(request, 'origin');
+    if (values.length === 0)
+        return null;
+    return values.length === 1 ? values[0] : '';
+}
+export function ingressCorsHeaders(origin) {
+    return { 'access-control-allow-origin': origin, 'access-control-expose-headers': INGRESS_EXPOSED_HEADERS, vary: 'Origin' };
+}
+/**
+ * Writes a gateway-decided ingress response: the error contract body, `no-store`, the response
+ * security headers, and CORS when the caller's origin is allowed, so the page can read the error.
+ */
+export function writeIngressError({ response, status, code, corsOrigin, retryAfterSeconds, wwwAuthenticate }) {
+    if (response.headersSent) {
+        response.destroy();
+        return;
+    }
+    for (const name of response.getHeaderNames())
+        if (name !== 'x-request-id')
+            response.removeHeader(name);
+    const authenticate = wwwAuthenticate ?? (code === 'invalid_token' ? 'Bearer error="invalid_token"' : undefined);
+    const retryAfter = retryAfterSeconds ?? (status === 503 ? 2 : undefined);
+    response.writeHead(status, {
+        ...INGRESS_RESPONSE_SECURITY_HEADERS,
+        'content-type': 'application/json',
+        connection: 'close',
+        ...(corsOrigin ? ingressCorsHeaders(corsOrigin) : {}),
+        ...(authenticate ? { 'www-authenticate': authenticate } : {}),
+        ...(retryAfter !== undefined ? { 'retry-after': String(retryAfter) } : {}),
+    });
+    response.end(JSON.stringify({ error: code }));
+}
+/** The union of a host's allowed origins: CORS for errors decided before a route is known. */
+export function hostOrigins(entry) {
+    return new Set(entry?.ingresses.flatMap((ingress) => ingress.allowedOrigins) ?? []);
+}
+export function corsFor(origin, allowed) {
+    return origin !== null && allowed.has(origin) ? origin : null;
+}
+export function requestedHeaders(request) {
+    const value = request.headers['access-control-request-headers'];
+    if (typeof value !== 'string')
+        return [];
+    return value.split(',').map((name) => name.trim().toLowerCase()).filter(Boolean);
+}
+/** Host, Origin and edge values from the bytes Node had buffered when the header block overflowed. */
+export function requestLineHeaders(raw) {
+    if (!raw)
+        return { edge: [] };
+    const lines = raw.subarray(0, 64 * 1024).toString('latin1').split('\r\n');
+    const values = (name) => lines.filter((line) => line.toLowerCase().startsWith(`${name}:`)).map((line) => line.slice(name.length + 1).trim());
+    const hosts = values('host'), origins = values('origin');
+    return { host: hosts.length === 1 ? hosts[0] : undefined, origin: origins.length === 1 ? origins[0] : null, edge: values('x-sequence-edge') };
+}
+export function writeIngressRefusal({ response, error, corsOrigin }) {
+    if (error instanceof IngressError) {
+        writeIngressError({ response, status: error.status, code: error.code, corsOrigin, ...error.extra });
+    }
+    else if (error instanceof ArtifactAdmissionError) {
+        const status = error.status === 429 ? 429 : 503;
+        writeIngressError({ response, status, code: status === 429 ? 'rate_limited' : 'temporarily_unavailable', corsOrigin, retryAfterSeconds: error.retryAfterSeconds });
+    }
+    else {
+        // An unexpected failure is an outage the caller may retry with its idempotency key.
+        writeIngressError({ response, status: 503, code: 'temporarily_unavailable', corsOrigin });
+    }
+}

package/dist/gateway/lattice-invoke.js

@@ -109,6 +109,8 @@ async function invokeAdmittedLattice(input) {
         });
         const result = await (input.invoke ?? invokeHostedArtifact)({
             upstreamUrl: input.grant.upstreamUrl,
+            runtimeTransport: input.grant.runtimeTransport,
+            environment: input.grant.environment,
             ...(input.grant.upstreamAudience ? { upstreamAudience: input.grant.upstreamAudience } : {}),
             path: input.grant.path,
             body: input.parsed.body ?? {},

package/dist/gateway/lattice-upstream.d.ts

@@ -1,7 +1,6 @@
 import { request as httpsRequest } from 'node:https';
-export interface HostedArtifactInvocation {
-    upstreamUrl: string;
-    upstreamAudience?: string;
+import { type HostedRuntimeTarget } from './hosted-proxy.js';
+export interface HostedArtifactInvocation extends HostedRuntimeTarget {
     path: string;
     body: unknown;
     requestContext: string;
@@ -30,7 +29,7 @@ export interface HostedArtifactInvocation {
 }
 /**
  * Buffered POST into a hosted Next.js app. The destination must already be a
- * Cloud Run origin Atlas resolved; this rejects anything else before dialing.
+ * admitted runtime origin Atlas resolved; this rejects anything else before dialing.
  */
 export declare function invokeHostedArtifact(input: HostedArtifactInvocation): Promise<{
     status: number;

package/dist/gateway/lattice-upstream.js

@@ -1,34 +1,36 @@
 import { request as httpsRequest } from 'node:https';
+import { request as httpRequest } from 'node:http';
 import { assertSafeRequest } from '../tunnel/protocol.js';
 import { isManagedServerInvokePath } from '../server/managed-server-path.js';
-import { HOSTED_ARTIFACT_PROXY_LIMITS, cloudRunOrigin, hostedIdentityToken } from './hosted-proxy.js';
+import { HOSTED_ARTIFACT_PROXY_LIMITS, resolveHostedTarget, hostedIdentityToken } from './hosted-proxy.js';
 const BODY_CAP = 1024 * 1024;
 /**
  * Buffered POST into a hosted Next.js app. The destination must already be a
- * Cloud Run origin Atlas resolved; this rejects anything else before dialing.
+ * admitted runtime origin Atlas resolved; this rejects anything else before dialing.
  */
 export async function invokeHostedArtifact(input) {
     if (!isManagedServerInvokePath(input.path))
         throw new Error('Invalid managed server path');
-    const upstream = cloudRunOrigin(input.upstreamUrl);
-    const audience = input.upstreamAudience === undefined ? upstream : cloudRunOrigin(input.upstreamAudience);
+    const { upstream, audience } = resolveHostedTarget({ target: input });
     assertSafeRequest('POST', input.path);
     const payload = Buffer.from(JSON.stringify(input.body ?? {}));
     if (payload.byteLength > BODY_CAP)
         throw new Error('Managed server body exceeds 1 MiB');
     const timeoutMs = Math.min(Math.max(input.timeoutMs, 1), HOSTED_ARTIFACT_PROXY_LIMITS.maxTimeoutMs);
     const signal = invocationSignal({ timeoutMs, signal: input.signal });
-    const token = await withSignal((input.identityTokenProvider ?? hostedIdentityToken)({ audience: audience.origin, signal }), signal);
-    if (!/^[A-Za-z0-9._~-]+$/.test(token) || token.length > 16384)
-        throw new Error('Invalid platform token');
     const headers = {
         host: upstream.host,
         'content-type': 'application/json',
         'content-length': String(payload.byteLength),
         'accept-encoding': 'identity',
-        'x-serverless-authorization': `Bearer ${token}`,
         'x-sequence-artifact-context': input.requestContext,
     };
+    if (audience) {
+        const token = await withSignal((input.identityTokenProvider ?? hostedIdentityToken)({ audience: audience.origin, signal }), signal);
+        if (!/^[A-Za-z0-9._~-]+$/.test(token) || token.length > 16384)
+            throw new Error('Invalid platform token');
+        headers['x-serverless-authorization'] = `Bearer ${token}`;
+    }
     const hop = { origin: upstream, path: input.path, headers, body: payload, timeoutMs, signal };
     const response = await withSignal(input.dispatch ? input.dispatch(hop) : postCloudRun({ ...hop, dial: input.dial }), signal);
     if (response.body.byteLength > BODY_CAP)
@@ -100,7 +102,7 @@ function postCloudRun(input) {
             stop();
             resolve(value);
         };
-        const request = (input.dial ?? httpsRequest)(input.origin, {
+        const request = (input.dial ?? (input.origin.protocol === 'http:' ? httpRequest : httpsRequest))(input.origin, {
             method: 'POST',
             path: input.path,
             headers: input.headers,

package/dist/gateway/runtime-transport.d.ts

@@ -0,0 +1,17 @@
+export interface HostedRuntimeTarget {
+    upstreamUrl: string;
+    /** Canonical service audience, used only for the Cloud Run transport. */
+    upstreamAudience?: string;
+    /** Missing on older control-plane records; these remain Cloud Run targets. */
+    runtimeTransport?: 'cloud-run' | 'local-docker';
+    environment?: string;
+}
+export declare function cloudRunOrigin(value: string): URL;
+/** Local deployments retain hosted authorization and signed contexts; only their private hop differs. */
+export declare function resolveHostedTarget({ target, environment }: {
+    target: HostedRuntimeTarget;
+    environment?: NodeJS.ProcessEnv;
+}): {
+    upstream: URL;
+    audience: URL | undefined;
+};

package/dist/gateway/runtime-transport.js

@@ -0,0 +1,26 @@
+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;
+}
+/** Local deployments retain hosted authorization and signed contexts; only their private hop differs. */
+export function resolveHostedTarget({ target, environment = process.env }) {
+    if (target.runtimeTransport === undefined || target.runtimeTransport === 'cloud-run') {
+        const upstream = cloudRunOrigin(target.upstreamUrl);
+        return { upstream, audience: target.upstreamAudience === undefined ? upstream : cloudRunOrigin(target.upstreamAudience) };
+    }
+    if (target.runtimeTransport !== 'local-docker' || environment.ARTIFACT_NEXT_RUNTIME_PROVIDER !== 'local-docker' ||
+        environment.APP_ENV !== 'development' || target.environment !== 'development' || environment.K_SERVICE || environment.VERCEL ||
+        !/^dev-[A-Za-z0-9_-]+$/.test(environment.LAKEBASE_BRANCH ?? '') || environment.LAKEBASE_BRANCH === 'dev-cloud-agents' ||
+        target.upstreamAudience !== undefined)
+        throw new Error('Invalid local deployment transport');
+    // Validate the original spelling: URL normalization otherwise admits integer/hex IPs and aliases.
+    const match = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{3,4})$/.exec(target.upstreamUrl);
+    const port = Number(match?.[1]);
+    if (!match || port < 1024 || port > 65535)
+        throw new Error('Invalid local deployment origin');
+    return { upstream: new URL(target.upstreamUrl), audience: undefined };
+}

package/dist/gateway/server.d.ts

@@ -4,6 +4,7 @@ import { ArtifactGatewayControl } from './control.js';
 import { type GatewaySessionSameSite } from './session.js';
 import { type ArtifactRequestAdmission } from './admission.js';
 import { type GatewayControlAdmission } from './control-admission.js';
+import { type ArtifactGatewayIngressOptions } from './ingress.js';
 export interface ArtifactGatewayOptions {
     control: ArtifactGatewayControl;
     runtimeDomain: string;
@@ -25,6 +26,8 @@ export interface ArtifactGatewayOptions {
     /** Rate limits `/_sequence/session` and `/_sequence/tunnel` before they reach Atlas. Without it
      * both endpoints fail closed. */
     controlAdmission?: Pick<GatewayControlAdmission, 'admit'>;
+    /** External ingress front door (design §(e)). Absent: every `ingress-*` host answers 404. */
+    ingress?: ArtifactGatewayIngressOptions;
     /** Reuse of a positive Atlas authorization (default GATEWAY_AUTHORIZATION_TTL_MS; 0 disables). */
     authorizationCacheTtlMs?: number;
     onError?: (event: {

package/dist/gateway/server.js

@@ -13,6 +13,9 @@ import { gatewayClientAddress } from './control-admission.js';
 import { gatewayAuthorizationKey, PositiveDecisionCache, tunnelAuthorizationKey } from './authorization-cache.js';
 import { GatewayUsageReporter } from './usage.js';
 import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+import { createDevelopmentIngressProxy } from './ingress-development.js';
+import { createIngressHandler, handleClientErrors } from './ingress-handler.js';
+import { resemblesIngressHost } from './ingress.js';
 function json(response, status, error) {
     if (response.headersSent) {
         response.destroy();
@@ -115,6 +118,7 @@ export function createArtifactGateway(options) {
     const tunnelAuthorizations = new PositiveDecisionCache({ ttlMs: options.authorizationCacheTtlMs });
     const usage = new GatewayUsageReporter({ send: events => options.control.usage(events), onFailure: failure => options.onError?.(failure) });
     let draining = false;
+    const isIngressRequest = (request) => resemblesIngressHost({ rawHost: header(request, 'host'), runtimeDomain: options.runtimeDomain });
     /** Admission for the unauthenticated endpoints; the release frees the in-flight permit. */
     async function admitControlCall(endpoint, request) {
         if (!options.controlAdmission)
@@ -254,7 +258,16 @@ export function createArtifactGateway(options) {
         onTunnelClosed: lease => { if (leases.get(lease.sessionId)?.lease.epoch === lease.epoch)
             leases.delete(lease.sessionId); },
     });
+    // A development target is proxied over its session tunnel only by a development gateway (design §(j.3) step 3).
+    const proxyDevelopment = options.ingress?.appEnv === 'development' ? createDevelopmentIngressProxy({ broker }) : undefined;
+    const ingress = createIngressHandler({ options: options.ingress, runtimeDomain: options.runtimeDomain, protocol: new URL(gatewayOrigin).protocol, isDraining: () => draining, onError: options.onError, usage, proxyDevelopment });
     const server = createServer({ maxHeaderSize: 32 * 1024, requestTimeout: 60_000, headersTimeout: 15_000 }, (request, response) => {
+        // Before readiness, bootstrap and requestOrigin(): an ingress host, canonical or not, never
+        // reaches a session-path handler or the 401/404→403 remap below (design §(e) "Branch placement").
+        if (isIngressRequest(request)) {
+            void ingress.handle(request, response);
+            return;
+        }
         const startedAt = new Date().toISOString(), started = performance.now();
         void (async () => {
             if (isReadinessRequest({ request, gatewayOrigin, runtimeDomain: options.runtimeDomain })) {
@@ -350,6 +363,11 @@ export function createArtifactGateway(options) {
                 rejectUpgrade(socket, 503);
                 return;
             }
+            // An ingress answers data requests only: no WebSocket, no tunnel.
+            if (isIngressRequest(request)) {
+                rejectUpgrade(socket, 404);
+                return;
+            }
             if (request.url === '/_sequence/tunnel') {
                 await broker.handleTunnelUpgrade(request, socket, head);
                 return;
@@ -362,6 +380,9 @@ export function createArtifactGateway(options) {
             await broker.handleWebSocketUpgrade(request, socket, head, authorized.target.sessionId);
         })().catch(() => rejectUpgrade(socket));
     });
+    // Only with the ingress branch configured: without it, Node's own clientError replies stay untouched.
+    if (options.ingress)
+        handleClientErrors({ server, ingress });
     return {
         server,
         /** Observations recorded but not yet confirmed by Atlas: what a forced exit would lose. */

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

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Response-header rules for the iframe session path of the hosted proxy (an ingress uses `ingress-response.ts`). */
+export declare function rewriteLocation({ location, upstream, publicOrigin }: {
+    location: string;
+    upstream: URL;
+    publicOrigin: string;
+}): string;
+export declare function mergeFramePolicy({ application, trusted }: {
+    application: string | string[];
+    trusted: string | string[];
+}): string[];
+export declare function enforceBrowserCachePolicy({ request, response }: {
+    request: IncomingMessage;
+    response: ServerResponse;
+}): void;

package/dist/gateway/session-response.js

@@ -0,0 +1,40 @@
+import { isSharedCacheDirective, SHARED_CACHE_REFUSAL } from '../tunnel/protocol.js';
+/** Response-header rules for the iframe session path of the hosted proxy (an ingress uses `ingress-response.ts`). */
+export 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;
+}
+export 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];
+}
+export 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);
+}

package/dist/gateway/usage.d.ts

@@ -1,8 +1,15 @@
 export interface GatewayUsageEvent {
     eventId: string;
     requestId: string;
-    /** The user the gateway acted for: the session owner Atlas authorized for this request. */
+    /**
+     * Who the gateway acted for: the session owner Atlas authorized for this request, or for an
+     * external ingress request the namespaced external subject (`ext|<provider>|<subject>`).
+     */
     actorId: string;
+    /** Present only for an external ingress request. */
+    principalKind?: 'external';
+    /** The ingress an external request arrived through. */
+    ingressId?: string;
     projectId: string;
     deploymentId?: string;
     devSessionId?: string;

package/dist/gateway-main.js

@@ -7,6 +7,7 @@ import { gatewaySessionSameSite } from './gateway/session.js';
 import { RedisTunnelOwnership, RedisTunnelRelay } from './tunnel/redis.js';
 import { ArtifactRequestAdmission } from './gateway/admission.js';
 import { GatewayControlAdmission } from './gateway/control-admission.js';
+import { createIngressRuntime, IngressSecretsError } from './gateway/ingress-runtime.js';
 function required(name) {
     const value = process.env[name];
     if (!value)
@@ -40,6 +41,8 @@ async function main() {
     // A flood of refused requests or forged frames must not become a log flood: count and report every 10 s.
     const refusals = new Map();
     const refuse = (kind) => { refusals.set(kind, (refusals.get(kind) ?? 0) + 1); };
+    // Kinds a caller can produce at request rate: counted, never logged one by one.
+    const counted = new Set(['admission_rejected', 'ingress_pass_rejected', 'ingress_token_rejected', 'ingress_edge_header_invalid', 'ingress_client_ip_invalid']);
     setInterval(() => {
         for (const [kind, count] of refusals)
             log({ event: 'artifact_gateway.request', kind, count });
@@ -56,26 +59,43 @@ async function main() {
     subscriber.on('ready', () => { if (!stopping)
         void relay.start().catch(() => undefined); });
     const controlUrl = required('ARTIFACT_NEXT_CONTROL_PLANE_URL');
+    const controlToken = required('ARTIFACT_NEXT_CONTROL_TOKEN');
+    const control = new ArtifactGatewayControl({ url: controlUrl, token: controlToken });
+    const contextPrivateKey = required('ARTIFACT_NEXT_CONTEXT_PRIVATE_KEY');
+    const contextKeyId = required('ARTIFACT_NEXT_CONTEXT_KEY_ID');
+    const admission = new ArtifactRequestAdmission({ redis: command, namespace });
+    // The external ingress branch: off (every ingress host 404) unless all four of its secrets are
+    // set; the process refuses to boot when they are set but unusable or not independent.
+    const ingress = createIngressRuntime({
+        env: process.env, control, controlToken, sessionKey, contextPrivateKey, contextKeyId, redis: command, namespace, admission, log,
+        onFailure: failure => { if ('count' in failure)
+            log({ event: 'artifact_gateway.request', ...failure });
+        else
+            refuse(failure.kind); },
+    });
     const gateway = createArtifactGateway({
-        control: new ArtifactGatewayControl({ url: controlUrl, token: required('ARTIFACT_NEXT_CONTROL_TOKEN') }),
+        control,
         runtimeDomain: required('ARTIFACT_NEXT_RUNTIME_DOMAIN'),
         parentOrigin: process.env.ARTIFACT_NEXT_PARENT_ORIGIN ?? new URL(controlUrl).origin,
         gatewayOrigin: required('ARTIFACT_NEXT_GATEWAY_URL'),
         sessionKey,
         sessionCookieSameSite: gatewaySessionSameSite({ value: process.env.ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE, appEnv: namespace }),
-        contextPrivateKey: required('ARTIFACT_NEXT_CONTEXT_PRIVATE_KEY'),
-        contextKeyId: required('ARTIFACT_NEXT_CONTEXT_KEY_ID'),
+        contextPrivateKey,
+        contextKeyId,
         nodeId, routing: ownership, relay,
-        admission: new ArtifactRequestAdmission({ redis: command, namespace }),
+        admission,
+        ingress: ingress.ingress,
         controlAdmission: new GatewayControlAdmission({ redis: command, namespace }),
         resolveLease: sessionId => ownership.resolveLease(sessionId),
         renewLease: lease => ownership.renew(lease, nodeId),
         ready: () => clients.every(client => client.status === 'ready') && relay.isReady(),
-        onError: event => { if (event.kind === 'admission_rejected')
+        onError: event => { if (counted.has(event.kind))
             refuse(event.kind);
         else
             log({ event: 'artifact_gateway.request', ...event }); },
     });
+    // The first snapshot pull starts before traffic; until it lands, ingress hosts answer 503.
+    ingress.start();
     const port = Number(process.env.PORT ?? '8080');
     if (!Number.isSafeInteger(port) || port < 1 || port > 65535)
         throw new Error('Invalid gateway PORT');
@@ -102,7 +122,8 @@ async function main() {
         }, 9_000);
         deadline.unref();
         await gateway.drain();
-        await relay.close();
+        // Audit delivery runs beside tunnel cleanup, never in front of it.
+        await Promise.allSettled([ingress.close(), relay.close()]);
         for (const client of clients)
             client.disconnect();
         clearTimeout(deadline);
@@ -110,7 +131,10 @@ async function main() {
     process.once('SIGTERM', () => { void stop(); });
     process.once('SIGINT', () => { void stop(); });
 }
-void main().catch(() => {
-    process.stderr.write(`${JSON.stringify({ event: 'artifact_gateway.start_failed' })}\n`);
+void main().catch((error) => {
+    // Only an ingress-secrets refusal is described: its message names variables, never values, by
+    // construction. Other errors (Redis, URLs) may carry connection strings.
+    const reason = error instanceof IngressSecretsError ? error.message : undefined;
+    process.stderr.write(`${JSON.stringify({ event: 'artifact_gateway.start_failed', ...(reason ? { reason } : {}) })}\n`);
     process.exit(1);
 });

package/dist/manifest-next-browser-data.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { type ArtifactStudioCustomRoles } from './manifest-custom-roles.js';
+/** Additional browser admission rules; neither these rules nor data reach grant access. */
+export declare const artifactNextBrowserDataSchema: z.ZodPrefault<z.ZodObject<{
+    operations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    required_capabilities: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
+    read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>>;
+export type ArtifactNextBrowserData = z.infer<typeof artifactNextBrowserDataSchema>;
+/** Restriction references must be backed by this browser's reach and declared artifact pins. */
+export declare function validateBrowserDataAdmission({ data, uses, roles, ctx }: {
+    data: ArtifactNextBrowserData;
+    uses: readonly string[];
+    roles?: ArtifactStudioCustomRoles;
+    ctx: z.RefinementCtx;
+}): void;

package/dist/manifest-next-browser-data.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { capabilityPinsSchema } from './manifest-custom-roles.js';
+import { boundedRef, ormOperationRef, reachShape } from './manifest-next-reach.js';
+const browserOperationRef = boundedRef.refine((ref) => ormOperationRef.test(ref), 'Browser ORM operations name each operation: namespace/ops/Operation');
+/** Additional browser admission rules; neither these rules nor data reach grant access. */
+export const artifactNextBrowserDataSchema = z.strictObject({
+    ...reachShape.data.unwrap().shape,
+    // Preserve absence: existing manifests use table-set admission. An explicit [] denies all.
+    operations: z.array(browserOperationRef).max(256).refine((operations) => new Set(operations).size === operations.length, 'Browser ORM operations must be unique').optional(),
+    // Keys name source namespaces, before development/preview namespace bindings are applied.
+    required_capabilities: z.preprocess((value, ctx) => {
+        // Zod records skip this own key before validating keys; reject it rather than silently drop it.
+        if (value !== null && typeof value === 'object' && Object.hasOwn(value, '__proto__')) {
+            ctx.addIssue({ code: 'custom', path: ['__proto__'], message: 'Capability guard keys are ORM source namespaces' });
+        }
+        return value;
+    }, z.record(z.string().regex(/^[a-z][a-z0-9_]{0,40}$/, 'Capability guard keys are ORM source namespaces'), capabilityPinsSchema.unwrap().min(1).refine((pins) => new Set(pins).size === pins.length, 'Required browser ORM capabilities must be unique'))).optional(),
+}).prefault({});
+/** Restriction references must be backed by this browser's reach and declared artifact pins. */
+export function validateBrowserDataAdmission({ data, uses, roles, ctx }) {
+    const reached = new Set([...data.read, ...data.write].map((ref) => ref.split('/', 1)[0]));
+    for (const [index, operation] of (data.operations ?? []).entries()) {
+        const namespace = operation.split('/', 1)[0];
+        if (!reached.has(namespace)) {
+            ctx.addIssue({
+                code: 'custom', path: ['capabilities', 'data', 'operations', index],
+                message: `${operation} names a namespace that browser capabilities.data.read or write does not reach`,
+            });
+        }
+    }
+    const declared = new Set([...Object.keys(roles?.capabilities ?? {}), ...uses]);
+    for (const [namespace, pins] of Object.entries(data.required_capabilities ?? {})) {
+        const path = ['capabilities', 'data', 'required_capabilities', namespace];
+        if (!reached.has(namespace)) {
+            ctx.addIssue({ code: 'custom', path, message: `${namespace} is not reached by browser capabilities.data.read or write` });
+        }
+        for (const [index, pin] of pins.entries()) {
+            if (!declared.has(pin)) {
+                ctx.addIssue({
+                    code: 'custom', path: [...path, index],
+                    message: `Required capability "${pin}" must be declared in capabilities.roles.capabilities or capabilities.uses`,
+                });
+            }
+        }
+    }
+}