@sequenceholdings/artifact-studio 0.6.4 → 0.6.7

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

package/dist/gateway/ingress-audit.js

@@ -0,0 +1,84 @@
+import { INGRESS_AUDIT_BATCH_MAX_EVENTS } from '../server/ingress-control-contract.js';
+export const INGRESS_AUDIT_FLUSH_INTERVAL_MS = 5_000;
+/** Refusals buffered between flushes; past this they are dropped and counted, never queued without bound. */
+export const INGRESS_AUDIT_CAPACITY = 5_000;
+/** Shutdown spends at most this on the final batch, so audit delivery never holds up tunnel cleanup. */
+export const INGRESS_AUDIT_CLOSE_BUDGET_MS = 2_000;
+/**
+ * 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 class IngressDenialAuditor {
+    options;
+    buffer = [];
+    dropped = 0;
+    timer;
+    flushing;
+    intervalMs;
+    capacity;
+    constructor(options) {
+        this.options = options;
+        this.intervalMs = options.intervalMs ?? INGRESS_AUDIT_FLUSH_INTERVAL_MS;
+        this.capacity = options.capacity ?? INGRESS_AUDIT_CAPACITY;
+    }
+    record(event) {
+        if (this.buffer.length >= this.capacity) {
+            this.dropped++;
+            return;
+        }
+        this.buffer.push(event);
+    }
+    /** Flushes every interval; the timer never keeps the process alive. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => { void this.flush(); }, this.intervalMs);
+        this.timer.unref();
+    }
+    /** One batch of at most 500 refusals, single-flight. Never rejects. */
+    flush() {
+        this.flushing ??= this.deliver().finally(() => { this.flushing = undefined; });
+        return this.flushing;
+    }
+    /**
+     * 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.
+     */
+    async close() {
+        clearInterval(this.timer);
+        this.timer = undefined;
+        let expire;
+        const budget = new Promise((resolve) => { expire = setTimeout(resolve, this.options.closeBudgetMs ?? INGRESS_AUDIT_CLOSE_BUDGET_MS); });
+        try {
+            await Promise.race([(this.flushing ?? Promise.resolve()).then(() => this.flush()), budget]);
+        }
+        finally {
+            clearTimeout(expire);
+        }
+        this.dropped += this.buffer.length;
+        this.buffer = [];
+        this.reportDropped();
+    }
+    async deliver() {
+        this.reportDropped();
+        const events = this.buffer.splice(0, INGRESS_AUDIT_BATCH_MAX_EVENTS);
+        if (events.length === 0)
+            return;
+        try {
+            await this.options.send({ events });
+        }
+        catch {
+            this.options.onFailure?.({ kind: 'ingress_audit_delivery_failed', count: events.length });
+        }
+    }
+    reportDropped() {
+        if (!this.dropped)
+            return;
+        this.options.onFailure?.({ kind: 'ingress_audit_dropped', count: this.dropped });
+        this.dropped = 0;
+    }
+}

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

@@ -0,0 +1,57 @@
+import type { IngressPassPayload } from './ingress-pass.js';
+/** What the gateway records of a caller's `User-Agent` (design §(f)): ≤ 512 characters, no control characters. */
+export declare const OBSERVED_USER_AGENT_MAX_LENGTH = 512;
+/**
+ * The user agent as the context carries it: control characters stripped, then truncated. The
+ * SHA-256 is of the header exactly as sent, so a truncated value still fingerprints the caller.
+ */
+export declare function observeUserAgent(raw: string | undefined): {
+    userAgent: string;
+    userAgentSha256: string;
+};
+/** The namespaced subject an external context and usage carry; ≤ 255 characters or refused at exchange. */
+export declare function externalSubject({ provider, subject }: {
+    provider: string;
+    subject: string;
+}): string;
+/**
+ * What an external context runs against: a published deployment, or (local development only,
+ * design §(j.3) step 5) the development session whose tunnel the gateway proxies over.
+ */
+export type ExternalContextRelease = {
+    mode: 'published';
+    deploymentId: string;
+} | {
+    mode: 'development';
+    devSessionId: string;
+};
+/**
+ * Signs the external (v2) context for one admitted ingress request (design §(f), "Steady state"
+ * step 8), with the gateway's external key, never the browser one. Lifetime ≤ 60 s. Validated
+ * against the strict v2 schema before signing, so the gateway never emits a context the SDK,
+ * sidecar or broker would refuse.
+ */
+export declare function signExternalGatewayContext({ privateKey, keyId, projectId, environment, release, requestId, method, path, serviceAccountId, pass, passKid, client, now, ttlSeconds, }: {
+    privateKey: string;
+    keyId: string;
+    projectId: string;
+    environment: string;
+    release: ExternalContextRelease;
+    /** Gateway-generated, never client-supplied. */
+    requestId: string;
+    method: string;
+    /** The canonical path plus raw query, as matched. */
+    path: string;
+    /** The grant's ingress service account. */
+    serviceAccountId: string;
+    pass: IngressPassPayload;
+    passKid: string;
+    client: {
+        ip: string;
+        userAgent: string;
+        userAgentSha256: string;
+        origin: string | null;
+    };
+    now?: number;
+    ttlSeconds?: number;
+}): string;

