@sequenceholdings/artifact-studio 0.6.4 → 0.6.6

package/dist/gateway/hosted-proxy.d.ts

@@ -1,16 +1,17 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type HostedArtifactIngressMode } from './ingress-response.js';
+import { type HostedRuntimeTarget } from './runtime-transport.js';
+export { cloudRunOrigin, resolveHostedTarget, type HostedRuntimeTarget } from './runtime-transport.js';
 export declare const HOSTED_ARTIFACT_PROXY_LIMITS: Readonly<{
-    maxBodyBytes: number;
+    maxRequestBytes: number;
+    maxResponseBytes: number;
     timeoutMs: 60000;
     maxTimeoutMs: 300000;
 }>;
 export interface HostedArtifactProxyOptions {
     request: IncomingMessage;
     response: ServerResponse;
-    target: {
-        upstreamUrl: string;
-        /** Canonical service URL from the same provider record as the revision URL. */
-        upstreamAudience?: string;
+    target: HostedRuntimeTarget & {
         publicOrigin: string;
         projectId: string;
         deploymentId: string;
@@ -26,16 +27,18 @@ export interface HostedArtifactProxyOptions {
     resolveUpstream?: (input: {
         url: URL;
     }) => URL;
-    /** Approved request timeouts may exceed the default up to the platform cap. */
+    /** Approved request timeouts may exceed the default up to the platform cap (55 s on an ingress). */
     limits?: {
-        maxBodyBytes?: number;
+        maxRequestBytes?: number;
+        maxResponseBytes?: number;
         timeoutMs?: number;
     };
+    /** Present only for an external ingress request. */
+    ingress?: HostedArtifactIngressMode;
 }
 export declare function hostedIdentityToken(input: {
     audience: string;
     signal: AbortSignal;
 }): Promise<string>;
-export declare function cloudRunOrigin(value: string): URL;
 /** HTTP-only streaming hop. Authentication, CSRF and release admission happen before calling this. */
 export declare function proxyHostedArtifact(options: HostedArtifactProxyOptions): Promise<void>;

package/dist/gateway/hosted-proxy.js

@@ -3,9 +3,13 @@ import { request as httpsRequest } from 'node:https';
 import { Duplex, Readable, Transform } from 'node:stream';
 import { createBrotliDecompress, createGunzip, createInflate } from 'node:zlib';
 import { GoogleAuth } from 'google-auth-library';
-import { assertSafeRequest, isSharedCacheDirective, normalizePublicOrigin, sanitizeRequestHeaders, sanitizeResponseHeaders, SHARED_CACHE_REFUSAL } from '../tunnel/protocol.js';
+import { assertSafeRequest, normalizePublicOrigin, sanitizeRequestHeaders, sanitizeResponseHeaders } from '../tunnel/protocol.js';
+import { enforceBrowserCachePolicy, mergeFramePolicy, rewriteLocation } from './session-response.js';
 import { createReleaseFormTransform } from '../server/release-forms.js';
-export const HOSTED_ARTIFACT_PROXY_LIMITS = Object.freeze({ maxBodyBytes: 32 * 1024 * 1024, timeoutMs: 60_000, maxTimeoutMs: 300_000 });
+import { declaredContentLength, INGRESS_PROXY_ERROR_CODES, INGRESS_PROXY_LIMITS, writeIngressResponseHead } from './ingress-response.js';
+import { resolveHostedTarget } from './runtime-transport.js';
+export { cloudRunOrigin, resolveHostedTarget } from './runtime-transport.js';
+export const HOSTED_ARTIFACT_PROXY_LIMITS = Object.freeze({ maxRequestBytes: 32 * 1024 * 1024, maxResponseBytes: 32 * 1024 * 1024, timeoutMs: 60_000, maxTimeoutMs: 300_000 });
 const googleAuth = new GoogleAuth();
 const identityClients = new Map();
 async function defaultIdentityTokenProvider({ audience }) {
@@ -35,58 +39,12 @@ async function defaultIdentityTokenProvider({ audience }) {
 export function hostedIdentityToken(input) {
     return defaultIdentityTokenProvider(input);
 }
-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;
-}
 function stripCloudHeaders(headers) {
     for (const name of Object.keys(headers)) {
         if (name === 'x-serverless-authorization' || name.startsWith('x-goog-'))
             delete headers[name];
     }
 }
-function rewriteLocation({ location, upstream, publicOrigin }) {
-    if (!/^(?:https?:)?\/\//i.test(location))
-        return location;
-    const url = new URL(location, upstream);
-    return url.origin === upstream.origin ? `${publicOrigin}${url.pathname}${url.search}${url.hash}` : location;
-}
-function mergeFramePolicy({ application, trusted }) {
-    const policies = Array.isArray(application) ? application : [application];
-    const frames = Array.isArray(trusted) ? trusted : [trusted];
-    return [...policies.map((policy) => policy.split(';')
-            .filter((directive) => directive.trim().split(/\s/, 1)[0].toLowerCase() !== 'frame-ancestors')
-            .map((directive) => directive.trim()).filter(Boolean).join('; ')).filter(Boolean), ...frames];
-}
-function enforceBrowserCachePolicy({ request, response }) {
-    const path = (request.url ?? '/').split('?', 1)[0];
-    let staticAsset = false;
-    try {
-        const segments = path.slice(1).split('/').map((segment) => decodeURIComponent(segment));
-        staticAsset = path.startsWith('/_next/static/') && /\.(?:js|css)$/.test(path) &&
-            segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..' && !/[\\/]/.test(segment));
-    }
-    catch { /* Malformed or ambiguous asset paths retain the default no-store policy. */ }
-    const contentType = response.getHeader('content-type');
-    const mediaType = typeof contentType === 'string' ? contentType.split(';', 1)[0].trim().toLowerCase() : undefined;
-    const assetType = path.endsWith('.css') ? mediaType === 'text/css' : mediaType === 'text/javascript' || mediaType === 'application/javascript';
-    const revalidateAsset = staticAsset && ['GET', 'HEAD'].includes(request.method ?? 'GET') &&
-        (response.statusCode === 200 || response.statusCode === 304) &&
-        (assetType || (response.statusCode === 304 && contentType === undefined));
-    // Every protected reuse must reach authorization. Retain only private static
-    // JS/CSS bytes and validators; app output may never opt into browser/CDN TTLs.
-    for (const name of response.getHeaderNames()) {
-        if (isSharedCacheDirective(name))
-            response.removeHeader(name);
-    }
-    response.setHeader('cache-control', revalidateAsset ? 'private, no-cache' : 'private, no-store');
-    for (const [name, value] of Object.entries(SHARED_CACHE_REFUSAL))
-        response.setHeader(name, value);
-}
 /** HTTP-only streaming hop. Authentication, CSRF and release admission happen before calling this. */
 export function proxyHostedArtifact(options) {
     return new HostedExchange(options).run();
@@ -94,9 +52,11 @@ export function proxyHostedArtifact(options) {
 class HostedExchange {
     options;
     controller = new AbortController();
-    maximum;
+    requestMaximum;
+    responseMaximum;
     timeoutMs;
     timer;
+    idleWriteTimer;
     upload;
     outgoing;
     incoming;
@@ -108,8 +68,10 @@ class HostedExchange {
     resolve;
     constructor(options) {
         this.options = options;
-        this.maximum = this.boundLimit(options.limits?.maxBodyBytes, HOSTED_ARTIFACT_PROXY_LIMITS.maxBodyBytes);
-        this.timeoutMs = this.boundLimit(options.limits?.timeoutMs, HOSTED_ARTIFACT_PROXY_LIMITS.maxTimeoutMs, HOSTED_ARTIFACT_PROXY_LIMITS.timeoutMs);
+        this.requestMaximum = this.boundLimit(options.limits?.maxRequestBytes, HOSTED_ARTIFACT_PROXY_LIMITS.maxRequestBytes);
+        this.responseMaximum = this.boundLimit(options.limits?.maxResponseBytes, HOSTED_ARTIFACT_PROXY_LIMITS.maxResponseBytes);
+        const maxTimeoutMs = options.ingress ? INGRESS_PROXY_LIMITS.maxTimeoutMs : HOSTED_ARTIFACT_PROXY_LIMITS.maxTimeoutMs;
+        this.timeoutMs = this.boundLimit(options.limits?.timeoutMs, maxTimeoutMs, Math.min(HOSTED_ARTIFACT_PROXY_LIMITS.timeoutMs, maxTimeoutMs));
     }
     boundLimit(value, maximum, fallback = maximum) {
         return Number.isSafeInteger(value) && value !== undefined && value > 0 ? Math.min(value, maximum) : fallback;
@@ -129,16 +91,15 @@ class HostedExchange {
             request.once('error', this.finish);
             this.timer = setTimeout(() => this.fail(504), this.timeoutMs);
             this.timer.unref();
-            void this.prepare().catch(() => this.fail(502));
+            void this.prepare().catch(() => this.fail(this.unavailableStatus));
         });
     }
     async prepare() {
         const { request, response, target, requestContext } = this.options;
-        const upstream = cloudRunOrigin(target.upstreamUrl);
+        const { upstream, audience } = resolveHostedTarget({ target });
         // Cloud Run revision tags select immutable transport destinations, but IAM
         // requires the canonical service audience. Both are control-plane owned;
         // never derive this from a browser host, header or query parameter.
-        const audience = target.upstreamAudience === undefined ? upstream : cloudRunOrigin(target.upstreamAudience);
         const publicOrigin = normalizePublicOrigin(target.publicOrigin);
         try {
             assertSafeRequest(request.method ?? 'GET', request.url ?? '/');
@@ -151,30 +112,41 @@ class HostedExchange {
             return;
         }
         const length = request.headers['content-length'];
-        if (length !== undefined && (!/^(0|[1-9][0-9]*)$/.test(length) || Number(length) > this.maximum)) {
+        if (length !== undefined && (!/^(0|[1-9][0-9]*)$/.test(length) || Number(length) > this.requestMaximum)) {
             this.fail(413);
             return;
         }
-        const headers = sanitizeRequestHeaders(request.headers, publicOrigin);
-        stripCloudHeaders(headers);
-        const provider = this.options.identityTokenProvider ?? defaultIdentityTokenProvider;
-        const token = await provider({ audience: audience.origin, signal: this.controller.signal });
-        if (this.stopped)
+        let headers;
+        try {
+            headers = sanitizeRequestHeaders(request.headers, publicOrigin, this.options.ingress ? { mode: 'ingress', appHeaders: this.options.ingress.requestHeaders } : {});
+        }
+        catch {
+            // A header map the schema refuses is the caller's malformed request: an ingress caller must
+            // not retry it as an outage (§(i) `bad_request`); a session keeps its 502.
+            this.fail(this.options.ingress ? 400 : 502);
             return;
-        if (!/^[A-Za-z0-9._~-]+$/.test(token) || token.length > 16384)
-            throw new Error('Invalid platform token');
+        }
+        stripCloudHeaders(headers);
+        if (audience) {
+            const provider = this.options.identityTokenProvider ?? defaultIdentityTokenProvider;
+            const token = await provider({ audience: audience.origin, signal: this.controller.signal });
+            if (this.stopped)
+                return;
+            if (!/^[A-Za-z0-9._~-]+$/.test(token) || token.length > 16384)
+                throw new Error('Invalid platform token');
+            // Cloud Run removes this token's signature before passing it to user code.
+            // https://cloud.google.com/run/docs/authenticating/service-to-service
+            headers['x-serverless-authorization'] = `Bearer ${token}`;
+        }
         headers.host = upstream.host;
         // HTML forms receive release markers. Avoid compression when possible;
         // runtimes that still compress HTML are decoded as a bounded stream below.
         headers['accept-encoding'] = 'identity';
-        // Cloud Run removes this token's signature before passing it to user code.
-        // https://cloud.google.com/run/docs/authenticating/service-to-service
-        headers['x-serverless-authorization'] = `Bearer ${token}`;
         headers['x-sequence-artifact-context'] = requestContext;
         const destination = this.resolveDestination(upstream);
         const transport = destination.protocol === 'https:' ? httpsRequest : httpRequest;
         this.outgoing = transport(destination, { method: request.method, path: request.url, headers, maxHeaderSize: 32 * 1024 }, (incoming) => this.receive({ incoming, upstream, publicOrigin }));
-        this.outgoing.on('error', () => this.fail(502));
+        this.outgoing.on('error', () => this.fail(this.unavailableStatus));
         this.outgoing.once('upgrade', (_incoming, socket) => { socket.destroy(); this.fail(502); });
         this.outgoing.on('drain', () => { if (!this.stopped)
             this.upload?.resume(); });
@@ -182,8 +154,16 @@ class HostedExchange {
         this.upload.on('data', this.sendChunk);
         this.upload.once('end', () => this.outgoing?.end());
         this.upload.once('error', () => this.fail(502));
-        response.on('drain', () => { if (!this.stopped)
-            this.responseSource?.resume(); });
+        response.on('drain', () => {
+            clearTimeout(this.idleWriteTimer);
+            this.idleWriteTimer = undefined;
+            if (!this.stopped)
+                this.responseSource?.resume();
+        });
+    }
+    /** An unreachable app is an outage an ingress caller retries; a session keeps its 502. */
+    get unavailableStatus() {
+        return this.options.ingress ? 503 : 502;
     }
     resolveDestination(upstream) {
         const destination = this.options.resolveUpstream?.({ url: upstream }) ?? upstream;
@@ -197,7 +177,7 @@ class HostedExchange {
         if (this.stopped)
             return;
         this.sentBytes += chunk.byteLength;
-        if (this.sentBytes > this.maximum) {
+        if (this.sentBytes > this.requestMaximum) {
             this.fail(413);
             return;
         }
@@ -211,29 +191,24 @@ class HostedExchange {
             return;
         }
         try {
+            // Read before sanitising, which removes content-length as a hop header.
+            const declaredLength = declaredContentLength(incoming.headers['content-length']);
             const headers = sanitizeResponseHeaders(incoming.headers);
             stripCloudHeaders(headers);
-            delete headers['x-frame-options'];
-            if (typeof headers.location === 'string')
-                headers.location = rewriteLocation({ location: headers.location, upstream, publicOrigin });
             const response = this.options.response;
-            this.responseSource = this.prepareResponseSource({ incoming, headers, publicOrigin });
-            const framePolicy = response.getHeader('content-security-policy');
-            if (headers['content-security-policy'] && (typeof framePolicy === 'string' || Array.isArray(framePolicy))) {
-                headers['content-security-policy'] = mergeFramePolicy({ application: headers['content-security-policy'], trusted: framePolicy });
-            }
-            response.statusCode = incoming.statusCode ?? 502;
-            for (const [name, value] of Object.entries(headers)) {
-                const existing = name === 'set-cookie' ? response.getHeader(name) : undefined;
-                if (typeof existing === 'string' || Array.isArray(existing)) {
-                    // Rolling gateway leases and application cookies share the response,
-                    // but application cookies were stripped of reserved names above.
-                    response.setHeader(name, [...(Array.isArray(existing) ? existing : [existing]), ...(Array.isArray(value) ? value : [value])]);
+            if (this.options.ingress) {
+                // Decided on the head, before any body byte; never the HTML release-marker path.
+                if (!writeIngressResponseHead({
+                    response, status: incoming.statusCode ?? 502, method: this.options.request.method ?? 'GET', headers, declaredLength,
+                    responses: this.options.ingress.responses, maxResponseBytes: this.responseMaximum,
+                })) {
+                    this.fail(502);
+                    return;
                 }
-                else
-                    response.setHeader(name, value);
+                this.responseSource = incoming;
             }
-            enforceBrowserCachePolicy({ request: this.options.request, response });
+            else
+                this.responseSource = this.writeSessionResponseHead({ incoming, headers, upstream, publicOrigin });
             this.responseSource.on('data', this.receiveChunk);
             this.responseSource.once('end', () => response.end());
             this.responseSource.once('error', () => this.fail(502));
@@ -244,6 +219,30 @@ class HostedExchange {
             this.fail(502);
         }
     }
+    writeSessionResponseHead({ incoming, headers, upstream, publicOrigin }) {
+        delete headers['x-frame-options'];
+        if (typeof headers.location === 'string')
+            headers.location = rewriteLocation({ location: headers.location, upstream, publicOrigin });
+        const response = this.options.response;
+        const source = this.prepareResponseSource({ incoming, headers, publicOrigin });
+        const framePolicy = response.getHeader('content-security-policy');
+        if (headers['content-security-policy'] && (typeof framePolicy === 'string' || Array.isArray(framePolicy))) {
+            headers['content-security-policy'] = mergeFramePolicy({ application: headers['content-security-policy'], trusted: framePolicy });
+        }
+        response.statusCode = incoming.statusCode ?? 502;
+        for (const [name, value] of Object.entries(headers)) {
+            const existing = name === 'set-cookie' ? response.getHeader(name) : undefined;
+            if (typeof existing === 'string' || Array.isArray(existing)) {
+                // Rolling gateway leases and application cookies share the response,
+                // but application cookies were stripped of reserved names above.
+                response.setHeader(name, [...(Array.isArray(existing) ? existing : [existing]), ...(Array.isArray(value) ? value : [value])]);
+            }
+            else
+                response.setHeader(name, value);
+        }
+        enforceBrowserCachePolicy({ request: this.options.request, response });
+        return source;
+    }
     prepareResponseSource({ incoming, headers, publicOrigin }) {
         const contentType = headers['content-type'];
         if (typeof contentType !== 'string' || contentType.split(';', 1)[0].trim().toLowerCase() !== 'text/html')
@@ -269,7 +268,7 @@ class HostedExchange {
             source = source.pipe(decoder);
         }
         let decodedBytes = 0;
-        const maximum = this.maximum;
+        const maximum = this.responseMaximum;
         const limit = new Transform({ transform(chunk, _encoding, callback) {
                 decodedBytes += chunk.byteLength;
                 if (decodedBytes > maximum)
@@ -287,12 +286,18 @@ class HostedExchange {
         if (this.stopped)
             return;
         this.receivedBytes += chunk.byteLength;
-        if (this.receivedBytes > this.maximum) {
+        if (this.receivedBytes > this.responseMaximum) {
             this.fail(502);
             return;
         }
-        if (!this.options.response.write(chunk))
-            this.responseSource?.pause();
+        if (this.options.response.write(chunk))
+            return;
+        this.responseSource?.pause();
+        // Backpressure would otherwise hold the admission permit until the request timeout.
+        if (this.options.ingress && !this.idleWriteTimer) {
+            this.idleWriteTimer = setTimeout(() => this.fail(504), this.options.ingress.idleWriteTimeoutMs ?? INGRESS_PROXY_LIMITS.idleWriteTimeoutMs);
+            this.idleWriteTimer.unref();
+        }
     };
     fail(status) {
         if (this.stopped)
@@ -303,6 +308,8 @@ class HostedExchange {
         const response = this.options.response;
         if (response.headersSent)
             response.destroy();
+        else if (this.options.ingress)
+            this.options.ingress.errorWriter({ status, code: INGRESS_PROXY_ERROR_CODES[status] });
         else {
             // Do not send application cookies, encodings or redirects with a gateway error.
             for (const name of response.getHeaderNames()) {
@@ -321,6 +328,7 @@ class HostedExchange {
             return;
         this.stopped = true;
         clearTimeout(this.timer);
+        clearTimeout(this.idleWriteTimer);
         this.controller.abort();
         this.upload?.off('data', this.sendChunk);
         this.incoming?.off('data', this.receiveChunk);

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

@@ -0,0 +1,77 @@
+import { type AdmissionRedis } from './admission.js';
+/**
+ * Rate limiting and in-flight pools for the external ingress (design §(e) "Rate limiting and
+ * admission"). A separate instance from `GatewayControlAdmission`, with its own in-flight pools,
+ * so a flood of borrower exchanges can never return 503 on an Atlas user's `/_sequence/session`.
+ * The same fail-closed fixed-window counters: when Redis cannot answer, nothing is admitted.
+ */
+export type IngressInFlightPool = 'ingress-public' | 'ingress-grant';
+export interface IngressAdmissionLimits {
+    /** Fixed Redis-clock window shared by every class. */
+    windowMs: number;
+    preflight: {
+        perClient: number;
+    };
+    exchange: {
+        perClient: number;
+        perHost: number;
+        environment: number;
+    };
+    logout: {
+        perSubject: number;
+        perClient: number;
+    };
+    subject: {
+        perSubject: number;
+    };
+    app: {
+        perApp: number;
+    };
+    /** Outstanding Atlas calls one gateway process may hold per pool. */
+    pools: Record<IngressInFlightPool, number>;
+}
+/** The design's defaults; bindings may lower them in Atlas, never raise them here. */
+export declare const INGRESS_ADMISSION_LIMITS: Readonly<IngressAdmissionLimits>;
+/**
+ * The address an ingress caller is budgeted against: an IPv4 address as is, an IPv6 address as its
+ * /48 (design §(e)), since one IPv6 customer commonly controls a /48 or a /56.
+ */
+export declare function ingressClientBucket(address: string): string;
+export declare class IngressAdmission {
+    private readonly options;
+    private readonly namespace;
+    private readonly limits;
+    private readonly inFlight;
+    constructor(options: {
+        redis: AdmissionRedis;
+        namespace: string;
+        limits?: IngressAdmissionLimits;
+    });
+    /** `ingress-preflight`: per client address only, no in-flight permit (no Atlas call follows). */
+    preflight({ clientIp }: {
+        clientIp: string;
+    }): Promise<void>;
+    /** `ingress-exchange`: per client, per host and environment-wide; holds an `ingress-public` permit. */
+    exchange({ clientIp, host }: {
+        clientIp: string;
+        host: string;
+    }): Promise<() => void>;
+    /** `ingress-logout`: per subject and per client, after the pass verified; holds an `ingress-public` permit. */
+    logout({ provider, subjectHash, clientIp }: {
+        provider: string;
+        subjectHash: string;
+        clientIp: string;
+    }): Promise<() => void>;
+    /** `ingress-subject` and `ingress-app`, on verified pass fields; plain counters, no in-flight permit. */
+    request({ provider, subjectHash, projectId, ingressId }: {
+        provider: string;
+        subjectHash: string;
+        projectId: string;
+        ingressId: string;
+    }): Promise<void>;
+    /** Runs one Atlas call under a permit from `pool`; a full pool is 503, never a queue. */
+    withPool<T>(pool: IngressInFlightPool, work: () => Promise<T>): Promise<T>;
+    private withPermit;
+    private take;
+    private count;
+}

package/dist/gateway/ingress-admission.js

@@ -0,0 +1,150 @@
+import { createHash } from 'node:crypto';
+import { isIPv6 } from 'node:net';
+import { z } from 'zod';
+import { redisNamespaceSchema } from '../tunnel/redis-ownership.js';
+import { ArtifactAdmissionError } from './admission.js';
+/** The design's defaults; bindings may lower them in Atlas, never raise them here. */
+export const INGRESS_ADMISSION_LIMITS = Object.freeze({
+    windowMs: 10_000,
+    // Sized for many borrowers behind one carrier-grade NAT; no Atlas call follows a preflight.
+    preflight: Object.freeze({ perClient: 600 }),
+    exchange: Object.freeze({ perClient: 30, perHost: 300, environment: 3000 }),
+    logout: Object.freeze({ perSubject: 5, perClient: 30 }),
+    subject: Object.freeze({ perSubject: 60 }),
+    app: Object.freeze({ perApp: 2000 }),
+    pools: Object.freeze({ 'ingress-public': 32, 'ingress-grant': 64 }),
+});
+const limit = z.number().int().min(1).max(1_000_000);
+const limitsSchema = z.strictObject({
+    windowMs: z.number().int().min(1_000).max(3_600_000),
+    preflight: z.strictObject({ perClient: limit }),
+    exchange: z.strictObject({ perClient: limit, perHost: limit, environment: limit }),
+    logout: z.strictObject({ perSubject: limit, perClient: limit }),
+    subject: z.strictObject({ perSubject: limit }),
+    app: z.strictObject({ perApp: limit }),
+    pools: z.strictObject({ 'ingress-public': z.number().int().min(1).max(10_000), 'ingress-grant': z.number().int().min(1).max(10_000) }),
+});
+// Every key of one call shares the `{namespace}` hash tag, so the script stays single-slot on Redis
+// Cluster. Limits are ARGV[1..n], the window ARGV[n+1]. A refused attempt consumes nothing, so one
+// noisy client cannot spend a host's or the environment's budget.
+const ADMIT = `-- artifact-gateway-ingress-admission-v1
+local window = tonumber(ARGV[#KEYS + 1])
+for index, key in ipairs(KEYS) do
+  if tonumber(redis.call('GET', key) or '0') >= tonumber(ARGV[index]) then
+    local ttl = redis.call('PTTL', key)
+    if ttl < 0 then
+      redis.call('PEXPIRE', key, window)
+      ttl = window
+    end
+    return {0, ttl}
+  end
+end
+for _, key in ipairs(KEYS) do
+  if redis.call('INCR', key) == 1 or redis.call('PTTL', key) < 0 then redis.call('PEXPIRE', key, window) end
+end
+return {1, 0}`;
+const replySchema = z.tuple([z.number().int().min(0).max(1), z.number().int().min(0)]);
+/** A bounded, opaque Redis key segment: no caller-chosen bytes reach a key. */
+function keyPart(...values) {
+    return createHash('sha256').update(values.join('\u0000')).digest('hex').slice(0, 32);
+}
+/**
+ * The address an ingress caller is budgeted against: an IPv4 address as is, an IPv6 address as its
+ * /48 (design §(e)), since one IPv6 customer commonly controls a /48 or a /56.
+ */
+export function ingressClientBucket(address) {
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(address);
+    if (mapped)
+        return mapped[1];
+    if (!isIPv6(address))
+        return address;
+    const [head = '', tail] = address.toLowerCase().split('::');
+    const leading = head ? head.split(':') : [];
+    const trailing = tail ? tail.split(':') : [];
+    const groups = tail === undefined ? leading : [...leading, ...Array(Math.max(0, 8 - leading.length - trailing.length)).fill('0'), ...trailing];
+    return `${groups.slice(0, 3).map((group) => group.padStart(4, '0')).join(':')}::/48`;
+}
+export class IngressAdmission {
+    options;
+    namespace;
+    limits;
+    inFlight = { 'ingress-public': 0, 'ingress-grant': 0 };
+    constructor(options) {
+        this.options = options;
+        this.namespace = redisNamespaceSchema.parse(options.namespace);
+        this.limits = limitsSchema.parse(options.limits ?? INGRESS_ADMISSION_LIMITS);
+        const policy = options.redis.options;
+        if (policy.enableOfflineQueue !== false || policy.autoResendUnfulfilledCommands !== false || policy.maxRetriesPerRequest !== 0) {
+            throw new Error('Ingress admission Redis must disable offline queues, command replay and retries');
+        }
+    }
+    /** `ingress-preflight`: per client address only, no in-flight permit (no Atlas call follows). */
+    async preflight({ clientIp }) {
+        await this.count({ name: 'preflight', counters: [[`client:${keyPart(ingressClientBucket(clientIp))}`, this.limits.preflight.perClient]] });
+    }
+    /** `ingress-exchange`: per client, per host and environment-wide; holds an `ingress-public` permit. */
+    async exchange({ clientIp, host }) {
+        const { perClient, perHost, environment } = this.limits.exchange;
+        return this.withPermit('ingress-public', () => this.count({ name: 'exchange', counters: [
+                [`client:${keyPart(ingressClientBucket(clientIp))}`, perClient], [`host:${keyPart(host)}`, perHost], ['environment', environment],
+            ] }));
+    }
+    /** `ingress-logout`: per subject and per client, after the pass verified; holds an `ingress-public` permit. */
+    async logout({ provider, subjectHash, clientIp }) {
+        const { perSubject, perClient } = this.limits.logout;
+        return this.withPermit('ingress-public', () => this.count({ name: 'logout', counters: [
+                [`subject:${keyPart(provider, subjectHash)}`, perSubject], [`client:${keyPart(ingressClientBucket(clientIp))}`, perClient],
+            ] }));
+    }
+    /** `ingress-subject` and `ingress-app`, on verified pass fields; plain counters, no in-flight permit. */
+    async request({ provider, subjectHash, projectId, ingressId }) {
+        await this.count({ name: 'request', counters: [
+                [`subject:${keyPart(provider, subjectHash)}`, this.limits.subject.perSubject], [`app:${keyPart(projectId, ingressId)}`, this.limits.app.perApp],
+            ] });
+    }
+    /** Runs one Atlas call under a permit from `pool`; a full pool is 503, never a queue. */
+    async withPool(pool, work) {
+        const release = this.take(pool);
+        try {
+            return await work();
+        }
+        finally {
+            release();
+        }
+    }
+    async withPermit(pool, admit) {
+        const release = this.take(pool);
+        try {
+            await admit();
+            return release;
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+    }
+    take(pool) {
+        if (this.inFlight[pool] >= this.limits.pools[pool])
+            throw new ArtifactAdmissionError(503, 'admission_unavailable');
+        this.inFlight[pool]++;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.inFlight[pool]--;
+        };
+    }
+    async count({ name, counters }) {
+        const prefix = `artifact-gateway-ingress:{${this.namespace}}:${name}`;
+        let reply;
+        try {
+            reply = replySchema.parse(await this.options.redis.eval(ADMIT, counters.length, ...counters.map(([key]) => `${prefix}:${key}`), ...counters.map(([, maximum]) => maximum), this.limits.windowMs));
+        }
+        catch {
+            throw new ArtifactAdmissionError(503, 'admission_unavailable');
+        }
+        if (reply[0] !== 1)
+            throw new ArtifactAdmissionError(429, 'capacity_exceeded', Math.max(1, Math.ceil(reply[1] / 1000)));
+    }
+}

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

@@ -0,0 +1,46 @@
+import { type IngressAuditBatch, type IngressAuditEvent } from '../server/ingress-control-contract.js';
+export declare const INGRESS_AUDIT_FLUSH_INTERVAL_MS = 5000;
+/** Refusals buffered between flushes; past this they are dropped and counted, never queued without bound. */
+export declare const INGRESS_AUDIT_CAPACITY = 5000;
+/** Shutdown spends at most this on the final batch, so audit delivery never holds up tunnel cleanup. */
+export declare const INGRESS_AUDIT_CLOSE_BUDGET_MS = 2000;
+export type IngressAuditFailure = {
+    kind: 'ingress_audit_dropped' | 'ingress_audit_delivery_failed';
+    count: number;
+};
+/**
+ * Batches the refusals the gateway decided itself (edge, client address, CORS, a refused authentic
+ * pass, freshness) to `control/ingress-audit` every 5 s, at most 500 per call. Garbage and
+ * admission refusals are counted elsewhere and never reach it. Refusals an Atlas control
+ * route returned are never recorded here: Atlas already audited them. Best effort and bounded: a
+ * refusal flood can cost Atlas at most one batch per interval per gateway process, and a failed
+ * delivery is counted, not retried into a backlog.
+ */
+export declare class IngressDenialAuditor {
+    private readonly options;
+    private buffer;
+    private dropped;
+    private timer;
+    private flushing;
+    private readonly intervalMs;
+    private readonly capacity;
+    constructor(options: {
+        send: (batch: IngressAuditBatch) => Promise<void>;
+        onFailure?: (failure: IngressAuditFailure) => void;
+        intervalMs?: number;
+        capacity?: number;
+        closeBudgetMs?: number;
+    });
+    record(event: IngressAuditEvent): void;
+    /** Flushes every interval; the timer never keeps the process alive. */
+    start(): void;
+    /** One batch of at most 500 refusals, single-flight. Never rejects. */
+    flush(): Promise<void>;
+    /**
+     * Stops the timer and makes one final delivery attempt within the close budget: a slow or failing
+     * Atlas costs shutdown at most that long. Whatever is still buffered is dropped and counted.
+     */
+    close(): Promise<void>;
+    private deliver;
+    private reportDropped;
+}