@sequenceholdings/artifact-studio 0.6.7 → 0.7.1

package/dist/gateway/server.js

@@ -1,4 +1,4 @@
-import { createPrivateKey, randomBytes, randomUUID } from 'node:crypto';
+import { createPrivateKey, randomUUID } from 'node:crypto';
 import { createServer } from 'node:http';
 import { z } from 'zod';
 import { ArtifactTunnelBroker } from '../tunnel/index.js';
@@ -6,16 +6,17 @@ 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 { bootstrapPage } from './bootstrap-page.js';
 import { routeSequenceRequest } from './lattice-invoke.js';
-import { admitHostedMutation, ReleaseAdmissionError } from './release-admission.js';
+import { admitHostedMutation, ReleaseAdmissionError, releaseHints } 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';
+import { gatewayElapsedMs, GatewayUsageReporter, snapshotGatewayTimings } from './usage.js';
 import { createDevelopmentIngressProxy } from './ingress-development.js';
 import { createIngressHandler, handleClientErrors } from './ingress-handler.js';
 import { resemblesIngressHost } from './ingress.js';
+import { serveStaticTarget, StaticArtifactFiles } from './static-files.js';
 function json(response, status, error) {
     if (response.headersSent) {
         response.destroy();
@@ -41,24 +42,6 @@ function header(request, key) {
 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);
@@ -73,16 +56,11 @@ async function boundedJson(request) {
     }
     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>`);
+/** Active use renews the session cookie within its admission bound. */
+function renewCookie({ options, request, response, session, target }) {
+    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, sameSite: options.sessionCookieSameSite }));
 }
 /** Probes reach the container by its own address; an application host keeps its own /health route. */
 function isReadinessRequest({ request, gatewayOrigin, runtimeDomain }) {
@@ -119,6 +97,7 @@ export function createArtifactGateway(options) {
     const usage = new GatewayUsageReporter({ send: events => options.control.usage(events), onFailure: failure => options.onError?.(failure) });
     let draining = false;
     const isIngressRequest = (request) => resemblesIngressHost({ rawHost: header(request, 'host'), runtimeDomain: options.runtimeDomain });
+    const staticFiles = options.staticFiles ?? new StaticArtifactFiles({ fetch: ({ deploymentId, path }) => options.control.staticFile({ deploymentId, path, parentOrigin }) });
     /** Admission for the unauthenticated endpoints; the release frees the in-flight permit. */
     async function admitControlCall(endpoint, request) {
         if (!options.controlAdmission)
@@ -132,15 +111,18 @@ export function createArtifactGateway(options) {
         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;
+        let session, target;
+        const asked = authorizations.reserve();
         try {
-            ({ session } = await options.control.bootstrap(ticket));
+            ({ session, target } = await options.control.bootstrap(ticket));
         }
         finally {
             release();
         }
         if (session.publicOrigin !== origin || session.bridge.parentOrigin !== parentOrigin)
             throw new GatewayControlError(403);
+        // Atlas just authorized this session: the document load that follows reuses it, not a second call.
+        authorizations.seed({ key: gatewayAuthorizationKey(session), value: target, asked, notAfter: value => value.expiresAt });
         response.setHeader('set-cookie', gatewaySessionCookies({ session, key: options.sessionKey, cookie: header(request, 'cookie'), sameSite: options.sessionCookieSameSite }));
         json(response, 200, 'connected');
     }
@@ -186,9 +168,12 @@ export function createArtifactGateway(options) {
         // 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 decision = safeMethod
+            ? authorizations.getObserved(lookup) : { promise: authorizations.refresh(lookup), source: 'refresh' };
+        const target = await decision.promise;
         const requestId = randomUUID();
-        const result = { session, target, requestId, requestContext: signGatewayContext({
+        // A static deployment has no server of its own to read a request context.
+        const result = { session, target, requestId, authorizationCache: decision.source, requestContext: target.kind === 'static' ? '' : 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,
             }) };
@@ -308,7 +293,14 @@ export function createArtifactGateway(options) {
                     request.url = url.pathname + url.search;
                 }
             }
-            const { session, target, requestContext, requestId } = await authorize(request);
+            const authorizationStarted = performance.now();
+            const { session, target, requestContext, requestId, authorizationCache } = await authorize(request);
+            // Immutable files Atlas already authorized this session for: no admission, context or usage.
+            if (target.kind === 'static') {
+                await serveStaticTarget({ request, response, target, files: staticFiles, renew: () => renewCookie({ options, request, response, session, target }), parentOrigin: session.bridge.parentOrigin });
+                return;
+            }
+            const gatewayTimings = { authorizationMs: gatewayElapsedMs(authorizationStarted), authorizationCache };
             let reported = false;
             const report = () => {
                 if (reported)
@@ -321,6 +313,7 @@ export function createArtifactGateway(options) {
                     measurements: { requestCount: 1, durationMs: Math.max(0, Math.round(performance.now() - started)) },
                     outcome: !response.writableFinished ? 'cancelled' : response.statusCode >= 400 ? 'error' : 'success',
                     httpStatus: response.statusCode,
+                    gatewayTimings: snapshotGatewayTimings(gatewayTimings),
                 });
             };
             response.once('finish', report);
@@ -329,9 +322,7 @@ export function createArtifactGateway(options) {
                 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, sameSite: options.sessionCookieSameSite }));
+            renewCookie({ options, request, response, session, target });
             // 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');
@@ -342,12 +333,14 @@ export function createArtifactGateway(options) {
             }
             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 });
+            const admissionStarted = performance.now();
+            const admitted = await options.admission.acquire({ environment: target.environment, projectId: target.projectId, deploymentId: target.deploymentId, resources: target.manifest?.server.resources })
+                .finally(() => { gatewayTimings.admissionMs = gatewayElapsedMs(admissionStarted); });
             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 } });
+            await proxyHostedArtifact({ request, response, target, requestContext, body, limits: { timeoutMs: admitted.timeoutMs }, gatewayTimings });
         })().catch(error => {
             options.onError?.({ kind: error instanceof ReleaseAdmissionError ? 'release_mismatch' : error instanceof GatewayControlError ? 'authorization_denied'
                     : error instanceof ArtifactAdmissionError ? 'admission_rejected' : 'request_failed' });

package/dist/gateway/session.d.ts

@@ -4,6 +4,7 @@ export declare function gatewayReleaseCookieName(deploymentId: string): string;
 declare const sessionSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     kind: z.ZodEnum<{
+        static: "static";
         development: "development";
         hosted: "hosted";
     }>;
@@ -38,16 +39,16 @@ export declare function renewGatewaySession({ session, authorizedExpiresAt, now
     now?: number;
 }): GatewaySession | null;
 /**
- * `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.
+ * `Strict` when every app origin sits under Atlas's own HTTPS host, so the iframe is same-site with
+ * its parent. Anywhere else — app origins on seqholdingsusercontent.com, or the local stack's
+ * http://localhost Atlas — a browser drops a `Strict` cookie inside the Atlas iframe, so the cookie
+ * is `SameSite=None; Partitioned`: the browser keys it to Atlas's top-level site and never sends it
+ * under any other. Cross-site writes are refused on `Origin` either way, not on SameSite.
  */
 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;
+export declare function gatewaySessionSameSite({ parentOrigin, runtimeDomain }: {
+    parentOrigin: string;
+    runtimeDomain: string;
 }): GatewaySessionSameSite;
 export declare function gatewaySessionCookies({ session, key, cookie, renewal, now, sameSite }: {
     session: GatewaySession;

package/dist/gateway/session.js

@@ -17,7 +17,7 @@ catch {
 } });
 const id = z.string().min(1).max(255);
 const sessionSchema = z.object({
-    version: z.literal(1), kind: z.enum(['development', 'hosted']),
+    version: z.literal(1), kind: z.enum(['development', 'hosted', 'static']),
     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(),
@@ -26,7 +26,10 @@ const sessionSchema = z.object({
     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);
+    // A static deployment has no Next build: its assets are named by the deployment itself.
+    : value.kind === 'static'
+        ? value.sessionId === null && value.deploymentId !== null && value.frameworkBuildId === null
+        : 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 &&
@@ -39,15 +42,10 @@ export function renewGatewaySession({ session, authorizedExpiresAt, now = Date.n
     const expiresAt = Math.min(authorizedExpiresAt, session.maxExpiresAt ?? session.expiresAt);
     return expiresAt > session.expiresAt ? { ...session, expiresAt } : null;
 }
-/** 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';
+export function gatewaySessionSameSite({ parentOrigin, runtimeDomain }) {
+    const parent = new URL(parentOrigin);
+    const underParent = runtimeDomain === parent.hostname || runtimeDomain.endsWith(`.${parent.hostname}`);
+    return parent.protocol === 'https:' && underParent ? 'Strict' : 'None';
 }
 function cookieAttributes(sameSite) {
     return `Path=/; HttpOnly; Secure; ${sameSite === 'None' ? 'SameSite=None; Partitioned' : 'SameSite=Strict'}`;

package/dist/gateway/static-files.d.ts

@@ -0,0 +1,66 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type GatewayTarget, type StaticArtifactFile } from './control.js';
+/** Default byte budget for cached static files on one gateway replica (the gateway runs with 1 GiB). */
+export declare const STATIC_CACHE_DEFAULT_BYTES: number;
+/**
+ * Files of static deployments, cached by deployment and path. A deployment's files never change,
+ * so an entry is valid until evicted (least recently used, bounded by bytes). Concurrent misses for
+ * one file share a single fetch. The page is never cached: Atlas renders it, and its bridge script
+ * follows Atlas releases.
+ */
+export declare class StaticArtifactFiles {
+    private readonly options;
+    private readonly entries;
+    private readonly inflight;
+    private bytes;
+    constructor(options: {
+        fetch: (input: {
+            deploymentId: string;
+            path: string;
+        }) => Promise<StaticArtifactFile>;
+        maxBytes?: number;
+    });
+    get cachedBytes(): number;
+    get({ deploymentId, path }: {
+        deploymentId: string;
+        path: string;
+    }): Promise<StaticArtifactFile & {
+        etag: string;
+    }>;
+    private remember;
+}
+/**
+ * The policy a static application runs under: the sandbox's former `<meta>` policy, now a header
+ * on the application's own origin (so `'self'` is the application, never Atlas), plus what a meta
+ * tag cannot express: `frame-ancestors` keeps the page inside Atlas.
+ */
+export declare function staticContentSecurityPolicy(parentOrigin: string): string;
+/**
+ * Where a static request is served from: `/_artifact/<deployment>/<file>` for assets, the page for
+ * every other path (in-app routes live in the hash or the page's own history). Null: not this
+ * deployment's file.
+ */
+export declare function staticFileForRequest({ url, deploymentId }: {
+    url: string;
+    deploymentId: string;
+}): string | null;
+/** Writes one authorized static file: GET or HEAD, revalidated on every use (each request is authorized). */
+export declare function sendStaticFile({ request, response, file, parentOrigin }: {
+    request: IncomingMessage;
+    response: ServerResponse;
+    file: StaticArtifactFile & {
+        etag: string;
+    };
+    parentOrigin: string;
+}): void;
+/** Answers one request for an authorized static target: reads only, and only this deployment's files. */
+export declare function serveStaticTarget({ request, response, target, files, renew, parentOrigin }: {
+    request: IncomingMessage;
+    response: ServerResponse;
+    target: Extract<GatewayTarget, {
+        kind: 'static';
+    }>;
+    files: Pick<StaticArtifactFiles, 'get'>;
+    renew: () => void;
+    parentOrigin: string;
+}): Promise<void>;

package/dist/gateway/static-files.js

@@ -0,0 +1,112 @@
+import { createHash } from 'node:crypto';
+import { GatewayControlError, STATIC_PAGE } from './control.js';
+/** Default byte budget for cached static files on one gateway replica (the gateway runs with 1 GiB). */
+export const STATIC_CACHE_DEFAULT_BYTES = 192 * 1024 * 1024;
+/**
+ * Files of static deployments, cached by deployment and path. A deployment's files never change,
+ * so an entry is valid until evicted (least recently used, bounded by bytes). Concurrent misses for
+ * one file share a single fetch. The page is never cached: Atlas renders it, and its bridge script
+ * follows Atlas releases.
+ */
+export class StaticArtifactFiles {
+    options;
+    entries = new Map();
+    inflight = new Map();
+    bytes = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    get cachedBytes() { return this.bytes; }
+    async get({ deploymentId, path }) {
+        if (path === STATIC_PAGE)
+            return withEtag(await this.options.fetch({ deploymentId, path }));
+        const key = `${deploymentId}/${path}`;
+        const hit = this.entries.get(key);
+        if (hit) {
+            // Refresh recency: a Map iterates in insertion order, so re-insert at the end.
+            this.entries.delete(key);
+            this.entries.set(key, hit);
+            return hit;
+        }
+        const pending = this.inflight.get(key);
+        if (pending)
+            return pending;
+        const load = this.options.fetch({ deploymentId, path }).then(file => {
+            const entry = withEtag(file);
+            this.remember(key, entry);
+            return entry;
+        }).finally(() => { this.inflight.delete(key); });
+        this.inflight.set(key, load);
+        return load;
+    }
+    remember(key, entry) {
+        const limit = this.options.maxBytes ?? STATIC_CACHE_DEFAULT_BYTES;
+        if (entry.body.length > limit)
+            return;
+        this.entries.set(key, entry);
+        this.bytes += entry.body.length;
+        for (const [oldest, value] of this.entries) {
+            if (this.bytes <= limit)
+                break;
+            this.entries.delete(oldest);
+            this.bytes -= value.body.length;
+        }
+    }
+}
+function withEtag(file) {
+    return { ...file, etag: file.etag ?? `"${createHash('sha256').update(file.body).digest('base64url')}"` };
+}
+/**
+ * The policy a static application runs under: the sandbox's former `<meta>` policy, now a header
+ * on the application's own origin (so `'self'` is the application, never Atlas), plus what a meta
+ * tag cannot express: `frame-ancestors` keeps the page inside Atlas.
+ */
+export function staticContentSecurityPolicy(parentOrigin) {
+    return [
+        "default-src 'none'", "script-src 'self' 'unsafe-inline' 'unsafe-eval'", "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data: blob: https:", "font-src 'self' data:", "connect-src 'self' blob:", "worker-src 'self' blob:",
+        "object-src blob:", "frame-src blob:", `frame-ancestors ${parentOrigin}`, "base-uri 'none'", "form-action 'none'",
+    ].join('; ');
+}
+/**
+ * Where a static request is served from: `/_artifact/<deployment>/<file>` for assets, the page for
+ * every other path (in-app routes live in the hash or the page's own history). Null: not this
+ * deployment's file.
+ */
+export function staticFileForRequest({ url, deploymentId }) {
+    const pathname = new URL(url, 'https://static.invalid').pathname;
+    const prefix = '/_artifact/';
+    if (!pathname.startsWith(prefix))
+        return STATIC_PAGE;
+    const [requested, ...rest] = pathname.slice(prefix.length).split('/');
+    if (requested !== deploymentId)
+        return null;
+    const file = rest.join('/');
+    return /^(?:bundle\.js|sourcemap\.json|chunks\/[A-Za-z0-9._-]{1,200})$/.test(file) ? file : null;
+}
+/** Writes one authorized static file: GET or HEAD, revalidated on every use (each request is authorized). */
+export function sendStaticFile({ request, response, file, parentOrigin }) {
+    const headers = {
+        'content-type': file.contentType, etag: file.etag, 'cache-control': 'private, no-cache',
+        'content-security-policy': staticContentSecurityPolicy(parentOrigin),
+        'x-content-type-options': 'nosniff', 'referrer-policy': 'same-origin',
+    };
+    if (request.headers['if-none-match'] === file.etag) {
+        response.writeHead(304, headers);
+        response.end();
+        return;
+    }
+    response.writeHead(200, { ...headers, 'content-length': String(file.body.length) });
+    response.end(request.method === 'HEAD' ? undefined : file.body);
+}
+/** Answers one request for an authorized static target: reads only, and only this deployment's files. */
+export async function serveStaticTarget({ request, response, target, files, renew, parentOrigin }) {
+    if (!['GET', 'HEAD'].includes(request.method ?? 'GET'))
+        throw new GatewayControlError(405);
+    const path = staticFileForRequest({ url: request.url ?? '/', deploymentId: target.deploymentId });
+    if (!path)
+        throw new GatewayControlError(404);
+    const file = await files.get({ deploymentId: target.deploymentId, path });
+    renew();
+    sendStaticFile({ request, response, file, parentOrigin });
+}

package/dist/gateway/usage.d.ts

@@ -1,3 +1,15 @@
+/** Closed, non-sensitive phase observations. An absent phase did not finish before reporting. */
+export interface GatewayTimings {
+    authorizationMs?: number;
+    authorizationCache?: 'hit' | 'shared' | 'load' | 'refresh';
+    admissionMs?: number;
+    identityTokenMs?: number;
+    /** Transport and app work until response headers, not pure app execution time. */
+    upstreamHeadersMs?: number;
+}
+export declare function gatewayElapsedMs(started: number): number;
+/** Detach the once-only usage event from work that can settle after cancellation. */
+export declare function snapshotGatewayTimings(timings: GatewayTimings): Readonly<GatewayTimings>;
 export interface GatewayUsageEvent {
     eventId: string;
     requestId: string;
@@ -22,6 +34,7 @@ export interface GatewayUsageEvent {
     };
     outcome: 'success' | 'error' | 'cancelled';
     httpStatus: number;
+    gatewayTimings?: Readonly<GatewayTimings>;
 }
 export type GatewayUsageFailure = {
     kind: 'usage_queue_full' | 'usage_delivery_failed' | 'usage_delivery_rejected' | 'usage_events_rejected' | 'usage_lost_on_shutdown';

package/dist/gateway/usage.js

@@ -1,3 +1,21 @@
+const MAX_GATEWAY_TIMING_MS = 600_000;
+export function gatewayElapsedMs(started) {
+    return Math.min(MAX_GATEWAY_TIMING_MS, Math.max(0, Math.round(performance.now() - started)));
+}
+/** Detach the once-only usage event from work that can settle after cancellation. */
+export function snapshotGatewayTimings(timings) {
+    const snapshot = {};
+    const durationKeys = ['authorizationMs', 'admissionMs', 'identityTokenMs', 'upstreamHeadersMs'];
+    for (const key of durationKeys) {
+        const value = timings[key];
+        if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= MAX_GATEWAY_TIMING_MS)
+            snapshot[key] = value;
+    }
+    const source = timings.authorizationCache;
+    if (source === 'hit' || source === 'shared' || source === 'load' || source === 'refresh')
+        snapshot.authorizationCache = source;
+    return Object.freeze(snapshot);
+}
 export const GATEWAY_USAGE_LIMITS = Object.freeze({ capacity: 10_000, maxBatch: 100, flushIntervalMs: 1_000, concurrency: 4 });
 const ATTEMPTS = 3;
 /**

package/dist/gateway-main.js

@@ -2,6 +2,8 @@ import { randomUUID } from 'node:crypto';
 import { isIP } from 'node:net';
 import { Redis } from 'ioredis';
 import { ArtifactGatewayControl } from './gateway/control.js';
+import { resolveGatewayControlConfig } from './gateway/control-config.js';
+import { hostedIdentityToken } from './gateway/hosted-proxy.js';
 import { createArtifactGateway } from './gateway/server.js';
 import { gatewaySessionSameSite } from './gateway/session.js';
 import { RedisTunnelOwnership, RedisTunnelRelay } from './tunnel/redis.js';
@@ -58,9 +60,9 @@ async function main() {
     let stopping = false;
     subscriber.on('ready', () => { if (!stopping)
         void relay.start().catch(() => undefined); });
-    const controlUrl = required('ARTIFACT_NEXT_CONTROL_PLANE_URL');
+    const controlConfig = resolveGatewayControlConfig({ env: process.env, identityToken: hostedIdentityToken });
     const controlToken = required('ARTIFACT_NEXT_CONTROL_TOKEN');
-    const control = new ArtifactGatewayControl({ url: controlUrl, token: controlToken });
+    const control = new ArtifactGatewayControl({ url: controlConfig.url, token: controlToken, identity: controlConfig.identity });
     const contextPrivateKey = required('ARTIFACT_NEXT_CONTEXT_PRIVATE_KEY');
     const contextKeyId = required('ARTIFACT_NEXT_CONTEXT_KEY_ID');
     const admission = new ArtifactRequestAdmission({ redis: command, namespace });
@@ -73,13 +75,14 @@ async function main() {
         else
             refuse(failure.kind); },
     });
+    const runtimeDomain = required('ARTIFACT_NEXT_RUNTIME_DOMAIN');
     const gateway = createArtifactGateway({
         control,
-        runtimeDomain: required('ARTIFACT_NEXT_RUNTIME_DOMAIN'),
-        parentOrigin: process.env.ARTIFACT_NEXT_PARENT_ORIGIN ?? new URL(controlUrl).origin,
+        runtimeDomain,
+        parentOrigin: controlConfig.parentOrigin,
         gatewayOrigin: required('ARTIFACT_NEXT_GATEWAY_URL'),
         sessionKey,
-        sessionCookieSameSite: gatewaySessionSameSite({ value: process.env.ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE, appEnv: namespace }),
+        sessionCookieSameSite: gatewaySessionSameSite({ parentOrigin: controlConfig.parentOrigin, runtimeDomain }),
         contextPrivateKey,
         contextKeyId,
         nodeId, routing: ownership, relay,

package/dist/git-clone.d.ts

@@ -1,5 +1,3 @@
-/** Read the git PAT from the environment (`ATLAS_GIT_PAT`), trimmed. */
-export declare function resolveGitPatFromEnv(): string | undefined;
 /** Full or abbreviated hex SHAs — not valid as `git clone --branch`. */
 export declare function looksLikeCommitSha(ref: string): boolean;
 /**
@@ -20,7 +18,7 @@ export type RunGitClone = (args: {
      * default branch in full, then check the SHA out.
      */
     depth?: number;
-    /** PAT used as Basic-auth password (username `git`). */
+    /** Login access token used as Basic-auth password (username `git`). */
     pat: string;
     /** Hard ceiling before the git child is killed (default 5m). */
     timeoutMs?: number;

package/dist/git-clone.js

@@ -5,20 +5,15 @@
  * re-exports it from `src/repos/git-clone.ts` so the `repos` tool and the
  * artifact `--repo` deploy path share one clone path.
  *
- * Credentials are supplied via an ephemeral GIT_ASKPASS script so the PAT
+ * Credentials are supplied via an ephemeral GIT_ASKPASS script so the token
  * never lands in `remote.origin.url` or the git argv. Callers pass a clean
- * HTTPS clone URL plus the PAT separately.
+ * HTTPS clone URL plus the login token separately.
  */
 import { spawn } from 'node:child_process';
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createScrubbedChildEnv } from './child-environment.js';
-/** Read the git PAT from the environment (`ATLAS_GIT_PAT`), trimmed. */
-export function resolveGitPatFromEnv() {
-    const value = process.env.ATLAS_GIT_PAT?.trim();
-    return value || undefined;
-}
 /** Full or abbreviated hex SHAs — not valid as `git clone --branch`. */
 export function looksLikeCommitSha(ref) {
     return /^[0-9a-f]{7,40}$/i.test(ref);
@@ -151,9 +146,12 @@ export async function withGitAskpass({ pat, fn, }) {
                 GIT_TERMINAL_PROMPT: '0',
                 GIT_CONFIG_NOSYSTEM: '1',
                 SEQ_STUDIO_GIT_ASKPASS_PASSWORD: pat,
-                GIT_CONFIG_COUNT: '1',
+                GIT_CONFIG_COUNT: '2',
                 GIT_CONFIG_KEY_0: 'credential.helper',
                 GIT_CONFIG_VALUE_0: '',
+                // Never redirect a platform credential, even to another path on this host.
+                GIT_CONFIG_KEY_1: 'http.followRedirects',
+                GIT_CONFIG_VALUE_1: 'false',
             },
         }));
     }

package/dist/manifest-next.d.ts

@@ -401,6 +401,10 @@ export declare const artifactStudioNextManifestSchema: z.ZodObject<{
         mobile: z.ZodOptional<z.ZodEnum<{
             responsive: "responsive";
         }>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            alpha: "alpha";
+            beta: "beta";
+        }>>;
     }, z.core.$strip>>;
     sidebarIcon: z.ZodOptional<z.ZodString>;
     sidebarBadge: z.ZodOptional<z.ZodObject<{

package/dist/manifest-static.d.ts

@@ -12,6 +12,10 @@ export declare const artifactPresentationSchema: z.ZodObject<{
     mobile: z.ZodOptional<z.ZodEnum<{
         responsive: "responsive";
     }>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        alpha: "alpha";
+        beta: "beta";
+    }>>;
 }, z.core.$strip>;
 export type ArtifactPresentation = z.infer<typeof artifactPresentationSchema>;
 export declare const artifactOfflineCapabilitySchema: z.ZodObject<{
@@ -95,6 +99,10 @@ export declare const artifactStudioStaticManifestSchema: z.ZodObject<{
         mobile: z.ZodOptional<z.ZodEnum<{
             responsive: "responsive";
         }>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            alpha: "alpha";
+            beta: "beta";
+        }>>;
     }, z.core.$strip>>;
     offline: z.ZodOptional<z.ZodObject<{
         mode: z.ZodEnum<{

package/dist/manifest-static.js

@@ -16,6 +16,11 @@ export const sidebarBadgeSchema = z.object({
 });
 export const artifactPresentationSchema = z.object({
     mobile: z.enum(['responsive']).optional(),
+    /**
+     * Lifecycle stage the Atlas shell shows as an Alpha/Beta badge beside the
+     * app's name. Omit for GA. Mirrors `App.status` for native apps.
+     */
+    status: z.enum(['alpha', 'beta']).optional(),
 });
 export const artifactOfflineCapabilitySchema = z.object({
     mode: z.enum(['read', 'read-write']),

package/dist/manifest.d.ts

@@ -69,6 +69,10 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
         mobile: z.ZodOptional<z.ZodEnum<{
             responsive: "responsive";
         }>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            alpha: "alpha";
+            beta: "beta";
+        }>>;
     }, z.core.$strip>>;
     offline: z.ZodOptional<z.ZodObject<{
         mode: z.ZodEnum<{
@@ -284,6 +288,10 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
         mobile: z.ZodOptional<z.ZodEnum<{
             responsive: "responsive";
         }>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            alpha: "alpha";
+            beta: "beta";
+        }>>;
     }, z.core.$strip>>;
     sidebarIcon: z.ZodOptional<z.ZodString>;
     sidebarBadge: z.ZodOptional<z.ZodObject<{