@sequenceholdings/artifact-studio 0.6.4 → 0.6.7

package/dist/gateway/ingress-stages.js

@@ -0,0 +1,387 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { artifactNextIngressIdSchema } from '../manifest-next-ingress.js';
+import { INGRESS_ROUTE_METHODS } from '../server/ingress-routes.js';
+import { ArtifactAdmissionError } from './admission.js';
+import { PositiveDecisionCache } from './authorization-cache.js';
+import { IngressControlError } from './control.js';
+import { ingressClientBucket } from './ingress-admission.js';
+import { externalSubject, observeUserAgent, signExternalGatewayContext } from './ingress-context.js';
+import { IngressPassTooLargeError, mintPass, verifyPass } from './ingress-pass.js';
+import { INGRESS_RESPONSE_SECURITY_HEADERS } from './ingress-response.js';
+import { ingressCorsHeaders, IngressError, } from './ingress.js';
+/**
+ * The authenticated half of the external ingress (design "First call" steps 3-5, "Steady state"
+ * steps 4-8, §(d), §(e) "Rate limiting and admission"): pass exchange, logout, and for API routes
+ * local pass verification, admission, grant, freshness, concurrency and the signed v2 context.
+ * Order matters: nothing a forged credential presents reaches Redis or Atlas, and garbage is only
+ * ever counted, never audited (design §(g) "Gateway denials").
+ */
+/** Exchange request bodies above this are refused unread past the limit, before admission. */
+export const INGRESS_EXCHANGE_MAX_BODY_BYTES = 1024;
+/** Routes with a body cap at or below this have the body buffered before a concurrency permit. */
+export const INGRESS_BUFFERED_BODY_MAX_BYTES = 1024 * 1024;
+/** A grant-triggered snapshot pull happens at most this often. */
+const POLICY_REFRESH_MIN_INTERVAL_MS = 1_000;
+/** Only GET reads reuse a grant; HEAD never matches a declared route (INGRESS_ROUTE_METHODS). */
+const READ_METHODS = new Set(['GET']);
+/** Pass refusals whose MAC held: an authentic pass refused by a decision, audited. The rest is garbage. */
+const AUTHENTIC_PASS_REFUSALS = new Set(['expired', 'not_yet_valid', 'wrong_origin', 'wrong_environment']);
+const exchangeBodySchema = z.strictObject({ ingress: artifactNextIngressIdSchema });
+export function subjectHashOf(subject) {
+    return createHash('sha256').update(subject).digest('hex');
+}
+/**
+ * A refused pass (design "Steady state" step 4): always counted; audited only when its MAC held,
+ * so a forged pass costs a local HMAC and a counter increment, never an Atlas audit write.
+ */
+function passRefused({ reason, authentic, detail = {} }) {
+    return new IngressError(401, 'invalid_token', { metric: 'ingress_pass_rejected', ...(authentic ? { audit: { reason, ...detail } } : {}) });
+}
+/** An identity token refused by the structural precheck: garbage, counted and never audited. */
+function tokenRefused() {
+    return new IngressError(401, 'invalid_token', { metric: 'ingress_token_rejected' });
+}
+/** The single `Authorization: Bearer <credential>` value, or null. The handler already refused repeats and oversize. */
+function bearer(request) {
+    const value = request.headers.authorization;
+    const match = typeof value === 'string' ? /^Bearer ([A-Za-z0-9._~+/=-]+)$/i.exec(value) : null;
+    return match ? match[1] : null;
+}
+function decodeJsonSegment(segment) {
+    try {
+        return JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+const jwsHeaderSchema = z.object({ alg: z.string(), kid: z.string().min(1).max(256) });
+const jwsPayloadSchema = z.object({ iss: z.string(), exp: z.number().int().positive().optional() });
+/**
+ * The structural precheck before any Redis or Atlas call (design "First call" step 3): three
+ * base64url segments, an `alg` among the provider's, a `kid`, and the provider's `iss`. No crypto
+ * and no JWKS: Atlas verifies the token. Returns the token's `exp`, which Atlas verified with it.
+ */
+export function precheckIdentityToken({ token, provider }) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts.every((part) => /^[A-Za-z0-9_-]+$/.test(part)))
+        return null;
+    const header = jwsHeaderSchema.safeParse(decodeJsonSegment(parts[0]));
+    const payload = jwsPayloadSchema.safeParse(decodeJsonSegment(parts[1]));
+    if (!header.success || !payload.success)
+        return null;
+    if (!provider.algorithms.includes(header.data.alg) || payload.data.iss !== provider.issuer)
+        return null;
+    return { exp: payload.data.exp ?? null };
+}
+/** The body, read up to `maxBytes`; beyond it 413 with nothing more read. */
+async function readBounded({ request, maxBytes }) {
+    const declared = Number(request.headers['content-length']);
+    if (Number.isFinite(declared) && declared > maxBytes)
+        throw new IngressError(413, 'payload_too_large');
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.from(chunk);
+        length += bytes.length;
+        if (length > maxBytes)
+            throw new IngressError(413, 'payload_too_large');
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks);
+}
+/** A refusal an Atlas control route returned, as the caller sees it; never audited by the gateway. */
+function fromControl(error) {
+    if (error instanceof IngressControlError && error.code !== null) {
+        return new IngressError(error.status, error.code, error.retryAfterSeconds === undefined ? {} : { retryAfterSeconds: error.retryAfterSeconds });
+    }
+    if (error instanceof ArtifactAdmissionError)
+        return fromAdmission(error);
+    // A bare failure, a timeout or an unparseable answer: an outage the caller may retry.
+    return new IngressError(503, 'temporarily_unavailable', error instanceof IngressControlError && error.retryAfterSeconds !== undefined ? { retryAfterSeconds: error.retryAfterSeconds } : {});
+}
+/** A rate limit or a Redis outage: a metric, never an audit event (a flood or an outage would become one per request). */
+function fromAdmission(error) {
+    return error.status === 429
+        ? new IngressError(429, 'rate_limited', { retryAfterSeconds: error.retryAfterSeconds ?? 1, metric: 'admission_rejected' })
+        : new IngressError(503, 'temporarily_unavailable', { retryAfterSeconds: error.retryAfterSeconds ?? 2, metric: 'admission_rejected' });
+}
+async function admitted(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (error instanceof ArtifactAdmissionError)
+            throw fromAdmission(error);
+        throw error;
+    }
+}
+/** A buffered body as the stream the proxy forwards. */
+async function* replay(body) {
+    if (body.length > 0)
+        yield body;
+}
+function writeJson({ response, status, body, corsOrigin }) {
+    response.writeHead(status, {
+        ...INGRESS_RESPONSE_SECURITY_HEADERS,
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+        ...(corsOrigin ? ingressCorsHeaders(corsOrigin) : {}),
+    });
+    response.end(body === undefined ? undefined : JSON.stringify(body));
+}
+/** The caller's origin for CORS on a success, or a 403 when this ingress does not allow it. */
+function ingressOrigin({ origin, ingress }) {
+    if (origin === null)
+        return null;
+    if (!ingress.allowedOrigins.includes(origin))
+        throw new IngressError(403, 'forbidden', { audit: { reason: 'origin_not_allowed', ingress: ingress.id } });
+    return origin;
+}
+function grantCacheKey(parts) {
+    return createHash('sha256').update(JSON.stringify(['ingress-grant-v1', ...parts])).digest('hex');
+}
+export function createIngressStages(options) {
+    const now = options.now ?? Date.now;
+    const seconds = () => Math.floor(now() / 1000);
+    const grants = new PositiveDecisionCache({ ttlMs: options.grantCacheTtlMs, now });
+    let lastPolicyRefresh = Number.NEGATIVE_INFINITY;
+    /** Local pass verification (design "Steady state" step 4): no Redis, no Atlas; failure is 401, uncharged. */
+    function verifiedPass({ request, publicOrigin, entry }) {
+        const token = bearer(request);
+        if (!token)
+            throw passRefused({ reason: 'pass_missing', authentic: false });
+        const verification = verifyPass({ keyring: options.keyring, token, now: seconds(), origin: publicOrigin, env: options.appEnv });
+        if (!verification.ok)
+            throw passRefused({ reason: `pass_${verification.reason}`, authentic: AUTHENTIC_PASS_REFUSALS.has(verification.reason) });
+        const { payload } = verification;
+        const ingress = entry.ingresses.find((candidate) => candidate.id === payload.ingress && candidate.provider === payload.provider);
+        if (!ingress || payload.projectId !== entry.projectId)
+            throw passRefused({ reason: 'pass_wrong_ingress', authentic: true, detail: { passId: payload.jti } });
+        return { pass: payload, kid: verification.kid, ingress };
+    }
+    async function preflight({ clientIp }) {
+        await admitted(() => options.ingressAdmission.preflight({ clientIp }));
+    }
+    async function exchange(input) {
+        const { request, response, host, publicOrigin, entry, clientIp, origin, requestId } = input;
+        // Read, bounded, before admission (design §(e) "Limits").
+        if (request.headers['content-type']?.split(';', 1)[0]?.trim().toLowerCase() !== 'application/json')
+            throw new IngressError(400, 'bad_request');
+        const raw = await readBounded({ request, maxBytes: INGRESS_EXCHANGE_MAX_BODY_BYTES });
+        let parsedBody;
+        try {
+            parsedBody = JSON.parse(raw.toString('utf8'));
+        }
+        catch {
+            throw new IngressError(400, 'bad_request');
+        }
+        const body = exchangeBodySchema.safeParse(parsedBody);
+        if (!body.success)
+            throw new IngressError(400, 'bad_request');
+        const ingress = entry.ingresses.find((candidate) => candidate.id === body.data.ingress);
+        if (!ingress)
+            throw new IngressError(404, 'not_found');
+        const corsOrigin = ingressOrigin({ origin, ingress });
+        const token = bearer(request);
+        if (!token)
+            throw tokenRefused();
+        const provider = options.snapshot.providers?.[ingress.provider];
+        if (!provider)
+            throw new IngressError(503, 'temporarily_unavailable');
+        const precheck = precheckIdentityToken({ token, provider });
+        if (!precheck)
+            throw tokenRefused();
+        const release = await admitted(() => options.ingressAdmission.exchange({ clientIp, host }));
+        let verified;
+        try {
+            verified = await options.control.ingressExchange({
+                host, ingress: ingress.id, origin, token, clientIp, userAgent: observeUserAgent(request.headers['user-agent']).userAgent, requestId,
+            });
+        }
+        catch (error) {
+            throw fromControl(error);
+        }
+        finally {
+            release();
+        }
+        const { principal } = verified;
+        // The context's `sub` is `ext|<provider>|<subject>`, at most 255 characters (design §(f)).
+        const denied = (reason) => new IngressError(403, 'exchange_denied', { audit: { reason, ingress: ingress.id, subjectHash: subjectHashOf(principal.subject) } });
+        if (externalSubject({ provider: ingress.provider, subject: principal.subject }).length > 255)
+            throw denied('subject_too_long');
+        const iat = seconds();
+        const exp = Math.min(precheck.exp ?? Number.POSITIVE_INFINITY, iat + verified.passTtlSeconds);
+        if (exp <= iat)
+            throw new IngressError(401, 'invalid_token', { audit: { reason: 'token_expired', ingress: ingress.id } });
+        let pass;
+        try {
+            pass = mintPass({ keyring: options.keyring, payload: {
+                    v: 1, typ: 'artifact-ingress-pass', env: options.appEnv, origin: publicOrigin, projectId: entry.projectId,
+                    ingress: ingress.id, provider: ingress.provider, bep: verified.bindingEpoch, ...principal,
+                    exchangeIp: clientIp, jti: randomUUID(), iat, exp,
+                } });
+        }
+        catch (error) {
+            // A principal near the schema maxima never fits: a decided refusal, not an outage to retry.
+            if (error instanceof IngressPassTooLargeError)
+                throw denied('pass_too_large');
+            throw error;
+        }
+        // `expiresAt` is epoch milliseconds, as the BAP's other token clocks are.
+        writeJson({ response, status: 200, body: { token: pass, expiresAt: exp * 1000 }, corsOrigin });
+    }
+    async function logout(input) {
+        const { response, host, clientIp, origin } = input;
+        const { pass, ingress } = verifiedPass(input);
+        const corsOrigin = ingressOrigin({ origin, ingress });
+        const subjectHash = subjectHashOf(pass.subject);
+        const release = await admitted(() => options.ingressAdmission.logout({ provider: pass.provider, subjectHash, clientIp }));
+        try {
+            await options.control.ingressRevoke({ host, ingress: ingress.id, provider: pass.provider, subject: pass.subject, passJti: pass.jti, tokenIssuedAt: pass.tokenIssuedAt });
+        }
+        catch (error) {
+            throw fromControl(error);
+        }
+        finally {
+            release();
+        }
+        writeJson({ response, status: 204, corsOrigin });
+    }
+    /** A grant for this exact (route, method), cached ≤ 5 s for reads only, under an `ingress-grant` permit. */
+    async function grantFor({ input, pass, subjectHash }) {
+        const method = input.request.method ?? 'GET';
+        const body = {
+            host: input.host, ingress: input.ingress.id, provider: input.ingress.provider, subjectHash, tokenIssuedAt: pass.tokenIssuedAt,
+            passJti: pass.jti, method: z.enum(INGRESS_ROUTE_METHODS).parse(method), routeId: input.match.routeId,
+        };
+        // The snapshot's target is part of the key: after an `artifact dev` restart a refreshed
+        // snapshot names the new session, so a read grant cached for the old one must miss.
+        const { target } = input.entry;
+        const lookup = {
+            key: grantCacheKey([body.host, body.ingress, subjectHash, body.passJti, body.routeId, body.method, target.kind === 'development' ? `development:${target.sessionId}` : 'published']),
+            load: () => options.ingressAdmission.withPool('ingress-grant', () => options.control.ingressGrant(body)),
+            notAfter: (grant) => grant.expiresAt,
+        };
+        try {
+            // Mutations always ask Atlas: revocation, a disabled binding or a new release stop them at once.
+            return READ_METHODS.has(method) ? await grants.get(lookup) : await grants.refresh(lookup);
+        }
+        catch (error) {
+            throw fromControl(error);
+        }
+    }
+    /** Pulls the snapshot now, at most once a second. A cache-buster only, never a reason to deny. */
+    function refreshSnapshot() {
+        if (now() - lastPolicyRefresh < POLICY_REFRESH_MIN_INTERVAL_MS)
+            return;
+        lastPolicyRefresh = now();
+        void options.snapshot.refresh();
+    }
+    /**
+     * The grant's release, or 503 when it does not match the snapshot entry it was asked for: a
+     * published grant only for a published target, and a development grant only on a development
+     * gateway (its own APP_ENV, never a value from the request or Atlas), for the snapshot's own
+     * development session (design §(j.3) steps 3-4). Never proxied over either session id alone:
+     * after an `artifact dev` restart inside one poll the two differ, so the request is refused and
+     * the snapshot pulled at once.
+     */
+    function releaseOf({ grant, entry }) {
+        const unavailable = () => { refreshSnapshot(); return new IngressError(503, 'temporarily_unavailable'); };
+        if (grant.mode === 'published') {
+            if (entry.target.kind !== 'published')
+                throw unavailable();
+            return { mode: 'published', deploymentId: grant.deploymentId };
+        }
+        if (options.appEnv !== 'development')
+            throw new IngressError(503, 'temporarily_unavailable');
+        if (entry.target.kind !== 'development' || entry.target.sessionId !== grant.devSessionId)
+            throw unavailable();
+        return { mode: 'development', devSessionId: grant.devSessionId };
+    }
+    /** Route freshness (design §(h)): `fresh_auth_seconds` against the pass's sign-in time, else a step-up 401. */
+    function requireFreshAuth({ pass, freshness, detail }) {
+        if (freshness > 0 && (pass.authTime === null || seconds() - pass.authTime > freshness)) {
+            throw new IngressError(401, 'insufficient_user_authentication', {
+                wwwAuthenticate: `Bearer error="insufficient_user_authentication", max_age=${freshness}`,
+                audit: { reason: 'step_up_required', ...detail },
+            });
+        }
+    }
+    /** A grant for this request that a context may still be signed with, and its release, else 503 before signing. */
+    async function usableGrant({ input, pass, detail }) {
+        const grant = await grantFor({ input, pass, subjectHash: detail.subjectHash });
+        if (grant.projectId !== input.entry.projectId || grant.expiresAt <= now())
+            throw new IngressError(503, 'temporarily_unavailable');
+        if (grant.policyEpoch > (options.snapshot.policyEpoch ?? 0))
+            refreshSnapshot();
+        const release = releaseOf({ grant, entry: input.entry });
+        // A deployment that does not trust the gateway's current kid would refuse the context: 503 before signing.
+        if (!grant.trustedExternalKids.includes(options.externalContext.keyId))
+            throw new IngressError(503, 'temporarily_unavailable', { audit: { reason: 'untrusted_external_kid', ...detail } });
+        return { grant, release };
+    }
+    async function admit(input) {
+        const { request, entry, ingress, match, clientIp, origin, requestId, signedPath } = input;
+        const { pass, kid: passKid, ingress: passIngress } = verifiedPass(input);
+        // A pass is good for its own ingress's routes only, whatever other ingress the host carries.
+        if (passIngress.id !== ingress.id)
+            throw passRefused({ reason: 'pass_wrong_ingress', authentic: true, detail: { ingress: ingress.id, passId: pass.jti } });
+        const subjectHash = subjectHashOf(pass.subject);
+        const detail = { ingress: ingress.id, subjectHash, passId: pass.jti };
+        const freshness = match.route.fresh_auth_seconds ?? 0;
+        // Freshness needs only the verified pass: refused early, before any Redis count or Atlas grant.
+        requireFreshAuth({ pass, freshness, detail });
+        await admitted(() => options.ingressAdmission.request({ provider: pass.provider, subjectHash, projectId: entry.projectId, ingressId: ingress.id }));
+        let { grant, release } = await usableGrant({ input, pass, detail });
+        const maxBodyBytes = match.route.max_body_bytes;
+        let body;
+        if (maxBodyBytes <= INGRESS_BUFFERED_BODY_MAX_BYTES) {
+            body = replay(await readBounded({ request, maxBytes: maxBodyBytes }));
+            // A slow upload can outlive the pass, the route's freshness window and the grant: decide all
+            // three again before signing, so nothing is forwarded on an authorization that has lapsed.
+            if (pass.exp <= seconds())
+                throw passRefused({ reason: 'pass_expired', authentic: true, detail: { ingress: ingress.id, passId: pass.jti } });
+            requireFreshAuth({ pass, freshness, detail });
+            if (grant.expiresAt <= now())
+                ({ grant, release } = await usableGrant({ input, pass, detail }));
+        }
+        // A development session takes the deployment's place in the concurrency keys.
+        const releaseId = release.mode === 'published' ? release.deploymentId : release.devSessionId;
+        const lease = await admitted(() => options.admission.acquire({ environment: grant.environment, projectId: grant.projectId, deploymentId: releaseId, resources: grant.resources }, { ingress: { id: ingress.id, subjectHash, clientBucket: ingressClientBucket(clientIp) } }));
+        let requestContext;
+        try {
+            requestContext = signExternalGatewayContext({
+                privateKey: options.externalContext.privateKey, keyId: options.externalContext.keyId,
+                projectId: grant.projectId, environment: grant.environment, release, requestId,
+                method: request.method ?? 'GET', path: signedPath, serviceAccountId: grant.serviceAccountId, pass, passKid,
+                client: { ip: clientIp, ...observeUserAgent(request.headers['user-agent']), origin }, now: seconds(),
+            });
+        }
+        catch (error) {
+            void lease.release().catch(() => undefined);
+            throw error;
+        }
+        const attribution = { actorId: usageActor({ provider: pass.provider, subject: pass.subject, subjectHash }), ingressId: ingress.id, projectId: grant.projectId, environment: grant.environment };
+        return {
+            target: grant.mode === 'published'
+                ? { upstreamUrl: grant.upstreamUrl, upstreamAudience: grant.upstreamAudience, projectId: grant.projectId, deploymentId: grant.deploymentId }
+                : { kind: 'development', projectId: grant.projectId, environment: grant.environment, sessionId: grant.devSessionId },
+            requestContext,
+            timeoutMs: lease.timeoutMs,
+            bind: (response, abort) => { lease.bind(response, abort); },
+            ...(body ? { body } : {}),
+            usage: release.mode === 'published' ? { ...attribution, deploymentId: release.deploymentId } : { ...attribution, devSessionId: release.devSessionId },
+        };
+    }
+    return { preflight, exchange, logout, admit };
+}
+/**
+ * The usage actor: the context's `ext|<provider>|<subject>` when Atlas's actor grammar accepts it
+ * (no whitespace or control characters, ≤ 255), else the subject's hash, so one odd subject can
+ * never fail a whole usage batch.
+ */
+export function usageActor({ provider, subject, subjectHash }) {
+    const actor = externalSubject({ provider, subject });
+    return actor.length <= 255 && /^[^\s\p{Cc}]+$/u.test(actor) ? actor : externalSubject({ provider, subject: `sha256:${subjectHash}` });
+}

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;