@sequenceholdings/artifact-studio 0.3.1 → 0.5.0

package/dist/gateway/lattice-invoke.js

@@ -0,0 +1,245 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { z } from 'zod';
+import { isManagedServerInvokePath } from '../server/managed-server-path.js';
+import { ARTIFACT_CONTEXT_MAX_AGE_SECONDS, ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS } from '../server/request-context.js';
+import { normalizePublicOrigin } from '../tunnel/protocol.js';
+import { ArtifactAdmissionError } from './admission.js';
+import { GatewayControlError } from './control.js';
+import { invokeHostedArtifact } from './lattice-upstream.js';
+import { signGatewayContext } from './session.js';
+const requestSchema = z.object({
+    server: z.string().min(1).max(255),
+    path: z.string().refine(isManagedServerInvokePath, 'Invalid managed server path'),
+    principalSub: z.string().min(1).max(255),
+    body: z.unknown().optional(),
+    lattice: z.object({
+        runId: z.string().min(1).max(255),
+        nodeId: z.string().min(1).max(255),
+        stepId: z.string().min(1).max(255),
+        processId: z.string().min(1).max(255),
+    }).strict(),
+    requestId: z.string().min(1).max(255),
+    timeoutMs: z.number().int().positive().max(300_000),
+}).strict();
+const BODY_CAP = Math.floor(1.1 * 1024 * 1024);
+/** Lattice invoke, then the generic refusal for every other `/_sequence/` path. */
+export async function routeSequenceRequest(input) {
+    if (await routeLatticeInvoke(input))
+        return true;
+    if (input.request.url?.startsWith('/_sequence/')) {
+        write(input.response, 404, { error: 'not_found' });
+        return true;
+    }
+    return false;
+}
+export async function routeLatticeInvoke(input) {
+    if ((input.request.url ?? '').split('?')[0] !== '/_sequence/lattice-invoke')
+        return false;
+    if (input.request.method !== 'POST') {
+        write(input.response, 404, { error: 'not_found' });
+        return true;
+    }
+    await handleLatticeInvoke(input);
+    return true;
+}
+export async function handleLatticeInvoke(input) {
+    const startedAt = new Date().toISOString();
+    const startedMs = performance.now();
+    const presented = bearer(input.request);
+    if (!presented || !input.control.tokenMatches(presented)) {
+        write(input.response, 403, { error: 'lattice_invoke_denied' });
+        return;
+    }
+    let parsed;
+    try {
+        parsed = requestSchema.parse(JSON.parse((await readBody(input.request)).toString('utf8')));
+    }
+    catch {
+        write(input.response, 400, { error: 'invalid_lattice_invoke' });
+        return;
+    }
+    let grant;
+    try {
+        grant = await input.control.latticeInvoke({
+            server: parsed.server,
+            path: parsed.path,
+            principalSub: parsed.principalSub,
+            lattice: parsed.lattice,
+            requestId: parsed.requestId,
+        });
+    }
+    catch (error) {
+        const status = error instanceof GatewayControlError ? error.status : 502;
+        if (status === 503) {
+            write(input.response, 503, { error: 'lattice_invoke_unavailable' });
+            return;
+        }
+        if (status === 401 || status === 403 || status === 404) {
+            write(input.response, 403, { error: 'lattice_invoke_denied' });
+            return;
+        }
+        write(input.response, 502, { error: 'lattice_invoke_failed' });
+        return;
+    }
+    if (grant.principalSub !== parsed.principalSub || grant.path !== parsed.path) {
+        write(input.response, 403, { error: 'lattice_invoke_denied' });
+        return;
+    }
+    const observed = await invokeAdmittedLattice({ ...input, grant, parsed });
+    input.usage?.record(latticeUsageEvent({ grant, requestId: parsed.requestId, startedAt, startedMs, ...observed }));
+}
+/** The browser proxy records on response finish. This path returns first, so it records the upstream result itself. */
+async function invokeAdmittedLattice(input) {
+    const signal = callerAbortSignal(input);
+    let release = () => { };
+    try {
+        const admitted = await acquireLatticeAdmission({ admission: input.admission, grant: input.grant });
+        release = admitted.bind(input.response, () => input.response.destroy());
+        const session = syntheticSession(input.grant, input.parsed.lattice);
+        const requestContext = signGatewayContext({
+            session,
+            method: 'POST',
+            path: input.grant.path,
+            privateKey: input.privateKey,
+            keyId: input.keyId,
+            serviceAccountId: input.grant.serviceAccountId,
+            requestId: input.parsed.requestId,
+            ttlSeconds: Math.min(ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS, Math.max(ARTIFACT_CONTEXT_MAX_AGE_SECONDS, Math.ceil(input.parsed.timeoutMs / 1000))),
+        });
+        const result = await (input.invoke ?? invokeHostedArtifact)({
+            upstreamUrl: input.grant.upstreamUrl,
+            ...(input.grant.upstreamAudience ? { upstreamAudience: input.grant.upstreamAudience } : {}),
+            path: input.grant.path,
+            body: input.parsed.body ?? {},
+            requestContext,
+            timeoutMs: input.parsed.timeoutMs,
+            signal,
+        });
+        write(input.response, 200, { status: result.status, body: result.body });
+        return latticeOutcome({ aborted: signal.aborted, status: result.status });
+    }
+    catch (error) {
+        if (error instanceof ArtifactAdmissionError) {
+            writeAdmissionFailure(input.response, error);
+            return { outcome: 'error', httpStatus: error.status };
+        }
+        if (signal.aborted || input.response.writableEnded)
+            return { outcome: 'cancelled', httpStatus: 499 };
+        write(input.response, 502, { error: 'lattice_invoke_failed' });
+        return { outcome: 'error', httpStatus: 502 };
+    }
+    finally {
+        release();
+    }
+}
+function latticeOutcome({ aborted, status }) {
+    const httpStatus = status >= 100 && status <= 599 ? status : 502;
+    if (aborted)
+        return { outcome: 'cancelled', httpStatus };
+    return { outcome: httpStatus >= 400 ? 'error' : 'success', httpStatus };
+}
+function latticeUsageEvent(input) {
+    return {
+        // One id per gateway call. Retries of the same Lattice step reuse requestId,
+        // and a later attempt with a different outcome would be rejected as a
+        // conflicting duplicate. Delivery retries resend this same object.
+        eventId: `gateway:${randomUUID()}`,
+        requestId: input.requestId,
+        actorId: input.grant.principalSub,
+        projectId: input.grant.projectId,
+        deploymentId: input.grant.deploymentId,
+        environment: input.grant.environment,
+        startedAt: input.startedAt,
+        endedAt: new Date().toISOString(),
+        measurements: { requestCount: 1, durationMs: Math.max(0, Math.round(performance.now() - input.startedMs)) },
+        outcome: input.outcome,
+        httpStatus: input.httpStatus,
+    };
+}
+function writeAdmissionFailure(response, error) {
+    const capacity = error.status === 429;
+    write(response, capacity ? 429 : 503, {
+        error: capacity ? 'lattice_invoke_capacity' : 'lattice_invoke_unavailable',
+    });
+}
+/** Same per-app lease the browser proxy acquires. Missing admission fails closed. */
+async function acquireLatticeAdmission(input) {
+    if (!input.admission)
+        throw new ArtifactAdmissionError(503, 'admission_unavailable');
+    return input.admission.acquire({
+        environment: input.grant.environment,
+        projectId: input.grant.projectId,
+        deploymentId: input.grant.deploymentId,
+        resources: input.grant.resources,
+    });
+}
+/** The worker closing its connection must abort the Cloud Run POST still in flight. */
+function callerAbortSignal(input) {
+    const abort = new AbortController();
+    const stop = () => {
+        if (!input.response.writableEnded)
+            abort.abort();
+    };
+    if (typeof input.request.on === 'function')
+        input.request.on('aborted', stop);
+    if (typeof input.response.on === 'function')
+        input.response.on('close', stop);
+    return abort.signal;
+}
+function syntheticSession(grant, lattice) {
+    const publicOrigin = normalizePublicOrigin(grant.publicOrigin);
+    return {
+        version: 1,
+        kind: 'hosted',
+        sessionId: null,
+        deploymentId: grant.deploymentId,
+        frameworkBuildId: grant.frameworkBuildId,
+        projectId: grant.projectId,
+        ownerId: grant.principalSub,
+        environment: grant.environment,
+        publicOrigin,
+        expiresAt: Date.now() + 60_000,
+        published: true,
+        bridge: {
+            parentOrigin: publicOrigin,
+            channelId: 'lattice-invoke',
+            nonce: randomBytes(16).toString('hex'),
+        },
+        lattice,
+    };
+}
+function bearer(request) {
+    const header = request.headers.authorization;
+    if (typeof header !== 'string' || !header.startsWith('Bearer '))
+        return null;
+    return header.slice('Bearer '.length);
+}
+function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let length = 0;
+        request.on('data', (chunk) => {
+            length += chunk.byteLength;
+            if (length > BODY_CAP) {
+                reject(new Error('body too large'));
+                request.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.on('end', () => resolve(Buffer.concat(chunks)));
+        request.on('error', reject);
+    });
+}
+function write(response, status, body) {
+    if (response.headersSent)
+        return;
+    response.writeHead(status, {
+        ...(status >= 400 ? { connection: 'close' } : {}),
+        'content-type': 'application/json',
+        'cache-control': 'no-store',
+        'x-content-type-options': 'nosniff',
+    });
+    response.end(JSON.stringify(body));
+}