package/dist/gateway/ingress-context.js

@@ -0,0 +1,57 @@
+import { createHash, createPrivateKey, randomUUID, sign } from 'node:crypto';
+import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX, ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS, requestContextV2ExternalSchema, } from '../server/request-context.js';
+/** What the gateway records of a caller's `User-Agent` (design §(f)): ≤ 512 characters, no control characters. */
+export const OBSERVED_USER_AGENT_MAX_LENGTH = 512;
+/**
+ * The user agent as the context carries it: control characters stripped, then truncated. The
+ * SHA-256 is of the header exactly as sent, so a truncated value still fingerprints the caller.
+ */
+export function observeUserAgent(raw) {
+    const value = raw ?? '';
+    const stripped = value.replace(/[\u0000-\u001f\u007f]/g, '');
+    // Truncate on a code point boundary, never splitting a surrogate pair.
+    let userAgent = '';
+    for (const character of stripped) {
+        if (userAgent.length + character.length > OBSERVED_USER_AGENT_MAX_LENGTH)
+            break;
+        userAgent += character;
+    }
+    return { userAgent, userAgentSha256: createHash('sha256').update(value).digest('hex') };
+}
+/** The namespaced subject an external context and usage carry; ≤ 255 characters or refused at exchange. */
+export function externalSubject({ provider, subject }) {
+    return `ext|${provider}|${subject}`;
+}
+/**
+ * Signs the external (v2) context for one admitted ingress request (design §(f), "Steady state"
+ * step 8), with the gateway's external key, never the browser one. Lifetime ≤ 60 s. Validated
+ * against the strict v2 schema before signing, so the gateway never emits a context the SDK,
+ * sidecar or broker would refuse.
+ */
+export function signExternalGatewayContext({ privateKey, keyId, projectId, environment, release, requestId, method, path, serviceAccountId, pass, passKid, client, now = Math.floor(Date.now() / 1000), ttlSeconds = ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS, }) {
+    if (!keyId.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX))
+        throw new Error('External contexts are signed only with an external- key');
+    const context = requestContextV2ExternalSchema.parse({
+        v: 2, iss: 'atlas-artifact-gateway', aud: `artifact:${projectId}`,
+        sub: externalSubject({ provider: pass.provider, subject: pass.subject }),
+        projectId, environment, mode: release.mode,
+        deploymentId: release.mode === 'published' ? release.deploymentId : null,
+        devSessionId: release.mode === 'development' ? release.devSessionId : null,
+        requestId, jti: randomUUID(), method, path, iat: now, exp: now + ttlSeconds, serviceAccountId,
+        principal: {
+            kind: 'external', ingress: pass.ingress, provider: pass.provider, issuer: pass.issuer, subject: pass.subject,
+            clientId: pass.clientId, email: pass.email, emailVerified: pass.emailVerified, authTime: pass.authTime, amr: pass.amr,
+            tokenIssuedAt: pass.tokenIssuedAt,
+            pass: { id: pass.jti, kid: passKid, issuedAt: pass.iat, exchangeIp: pass.exchangeIp },
+            client,
+        },
+        crit: [], ext: {},
+    });
+    const key = createPrivateKey(privateKey);
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new Error('External context key must be Ed25519');
+    const header = Buffer.from(JSON.stringify({ alg: 'EdDSA', typ: 'JWT', kid: keyId })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify(context)).toString('base64url');
+    const signed = `${header}.${payload}`;
+    return `${signed}.${sign(null, Buffer.from(signed), key).toString('base64url')}`;
+}

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

