@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/dist/gateway/server.js

@@ -0,0 +1,382 @@
+import { createPrivateKey, randomBytes, randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { z } from 'zod';
+import { ArtifactTunnelBroker } from '../tunnel/index.js';
+import { assertSafeRequest, normalizePublicOrigin } from '../tunnel/protocol.js';
+import { GatewayControlError } from './control.js';
+import { decodeGatewaySession, gatewaySessionCookies, renewGatewaySession, signGatewayContext } from './session.js';
+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) {
+    if (response.headersSent) {
+        response.destroy();
+        return;
+    }
+    if (status >= 400)
+        response.setHeader('connection', 'close');
+    response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+    response.end(JSON.stringify({ error }));
+}
+function rejectUpgrade(socket, status = 403) {
+    socket.end(`HTTP/1.1 ${status} Rejected\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+}
+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];
+        if (value === undefined)
+            return undefined;
+        const count = request.rawHeaders.filter((_, index) => index % 2 === 0 && request.rawHeaders[index].toLowerCase() === name).length;
+        if (typeof value !== 'string' || count !== 1 || !artifactNextFrameworkBuildIdSchema.safeParse(value).success)
+            throw new ReleaseAdmissionError('conflicting-release');
+        return value;
+    }
+    const deploymentId = uniqueHeader('x-sequence-artifact-release');
+    const frameworkHeader = uniqueHeader('x-deployment-id');
+    const query = new URL(request.url ?? '/', 'https://gateway.invalid').searchParams.getAll('dpl');
+    if (query.length > 1 || (query.length === 1 && !artifactNextFrameworkBuildIdSchema.safeParse(query[0]).success) ||
+        (frameworkHeader && query.length === 1 && frameworkHeader !== query[0]))
+        throw new ReleaseAdmissionError('conflicting-release');
+    return { deploymentId, frameworkBuildId: frameworkHeader ?? query[0] };
+}
+async function boundedJson(request) {
+    if (header(request, 'content-type')?.split(';', 1)[0] !== 'application/json')
+        throw new GatewayControlError(400);
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.from(chunk);
+        length += bytes.length;
+        if (length > 2048)
+            throw new GatewayControlError(413);
+        chunks.push(bytes);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+/** The bootstrap ticket travels in a fragment and a POST body, never a request URL or log. The page
+ * exchanges it only inside the Atlas frame; browsers without Fetch Metadata are covered by the script check. */
+function bootstrapPage({ response, parentOrigin }) {
+    const nonce = randomBytes(24).toString('base64');
+    response.writeHead(200, {
+        'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer',
+        'x-content-type-options': 'nosniff',
+        'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; connect-src 'self'; frame-ancestors ${parentOrigin}; base-uri 'none'; form-action 'none'`,
+    });
+    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);
+    if (!/^[a-z0-9.-]+$/.test(options.runtimeDomain) || options.runtimeDomain.includes('..'))
+        throw new Error('Invalid Artifact runtime domain');
+    // Validate signing and cookie keys before accepting traffic.
+    if (Buffer.byteLength(options.sessionKey) < 32)
+        throw new Error('Artifact gateway session key is too short');
+    if (createPrivateKey(options.contextPrivateKey).asymmetricKeyType !== 'ed25519')
+        throw new Error('Artifact context key must be Ed25519');
+    const activeRequests = new WeakMap();
+    const leases = new Map();
+    // 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))
+            throw new GatewayControlError(403);
+        const origin = `${new URL(gatewayOrigin).protocol}//${host}`;
+        const url = new URL(origin);
+        // One DNS label per application/session prevents suffix tricks and parent-domain cookies.
+        const suffix = `.${options.runtimeDomain}`;
+        if (url.hostname !== new URL(gatewayOrigin).hostname &&
+            (!url.hostname.endsWith(suffix) || !/^[a-z0-9-]+$/.test(url.hostname.slice(0, -suffix.length))))
+            throw new GatewayControlError(403);
+        if (url.port !== new URL(gatewayOrigin).port)
+            throw new GatewayControlError(403);
+        return origin;
+    }
+    async function authorize(request) {
+        const cached = activeRequests.get(request);
+        if (cached)
+            return cached;
+        const origin = requestOrigin(request);
+        assertSafeRequest(request.method ?? 'GET', request.url ?? '/');
+        const hints = releaseHints(request);
+        // Retained releases must belong to the valid main session's actor and scope.
+        const session = decodeGatewaySession({ cookie: header(request, 'cookie'), key: options.sessionKey, origin, ...hints });
+        if (!session || session.bridge.parentOrigin !== parentOrigin)
+            throw new GatewayControlError(403);
+        const method = request.method ?? 'GET';
+        const safeMethod = ['GET', 'HEAD', 'OPTIONS'].includes(method);
+        if ((!safeMethod || header(request, 'upgrade')) && header(request, 'origin') !== origin)
+            throw new GatewayControlError(403);
+        // 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,
+                capabilities: target.capabilities, serviceAccountId: target.serviceAccountId, requestId,
+            }) };
+        activeRequests.set(request, result);
+        return result;
+    }
+    const broker = new ArtifactTunnelBroker({
+        nodeId: options.nodeId, routing: options.routing, relay: options.relay, resolveLease: options.resolveLease,
+        authorizeTunnel: async (request) => {
+            if (draining || requestOrigin(request) !== gatewayOrigin || header(request, 'origin'))
+                return null;
+            const authorization = header(request, 'authorization'), sessionId = header(request, 'x-artifact-session-id');
+            const epoch = Number(header(request, 'x-artifact-tunnel-epoch'));
+            if (!authorization?.startsWith('Bearer ') || !sessionId || !Number.isSafeInteger(epoch) || epoch < 1)
+                return null;
+            const token = authorization.slice(7);
+            // 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;
+        },
+        authorizeRequest: async (request, sessionId) => {
+            const authorized = await authorize(request);
+            if (authorized.target.kind !== 'development' || authorized.target.sessionId !== sessionId)
+                return null;
+            return { ownerId: authorized.session.ownerId, publicOrigin: authorized.session.publicOrigin, requestContext: authorized.requestContext };
+        },
+        validateLease: async (lease) => {
+            const credential = leases.get(lease.sessionId);
+            // Remote browser nodes use the control-plane session check above; only the owner holds the tunnel credential.
+            if (!credential) {
+                const owner = await options.routing.lookup(lease.sessionId);
+                return Boolean(options.relay && owner && owner.nodeId !== options.nodeId && owner.epoch === lease.epoch);
+            }
+            if (credential.lease.epoch !== lease.epoch)
+                return false;
+            try {
+                // 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);
+                // Before the claim, an authorized newer epoch must reach routing.claim, which atomically fences
+                // the older owner, including a record a dead node left behind. Only a current owner is checked and renewed.
+                if (!owner || owner.epoch < lease.epoch)
+                    return true;
+                if (owner.nodeId !== options.nodeId || owner.epoch !== lease.epoch)
+                    return false;
+                if (options.renewLease && !await options.renewLease(lease))
+                    return false;
+                return true;
+            }
+            catch {
+                if (leases.get(lease.sessionId) === credential)
+                    leases.delete(lease.sessionId);
+                return false;
+            }
+        },
+        onTunnelClosed: lease => { if (leases.get(lease.sessionId)?.lease.epoch === lease.epoch)
+            leases.delete(lease.sessionId); },
+    });
+    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 (isReadinessRequest({ request, gatewayOrigin, runtimeDomain: options.runtimeDomain })) {
+                const ready = !draining && (options.ready?.() ?? true);
+                json(response, ready ? 200 : 503, ready ? 'ready' : 'unavailable');
+                return;
+            }
+            if (draining) {
+                response.setHeader('connection', 'close');
+                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
+                // link from exchanging someone else's ticket in the victim's browser (login CSRF).
+                const destination = header(request, 'sec-fetch-dest');
+                if (destination !== undefined && destination !== 'iframe')
+                    throw new GatewayControlError(403);
+                bootstrapPage({ response, parentOrigin });
+                return;
+            }
+            if (request.url === '/_sequence/session' && request.method === 'POST') {
+                await exchangeTicket({ request, response, origin });
+                return;
+            }
+            if (request.url?.startsWith('/_sequence/')) {
+                json(response, 404, 'not_found');
+                return;
+            }
+            if (['GET', 'HEAD'].includes(request.method ?? 'GET')) {
+                const url = new URL(request.url ?? '/', origin);
+                if (url.searchParams.has('__sequence_release')) {
+                    url.searchParams.delete('__sequence_release');
+                    request.url = url.pathname + url.search;
+                }
+            }
+            const { session, target, requestContext, requestId } = await authorize(request);
+            let reported = false;
+            const report = () => {
+                if (reported)
+                    return;
+                reported = true;
+                usage.record({
+                    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)) },
+                    outcome: !response.writableFinished ? 'cancelled' : response.statusCode >= 400 ? 'error' : 'success',
+                    httpStatus: response.statusCode,
+                });
+            };
+            response.once('finish', report);
+            response.once('close', report);
+            if (response.destroyed) {
+                report();
+                return;
+            }
+            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 }));
+            // 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');
+            response.setHeader('x-content-type-options', 'nosniff');
+            if (target.kind === 'development') {
+                await broker.handleHttp(request, response, target.sessionId);
+                return;
+            }
+            if (!options.admission)
+                throw new ArtifactAdmissionError(503, 'admission_unavailable');
+            const admitted = await options.admission.acquire({ environment: target.environment, projectId: target.projectId, deploymentId: target.deploymentId, resources: target.manifest?.server.resources });
+            admitted.bind(response, () => response.destroy());
+            if (response.destroyed)
+                return;
+            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'
+                    : 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');
+        });
+    });
+    server.on('upgrade', (request, socket, head) => {
+        void (async () => {
+            if (draining) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
+            if (request.url === '/_sequence/tunnel') {
+                await broker.handleTunnelUpgrade(request, socket, head);
+                return;
+            }
+            const authorized = await authorize(request);
+            if (authorized.target.kind !== 'development') {
+                rejectUpgrade(socket);
+                return;
+            }
+            await broker.handleWebSocketUpgrade(request, socket, head, authorized.target.sessionId);
+        })().catch(() => rejectUpgrade(socket));
+    });
+    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.close();
+        },
+    };
+}

