@sequenceholdings/artifact-studio 0.3.0 → 0.3.1

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') }));
+        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)) },
@@ -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

@@ -57,6 +57,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

@@ -122,12 +122,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,11 @@
 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 { 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 +35,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 +60,44 @@ 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,
         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/manifest-next.js

@@ -18,9 +18,21 @@ const apiPath = z.string().min(1).max(512).refine((value) => {
         return false;
     return value.split('/').slice(1).every((part, index, parts) => part !== '.' && part !== '..' && (part !== '' || index === parts.length - 1));
 }, 'API capability paths must be scoped below /api/ without encoded paths, traversal, queries, or fragments');
+// ORM references are what a delegated data token covers (orm-data-plane checkDataTokenScope):
+// a query needs namespace/table for every table it reads, and a mutation needs its
+// namespace/ops/Operation (or table coverage). Any other shape can never match, so it is
+// a typo to report here rather than a 403 at request time. The patterns mirror the ORM's
+// NAMESPACE_PATTERN, IDENTIFIER_PATTERN and GraphQL operation names; they are kept local so
+// browser code that parses manifests does not load the ORM package. platformUsers is the
+// ORM's built-in platform-user entity (PLATFORM_USER_TABLE), a logical key outside the
+// identifier pattern that queries traversing user relations read.
+const ormTableRef = /^[a-z][a-z0-9_]{0,40}\/(?:[a-z][a-z0-9_]{0,62}|platformUsers)$/;
+const ormOperationRef = /^[a-z][a-z0-9_]{0,40}\/ops\/[_A-Za-z][_0-9A-Za-z]*$/;
+const dataReadRef = boundedRef.refine((ref) => ormTableRef.test(ref), 'ORM read references use namespace/table');
+const dataWriteRef = boundedRef.refine((ref) => ormTableRef.test(ref) || ormOperationRef.test(ref), 'ORM write references use namespace/ops/Operation or namespace/table');
 const reachShape = {
     storage: storageScopesSchema.optional(),
-    data: z.strictObject({ read: z.array(boundedRef).max(256).default([]), write: z.array(boundedRef).max(256).default([]) }).prefault({}),
+    data: z.strictObject({ read: z.array(dataReadRef).max(256).default([]), write: z.array(dataWriteRef).max(256).default([]) }).prefault({}),
     api: z.strictObject({ read: z.array(apiPath).max(256).default([]), write: z.array(apiPath).max(256).default([]) }).prefault({}),
     functions: z.strictObject({ invoke: z.array(boundedRef).max(256).default([]) }).prefault({}),
 };

package/dist/next/bridge.js

@@ -103,7 +103,14 @@ export function createNextArtifactBridge(options) {
             if (ready)
                 return ready;
             if (!transport) {
-                transport = createNextArtifactWindowTransport();
+                // Report a missing Atlas parent frame like every other connection failure,
+                // so a caller's promise handler sees it instead of an uncaught throw.
+                try {
+                    transport = createNextArtifactWindowTransport();
+                }
+                catch (error) {
+                    return Promise.reject(error instanceof Error ? error : new Error('Artifact bridge transport unavailable'));
+                }
                 uninstallReleaseGuard = installArtifactReleaseGuard({ deploymentId: bootstrap.deploymentId ?? null });
             }
             ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });