@sequenceholdings/artifact-studio 0.6.3 → 0.6.6

package/dist/gateway/ingress.d.ts

@@ -0,0 +1,259 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { IngressAuditEvent, IngressSnapshotHost } from '../server/ingress-control-contract.js';
+import { type IngressRouteMatch } from '../server/ingress-routes.js';
+import type { HostedArtifactProxyOptions, proxyHostedArtifact } from './hosted-proxy.js';
+import { type HostedArtifactIngressMode } from './ingress-response.js';
+import type { IngressSnapshotCache } from './ingress-snapshot.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 declare const INGRESS_TOKEN_PATH = "/_sequence/ingress/token";
+export declare const INGRESS_LOGOUT_PATH = "/_sequence/ingress/logout";
+export declare const INGRESS_LIMITS: Readonly<{
+    /** A pass is at most 2 KiB; an API (and logout) `Authorization` header above this is refused unread. */
+    maxApiAuthorizationBytes: number;
+    /** The exchange carries the identity provider's token, which may be larger than a pass. */
+    maxExchangeAuthorizationBytes: number;
+    maxResponseBytes: number;
+    preflightMaxAgeSeconds: 600;
+}>;
+export declare const INGRESS_EXPOSED_HEADERS = "retry-after, x-request-id, www-authenticate, content-disposition";
+export declare const BASE_ALLOWED_REQUEST_HEADERS: readonly ["authorization", "content-type"];
+/** Error contract codes (design §(i)). App responses pass through with their own bodies. */
+export type IngressErrorCode = 'bad_request' | 'invalid_token' | 'insufficient_user_authentication' | 'exchange_denied' | 'forbidden' | 'not_found' | 'request_timeout' | 'too_large' | 'payload_too_large' | 'request_header_fields_too_large' | 'rate_limited' | 'upstream_response_refused' | 'temporarily_unavailable' | 'upstream_timeout';
+/**
+ * A refusal the gateway decided itself about a request that is not garbage (edge, client address,
+ * CORS, a refused authentic pass, freshness), for the denial audit batch. Garbage (a missing,
+ * malformed or forged credential) and admission refusals are a metric only, and refusals an Atlas
+ * control route returned are never marked: Atlas audits those itself (design §(g) "Gateway denials").
+ */
+export interface IngressDenialDetail {
+    /** snake_case, for example `pass_bad_mac` or `origin_not_allowed`. */
+    reason: string;
+    ingress?: string | null;
+    subjectHash?: string;
+    passId?: string;
+}
+/**
+ * The in-process counters refusals feed (the gateway's onError, aggregated every 10 s): what a
+ * forged credential or a flood costs is a counter increment, never an audit write.
+ */
+export type IngressRefusalMetric = 'ingress_pass_rejected' | 'ingress_token_rejected' | 'admission_rejected'
+/** Should both stay zero: non-zero means a request reached the gateway around our Cloudflare zone, or Pseudo IPv4 is on. */
+ | 'ingress_edge_header_invalid' | 'ingress_client_ip_invalid';
+/** Thrown by an ingress handler; written through the ingress writer, never the session remap. */
+export declare class IngressError extends Error {
+    readonly status: number;
+    readonly code: IngressErrorCode;
+    readonly extra: {
+        retryAfterSeconds?: number;
+        wwwAuthenticate?: string;
+        audit?: IngressDenialDetail;
+        metric?: IngressRefusalMetric;
+    };
+    constructor(status: number, code: IngressErrorCode, extra?: {
+        retryAfterSeconds?: number;
+        wwwAuthenticate?: string;
+        audit?: IngressDenialDetail;
+        metric?: IngressRefusalMetric;
+    });
+}
+/** Every ingress host's first label starts with this. */
+export declare const INGRESS_HOST_PREFIX = "ingress-";
+/** The raw `Host` exactly as an ingress host must arrive: lowercase, no port, no trailing dot. */
+export declare function isIngressHost({ rawHost, runtimeDomain }: {
+    rawHost: string | undefined;
+    runtimeDomain: string;
+}): boolean;
+/**
+ * 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 declare function resemblesIngressHost({ rawHost, runtimeDomain }: {
+    rawHost: string | undefined;
+    runtimeDomain: string;
+}): boolean;
+/** Every value of a header as sent, so a repeated header is seen (Node keeps only the first of some). */
+export declare function rawHeaderValues(request: IncomingMessage, name: string): string[];
+/**
+ * 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 declare const MIN_EDGE_SECRET_LENGTH = 32;
+/** Every `Authorization` value at most `maxBytes`, and at most one of them: none is ever picked. */
+export declare function hasAcceptableAuthorization({ request, maxBytes }: {
+    request: IncomingMessage;
+    maxBytes: number;
+}): boolean;
+/** The presented `x-sequence-edge` values match: exactly one, equal in constant time to a usable secret. */
+export declare function edgeValuesMatch({ values, secrets }: {
+    values: readonly string[];
+    secrets: readonly string[];
+}): boolean;
+/**
+ * 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 declare function hasValidEdgeHeader({ request, secrets }: {
+    request: IncomingMessage;
+    secrets: readonly string[];
+}): boolean;
+/**
+ * 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 declare function edgeClientIp(request: IncomingMessage): string | null;
+export type SnapshotIngress = IngressSnapshotHost['ingresses'][number];
+export type IngressRoute = SnapshotIngress['routes'][number];
+/** A matched route and the one ingress on this host that declares it. */
+export interface IngressRouteResolution {
+    ingress: SnapshotIngress;
+    match: IngressRouteMatch<IngressRoute>;
+}
+/** Exactly one ingress on the host may declare the matched (method, path); ambiguity is no match. */
+export declare function resolveIngressRoute({ entry, method, path }: {
+    entry: IngressSnapshotHost;
+    method: string;
+    path: string;
+}): IngressRouteResolution | null;
+/** The caller's `Origin`, or null when absent. Several `Origin` headers never match an allowed origin. */
+export declare function callerOrigin(request: IncomingMessage): string | null;
+export declare function ingressCorsHeaders(origin: string): Record<string, string>;
+/**
+ * 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 declare function writeIngressError({ response, status, code, corsOrigin, retryAfterSeconds, wwwAuthenticate }: {
+    response: ServerResponse;
+    status: number;
+    code: IngressErrorCode | string;
+    corsOrigin: string | null;
+    retryAfterSeconds?: number;
+    wwwAuthenticate?: string;
+}): void;
+/** A request every local check admitted, handed to the pass, admission and grant stage (C6b). */
+export interface IngressRequest {
+    request: IncomingMessage;
+    response: ServerResponse;
+    /** The canonical raw host, and its public origin. */
+    host: string;
+    publicOrigin: string;
+    entry: IngressSnapshotHost;
+    clientIp: string;
+    /** The caller's allowed `Origin`, or null for a non-browser caller. */
+    origin: string | null;
+    requestId: string;
+}
+export interface IngressApiRequest extends IngressRequest {
+    ingress: SnapshotIngress;
+    match: IngressRouteMatch<IngressRoute>;
+    /** Canonical path plus raw query: the string the context signs and Atlas re-matches. */
+    signedPath: string;
+}
+/**
+ * A development session to proxy to over its tunnel. Local development only: the stage admits it
+ * only on a gateway with APP_ENV=development, for the snapshot's own development target (design
+ * §(j.3) step 3).
+ */
+export interface IngressDevelopmentTarget {
+    kind: 'development';
+    projectId: string;
+    environment: string;
+    sessionId: string;
+}
+/** Where an admitted request goes: the active deployment, or a development session's tunnel. */
+export type IngressAdmittedTarget = (Omit<HostedArtifactProxyOptions['target'], 'publicOrigin'> & {
+    kind?: 'published';
+}) | IngressDevelopmentTarget;
+/** What the admit stage returns: where to proxy, and the signed context. */
+export interface IngressAdmittedRequest {
+    target: IngressAdmittedTarget;
+    requestContext: string;
+    /** The admitted request timeout; the proxy caps it at 55 s. */
+    timeoutMs: number;
+    /** Ties a concurrency permit to the response's lifetime. */
+    bind?: (response: ServerResponse, abort: () => void) => void;
+    /** The request body, when the stage buffered it before taking a concurrency permit. */
+    body?: AsyncIterable<Uint8Array>;
+    /** Attribution for the request's usage observation: a deployment, or a development session. */
+    usage?: {
+        actorId: string;
+        ingressId: string;
+        projectId: string;
+        environment: string;
+    } & ({
+        deploymentId: string;
+    } | {
+        devSessionId: string;
+    });
+}
+/**
+ * Proxies an admitted ingress request over a development session's tunnel, under the same
+ * ingress request sanitising, response policy, limits and error writer as the hosted proxy.
+ */
+export type IngressDevelopmentProxy = (input: {
+    request: IncomingMessage;
+    response: ServerResponse;
+    target: IngressDevelopmentTarget;
+    /** The ingress host's canonical origin: the app sees it as `x-forwarded-host`, as on a hosted release. */
+    publicOrigin: string;
+    requestContext: string;
+    body?: AsyncIterable<Uint8Array>;
+    limits: {
+        maxRequestBytes: number;
+        maxResponseBytes: number;
+        timeoutMs: number;
+    };
+    ingress: HostedArtifactIngressMode;
+}) => Promise<void>;
+export interface IngressHandlers {
+    /** Admission for a preflight (`ingress-preflight`), after the local checks; throws to refuse. Absent: none. */
+    preflight?: (input: IngressRequest) => Promise<void>;
+    /** `POST /_sequence/ingress/token`; writes its own response. */
+    exchange?: (input: IngressRequest) => Promise<void>;
+    /** `POST /_sequence/ingress/logout`; writes its own response. */
+    logout?: (input: IngressRequest) => Promise<void>;
+    /** Pass, admission and grant for an API route; throws IngressError to refuse. */
+    admit?: (input: IngressApiRequest) => Promise<IngressAdmittedRequest>;
+}
+export interface ArtifactGatewayIngressOptions {
+    /** Current and next `x-sequence-edge` values. */
+    edgeSecrets: readonly string[];
+    snapshot: Pick<IngressSnapshotCache, 'lookup'>;
+    /** The gateway's APP_ENV: a `development` snapshot target is honoured only under `development`. */
+    appEnv: string;
+    /** Absent stages answer 503 `temporarily_unavailable`. */
+    handlers?: IngressHandlers;
+    /** Injectable proxy for isolated tests. */
+    proxy?: typeof proxyHostedArtifact;
+    /** Injectable for tests of the idle-write timeout. */
+    idleWriteTimeoutMs?: number;
+    /** Injectable for tests of the response cap (default INGRESS_LIMITS.maxResponseBytes). */
+    maxResponseBytes?: number;
+    /** Receives every refusal the gateway decided itself on a host in the snapshot (the denial audit). */
+    onDenial?: (event: IngressAuditEvent) => void;
+}
+/** The union of a host's allowed origins: CORS for errors decided before a route is known. */
+export declare function hostOrigins(entry: IngressSnapshotHost | undefined): ReadonlySet<string>;
+export declare function corsFor(origin: string | null, allowed: ReadonlySet<string>): string | null;
+export declare function requestedHeaders(request: IncomingMessage): string[];
+/** Host, Origin and edge values from the bytes Node had buffered when the header block overflowed. */
+export declare function requestLineHeaders(raw: Buffer | undefined): {
+    host?: string;
+    origin?: string | null;
+    edge: string[];
+};
+export declare function writeIngressRefusal({ response, error, corsOrigin }: {
+    response: ServerResponse;
+    error: unknown;
+    corsOrigin: string | null;
+}): void;

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: {