@sequenceholdings/artifact-studio 0.6.4 → 0.6.6

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

package/dist/gateway/ingress-response.js

@@ -0,0 +1,98 @@
+import { isSharedCacheDirective, SHARED_CACHE_REFUSAL } from '../tunnel/protocol.js';
+/**
+ * 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 const INGRESS_RESPONSE_SECURITY_HEADERS = Object.freeze({
+    'content-security-policy': "default-src 'none'; sandbox; frame-ancestors 'none'",
+    'x-content-type-options': 'nosniff',
+    'referrer-policy': 'no-referrer',
+    'cross-origin-resource-policy': 'same-origin',
+    'cache-control': 'private, no-store',
+    ...SHARED_CACHE_REFUSAL,
+});
+// The app may not set CORS, cookies, framing or navigation; the gateway owns the security headers
+// above and the request id it generated.
+const STRIPPED_RESPONSE_HEADERS = new Set([
+    'set-cookie', 'clear-site-data', 'x-frame-options', 'refresh', 'x-request-id',
+    'content-security-policy-report-only', ...Object.keys(INGRESS_RESPONSE_SECURITY_HEADERS),
+]);
+const JSON_TYPES = new Set(['application/json', 'application/problem+json']);
+function mediaType(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const type = value.split(';', 1)[0].trim().toLowerCase();
+    return type === '' ? undefined : type;
+}
+function attachment(disposition) {
+    if (typeof disposition !== 'string')
+        return 'attachment';
+    // Keep the app's parameters (filename) and replace only the disposition type.
+    const parameters = disposition.split(';').slice(1).map((part) => part.trim()).filter(Boolean);
+    return ['attachment', ...parameters].join('; ');
+}
+/**
+ * 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 function applyIngressResponsePolicy({ status, method, headers, declaredLength, responses }) {
+    // 304 carries no body and no destination; every other 3xx would navigate a cross-origin caller.
+    if (status >= 300 && status < 400 && status !== 304)
+        return { allowed: false, reason: 'redirect' };
+    const type = mediaType(headers['content-type']);
+    if (type === 'text/event-stream')
+        return { allowed: false, reason: 'event_stream' };
+    if (type === undefined) {
+        const empty = status === 204 || status === 304 || method === 'HEAD' || declaredLength === 0;
+        if (!empty || headers['content-type'] !== undefined)
+            return { allowed: false, reason: 'missing_content_type' };
+    }
+    else if (type !== 'application/problem+json' && !responses.includes(type)) {
+        return { allowed: false, reason: 'content_type' };
+    }
+    const kept = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (STRIPPED_RESPONSE_HEADERS.has(name) || name.startsWith('access-control-') || isSharedCacheDirective(name))
+            continue;
+        kept[name] = value;
+    }
+    if (type === undefined || !JSON_TYPES.has(type))
+        kept['content-disposition'] = attachment(headers['content-disposition']);
+    return { allowed: true, headers: { ...kept, ...INGRESS_RESPONSE_SECURITY_HEADERS } };
+}
+/**
+ * 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 function writeIngressResponseHead({ response, status, method, headers, declaredLength, responses, maxResponseBytes }) {
+    const decision = applyIngressResponsePolicy({ status, method, headers, declaredLength, responses });
+    if (!decision.allowed || (declaredLength !== null && declaredLength > maxResponseBytes))
+        return false;
+    response.statusCode = status;
+    for (const [name, value] of Object.entries(decision.headers)) {
+        // The gateway's `Vary: Origin` (set with CORS) survives an app's own Vary.
+        const vary = name === 'vary' ? response.getHeader('vary') : undefined;
+        response.setHeader(name, typeof vary === 'string' ? `${vary}, ${Array.isArray(value) ? value.join(', ') : value}` : value);
+    }
+    return true;
+}
+/** An ingress caller gets a deterministic 504 before its 60 s context expires (design §(e) "Limits"). */
+export const INGRESS_PROXY_LIMITS = Object.freeze({ maxTimeoutMs: 55_000, idleWriteTimeoutMs: 10_000 });
+/** Error contract codes (design §(i)) for the failures the proxy itself decides. */
+export const INGRESS_PROXY_ERROR_CODES = Object.freeze({
+    400: 'bad_request', 413: 'payload_too_large', 502: 'upstream_response_refused', 503: 'temporarily_unavailable', 504: 'upstream_timeout',
+});

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

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import type { AdmissionRedis, ArtifactRequestAdmission } from './admission.js';
+import type { ArtifactGatewayControl } from './control.js';
+import { type IngressAuditFailure } from './ingress-audit.js';
+import { type IngressPassKeyring } from './ingress-pass.js';
+import { type ArtifactGatewayIngressOptions } from './ingress.js';
+/**
+ * Startup of the external ingress branch (design §(b.1) item 4): its four secrets, the checks
+ * that keep them independent of every other gateway secret, and the wiring of snapshot,
+ * admission, stages and denial audit. Errors and logs name variables, never values.
+ */
+export declare const INGRESS_SECRET_NAMES: readonly ["ARTIFACT_NEXT_EXTERNAL_CONTEXT_PRIVATE_KEY", "ARTIFACT_NEXT_EXTERNAL_CONTEXT_KEY_ID", "ARTIFACT_NEXT_INGRESS_PASS_KEYS", "ARTIFACT_NEXT_INGRESS_EDGE_SECRETS"];
+type IngressSecretName = typeof INGRESS_SECRET_NAMES[number];
+export interface IngressSecrets {
+    externalContext: {
+        privateKey: string;
+        keyId: string;
+    };
+    keyring: IngressPassKeyring;
+    /** Current and, during a rotation, next. */
+    edgeSecrets: string[];
+}
+export type IngressSecretsResult = 
+/** All four absent (`missing` lists all four) or only some present: the branch stays off. */
+{
+    state: 'disabled';
+    missing: IngressSecretName[];
+    partial: boolean;
+} | {
+    state: 'enabled';
+    secrets: IngressSecrets;
+};
+/** A refusal to boot: the ingress secrets are present but unusable. Its message names variables only. */
+export declare class IngressSecretsError extends Error {
+    constructor(message: string);
+}
+/** `ARTIFACT_NEXT_INGRESS_EDGE_SECRETS`: `{"current":"…","next":"…"|null}`, each at least 32 characters. */
+export declare const ingressEdgeSecretsSchema: z.ZodObject<{
+    current: z.ZodString;
+    next: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+/**
+ * Reads the four ingress secrets. All absent: disabled (the image can roll before the secrets
+ * exist). Some absent: disabled, with `partial` so the caller logs an error naming them. All
+ * present: enabled, or IngressSecretsError when any is malformed, when any two of {control token,
+ * session key, each pass key, each edge secret} are equal, when the external context key is the
+ * browser context key, or when the browser key id is the external one or an `external-` id (the
+ * sidecar pairs `external-` kids with v2 contexts only).
+ */
+export declare function loadIngressSecrets({ env, controlToken, sessionKey, browserContextPrivateKey, browserContextKeyId }: {
+    env: Readonly<Record<string, string | undefined>>;
+    controlToken: string;
+    sessionKey: string;
+    browserContextPrivateKey: string;
+    browserContextKeyId: string;
+}): IngressSecretsResult;
+export interface IngressRuntime {
+    /** Absent: the branch is disabled and every ingress host answers 404. */
+    ingress: ArtifactGatewayIngressOptions | undefined;
+    /** Starts the snapshot pulls and the denial audit flushes. */
+    start(): void;
+    /** Stops them and delivers the buffered refusals. */
+    close(): Promise<void>;
+}
+/**
+ * The ingress branch for one gateway process, or none. Throws IngressSecretsError (the process
+ * must refuse to boot) only when every secret is present and one is unusable.
+ */
+export declare function createIngressRuntime({ env, control, controlToken, sessionKey, contextPrivateKey, contextKeyId, redis, namespace, admission, log, onFailure }: {
+    env: Readonly<Record<string, string | undefined>>;
+    control: ArtifactGatewayControl;
+    controlToken: string;
+    sessionKey: string;
+    contextPrivateKey: string;
+    /** ARTIFACT_NEXT_CONTEXT_KEY_ID, the browser context key's id. */
+    contextKeyId: string;
+    redis: AdmissionRedis;
+    /** APP_ENV. */
+    namespace: string;
+    admission: Pick<ArtifactRequestAdmission, 'acquire'>;
+    log: (event: Record<string, unknown>) => void;
+    onFailure?: (failure: IngressAuditFailure | {
+        kind: 'ingress_snapshot_failed';
+    }) => void;
+}): IngressRuntime;
+export {};

package/dist/gateway/ingress-runtime.js

@@ -0,0 +1,126 @@
+import { createHash, createPrivateKey, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+import { ingressExternalKidSchema } from '../server/ingress-control-contract.js';
+import { IngressAdmission } from './ingress-admission.js';
+import { IngressDenialAuditor } from './ingress-audit.js';
+import { ingressPassKeyringSchema } from './ingress-pass.js';
+import { IngressSnapshotCache } from './ingress-snapshot.js';
+import { createIngressStages } from './ingress-stages.js';
+import { MIN_EDGE_SECRET_LENGTH } from './ingress.js';
+/**
+ * Startup of the external ingress branch (design §(b.1) item 4): its four secrets, the checks
+ * that keep them independent of every other gateway secret, and the wiring of snapshot,
+ * admission, stages and denial audit. Errors and logs name variables, never values.
+ */
+export const INGRESS_SECRET_NAMES = [
+    'ARTIFACT_NEXT_EXTERNAL_CONTEXT_PRIVATE_KEY',
+    'ARTIFACT_NEXT_EXTERNAL_CONTEXT_KEY_ID',
+    'ARTIFACT_NEXT_INGRESS_PASS_KEYS',
+    'ARTIFACT_NEXT_INGRESS_EDGE_SECRETS',
+];
+/** A refusal to boot: the ingress secrets are present but unusable. Its message names variables only. */
+export class IngressSecretsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IngressSecretsError';
+    }
+}
+/** `ARTIFACT_NEXT_INGRESS_EDGE_SECRETS`: `{"current":"…","next":"…"|null}`, each at least 32 characters. */
+export const ingressEdgeSecretsSchema = z.strictObject({
+    current: z.string().min(MIN_EDGE_SECRET_LENGTH).max(1024),
+    next: z.string().min(MIN_EDGE_SECRET_LENGTH).max(1024).nullable().default(null),
+});
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest();
+}
+/** Every pair compared in constant time, all of them, so timing reveals neither which nor whether. */
+function anyEqual(values) {
+    const digests = values.map(digest);
+    let equal = false;
+    for (let left = 0; left < digests.length; left++) {
+        for (let right = left + 1; right < digests.length; right++)
+            equal = timingSafeEqual(digests[left], digests[right]) || equal;
+    }
+    return equal;
+}
+function privateKeyBytes(pem, name) {
+    let key;
+    try {
+        key = createPrivateKey(pem);
+    }
+    catch {
+        throw new IngressSecretsError(`${name} is not a private key`);
+    }
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new IngressSecretsError(`${name} must be an Ed25519 key`);
+    return key.export({ format: 'der', type: 'pkcs8' });
+}
+/**
+ * Reads the four ingress secrets. All absent: disabled (the image can roll before the secrets
+ * exist). Some absent: disabled, with `partial` so the caller logs an error naming them. All
+ * present: enabled, or IngressSecretsError when any is malformed, when any two of {control token,
+ * session key, each pass key, each edge secret} are equal, when the external context key is the
+ * browser context key, or when the browser key id is the external one or an `external-` id (the
+ * sidecar pairs `external-` kids with v2 contexts only).
+ */
+export function loadIngressSecrets({ env, controlToken, sessionKey, browserContextPrivateKey, browserContextKeyId }) {
+    const missing = INGRESS_SECRET_NAMES.filter((name) => !env[name]);
+    if (missing.length > 0)
+        return { state: 'disabled', missing, partial: missing.length < INGRESS_SECRET_NAMES.length };
+    const privateKey = env.ARTIFACT_NEXT_EXTERNAL_CONTEXT_PRIVATE_KEY;
+    const keyId = env.ARTIFACT_NEXT_EXTERNAL_CONTEXT_KEY_ID;
+    if (!ingressExternalKidSchema.safeParse(keyId).success)
+        throw new IngressSecretsError('ARTIFACT_NEXT_EXTERNAL_CONTEXT_KEY_ID must start with external-');
+    if (browserContextKeyId === keyId || browserContextKeyId.startsWith('external-')) {
+        throw new IngressSecretsError('ARTIFACT_NEXT_CONTEXT_KEY_ID must differ from ARTIFACT_NEXT_EXTERNAL_CONTEXT_KEY_ID and must not start with external-');
+    }
+    const keyring = ingressPassKeyringSchema.safeParse(parseJson(env.ARTIFACT_NEXT_INGRESS_PASS_KEYS));
+    if (!keyring.success)
+        throw new IngressSecretsError('ARTIFACT_NEXT_INGRESS_PASS_KEYS is malformed');
+    const edge = ingressEdgeSecretsSchema.safeParse(parseJson(env.ARTIFACT_NEXT_INGRESS_EDGE_SECRETS));
+    if (!edge.success)
+        throw new IngressSecretsError('ARTIFACT_NEXT_INGRESS_EDGE_SECRETS is malformed');
+    const external = privateKeyBytes(privateKey, 'ARTIFACT_NEXT_EXTERNAL_CONTEXT_PRIVATE_KEY');
+    const browser = privateKeyBytes(browserContextPrivateKey, 'ARTIFACT_NEXT_CONTEXT_PRIVATE_KEY');
+    const edgeSecrets = [edge.data.current, ...(edge.data.next === null ? [] : [edge.data.next])];
+    const independent = [controlToken, sessionKey, ...Object.values(keyring.data.keys), ...edgeSecrets].map((value) => Buffer.from(value, 'utf8'));
+    if (anyEqual(independent)) {
+        throw new IngressSecretsError('Gateway secrets must be independent: the control token, session key, pass keys and edge secrets must all differ');
+    }
+    if (anyEqual([external, browser]))
+        throw new IngressSecretsError('ARTIFACT_NEXT_EXTERNAL_CONTEXT_PRIVATE_KEY must not be the browser context key');
+    return { state: 'enabled', secrets: { externalContext: { privateKey, keyId }, keyring: keyring.data, edgeSecrets } };
+}
+/**
+ * The ingress branch for one gateway process, or none. Throws IngressSecretsError (the process
+ * must refuse to boot) only when every secret is present and one is unusable.
+ */
+export function createIngressRuntime({ env, control, controlToken, sessionKey, contextPrivateKey, contextKeyId, redis, namespace, admission, log, onFailure }) {
+    const loaded = loadIngressSecrets({ env, controlToken, sessionKey, browserContextPrivateKey: contextPrivateKey, browserContextKeyId: contextKeyId });
+    if (loaded.state === 'disabled') {
+        if (loaded.partial)
+            log({ event: 'artifact_gateway.ingress_disabled', level: 'error', missing: loaded.missing });
+        return { ingress: undefined, start: () => undefined, close: async () => undefined };
+    }
+    log({ event: 'artifact_gateway.ingress_secrets_checked', message: 'ingress secrets checked' });
+    const { secrets } = loaded;
+    const snapshot = new IngressSnapshotCache({ load: () => control.ingressSnapshot(), onError: (event) => onFailure?.(event) });
+    const auditor = new IngressDenialAuditor({ send: (batch) => control.ingressAudit(batch), onFailure });
+    const handlers = createIngressStages({
+        control, snapshot, keyring: secrets.keyring, externalContext: secrets.externalContext, admission,
+        ingressAdmission: new IngressAdmission({ redis, namespace }), appEnv: namespace,
+    });
+    return {
+        ingress: { edgeSecrets: secrets.edgeSecrets, snapshot, appEnv: namespace, handlers, onDenial: (event) => auditor.record(event) },
+        start: () => { snapshot.start(); auditor.start(); },
+        close: async () => { snapshot.stop(); await auditor.close(); },
+    };
+}

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