package/dist/gateway/lattice-upstream.d.ts

@@ -0,0 +1,38 @@
+import { request as httpsRequest } from 'node:https';
+export interface HostedArtifactInvocation {
+    upstreamUrl: string;
+    upstreamAudience?: string;
+    path: string;
+    body: unknown;
+    requestContext: string;
+    timeoutMs: number;
+    /** Wall-clock cancellation from the caller, combined with `timeoutMs`. */
+    signal?: AbortSignal;
+    identityTokenProvider?: (input: {
+        audience: string;
+        signal: AbortSignal;
+    }) => Promise<string>;
+    /** Tests supply the socket. Production uses `https.request`. */
+    dial?: typeof httpsRequest;
+    /** Tests supply the hop. Production dials the validated Cloud Run origin. */
+    dispatch?: (input: {
+        origin: URL;
+        path: string;
+        headers: Record<string, string>;
+        body: Buffer;
+        timeoutMs: number;
+        signal: AbortSignal;
+    }) => Promise<{
+        status: number;
+        contentType?: string;
+        body: Buffer;
+    }>;
+}
+/**
+ * Buffered POST into a hosted Next.js app. The destination must already be a
+ * Cloud Run origin Atlas resolved; this rejects anything else before dialing.
+ */
+export declare function invokeHostedArtifact(input: HostedArtifactInvocation): Promise<{
+    status: number;
+    body: unknown;
+}>;