@@ -0,0 +1,12 @@
+import type { ArtifactTunnelBroker } from '../tunnel/index.js';
+import type { IngressDevelopmentProxy } from './ingress.js';
+/**
+ * The ingress proxy for a development target (design §(j.3) step 3): the admitted request goes
+ * over the development session's tunnel instead of to a hosted deployment, under the hosted
+ * ingress proxy's rules: ingress request sanitising, the route's response policy decided on the
+ * head, the request and response caps, the idle-write timeout and the error-contract writer.
+ * The gateway wires it only when its own APP_ENV is `development`.
+ */
+export declare function createDevelopmentIngressProxy({ broker }: {
+    broker: Pick<ArtifactTunnelBroker, 'handleExternalHttp'>;
+}): IngressDevelopmentProxy;

package/dist/gateway/ingress-development.js

@@ -0,0 +1,23 @@
+import { INGRESS_PROXY_ERROR_CODES, INGRESS_PROXY_LIMITS, writeIngressResponseHead } from './ingress-response.js';
+/**
+ * The ingress proxy for a development target (design §(j.3) step 3): the admitted request goes
+ * over the development session's tunnel instead of to a hosted deployment, under the hosted
+ * ingress proxy's rules: ingress request sanitising, the route's response policy decided on the
+ * head, the request and response caps, the idle-write timeout and the error-contract writer.
+ * The gateway wires it only when its own APP_ENV is `development`.
+ */
+export function createDevelopmentIngressProxy({ broker }) {
+    return ({ request, response, target, publicOrigin, requestContext, body, limits, ingress }) => broker.handleExternalHttp({
+        request, response, requestContext, body, publicOrigin,
+        sessionId: target.sessionId, projectId: target.projectId, environment: target.environment,
+        appHeaders: ingress.requestHeaders,
+        maxRequestBytes: limits.maxRequestBytes,
+        maxResponseBytes: limits.maxResponseBytes,
+        timeoutMs: Math.min(limits.timeoutMs, INGRESS_PROXY_LIMITS.maxTimeoutMs),
+        idleWriteTimeoutMs: ingress.idleWriteTimeoutMs ?? INGRESS_PROXY_LIMITS.idleWriteTimeoutMs,
+        writeHead: ({ status, headers, declaredLength }) => writeIngressResponseHead({
+            response, status, method: request.method ?? 'GET', headers, declaredLength, responses: ingress.responses, maxResponseBytes: limits.maxResponseBytes,
+        }),
+        fail: (status) => ingress.errorWriter({ status, code: INGRESS_PROXY_ERROR_CODES[status] }),
+    });
+}

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

@@ -0,0 +1,44 @@
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { type ArtifactGatewayIngressOptions, type IngressDevelopmentProxy } from './ingress.js';
+import type { GatewayUsageReporter } from './usage.js';
+/**
+ * The ingress request pipeline (design §(e), "Steady state" steps 1-3 and 9). Order matters:
+ * canonical host, edge header, snapshot, client address, canonical path, declared route and
+ * CORS are all local, so nothing unauthenticated reaches Redis or Atlas before `handlers.admit`.
+ */
+export declare function createIngressHandler({ options, runtimeDomain, protocol, isDraining, onError, usage, proxyDevelopment }: {
+    /** Absent: the ingress branch is disabled and every ingress host answers 404. */
+    options: ArtifactGatewayIngressOptions | undefined;
+    runtimeDomain: string;
+    /** `https:` in every deployed environment; `http:` only for a loopback development gateway. */
+    protocol: string;
+    isDraining: () => boolean;
+    /** Counts refusal metrics and failures that are not a decided refusal (the gateway's own onError). */
+    onError?: (event: {
+        kind: string;
+    }) => void;
+    /** Records one observation per proxied ingress request, attributed to the external principal. */
+    usage?: Pick<GatewayUsageReporter, 'record'>;
+    /**
+     * Proxies over a development session's tunnel. Used only when `options.appEnv` is `development`
+     * (design §(j.3) step 3); anywhere else a development target is never proxied.
+     */
+    proxyDevelopment?: IngressDevelopmentProxy;
+}): {
+    handle: (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+    clientError: ({ error, socket }: {
+        error: NodeJS.ErrnoException & {
+            rawPacket?: Buffer;
+        };
+        socket: Duplex;
+    }) => boolean;
+};
+/**
+ * Installs `clientError` on the gateway server: an attributable ingress request gets the ingress
+ * reply, everything else Node's own. Tracks the response in flight on each socket for the check.
+ */
+export declare function handleClientErrors({ server, ingress }: {
+    server: Server;
+    ingress: Pick<ReturnType<typeof createIngressHandler>, 'clientError'>;
+}): void;