package/dist/gateway/session.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+export declare const GATEWAY_SESSION_COOKIE = "__Host-atlas-artifact-session";
+export declare function gatewayReleaseCookieName(deploymentId: string): string;
+declare const sessionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    kind: z.ZodEnum<{
+        development: "development";
+        hosted: "hosted";
+    }>;
+    sessionId: z.ZodNullable<z.ZodString>;
+    deploymentId: z.ZodNullable<z.ZodString>;
+    frameworkBuildId: z.ZodNullable<z.ZodString>;
+    projectId: z.ZodString;
+    ownerId: z.ZodString;
+    environment: z.ZodString;
+    publicOrigin: z.ZodString;
+    expiresAt: z.ZodNumber;
+    maxExpiresAt: z.ZodOptional<z.ZodNumber>;
+    published: z.ZodBoolean;
+    bridge: z.ZodObject<{
+        parentOrigin: z.ZodString;
+        channelId: z.ZodString;
+        nonce: z.ZodString;
+    }, z.core.$strict>;
+    lattice: z.ZodOptional<z.ZodObject<{
+        runId: z.ZodNullable<z.ZodString>;
+        nodeId: z.ZodNullable<z.ZodString>;
+        stepId: z.ZodNullable<z.ZodString>;
+        processId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type GatewaySession = z.infer<typeof sessionSchema>;
+/** Active use renews the idle window, but never extends the original admission's eight-hour bound. */
+export declare function renewGatewaySession({ session, authorizedExpiresAt, now }: {
+    session: GatewaySession;
+    authorizedExpiresAt: number;
+    now?: number;
+}): GatewaySession | null;
+export declare function gatewaySessionCookies({ session, key, cookie, renewal, now }: {
+    session: GatewaySession;
+    key: string;
+    cookie?: string;
+    renewal?: boolean;
+    now?: number;
+}): string[];
+export declare function encodeGatewaySession({ session, key }: {
+    session: GatewaySession;
+    key: string;
+}): string;
+/** Retained releases preserve tabs, never a different login or runtime scope. */
+export declare function decodeGatewaySession(input: {
+    cookie: string | undefined;
+    key: string;
+    origin: string;
+    now?: number;
+    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;
+    path: string;
+    privateKey: string;
+    keyId: string;
+    now?: number;
+    capabilities?: string[];
+    serviceAccountId?: string | null;
+    requestId?: string;
+}): string;
+export {};

package/dist/gateway/session.js

@@ -0,0 +1,144 @@
+import { createHmac, createPrivateKey, randomUUID, sign, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+import { artifactRequestContextSchema } from '../server/request-context.js';
+import { normalizePublicOrigin } from '../tunnel/protocol.js';
+import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+export const GATEWAY_SESSION_COOKIE = '__Host-atlas-artifact-session';
+export function gatewayReleaseCookieName(deploymentId) {
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(deploymentId))
+        throw new Error('Invalid deployment identifier');
+    return `${GATEWAY_SESSION_COOKIE}-${deploymentId}`;
+}
+const origin = z.string().refine(value => { try {
+    return normalizePublicOrigin(value) === value;
+}
+catch {
+    return false;
+} });
+const id = z.string().min(1).max(255);
+const sessionSchema = z.object({
+    version: z.literal(1), kind: z.enum(['development', 'hosted']),
+    sessionId: id.nullable(), deploymentId: id.nullable(),
+    frameworkBuildId: artifactNextFrameworkBuildIdSchema.nullable(), projectId: id, ownerId: id,
+    environment: id, publicOrigin: origin, expiresAt: z.number().int().positive(), maxExpiresAt: z.number().int().positive().optional(), published: z.boolean(),
+    bridge: artifactRequestContextSchema.shape.bridge,
+    lattice: artifactRequestContextSchema.shape.lattice.optional(),
+    taskRoutes: artifactRequestContextSchema.shape.taskRoutes,
+}).strict().refine(value => value.kind === 'development'
+    ? value.sessionId !== null && value.deploymentId === null && value.frameworkBuildId === null && !value.published
+    : value.sessionId === null && value.deploymentId !== null && value.frameworkBuildId !== null);
+function sameSessionScope(left, right) {
+    return left.ownerId === right.ownerId && left.projectId === right.projectId &&
+        left.environment === right.environment && left.publicOrigin === right.publicOrigin &&
+        left.kind === right.kind && left.published === right.published;
+}
+/** Active use renews the idle window, but never extends the original admission's eight-hour bound. */
+export function renewGatewaySession({ session, authorizedExpiresAt, now = Date.now() }) {
+    if (session.expiresAt <= now || session.expiresAt - now > 15 * 60_000)
+        return null;
+    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() }) {
+    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 current = renewal ? decodeGatewaySession({ cookie, key, origin: session.publicOrigin, now }) : session;
+    if (!current || !sameSessionScope(current, session))
+        return [];
+    const sameTarget = current.deploymentId === session.deploymentId && current.sessionId === session.sessionId;
+    const cookies = sameTarget ? [`${GATEWAY_SESSION_COOKIE}=${value}`] : [];
+    if (session.deploymentId)
+        cookies.push(`${gatewayReleaseCookieName(session.deploymentId)}=${value}`);
+    if (!renewal) {
+        const selected = session.deploymentId ? gatewayReleaseCookieName(session.deploymentId) : '';
+        const retained = [...new Set((cookie ?? '').split(';').map(item => item.trim().split('=', 1)[0])
+                .filter(name => name.startsWith(`${GATEWAY_SESSION_COOKIE}-`) && name !== selected && /^[a-zA-Z0-9_-]+$/.test(name)))];
+        const sameScope = [], revoked = [];
+        for (const name of retained) {
+            const release = decodeSignedCookie({ cookie, key, origin: session.publicOrigin, now,
+                deploymentId: name.slice(GATEWAY_SESSION_COOKIE.length + 1) });
+            if (release && sameSessionScope(release, session))
+                sameScope.push(name);
+            else
+                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`);
+        }
+    }
+    return cookies;
+}
+function mac(value, key) {
+    if (Buffer.byteLength(key) < 32)
+        throw new Error('Gateway session key requires at least 32 bytes');
+    return createHmac('sha256', key).update(value).digest();
+}
+export function encodeGatewaySession({ session, key }) {
+    const payload = Buffer.from(JSON.stringify(sessionSchema.parse(session))).toString('base64url');
+    return `${payload}.${mac(payload, key).toString('base64url')}`;
+}
+function decodeSignedCookie({ cookie, key, origin: expectedOrigin, now = Date.now(), deploymentId }) {
+    try {
+        if (!cookie || cookie.length > 32768)
+            return null;
+        const name = deploymentId ? gatewayReleaseCookieName(deploymentId) : GATEWAY_SESSION_COOKIE;
+        const values = cookie.split(';').map(value => value.trim()).filter(value => value.startsWith(`${name}=`));
+        if (values.length !== 1)
+            return null;
+        const [payload, signature, extra] = values[0].slice(name.length + 1).split('.');
+        if (!payload || !signature || extra || !/^[A-Za-z0-9_-]+$/.test(payload) || !/^[A-Za-z0-9_-]+$/.test(signature))
+            return null;
+        const expected = mac(payload, key), actual = Buffer.from(signature, 'base64url');
+        if (actual.length !== expected.length || !timingSafeEqual(expected, actual))
+            return null;
+        const session = sessionSchema.parse(JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')));
+        return session.expiresAt > now && session.publicOrigin === expectedOrigin &&
+            (!deploymentId || session.deploymentId === deploymentId) ? session : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Retained releases preserve tabs, never a different login or runtime scope. */
+export function decodeGatewaySession(input) {
+    const current = decodeSignedCookie({ ...input, deploymentId: undefined });
+    if (!current)
+        return null;
+    const matchesBuild = (candidate) => !input.frameworkBuildId || candidate.frameworkBuildId === input.frameworkBuildId;
+    if (input.deploymentId) {
+        const selected = current.deploymentId === input.deploymentId ? current : decodeSignedCookie(input);
+        return selected && sameSessionScope(current, selected) && matchesBuild(selected) ? selected : null;
+    }
+    // Next's build id identifies immutable assets, not an activation. A rollback
+    // can reuse that build: prefer the current activation when it matches.
+    if (matchesBuild(current))
+        return current;
+    const names = [...new Set((input.cookie ?? '').split(';').map(item => item.trim().split('=', 1)[0])
+            .filter(name => name.startsWith(`${GATEWAY_SESSION_COOKIE}-`) && /^[a-zA-Z0-9_-]+$/.test(name)))];
+    const matches = names.map(name => decodeSignedCookie({ ...input,
+        deploymentId: name.slice(GATEWAY_SESSION_COOKIE.length + 1),
+    })).filter((candidate) => candidate !== null && sameSessionScope(current, candidate) && matchesBuild(candidate));
+    // Several retained activations may share identical output. Prefer the latest
+    // 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, 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 },
+        ...(session.taskRoutes ? { taskRoutes: session.taskRoutes } : {}),
+    });
+    const header = Buffer.from(JSON.stringify({ alg: 'EdDSA', typ: 'JWT', kid: keyId })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify(context)).toString('base64url');
+    const key = createPrivateKey(privateKey);
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new Error('Gateway context key must be Ed25519');
+    const signed = `${header}.${payload}`;
+    return `${signed}.${sign(null, Buffer.from(signed), key).toString('base64url')}`;
+}