package/dist/gateway/lattice-upstream.js

@@ -0,0 +1,136 @@
+import { request as httpsRequest } from 'node:https';
+import { assertSafeRequest } from '../tunnel/protocol.js';
+import { isManagedServerInvokePath } from '../server/managed-server-path.js';
+import { HOSTED_ARTIFACT_PROXY_LIMITS, cloudRunOrigin, hostedIdentityToken } from './hosted-proxy.js';
+const BODY_CAP = 1024 * 1024;
+/**
+ * Buffered POST into a hosted Next.js app. The destination must already be a
+ * Cloud Run origin Atlas resolved; this rejects anything else before dialing.
+ */
+export async function invokeHostedArtifact(input) {
+    if (!isManagedServerInvokePath(input.path))
+        throw new Error('Invalid managed server path');
+    const upstream = cloudRunOrigin(input.upstreamUrl);
+    const audience = input.upstreamAudience === undefined ? upstream : cloudRunOrigin(input.upstreamAudience);
+    assertSafeRequest('POST', input.path);
+    const payload = Buffer.from(JSON.stringify(input.body ?? {}));
+    if (payload.byteLength > BODY_CAP)
+        throw new Error('Managed server body exceeds 1 MiB');
+    const timeoutMs = Math.min(Math.max(input.timeoutMs, 1), HOSTED_ARTIFACT_PROXY_LIMITS.maxTimeoutMs);
+    const signal = invocationSignal({ timeoutMs, signal: input.signal });
+    const token = await withSignal((input.identityTokenProvider ?? hostedIdentityToken)({ audience: audience.origin, signal }), signal);
+    if (!/^[A-Za-z0-9._~-]+$/.test(token) || token.length > 16384)
+        throw new Error('Invalid platform token');
+    const headers = {
+        host: upstream.host,
+        'content-type': 'application/json',
+        'content-length': String(payload.byteLength),
+        'accept-encoding': 'identity',
+        'x-serverless-authorization': `Bearer ${token}`,
+        'x-sequence-artifact-context': input.requestContext,
+    };
+    const hop = { origin: upstream, path: input.path, headers, body: payload, timeoutMs, signal };
+    const response = await withSignal(input.dispatch ? input.dispatch(hop) : postCloudRun({ ...hop, dial: input.dial }), signal);
+    if (response.body.byteLength > BODY_CAP)
+        throw new Error('Managed server response exceeds 1 MiB');
+    return { status: response.status, body: decodeBody(response) };
+}
+function decodeBody(response) {
+    if (response.body.byteLength === 0)
+        return null;
+    const text = response.body.toString('utf8');
+    if (response.contentType?.split(';', 1)[0]?.trim().toLowerCase() !== 'application/json')
+        return text;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * `timeoutMs` is a deadline from the start of the call, not socket idle time.
+ * Streaming a chunk forever must not extend it. `signal` is the worker's
+ * disconnect; either one destroys the Cloud Run request.
+ */
+function invocationSignal({ timeoutMs, signal }) {
+    const deadline = AbortSignal.timeout(timeoutMs);
+    return signal ? AbortSignal.any([signal, deadline]) : deadline;
+}
+function invocationAbortError(signal) {
+    const reason = signal.reason;
+    if (reason instanceof Error && reason.name === 'TimeoutError')
+        return new Error('Managed server invocation timed out');
+    if (reason instanceof Error && /timed out/i.test(reason.message))
+        return reason;
+    return new Error('Managed server invocation cancelled');
+}
+function withSignal(work, signal) {
+    if (signal.aborted)
+        return Promise.reject(invocationAbortError(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(invocationAbortError(signal));
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then((value) => { signal.removeEventListener('abort', onAbort); resolve(value); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+}
+function postCloudRun(input) {
+    return new Promise((resolve, reject) => {
+        if (input.signal.aborted) {
+            reject(invocationAbortError(input.signal));
+            return;
+        }
+        let settled = false;
+        let incoming;
+        let onAbort = () => { };
+        const stop = () => input.signal.removeEventListener('abort', onAbort);
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            stop();
+            incoming?.destroy();
+            request.destroy();
+            reject(error instanceof Error ? error : new Error('Managed server invocation failed'));
+        };
+        const succeed = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            stop();
+            resolve(value);
+        };
+        const request = (input.dial ?? httpsRequest)(input.origin, {
+            method: 'POST',
+            path: input.path,
+            headers: input.headers,
+            timeout: input.timeoutMs,
+        }, (response) => {
+            incoming = response;
+            const chunks = [];
+            let length = 0;
+            response.on('data', (chunk) => {
+                length += chunk.byteLength;
+                if (length > BODY_CAP) {
+                    fail(new Error('Managed server response exceeds 1 MiB'));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on('end', () => {
+                const contentType = response.headers['content-type'];
+                succeed({
+                    status: response.statusCode ?? 502,
+                    ...(typeof contentType === 'string' ? { contentType } : {}),
+                    body: Buffer.concat(chunks),
+                });
+            });
+            response.on('error', fail);
+        });
+        onAbort = () => fail(invocationAbortError(input.signal));
+        input.signal.addEventListener('abort', onAbort, { once: true });
+        request.on('error', fail);
+        request.on('timeout', () => fail(new Error('Managed server invocation timed out')));
+        request.end(input.body);
+    });
+}

package/dist/gateway/server.d.ts

@@ -1,6 +1,7 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type TunnelLease, type TunnelBrokerOptions } from '../tunnel/index.js';
 import { ArtifactGatewayControl } from './control.js';
+import { type GatewaySessionSameSite } from './session.js';
 import { type ArtifactRequestAdmission } from './admission.js';
 import { type GatewayControlAdmission } from './control-admission.js';
 export interface ArtifactGatewayOptions {
@@ -9,6 +10,8 @@ export interface ArtifactGatewayOptions {
     parentOrigin: string;
     gatewayOrigin: string;
     sessionKey: string;
+    /** Defaults to `Strict`. `None` only for a local development gateway (see GatewaySessionSameSite). */
+    sessionCookieSameSite?: GatewaySessionSameSite;
     contextPrivateKey: string;
     contextKeyId: string;
     /** Unique per process, never a shared Cloud Run revision name. */

package/dist/gateway/server.js

@@ -6,6 +6,7 @@ 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 { routeSequenceRequest } from './lattice-invoke.js';
 import { admitHostedMutation, ReleaseAdmissionError } from './release-admission.js';
 import { ArtifactAdmissionError } from './admission.js';
 import { gatewayClientAddress } from './control-admission.js';
@@ -136,7 +137,7 @@ export function createArtifactGateway(options) {
         }
         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') }));
+        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. */
@@ -285,10 +286,8 @@ export function createArtifactGateway(options) {
                 await exchangeTicket({ request, response, origin });
                 return;
             }
-            if (request.url?.startsWith('/_sequence/')) {
-                json(response, 404, 'not_found');
+            if (await routeSequenceRequest({ request, response, control: options.control, privateKey: options.contextPrivateKey, keyId: options.contextKeyId, admission: options.admission, usage }))
                 return;
-            }
             if (['GET', 'HEAD'].includes(request.method ?? 'GET')) {
                 const url = new URL(request.url ?? '/', origin);
                 if (url.searchParams.has('__sequence_release')) {
@@ -319,7 +318,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');

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;
@@ -58,7 +71,7 @@ export declare function decodeGatewaySession(input: {
     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 }: {
+export declare function signGatewayContext({ session, method, path, privateKey, keyId, now, capabilities, serviceAccountId, requestId, ttlSeconds }: {
     session: GatewaySession;
     method: string;
     path: string;
@@ -68,5 +81,7 @@ export declare function signGatewayContext({ session, method, path, privateKey,
     capabilities?: string[];
     serviceAccountId?: string | null;
     requestId?: string;
+    /** Seconds until exp. Browser requests stay at 60; a Lattice run may last up to 300. */
+    ttlSeconds?: number;
 }): string;
 export {};

package/dist/gateway/session.js

@@ -1,6 +1,6 @@
 import { createHmac, createPrivateKey, randomUUID, sign, timingSafeEqual } from 'node:crypto';
 import { z } from 'zod';
-import { artifactRequestContextSchema } from '../server/request-context.js';
+import { ARTIFACT_CONTEXT_MAX_AGE_SECONDS, ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS, 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';
@@ -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;
@@ -123,13 +137,20 @@ export function decodeGatewaySession(input) {
     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() }) {
+export function signGatewayContext({ session, method, path, privateKey, keyId, now = Math.floor(Date.now() / 1000), capabilities = [], serviceAccountId = null, requestId = randomUUID(), ttlSeconds = ARTIFACT_CONTEXT_MAX_AGE_SECONDS }) {
+    const latticeRun = session.lattice?.runId ?? null;
+    const ceiling = latticeRun !== null && latticeRun !== ''
+        ? ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS
+        : ARTIFACT_CONTEXT_MAX_AGE_SECONDS;
+    if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > ceiling) {
+        throw new Error(`Artifact context lifetime must be 1..${ceiling} seconds`);
+    }
     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,
+        method, path, iat: now, exp: now + ttlSeconds, capabilities, serviceAccountId,
         bridge: session.bridge, theme: 'system',
         lattice: session.lattice ?? { runId: null, nodeId: null, stepId: null, processId: null },
         ...(session.taskRoutes ? { taskRoutes: session.taskRoutes } : {}),

package/dist/gateway-main.js

@@ -3,6 +3,7 @@ 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';
@@ -61,6 +62,7 @@ async function main() {
         parentOrigin: process.env.ARTIFACT_NEXT_PARENT_ORIGIN ?? new URL(controlUrl).origin,
         gatewayOrigin: required('ARTIFACT_NEXT_GATEWAY_URL'),
         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,

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

package/dist/manifest-custom-roles.d.ts

@@ -42,13 +42,23 @@ export declare function customRolesDeclared(block: ArtifactStudioCustomRoles | n
  * manifest's `capabilities.roles.capabilities` record, or already published
  * to the host's registry scope). Roles are never pinned — composition and
  * grants are live runtime configuration owned by the registry.
+ *
+ * `app/<application-id>/<key>` pins a capability an Application defines in
+ * `sequence.app.yml`. It needn't exist yet (members deploy first) and counts
+ * only while the host is a member of that Application.
  */
 export declare const CUSTOM_CAPABILITY_PIN_RE: RegExp;
 export declare const capabilityPinsSchema: z.ZodDefault<z.ZodArray<z.ZodString>>;
-export interface ParsedCapabilityPin {
+export type ParsedCapabilityPin = {
     scope: 'org' | 'project';
     key: string;
 }
+/** An Application capability: live only while the project is a member of `applicationId`. */
+ | {
+    scope: 'app';
+    applicationId: string;
+    key: string;
+};
 /** Split a pin into its scope and key. Assumes the pin grammar validated. */
 export declare function parseCapabilityPin(pin: string): ParsedCapabilityPin;
 /**