@@ -0,0 +1,54 @@
+import type { IngressSnapshot, IngressSnapshotHost } from '../server/ingress-control-contract.js';
+/**
+ * The gateway's local copy of every enabled ingress host (design §(e) "Host snapshot"). It is
+ * pulled from `control/ingress-snapshot` on a timer and never on request, so a request for a
+ * random hostname costs a map lookup and can never amplify into an Atlas call.
+ */
+export declare const INGRESS_SNAPSHOT_INTERVAL_MS = 15000;
+/** Older than this (Atlas unreachable for eight pulls), every ingress request answers 503. */
+export declare const INGRESS_SNAPSHOT_STALE_AFTER_MS = 120000;
+export type IngressSnapshotLookup = {
+    state: 'fresh';
+    entry: IngressSnapshotHost;
+} | {
+    state: 'unknown';
+}
+/** Too old to act on. `entry` is the last known one, for CORS on the 503 only. */
+ | {
+    state: 'stale';
+    entry: IngressSnapshotHost | undefined;
+};
+export interface IngressSnapshotCacheOptions {
+    /** Fetches and validates the snapshot (`ArtifactGatewayControl.ingressSnapshot`). */
+    load: () => Promise<IngressSnapshot>;
+    intervalMs?: number;
+    staleAfterMs?: number;
+    now?: () => number;
+    /** A failed pull keeps the previous snapshot until it goes stale. */
+    onError?: (event: {
+        kind: 'ingress_snapshot_failed';
+    }) => void;
+}
+export declare class IngressSnapshotCache {
+    private readonly options;
+    private hosts;
+    private snapshot;
+    private loadedAt;
+    private pending;
+    private timer;
+    private readonly intervalMs;
+    private readonly staleAfterMs;
+    private readonly now;
+    constructor(options: IngressSnapshotCacheOptions);
+    /** Pulls now and then every interval; the timer never keeps the process alive. */
+    start(): void;
+    stop(): void;
+    /** Single-flight: concurrent callers share one pull. Never rejects. */
+    refresh(): Promise<void>;
+    /** `host` must already be the canonical raw Host. A local map lookup; never a network call. */
+    lookup(host: string): IngressSnapshotLookup;
+    /** The non-secret per-provider summary the exchange precheck reads; undefined until a pull succeeds. */
+    get providers(): IngressSnapshot['providers'] | undefined;
+    /** The last pulled snapshot's policy epoch; a newer one on a grant asks for a pull now. */
+    get policyEpoch(): number | undefined;
+}