@sequenceholdings/artifact-studio 0.3.0 → 0.4.0

package/dist/gateway/server.js

@@ -8,6 +8,8 @@ import { decodeGatewaySession, gatewaySessionCookies, renewGatewaySession, signG
 import { proxyHostedArtifact } from './hosted-proxy.js';
 import { admitHostedMutation, ReleaseAdmissionError } from './release-admission.js';
 import { ArtifactAdmissionError } from './admission.js';
+import { gatewayClientAddress } from './control-admission.js';
+import { gatewayAuthorizationKey, PositiveDecisionCache, tunnelAuthorizationKey } from './authorization-cache.js';
 import { GatewayUsageReporter } from './usage.js';
 import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
 function json(response, status, error) {
@@ -27,6 +29,14 @@ function header(request, key) {
     const value = request.headers[key];
     return typeof value === 'string' ? value : undefined;
 }
+/**
+ * Browsers mark every service worker script fetch, for registration and for update checks. A worker
+ * outlives the release that installed it on the stable application origin, so it could keep serving
+ * a rolled-back release's code and read the bootstrap ticket. No application origin may install one.
+ */
+function isServiceWorkerScript(request) {
+    return request.headers['service-worker'] !== undefined || request.headers['sec-fetch-dest'] === 'serviceworker';
+}
 function releaseHints(request) {
     function uniqueHeader(name) {
         const value = request.headers[name];
@@ -70,6 +80,23 @@ function bootstrapPage({ response, parentOrigin }) {
     });
     response.end(`<!doctype html><meta charset="utf-8"><title>Connecting application</title><p id="status">Connecting application…</p><script nonce="${nonce}">(() => {const ticket=new URLSearchParams(location.hash.slice(1)).get('ticket');history.replaceState(null,'',location.pathname);if(!ticket||window.top===window){document.getElementById('status').textContent='Open this application from Atlas.';return;}fetch('/_sequence/session',{method:'POST',credentials:'same-origin',headers:{'content-type':'application/json'},body:JSON.stringify({ticket})}).then(r=>{if(!r.ok)throw new Error();location.replace('/');}).catch(()=>{document.getElementById('status').textContent='This preview expired. Open it again from Atlas.';});})();</script>`);
 }
+/** Probes reach the container by its own address; an application host keeps its own /health route. */
+function isReadinessRequest({ request, gatewayOrigin, runtimeDomain }) {
+    if (request.method !== 'GET')
+        return false;
+    if (request.url === '/_sequence/health')
+        return true;
+    if (request.url !== '/health')
+        return false;
+    let hostname;
+    try {
+        hostname = new URL(`http://${header(request, 'host') ?? ''}`).hostname;
+    }
+    catch {
+        return true;
+    }
+    return hostname === new URL(gatewayOrigin).hostname || !hostname.endsWith(`.${runtimeDomain}`);
+}
 export function createArtifactGateway(options) {
     const parentOrigin = normalizePublicOrigin(options.parentOrigin);
     const gatewayOrigin = normalizePublicOrigin(options.gatewayOrigin);
@@ -82,8 +109,44 @@ export function createArtifactGateway(options) {
         throw new Error('Artifact context key must be Ed25519');
     const activeRequests = new WeakMap();
     const leases = new Map();
-    const usage = new GatewayUsageReporter({ send: event => options.control.usage(event), onFailure: event => options.onError?.(event) });
+    // Positive decisions only, for a few seconds: revocation reaches admitted browsers within the TTL.
+    const authorizations = new PositiveDecisionCache({ ttlMs: options.authorizationCacheTtlMs });
+    const tunnelAuthorizations = new PositiveDecisionCache({ ttlMs: options.authorizationCacheTtlMs });
+    const usage = new GatewayUsageReporter({ send: events => options.control.usage(events), onFailure: failure => options.onError?.(failure) });
     let draining = false;
+    /** Admission for the unauthenticated endpoints; the release frees the in-flight permit. */
+    async function admitControlCall(endpoint, request) {
+        if (!options.controlAdmission)
+            throw new ArtifactAdmissionError(503, 'admission_unavailable');
+        return options.controlAdmission.admit({ endpoint, client: gatewayClientAddress(request) });
+    }
+    /** One-use ticket exchange for a host-only session cookie. */
+    async function exchangeTicket({ request, response, origin }) {
+        if (header(request, 'origin') !== origin)
+            throw new GatewayControlError(403);
+        const { ticket } = z.object({ ticket: z.string().regex(/^[A-Za-z0-9_-]{43}$/) }).strict().parse(await boundedJson(request));
+        // Anyone can post a ticket: rate limit and admit before the exchange reaches Atlas.
+        const release = await admitControlCall('session', request);
+        let session;
+        try {
+            ({ session } = await options.control.bootstrap(ticket));
+        }
+        finally {
+            release();
+        }
+        if (session.publicOrigin !== origin || session.bridge.parentOrigin !== parentOrigin)
+            throw new GatewayControlError(403);
+        response.setHeader('set-cookie', gatewaySessionCookies({ session, key: options.sessionKey, cookie: header(request, 'cookie'), sameSite: options.sessionCookieSameSite }));
+        json(response, 200, 'connected');
+    }
+    /** Tunnel credential validation, shared by connection admission and every lease check. */
+    async function tunnelLease(credential) {
+        const lease = await tunnelAuthorizations.get({
+            key: tunnelAuthorizationKey(credential), load: () => options.control.tunnel(credential), notAfter: value => value.expiresAt,
+        });
+        // Brokers update lease expiry in place; never hand them the cached object.
+        return { ...lease };
+    }
     function requestOrigin(request) {
         const host = header(request, 'host');
         if (!host || /[\s/@\\?#]/.test(host))
@@ -111,9 +174,14 @@ export function createArtifactGateway(options) {
         if (!session || session.bridge.parentOrigin !== parentOrigin)
             throw new GatewayControlError(403);
         const method = request.method ?? 'GET';
-        if ((!['GET', 'HEAD', 'OPTIONS'].includes(method) || header(request, 'upgrade')) && header(request, 'origin') !== origin)
+        const safeMethod = ['GET', 'HEAD', 'OPTIONS'].includes(method);
+        if ((!safeMethod || header(request, 'upgrade')) && header(request, 'origin') !== origin)
             throw new GatewayControlError(403);
-        const target = await options.control.authorize(session);
+        // Every request is authorized, static chunks included. Reads reuse this replica's answer for the
+        // same session and target for up to the cache TTL (never past the target's own expiry). Mutations
+        // always ask Atlas, so revocation, suspension and a changed activation stop them immediately.
+        const lookup = { key: gatewayAuthorizationKey(session), load: () => options.control.authorize(session), notAfter: (value) => value.expiresAt };
+        const target = safeMethod ? await authorizations.get(lookup) : await authorizations.refresh(lookup);
         const requestId = randomUUID();
         const result = { session, target, requestId, requestContext: signGatewayContext({
                 session: { ...session, lattice: target.lattice, taskRoutes: target.taskRoutes }, method, path: request.url ?? '/', privateKey: options.contextPrivateKey, keyId: options.contextKeyId,
@@ -132,7 +200,15 @@ export function createArtifactGateway(options) {
             if (!authorization?.startsWith('Bearer ') || !sessionId || !Number.isSafeInteger(epoch) || epoch < 1)
                 return null;
             const token = authorization.slice(7);
-            const lease = await options.control.tunnel({ token, sessionId, epoch });
+            // Unauthenticated until Atlas validates the credential: admit before calling it.
+            const release = await admitControlCall('tunnel', request);
+            let lease;
+            try {
+                lease = await tunnelLease({ token, sessionId, epoch });
+            }
+            finally {
+                release();
+            }
             leases.set(sessionId, { token, lease });
             return lease;
         },
@@ -152,7 +228,9 @@ export function createArtifactGateway(options) {
             if (credential.lease.epoch !== lease.epoch)
                 return false;
             try {
-                const current = await options.control.tunnel({ token: credential.token, sessionId: lease.sessionId, epoch: lease.epoch });
+                // Per-request and periodic checks share the cached decision; revocation closes the tunnel
+                // at the first check after the cache window.
+                const current = await tunnelLease({ token: credential.token, sessionId: lease.sessionId, epoch: lease.epoch });
                 lease.expiresAt = current.expiresAt;
                 credential.lease = current;
                 const owner = await options.routing.lookup(lease.sessionId);
@@ -178,7 +256,7 @@ export function createArtifactGateway(options) {
     const server = createServer({ maxHeaderSize: 32 * 1024, requestTimeout: 60_000, headersTimeout: 15_000 }, (request, response) => {
         const startedAt = new Date().toISOString(), started = performance.now();
         void (async () => {
-            if ((request.url === '/_sequence/health' || request.url === '/health') && request.method === 'GET') {
+            if (isReadinessRequest({ request, gatewayOrigin, runtimeDomain: options.runtimeDomain })) {
                 const ready = !draining && (options.ready?.() ?? true);
                 json(response, ready ? 200 : 503, ready ? 'ready' : 'unavailable');
                 return;
@@ -188,6 +266,11 @@ export function createArtifactGateway(options) {
                 json(response, 503, 'gateway_draining');
                 return;
             }
+            // Refused before authorization, for development and hosted origins alike: nothing may register.
+            if (isServiceWorkerScript(request)) {
+                json(response, 403, 'service_workers_unsupported');
+                return;
+            }
             const origin = requestOrigin(request);
             if (request.url === '/_sequence/bootstrap' && request.method === 'GET') {
                 // Atlas only embeds this page (see frame-ancestors). Refusing top-level loads keeps a crafted
@@ -199,14 +282,7 @@ export function createArtifactGateway(options) {
                 return;
             }
             if (request.url === '/_sequence/session' && request.method === 'POST') {
-                if (header(request, 'origin') !== origin)
-                    throw new GatewayControlError(403);
-                const { ticket } = z.object({ ticket: z.string().regex(/^[A-Za-z0-9_-]{43}$/) }).strict().parse(await boundedJson(request));
-                const { session } = await options.control.bootstrap(ticket);
-                if (session.publicOrigin !== origin || session.bridge.parentOrigin !== parentOrigin)
-                    throw new GatewayControlError(403);
-                response.setHeader('set-cookie', gatewaySessionCookies({ session, key: options.sessionKey, cookie: header(request, 'cookie') }));
-                json(response, 200, 'connected');
+                await exchangeTicket({ request, response, origin });
                 return;
             }
             if (request.url?.startsWith('/_sequence/')) {
@@ -227,7 +303,7 @@ export function createArtifactGateway(options) {
                     return;
                 reported = true;
                 usage.record({
-                    eventId: `gateway:${requestId}`, requestId, projectId: target.projectId, environment: target.environment,
+                    eventId: `gateway:${requestId}`, requestId, actorId: session.ownerId, projectId: target.projectId, environment: target.environment,
                     ...(target.kind === 'development' ? { devSessionId: target.sessionId } : { deploymentId: target.deploymentId }),
                     startedAt, endedAt: new Date().toISOString(),
                     measurements: { requestCount: 1, durationMs: Math.max(0, Math.round(performance.now() - started)) },
@@ -243,7 +319,7 @@ export function createArtifactGateway(options) {
             }
             const renewed = renewGatewaySession({ session, authorizedExpiresAt: target.expiresAt });
             if (renewed)
-                response.setHeader('set-cookie', gatewaySessionCookies({ session: renewed, key: options.sessionKey, cookie: header(request, 'cookie'), renewal: true }));
+                response.setHeader('set-cookie', gatewaySessionCookies({ session: renewed, key: options.sessionKey, cookie: header(request, 'cookie'), renewal: true, sameSite: options.sessionCookieSameSite }));
             // Authorization precedes every response, including Next static assets and cached pages.
             response.setHeader('content-security-policy', `frame-ancestors ${session.bridge.parentOrigin}`);
             response.setHeader('referrer-policy', 'same-origin');
@@ -261,8 +337,11 @@ export function createArtifactGateway(options) {
             const { body } = await admitHostedMutation({ request, expectedDeploymentId: target.deploymentId, expectedFrameworkBuildId: target.frameworkBuildId, active: target.active, published: session.published });
             await proxyHostedArtifact({ request, response, target, requestContext, body, limits: { timeoutMs: admitted.timeoutMs } });
         })().catch(error => {
-            options.onError?.({ kind: error instanceof ReleaseAdmissionError ? 'release_mismatch' : error instanceof GatewayControlError ? 'authorization_denied' : 'request_failed' });
+            options.onError?.({ kind: error instanceof ReleaseAdmissionError ? 'release_mismatch' : error instanceof GatewayControlError ? 'authorization_denied'
+                    : error instanceof ArtifactAdmissionError ? 'admission_rejected' : 'request_failed' });
             const status = error instanceof ReleaseAdmissionError || error instanceof GatewayControlError || error instanceof ArtifactAdmissionError ? error.status : 400;
+            if (error instanceof ArtifactAdmissionError && error.retryAfterSeconds && !response.headersSent)
+                response.setHeader('retry-after', String(error.retryAfterSeconds));
             json(response, status === 401 || status === 404 ? 403 : status, error instanceof ReleaseAdmissionError ? 'update_required' : 'artifact_request_failed');
         });
     });
@@ -286,13 +365,18 @@ export function createArtifactGateway(options) {
     });
     return {
         server,
+        /** Observations recorded but not yet confirmed by Atlas: what a forced exit would lose. */
+        get pendingUsage() { return usage.pending; },
         async drain() {
             draining = true;
             server.closeIdleConnections();
             broker.close();
             leases.clear();
+            authorizations.clear();
+            tunnelAuthorizations.clear();
+            // The usage timer keeps flushing while in-flight requests finish.
             await new Promise(resolve => server.close(() => resolve()));
-            await usage.flush();
+            await usage.close();
         },
     };
 }

package/dist/gateway/session.d.ts

@@ -37,12 +37,25 @@ export declare function renewGatewaySession({ session, authorizedExpiresAt, now
     authorizedExpiresAt: number;
     now?: number;
 }): GatewaySession | null;
-export declare function gatewaySessionCookies({ session, key, cookie, renewal, now }: {
+/**
+ * `Strict` everywhere Atlas and the runtime domain are one site, as every deployed environment is.
+ * `None` is for the local stack only: Atlas on http://localhost is cross-site to
+ * https://*.apps.localhost, so browsers drop a `Strict` cookie inside the preview iframe.
+ * Partitioned keeps the relaxed cookie to Atlas's top-level site.
+ */
+export type GatewaySessionSameSite = 'Strict' | 'None';
+/** Reads ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE; only a development gateway may relax the cookie. */
+export declare function gatewaySessionSameSite({ value, appEnv }: {
+    value: string | undefined;
+    appEnv: string;
+}): GatewaySessionSameSite;
+export declare function gatewaySessionCookies({ session, key, cookie, renewal, now, sameSite }: {
     session: GatewaySession;
     key: string;
     cookie?: string;
     renewal?: boolean;
     now?: number;
+    sameSite?: GatewaySessionSameSite;
 }): string[];
 export declare function encodeGatewaySession({ session, key }: {
     session: GatewaySession;
@@ -57,6 +70,7 @@ export declare function decodeGatewaySession(input: {
     deploymentId?: string;
     frameworkBuildId?: string;
 }): GatewaySession | null;
+/** A fresh jti on every signature: a context names one originating request and its method. */
 export declare function signGatewayContext({ session, method, path, privateKey, keyId, now, capabilities, serviceAccountId, requestId }: {
     session: GatewaySession;
     method: string;

package/dist/gateway/session.js

@@ -39,9 +39,23 @@ export function renewGatewaySession({ session, authorizedExpiresAt, now = Date.n
     const expiresAt = Math.min(authorizedExpiresAt, session.maxExpiresAt ?? session.expiresAt);
     return expiresAt > session.expiresAt ? { ...session, expiresAt } : null;
 }
-export function gatewaySessionCookies({ session, key, cookie, renewal = false, now = Date.now() }) {
+/** Reads ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE; only a development gateway may relax the cookie. */
+export function gatewaySessionSameSite({ value, appEnv }) {
+    if (value === undefined || value === '' || value === 'strict')
+        return 'Strict';
+    if (value !== 'none')
+        throw new Error('ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE must be "strict" or "none"');
+    if (appEnv !== 'development')
+        throw new Error('ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE=none is only for a local development gateway');
+    return 'None';
+}
+function cookieAttributes(sameSite) {
+    return `Path=/; HttpOnly; Secure; ${sameSite === 'None' ? 'SameSite=None; Partitioned' : 'SameSite=Strict'}`;
+}
+export function gatewaySessionCookies({ session, key, cookie, renewal = false, now = Date.now(), sameSite = 'Strict' }) {
     const maxAge = Math.max(0, Math.floor((session.expiresAt - now) / 1000));
-    const value = `${encodeGatewaySession({ session, key })}; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=${maxAge}`;
+    const attributes = cookieAttributes(sameSite);
+    const value = `${encodeGatewaySession({ session, key })}; ${attributes}; Max-Age=${maxAge}`;
     const current = renewal ? decodeGatewaySession({ cookie, key, origin: session.publicOrigin, now }) : session;
     if (!current || !sameSessionScope(current, session))
         return [];
@@ -63,7 +77,7 @@ export function gatewaySessionCookies({ session, key, cookie, renewal = false, n
                 revoked.push(name);
         }
         for (const name of [...revoked, ...sameScope.slice(0, Math.max(0, sameScope.length - 5))]) {
-            cookies.push(`${name}=; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=0`);
+            cookies.push(`${name}=; ${attributes}; Max-Age=0`);
         }
     }
     return cookies;
@@ -122,12 +136,13 @@ export function decodeGatewaySession(input) {
     // admitted session deterministically; every candidate is reauthorized below.
     return matches.sort((left, right) => right.expiresAt - left.expiresAt || (left.deploymentId ?? '').localeCompare(right.deploymentId ?? ''))[0] ?? null;
 }
+/** A fresh jti on every signature: a context names one originating request and its method. */
 export function signGatewayContext({ session, method, path, privateKey, keyId, now = Math.floor(Date.now() / 1000), capabilities = [], serviceAccountId = null, requestId = randomUUID() }) {
     const context = artifactRequestContextSchema.parse({
         v: 1, iss: 'atlas-artifact-gateway', aud: `artifact:${session.projectId}`,
         sub: session.ownerId, projectId: session.projectId, environment: session.environment,
         mode: session.kind === 'development' ? 'development' : session.published ? 'published' : 'preview',
-        deploymentId: session.deploymentId, devSessionId: session.sessionId, requestId,
+        deploymentId: session.deploymentId, devSessionId: session.sessionId, requestId, jti: randomUUID(),
         method, path, iat: now, exp: now + 60, capabilities, serviceAccountId,
         bridge: session.bridge, theme: 'system',
         lattice: session.lattice ?? { runId: null, nodeId: null, stepId: null, processId: null },

package/dist/gateway/usage.d.ts

@@ -1,6 +1,8 @@
 export interface GatewayUsageEvent {
     eventId: string;
     requestId: string;
+    /** The user the gateway acted for: the session owner Atlas authorized for this request. */
+    actorId: string;
     projectId: string;
     deploymentId?: string;
     devSessionId?: string;
@@ -14,24 +16,55 @@ export interface GatewayUsageEvent {
     outcome: 'success' | 'error' | 'cancelled';
     httpStatus: number;
 }
-/** Bounded delivery of observations; accepted records are deduplicated durably by Atlas.
- * Process loss can drop pending observations, so these are not provider billing totals.
+export type GatewayUsageFailure = {
+    kind: 'usage_queue_full' | 'usage_delivery_failed' | 'usage_delivery_rejected' | 'usage_events_rejected' | 'usage_lost_on_shutdown';
+    count: number;
+};
+export interface GatewayUsageLimits {
+    /** Events buffered or in delivery; later observations are dropped and counted. */
+    capacity: number;
+    /** Events per control-plane call. Atlas accepts at most this many per batch. */
+    maxBatch: number;
+    /** Longest an observation waits in the buffer before a partial batch is sent. */
+    flushIntervalMs: number;
+    /** Concurrent batch deliveries. */
+    concurrency: number;
+}
+export declare const GATEWAY_USAGE_LIMITS: Readonly<GatewayUsageLimits>;
+/**
+ * Batched, bounded delivery of request observations: one control-plane call per `maxBatch` events or
+ * per flush interval, instead of one per request. Atlas deduplicates accepted records durably, so a
+ * retried batch is idempotent. Observations are telemetry, not billing totals. A crash loses at most
+ * the unflushed buffer (about one flush interval) and the batches in flight; a graceful drain flushes
+ * everything, and a forced exit reports `pending` as `usage_lost_on_shutdown`.
  */
 export declare class GatewayUsageReporter {
     private readonly options;
-    private readonly queue;
-    private readonly pending;
+    private readonly buffer;
+    private readonly inFlight;
+    private readonly limits;
+    private timer;
+    private dropped;
+    private closed;
     constructor(options: {
-        send: (event: GatewayUsageEvent) => Promise<void>;
-        onFailure: (event: {
-            kind: string;
-            requestId: string;
-        }) => void;
-        capacity?: number;
-        concurrency?: number;
+        send: (events: GatewayUsageEvent[]) => Promise<{
+            rejected: number;
+        }>;
+        onFailure: (failure: GatewayUsageFailure) => void;
+        limits?: Partial<GatewayUsageLimits>;
     });
+    /** Observations accepted but not yet confirmed by Atlas. */
+    get pending(): number;
     record(event: GatewayUsageEvent): void;
+    /**
+     * Stops accepting observations and delivers everything buffered; each batch is bounded by its
+     * retries. A process that must exit sooner reports `pending` as lost (see gateway-main).
+     */
+    close(): Promise<void>;
+    private drainAll;
+    private scheduleFlush;
+    private reportDropped;
+    /** Sends full batches, and a partial batch too when forced by the timer or shutdown. */
     private pump;
     private deliver;
-    flush(): Promise<void>;
 }

package/dist/gateway/usage.js

@@ -1,46 +1,116 @@
-/** Bounded delivery of observations; accepted records are deduplicated durably by Atlas.
- * Process loss can drop pending observations, so these are not provider billing totals.
+export const GATEWAY_USAGE_LIMITS = Object.freeze({ capacity: 10_000, maxBatch: 100, flushIntervalMs: 1_000, concurrency: 4 });
+const ATTEMPTS = 3;
+/**
+ * Batched, bounded delivery of request observations: one control-plane call per `maxBatch` events or
+ * per flush interval, instead of one per request. Atlas deduplicates accepted records durably, so a
+ * retried batch is idempotent. Observations are telemetry, not billing totals. A crash loses at most
+ * the unflushed buffer (about one flush interval) and the batches in flight; a graceful drain flushes
+ * everything, and a forced exit reports `pending` as `usage_lost_on_shutdown`.
  */
 export class GatewayUsageReporter {
     options;
-    queue = [];
-    pending = new Set();
+    buffer = [];
+    inFlight = new Map();
+    limits;
+    timer;
+    dropped = 0;
+    closed = false;
     constructor(options) {
         this.options = options;
+        this.limits = { ...GATEWAY_USAGE_LIMITS, ...options.limits };
+        for (const value of Object.values(this.limits)) {
+            if (!Number.isSafeInteger(value) || value < 1)
+                throw new Error('Gateway usage limits must be positive integers');
+        }
+    }
+    /** Observations accepted but not yet confirmed by Atlas. */
+    get pending() {
+        let count = this.buffer.length;
+        for (const size of this.inFlight.values())
+            count += size;
+        return count;
     }
     record(event) {
-        if (this.queue.length + this.pending.size >= (this.options.capacity ?? 1024)) {
-            this.options.onFailure({ kind: 'usage_queue_full', requestId: event.requestId });
+        if (this.closed) {
+            this.options.onFailure({ kind: 'usage_lost_on_shutdown', count: 1 });
             return;
         }
-        this.queue.push(event);
-        this.pump();
-    }
-    pump() {
-        while (this.queue.length && this.pending.size < (this.options.concurrency ?? 8)) {
-            const event = this.queue.shift();
-            const pending = this.deliver(event).finally(() => { this.pending.delete(pending); this.pump(); });
-            this.pending.add(pending);
+        if (this.pending >= this.limits.capacity) {
+            this.dropped++;
+            this.scheduleFlush();
+            return;
         }
+        this.buffer.push(event);
+        if (this.buffer.length >= this.limits.maxBatch)
+            this.pump();
+        else
+            this.scheduleFlush();
+    }
+    /**
+     * Stops accepting observations and delivers everything buffered; each batch is bounded by its
+     * retries. A process that must exit sooner reports `pending` as lost (see gateway-main).
+     */
+    async close() {
+        this.closed = true;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        await this.drainAll();
+        this.reportDropped();
     }
-    async deliver(event) {
-        for (let attempt = 0; attempt < 3; attempt++) {
+    async drainAll() {
+        while (this.buffer.length || this.inFlight.size) {
+            this.pump({ force: true });
+            if (this.inFlight.size)
+                await Promise.race(this.inFlight.keys());
+        }
+    }
+    scheduleFlush() {
+        if (this.timer || this.closed)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.reportDropped();
+            this.pump({ force: true });
+            if (this.buffer.length)
+                this.scheduleFlush();
+        }, this.limits.flushIntervalMs);
+        this.timer.unref();
+    }
+    reportDropped() {
+        if (!this.dropped)
+            return;
+        this.options.onFailure({ kind: 'usage_queue_full', count: this.dropped });
+        this.dropped = 0;
+    }
+    /** Sends full batches, and a partial batch too when forced by the timer or shutdown. */
+    pump({ force = false } = {}) {
+        while (this.inFlight.size < this.limits.concurrency && (this.buffer.length >= this.limits.maxBatch || (force && this.buffer.length))) {
+            const batch = this.buffer.splice(0, this.limits.maxBatch);
+            const delivery = this.deliver(batch).finally(() => {
+                this.inFlight.delete(delivery);
+                this.pump({ force: this.closed });
+            });
+            this.inFlight.set(delivery, batch.length);
+        }
+    }
+    async deliver(batch) {
+        for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
             try {
-                await this.options.send(event);
+                const { rejected } = await this.options.send(batch);
+                if (rejected > 0)
+                    this.options.onFailure({ kind: 'usage_events_rejected', count: rejected });
                 return;
             }
             catch (error) {
                 const status = typeof error === 'object' && error !== null && 'status' in error ? error.status : undefined;
-                if (typeof status === 'number' && status >= 400 && status < 500 && status !== 429)
-                    break;
-                if (attempt < 2)
-                    await new Promise(resolve => setTimeout(resolve, 100 * 2 ** attempt));
+                if (typeof status === 'number' && status >= 400 && status < 500 && status !== 429) {
+                    this.options.onFailure({ kind: 'usage_delivery_rejected', count: batch.length });
+                    return;
+                }
+                if (attempt < ATTEMPTS - 1)
+                    await new Promise((resolve) => setTimeout(resolve, 100 * 2 ** attempt));
             }
         }
-        this.options.onFailure({ kind: 'usage_delivery_failed', requestId: event.requestId });
-    }
-    async flush() {
-        while (this.pending.size)
-            await Promise.all(this.pending);
+        this.options.onFailure({ kind: 'usage_delivery_failed', count: batch.length });
     }
 }

package/dist/gateway-main.js

@@ -1,9 +1,12 @@
 import { randomUUID } from 'node:crypto';
+import { isIP } from 'node:net';
 import { Redis } from 'ioredis';
 import { ArtifactGatewayControl } from './gateway/control.js';
 import { createArtifactGateway } from './gateway/server.js';
+import { gatewaySessionSameSite } from './gateway/session.js';
 import { RedisTunnelOwnership, RedisTunnelRelay } from './tunnel/redis.js';
 import { ArtifactRequestAdmission } from './gateway/admission.js';
+import { GatewayControlAdmission } from './gateway/control-admission.js';
 function required(name) {
     const value = process.env[name];
     if (!value)
@@ -33,8 +36,21 @@ async function main() {
             process.stderr.write(`${JSON.stringify({ event: 'artifact_gateway.redis_unavailable', nodeId })}\n`);
         });
     await Promise.all(clients.map(client => client.connect()));
+    const log = (event) => process.stderr.write(`${JSON.stringify({ ...event, nodeId })}\n`);
+    // A flood of refused requests or forged frames must not become a log flood: count and report every 10 s.
+    const refusals = new Map();
+    const refuse = (kind) => { refusals.set(kind, (refusals.get(kind) ?? 0) + 1); };
+    setInterval(() => {
+        for (const [kind, count] of refusals)
+            log({ event: 'artifact_gateway.request', kind, count });
+        refusals.clear();
+    }, 10_000).unref();
+    const sessionKey = required('ARTIFACT_NEXT_SESSION_KEY');
     const ownership = new RedisTunnelOwnership({ command, namespace });
-    const relay = new RedisTunnelRelay({ nodeId, namespace, ownership, publisher, subscriber });
+    // Relay frames are authenticated with a subkey of the gateway-only session key, which every
+    // replica already shares and Atlas never holds.
+    const relay = new RedisTunnelRelay({ nodeId, namespace, ownership, publisher, subscriber, secret: sessionKey,
+        onRejectedFrame: () => refuse('relay_frame_rejected') });
     await relay.start();
     let stopping = false;
     subscriber.on('ready', () => { if (!stopping)
@@ -45,29 +61,45 @@ async function main() {
         runtimeDomain: required('ARTIFACT_NEXT_RUNTIME_DOMAIN'),
         parentOrigin: process.env.ARTIFACT_NEXT_PARENT_ORIGIN ?? new URL(controlUrl).origin,
         gatewayOrigin: required('ARTIFACT_NEXT_GATEWAY_URL'),
-        sessionKey: required('ARTIFACT_NEXT_SESSION_KEY'),
+        sessionKey,
+        sessionCookieSameSite: gatewaySessionSameSite({ value: process.env.ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE, appEnv: namespace }),
         contextPrivateKey: required('ARTIFACT_NEXT_CONTEXT_PRIVATE_KEY'),
         contextKeyId: required('ARTIFACT_NEXT_CONTEXT_KEY_ID'),
         nodeId, routing: ownership, relay,
         admission: new ArtifactRequestAdmission({ redis: command, namespace }),
+        controlAdmission: new GatewayControlAdmission({ redis: command, namespace }),
         resolveLease: sessionId => ownership.resolveLease(sessionId),
         renewLease: lease => ownership.renew(lease, nodeId),
         ready: () => clients.every(client => client.status === 'ready') && relay.isReady(),
-        onError: event => process.stderr.write(`${JSON.stringify({ event: 'artifact_gateway.request', ...event, nodeId })}\n`),
+        onError: event => { if (event.kind === 'admission_rejected')
+            refuse(event.kind);
+        else
+            log({ event: 'artifact_gateway.request', ...event }); },
     });
     const port = Number(process.env.PORT ?? '8080');
     if (!Number.isSafeInteger(port) || port < 1 || port > 65535)
         throw new Error('Invalid gateway PORT');
+    // Every interface in its container; a laptop run (scripts/local-stack.sh) keeps it on loopback.
+    const host = process.env.ARTIFACT_NEXT_GATEWAY_HOST ?? '0.0.0.0';
+    if (isIP(host) === 0)
+        throw new Error('Invalid ARTIFACT_NEXT_GATEWAY_HOST: expected an IP address');
     await new Promise((resolve, reject) => {
         gateway.server.once('error', reject);
-        gateway.server.listen(port, '0.0.0.0', resolve);
+        gateway.server.listen(port, host, resolve);
     });
     process.stdout.write(`${JSON.stringify({ event: 'artifact_gateway.ready', nodeId, port })}\n`);
     const stop = async () => {
         if (stopping)
             return;
         stopping = true;
-        const deadline = setTimeout(() => { gateway.server.closeAllConnections(); process.exit(1); }, 9_000);
+        const deadline = setTimeout(() => {
+            // Account for observations a forced exit discards; a graceful drain reports its own losses.
+            const lost = gateway.pendingUsage;
+            if (lost)
+                log({ event: 'artifact_gateway.request', kind: 'usage_lost_on_shutdown', count: lost });
+            gateway.server.closeAllConnections();
+            process.exit(1);
+        }, 9_000);
         deadline.unref();
         await gateway.drain();
         await relay.close();

package/dist/loopback.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Hosts a browser always resolves to this machine: the loopback literals, `localhost` and every
+ * `*.localhost` name (RFC 6761). Browsers treat plain HTTP on them as a secure context, which is
+ * what lets local development serve application origins without TLS.
+ */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/** `local` and the per-worktree `local:<name>` environments seq-studio discovers. */
+export declare function isLocalEnvironmentName(name: string): boolean;

package/dist/loopback.js

@@ -0,0 +1,13 @@
+/**
+ * Hosts a browser always resolves to this machine: the loopback literals, `localhost` and every
+ * `*.localhost` name (RFC 6761). Browsers treat plain HTTP on them as a secure context, which is
+ * what lets local development serve application origins without TLS.
+ */
+export function isLoopbackHostname(hostname) {
+    const host = hostname.toLowerCase();
+    return host === '127.0.0.1' || host === '[::1]' || host === 'localhost' || host.endsWith('.localhost');
+}
+/** `local` and the per-worktree `local:<name>` environments seq-studio discovers. */
+export function isLocalEnvironmentName(name) {
+    return name === 'local' || name.startsWith('local:');
+}