@sequenceholdings/artifact-studio 0.6.6 → 0.7.0

package/README.md

@@ -5,6 +5,28 @@ requests use the current user's normal permissions.
 
 ## Governed ORM operations
 
+### Default SQL (planned SDK 0.7.0)
+
+With the matching Atlas runtime, no operation manifest or registration is needed
+for read-only runtime SQL:
+
+```ts
+const orm = createArtifactOrmExecutor({ namespace: 'lending' })
+const result = await orm.sql({
+  sql: `SELECT l.id, c.name FROM lending.loans l
+    JOIN party.customers c ON c.id = l."customerId"`,
+})
+```
+
+Keep the namespace bridge path declaration below. Caller permissions, row
+policies, foreign export gates and optional ontology consumer contracts still
+apply. Results contain `columns`, array-valued `rows`, and `truncated`; exact
+numeric/bigint values are strings. Queries are capped at 1,000 rows / 8 MiB.
+This prerelease source requires package publication and the matching server
+rollout. The generated-manifest path below remains backward-compatible.
+
+### Registered operations
+
 Use the published caller-aware adapter inside an Artifact Studio Preview or a
 deployed artifact. Generate and apply the namespace first, then import its
 `operations.manifest.json` into your application:
@@ -17,7 +39,7 @@ const orm = createArtifactOrmExecutor({ namespace: 'team_directory', manifest })
 const result = await orm.execute('Profiles', { limit: 100, offset: 0 })
 ```
 
-Declare the exact namespace path in `artifact.bundle.yml`:
+For a static (schema-v1) artifact, declare the exact namespace path in `artifact.bundle.yml`:
 
 ```yaml
 capabilities:
@@ -25,7 +47,7 @@ capabilities:
     write: ['/api/data/v2/team_directory']
 ```
 
-Persisted queries and mutations both use POST, so both require this `write`
+In that runtime, persisted queries and mutations both use POST, so both require this `write`
 declaration. This declaration permits the artifact to make the request; each
 user still needs namespace runtime access and the operation's role/capability.
 ORM row policies and write checks enforce that caller's access. The helper uses
@@ -36,10 +58,80 @@ contract for external clients.
 The adapter validates the namespace and manifest, rejects unknown operations,
 and returns the operation's `data`. Errors retain `OrmOperationError.status`,
 `code`, and `errors`; missing host context or malformed success responses fail
-instead of reporting saved data. The adapter never retries a call automatically. For
-several operations in one traced UI action, pass `withTraceAction`'s client as
+instead of reporting saved data. The adapter never retries a call automatically. On the
+static runtime, for several operations in one traced UI action, pass `withTraceAction`'s client as
 the optional `sdk` argument.
 
+### Next.js browser ORM admission (internal prerelease)
+
+The following schema-v2 manifest controls are planned for Artifact Studio 0.6.7
+and Studio CLI 0.4.7. They require the matching platform deployment as well as
+the SDK/CLI release; workspace source and version numbers alone do not establish
+published availability. The Next.js runtime remains an internal, opt-in Preview
+surface.
+
+For a Next.js artifact, declare browser table reach and optionally restrict the
+persisted operations and artifact capabilities required to use that reach:
+
+```yaml
+capabilities:
+  roles:
+    capabilities:
+      directory-reader:
+        description: Read the team directory in this application
+  data:
+    read: [team_directory/profiles]
+    write: []
+    operations: [team_directory/ops/Profiles]
+    required_capabilities:
+      team_directory: [directory-reader]
+```
+
+`operations` accepts at most 256 exact `namespace/ops/Operation` references;
+wildcards are not accepted. Omitting it preserves existing table-based
+admission. An explicit `operations: []` denies every browser ORM operation.
+Listing an operation does not replace its `data.read` or `data.write` reach:
+queries still need every table they read, and mutations still need write reach.
+The Next.js host routes ORM requests through this data contract; no additional
+API path declaration is needed. The POST transport does not grant mutation authority.
+
+The allowlist admits registered persisted operations and the server-owned
+`<namespace>/ops/BuiltinSqlRead` identity when explicitly listed. Default SQL
+still needs all of its table read reach and caller policies; listing it does
+not grant arbitrary database access. Autogenerated
+`DatasetPreview_*` hashes are excluded even if a registered operation has the
+same name. Operation admission retains the existing active and previous
+operation-set fallback; the allowlist pins names, not one content hash. Give a
+security-tightened replacement query a new operation name and remove the old
+name from the allowlist, otherwise a retained older hash with that name can
+remain admissible.
+
+`required_capabilities` maps a source namespace to a nonempty list of artifact
+capability pins. Every listed pin is required, and each must be declared in
+`capabilities.uses` or, for a local bare key, defined under
+`capabilities.roles.capabilities`. Pins use the existing bare `<key>`,
+`org/<key>`, or `app/<application-id>/<key>` grammar. Each namespace in either control must
+also be reached by browser `data.read` or `data.write`. Preview bindings retain
+the source namespace keys in these declarations.
+
+The platform checks the persisted manifest against the authenticated user's
+current artifact capability claims before ORM delegation. Caller-provided
+claims and UI checks cannot satisfy the requirement. Namespace runtime grants,
+operation capability checks, and row/write policies still apply independently;
+these declarations grant no access. They constrain only Next.js browser ORM
+requests, not server SDK calls or external ingress, which keep their own
+declarations and authorization. They also do not transitively restrict ORM
+work inside Managed Functions or general API calls; those surfaces enforce
+their own permission contracts. The `createArtifactOrmExecutor` API is
+unchanged.
+
+For request correlation, the original `seq.api.fetch` response envelope includes
+an `x-request-id` header after browser authorization succeeds, including later
+denials. The platform generates this ID and records it in the browser admission
+audit; it never uses an iframe-supplied ID. Authentication failures have no
+browser admission ID. The ORM executor still returns the operation data, so
+capture the fetch envelope when support tooling needs this correlation value.
+
 ### Exact numbers
 
 By default `numeric` and `bigint` values come back as JSON numbers, which

package/VERSION-PIN.md

@@ -112,6 +112,28 @@ entry points, which remain classified **internal**. They add no package export
 subpath or supported direct HTTP surface. Publication and a reviewed public
 contract decision are separate from local build verification.
 
+## Planned browser ORM admission release
+
+Artifact Studio 0.6.7 and Studio CLI 0.4.7 are the planned package pair for
+schema-v2 Next.js browser `capabilities.data.operations` and
+`capabilities.data.required_capabilities`. Atlas UI stays pinned at 3.4.1.
+Publish the SDK and downstream CLI through the normal chain release, and
+deploy the matching platform support before using these controls. This note
+records the intended release; it is not evidence of npm publication or
+environment rollout. The Next.js manifest/runtime surfaces remain internal.
+
+Older schema-v2 parsers reject the new keys. Existing manifests that omit them
+keep table-based browser admission. An empty `operations` list instead denies
+all browser ORM operations; a nonempty list names exact persisted operations.
+Namespace-scoped `required_capabilities` adds an all-of artifact capability
+check to the existing namespace grants and row/write policies. These controls
+do not change server SDK or external-ingress admission or transitively restrict
+Managed Functions and general API calls. The executor API is unchanged.
+Operation names retain active/previous persisted-operation fallback, so a
+security-tightened query needs a fresh name to exclude retained older hashes;
+autogenerated preview hashes never qualify. See the SDK README for the full
+declaration contract and source-namespace preview behavior.
+
 ## What this means
 
 `shared/services/artifact-studio/src/build.ts` force-aliases platform peers via

package/dist/cli.js

@@ -58,12 +58,10 @@ const USAGE = `usage:
   trees; feature branches and dirty source trees remain preview-only for
   deployed environments (\`artifact dev\` / preview channel).
 
-  Interactive --repo builds clone over smart-HTTP and require a repo:read git
-  PAT in ATLAS_GIT_PAT — create one with \`seq-studio auth pat create --scopes
-  repo:read\` or in Atlas → Settings → Tokens. Headless M2M builds use JSON
-  materialize and accept only platform-managed --repo sources. (--env +
-  seq-studio login are still needed to resolve the repo and upload the
-  deployment.)
+  Interactive --repo builds clone over smart-HTTP using your seq-studio login
+  and repository read access. No PAT is needed. Headless M2M builds use JSON
+  materialize and accept only platform-managed --repo sources. Use --env to
+  select the same environment for source and deployment.
 
   Next.js: init --template nextjs, then pnpm install with Node.js 24. dev starts
   a local Next server and an owner-only Atlas preview tunnel (no cloud credentials).

package/dist/gateway/abort.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Settles with `work`, or rejects with the signal's reason as soon as it aborts. For work
+ * that cannot itself be cancelled (google-auth-library token refreshes): the caller stops
+ * waiting at its deadline, and the abandoned work still settles, with its rejection handled.
+ */
+export declare function untilAborted<T>(work: Promise<T>, signal: AbortSignal): Promise<T>;

package/dist/gateway/abort.js

@@ -0,0 +1,16 @@
+/**
+ * Settles with `work`, or rejects with the signal's reason as soon as it aborts. For work
+ * that cannot itself be cancelled (google-auth-library token refreshes): the caller stops
+ * waiting at its deadline, and the abandoned work still settles, with its rejection handled.
+ */
+export function untilAborted(work, signal) {
+    if (signal.aborted) {
+        work.catch(() => undefined);
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then((value) => { signal.removeEventListener('abort', onAbort); resolve(value); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+}

package/dist/gateway/authorization-cache.d.ts

@@ -10,6 +10,10 @@ type Lookup<T> = {
     load: () => Promise<T>;
     notAfter: (value: T) => number;
 };
+export type SeedReservation = {
+    readonly sequence: number;
+    readonly askedAt: number;
+};
 /**
  * Per-process, positive-only decision cache with single-flight loading: the burst of chunk
  * requests behind one page load costs one control-plane call per gateway replica per window.
@@ -31,11 +35,31 @@ export declare class PositiveDecisionCache<T> {
     });
     /** `notAfter` bounds the entry by the decision's own validity, such as a session's expiry. */
     get(lookup: Lookup<T>): Promise<T>;
+    /** The decision source is observed without another lookup or a wrapper around its promise. */
+    getObserved(lookup: Lookup<T>): {
+        promise: Promise<T>;
+        source: 'hit' | 'shared' | 'load';
+    };
     /**
      * Always asks the source, for decisions that must be current (a mutation). An allow refreshes the
      * cached entry; a refusal evicts it and fences older lookups, so the next read asks again too.
      */
     refresh(lookup: Lookup<T>): Promise<T>;
+    /**
+     * Places a question asked through another call, such as a ticket exchange, in this cache's order.
+     * Reserve before asking, then {@link seed} the answer.
+     */
+    reserve(): SeedReservation;
+    /**
+     * Stores an allow returned for a {@link reserve}d question. It ages from when that question was
+     * asked, and an answer asked later for the same key, a refusal included, is never replaced by it.
+     */
+    seed({ key, value, asked, notAfter }: {
+        key: string;
+        value: T;
+        asked: SeedReservation;
+        notAfter: (value: T) => number;
+    }): void;
     clear(): void;
     private ask;
     private record;

package/dist/gateway/authorization-cache.js

@@ -31,13 +31,17 @@ export class PositiveDecisionCache {
     }
     /** `notAfter` bounds the entry by the decision's own validity, such as a session's expiry. */
     get(lookup) {
+        return this.getObserved(lookup).promise;
+    }
+    /** The decision source is observed without another lookup or a wrapper around its promise. */
+    getObserved(lookup) {
         const cached = this.entries.get(lookup.key);
         if (cached && !cached.refused && cached.expiresAt > this.now())
-            return Promise.resolve(cached.value);
+            return { promise: Promise.resolve(cached.value), source: 'hit' };
         const inFlight = this.pending.get(lookup.key);
         if (inFlight)
-            return inFlight.promise;
-        return this.ask({ lookup, share: true });
+            return { promise: inFlight.promise, source: 'shared' };
+        return { promise: this.ask({ lookup, share: true }), source: 'load' };
     }
     /**
      * Always asks the source, for decisions that must be current (a mutation). An allow refreshes the
@@ -46,6 +50,20 @@ export class PositiveDecisionCache {
     refresh(lookup) {
         return this.ask({ lookup, share: false });
     }
+    /**
+     * Places a question asked through another call, such as a ticket exchange, in this cache's order.
+     * Reserve before asking, then {@link seed} the answer.
+     */
+    reserve() {
+        return { sequence: ++this.sequence, askedAt: this.now() };
+    }
+    /**
+     * Stores an allow returned for a {@link reserve}d question. It ages from when that question was
+     * asked, and an answer asked later for the same key, a refusal included, is never replaced by it.
+     */
+    seed({ key, value, asked, notAfter }) {
+        this.record({ key, entry: { sequence: asked.sequence, refused: false, value, expiresAt: Math.min(asked.askedAt + this.ttlMs, notAfter(value)) } });
+    }
     clear() {
         this.entries.clear();
         this.pending.clear();

package/dist/gateway/bootstrap-page.d.ts

@@ -0,0 +1,16 @@
+import type { ServerResponse } from 'node:http';
+/**
+ * Where the frame lands once the ticket is exchanged: the host's deep link when it is a path on
+ * this origin, else the application root. Landing on the route directly spares the application a
+ * root render (and any root redirect) followed by a client navigation once the bridge connects.
+ * Returns the validated absolute URL, never a path the browser would parse again: a path that
+ * normalizes to `//host` would otherwise read as protocol-relative and leave the application.
+ * The page embeds this function's source, so it must stay self-contained.
+ */
+export declare function bootstrapLandingUrl(route: string | null, origin: string): string;
+/** 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. */
+export declare function bootstrapPage({ response, parentOrigin }: {
+    response: ServerResponse;
+    parentOrigin: string;
+}): void;

package/dist/gateway/bootstrap-page.js

@@ -0,0 +1,34 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * Where the frame lands once the ticket is exchanged: the host's deep link when it is a path on
+ * this origin, else the application root. Landing on the route directly spares the application a
+ * root render (and any root redirect) followed by a client navigation once the bridge connects.
+ * Returns the validated absolute URL, never a path the browser would parse again: a path that
+ * normalizes to `//host` would otherwise read as protocol-relative and leave the application.
+ * The page embeds this function's source, so it must stay self-contained.
+ */
+export function bootstrapLandingUrl(route, origin) {
+    const root = origin + '/';
+    if (typeof route !== 'string' || route.length > 2048 || !route.startsWith('/') || route.startsWith('//') || route.includes('\\'))
+        return root;
+    try {
+        const url = new URL(route, origin);
+        if (url.origin !== origin || url.pathname.startsWith('//') || url.pathname.startsWith('/_sequence'))
+            return root;
+        return url.href;
+    }
+    catch {
+        return root;
+    }
+}
+/** 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. */
+export 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 landing=${bootstrapLandingUrl.toString()};const fragment=new URLSearchParams(location.hash.slice(1));const ticket=fragment.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(landing(fragment.get('route'),location.origin));}).catch(()=>{document.getElementById('status').textContent='This preview expired. Open it again from Atlas.';});})();</script>`);
+}

package/dist/gateway/control-config.d.ts

@@ -0,0 +1,21 @@
+import type { GatewayControlIdentity } from './control.js';
+export interface GatewayControlConfig {
+    /** Where the gateway calls Atlas: its public origin, or its private Cloud Run address. */
+    url: string;
+    /** The Atlas origin allowed to frame applications. */
+    parentOrigin: string;
+    /** Absent only for a local gateway: the shared control token authenticates its calls. */
+    identity?: GatewayControlIdentity;
+}
+/**
+ * A deployed gateway presents its service account's identity token, the only gateway
+ * credential a deployed Atlas accepts. A local gateway has no metadata server to mint one,
+ * so it presents the shared control token, which only a local Atlas accepts. Cloud Run sets
+ * K_SERVICE, so a mislabelled deployment never falls back to the shared token. The token's
+ * audience is the parent origin's control path: the public origin Atlas also derives it
+ * from, whichever address the call is routed to.
+ */
+export declare function resolveGatewayControlConfig({ env, identityToken }: {
+    env: NodeJS.ProcessEnv;
+    identityToken: GatewayControlIdentity['token'];
+}): GatewayControlConfig;

package/dist/gateway/control-config.js

@@ -0,0 +1,18 @@
+import { artifactNextControlAudience } from '../runtime-contracts.js';
+/**
+ * A deployed gateway presents its service account's identity token, the only gateway
+ * credential a deployed Atlas accepts. A local gateway has no metadata server to mint one,
+ * so it presents the shared control token, which only a local Atlas accepts. Cloud Run sets
+ * K_SERVICE, so a mislabelled deployment never falls back to the shared token. The token's
+ * audience is the parent origin's control path: the public origin Atlas also derives it
+ * from, whichever address the call is routed to.
+ */
+export function resolveGatewayControlConfig({ env, identityToken }) {
+    const url = env.ARTIFACT_NEXT_CONTROL_PLANE_URL?.trim();
+    if (!url)
+        throw new Error('Missing required gateway configuration: ARTIFACT_NEXT_CONTROL_PLANE_URL');
+    const parentOrigin = env.ARTIFACT_NEXT_PARENT_ORIGIN?.trim() || new URL(url).origin;
+    if (env.APP_ENV === 'development' && !env.K_SERVICE)
+        return { url, parentOrigin };
+    return { url, parentOrigin, identity: { audience: artifactNextControlAudience(parentOrigin), token: identityToken } };
+}

package/dist/gateway/control.d.ts

@@ -115,15 +115,27 @@ export declare class IngressControlError extends GatewayControlError {
     readonly retryAfterSeconds?: number | undefined;
     constructor(status: number, code: IngressControlCode | null, retryAfterSeconds?: number | undefined);
 }
+/** Calls Atlas with the gateway service account's identity token instead of the shared control token. */
+export interface GatewayControlIdentity {
+    audience: string;
+    token: (input: {
+        audience: string;
+        signal: AbortSignal;
+    }) => Promise<string>;
+}
 export declare class ArtifactGatewayControl {
     private readonly options;
     private readonly origin;
+    /** `token` stays required with an identity: Atlas still presents it when it calls the gateway (tokenMatches). */
     constructor(options: {
         url: string;
         token: string;
+        identity?: GatewayControlIdentity;
         fetch?: typeof fetch;
     });
     private call;
+    /** An identity token that cannot be minted is an unavailable control plane, never a call without credentials. */
+    private credential;
     private send;
     /** Every enabled ingress host (GET, at most 1 MiB); the gateway pulls it on a timer, never per request. */
     ingressSnapshot(): Promise<IngressSnapshot>;

package/dist/gateway/control.js

@@ -2,7 +2,8 @@ import { createHash, timingSafeEqual } from 'node:crypto';
 import { z } from 'zod';
 import { normalizePublicOrigin } from '../tunnel/protocol.js';
 import { artifactRequestContextSchema } from '../server/request-context.js';
-import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+import { ARTIFACT_NEXT_CONTROL_PATH, artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+import { untilAborted } from './abort.js';
 import { INGRESS_SNAPSHOT_MAX_BYTES, ingressExchangeResponseSchema, ingressGrantResponseSchema, ingressSnapshotSchema, } from '../server/ingress-control-contract.js';
 const id = z.string().min(1).max(255);
 const base = {
@@ -94,6 +95,7 @@ async function ingressRefusal(response) {
 export class ArtifactGatewayControl {
     options;
     origin;
+    /** `token` stays required with an identity: Atlas still presents it when it calls the gateway (tokenMatches). */
     constructor(options) {
         this.options = options;
         this.origin = normalizePublicOrigin(options.url);
@@ -103,11 +105,26 @@ export class ArtifactGatewayControl {
     call(path, body, timeoutMs = 10_000) {
         return this.send({ path, body, timeoutMs, maxBytes: 128 * 1024 });
     }
+    /** An identity token that cannot be minted is an unavailable control plane, never a call without credentials. */
+    async credential(signal) {
+        const identity = this.options.identity;
+        if (!identity)
+            return this.options.token;
+        // The token source may ignore `signal`; the call's own deadline still bounds the wait.
+        try {
+            return await untilAborted(identity.token({ audience: identity.audience, signal }), signal);
+        }
+        catch {
+            throw new GatewayControlError(503);
+        }
+    }
     async send({ path, body, timeoutMs, maxBytes, ingress = false }) {
-        const response = await (this.options.fetch ?? fetch)(`${this.origin}/api/artifact-studio/next/control/${path}`, {
+        const signal = AbortSignal.timeout(timeoutMs);
+        const credential = await this.credential(signal);
+        const response = await (this.options.fetch ?? fetch)(`${this.origin}${ARTIFACT_NEXT_CONTROL_PATH}/${path}`, {
             method: body === undefined ? 'GET' : 'POST',
-            headers: { authorization: `Bearer ${this.options.token}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
-            ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(timeoutMs), redirect: 'error',
+            headers: { authorization: `Bearer ${credential}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal, redirect: 'error',
         });
         if (!response.ok)
             throw ingress ? await ingressRefusal(response) : new GatewayControlError(response.status);

package/dist/gateway/hosted-proxy.d.ts

@@ -1,6 +1,7 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type HostedArtifactIngressMode } from './ingress-response.js';
 import { type HostedRuntimeTarget } from './runtime-transport.js';
+import { type GatewayTimings } from './usage.js';
 export { cloudRunOrigin, resolveHostedTarget, type HostedRuntimeTarget } from './runtime-transport.js';
 export declare const HOSTED_ARTIFACT_PROXY_LIMITS: Readonly<{
     maxRequestBytes: number;
@@ -35,6 +36,8 @@ export interface HostedArtifactProxyOptions {
     };
     /** Present only for an external ingress request. */
     ingress?: HostedArtifactIngressMode;
+    /** Request-local observations; the caller snapshots them when recording usage. */
+    gatewayTimings?: GatewayTimings;
 }
 export declare function hostedIdentityToken(input: {
     audience: string;

package/dist/gateway/hosted-proxy.js

@@ -8,6 +8,7 @@ import { enforceBrowserCachePolicy, mergeFramePolicy, rewriteLocation } from './
 import { createReleaseFormTransform } from '../server/release-forms.js';
 import { declaredContentLength, INGRESS_PROXY_ERROR_CODES, INGRESS_PROXY_LIMITS, writeIngressResponseHead } from './ingress-response.js';
 import { resolveHostedTarget } from './runtime-transport.js';
+import { gatewayElapsedMs } from './usage.js';
 export { cloudRunOrigin, resolveHostedTarget } from './runtime-transport.js';
 export const HOSTED_ARTIFACT_PROXY_LIMITS = Object.freeze({ maxRequestBytes: 32 * 1024 * 1024, maxResponseBytes: 32 * 1024 * 1024, timeoutMs: 60_000, maxTimeoutMs: 300_000 });
 const googleAuth = new GoogleAuth();
@@ -129,7 +130,11 @@ class HostedExchange {
         stripCloudHeaders(headers);
         if (audience) {
             const provider = this.options.identityTokenProvider ?? defaultIdentityTokenProvider;
-            const token = await provider({ audience: audience.origin, signal: this.controller.signal });
+            const identityStarted = performance.now();
+            const token = await provider({ audience: audience.origin, signal: this.controller.signal }).finally(() => {
+                if (!this.stopped && this.options.gatewayTimings)
+                    this.options.gatewayTimings.identityTokenMs = gatewayElapsedMs(identityStarted);
+            });
             if (this.stopped)
                 return;
             if (!/^[A-Za-z0-9._~-]+$/.test(token) || token.length > 16384)
@@ -145,7 +150,12 @@ class HostedExchange {
         headers['x-sequence-artifact-context'] = requestContext;
         const destination = this.resolveDestination(upstream);
         const transport = destination.protocol === 'https:' ? httpsRequest : httpRequest;
-        this.outgoing = transport(destination, { method: request.method, path: request.url, headers, maxHeaderSize: 32 * 1024 }, (incoming) => this.receive({ incoming, upstream, publicOrigin }));
+        const upstreamStarted = performance.now();
+        this.outgoing = transport(destination, { method: request.method, path: request.url, headers, maxHeaderSize: 32 * 1024 }, (incoming) => {
+            if (!this.stopped && this.options.gatewayTimings)
+                this.options.gatewayTimings.upstreamHeadersMs = gatewayElapsedMs(upstreamStarted);
+            this.receive({ incoming, upstream, publicOrigin });
+        });
         this.outgoing.on('error', () => this.fail(this.unavailableStatus));
         this.outgoing.once('upgrade', (_incoming, socket) => { socket.destroy(); this.fail(502); });
         this.outgoing.on('drain', () => { if (!this.stopped)

package/dist/gateway/server.d.ts

@@ -11,7 +11,7 @@ export interface ArtifactGatewayOptions {
     parentOrigin: string;
     gatewayOrigin: string;
     sessionKey: string;
-    /** Defaults to `Strict`. `None` only for a local development gateway (see GatewaySessionSameSite). */
+    /** Defaults to `Strict`; `None` when app origins are cross-site to Atlas (see gatewaySessionSameSite). */
     sessionCookieSameSite?: GatewaySessionSameSite;
     contextPrivateKey: string;
     contextKeyId: string;

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,12 +6,13 @@ 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 { ArtifactAdmissionError } from './admission.js';
 import { gatewayClientAddress } from './control-admission.js';
 import { gatewayAuthorizationKey, PositiveDecisionCache, tunnelAuthorizationKey } from './authorization-cache.js';
-import { GatewayUsageReporter } from './usage.js';
+import { gatewayElapsedMs, GatewayUsageReporter, snapshotGatewayTimings } from './usage.js';
 import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
 import { createDevelopmentIngressProxy } from './ingress-development.js';
 import { createIngressHandler, handleClientErrors } from './ingress-handler.js';
@@ -73,17 +74,6 @@ 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>`);
-}
 /** 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')
@@ -132,15 +122,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 +179,11 @@ 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({
+        const result = { session, target, requestId, authorizationCache: decision.source, 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,
             }) };
@@ -308,7 +303,9 @@ 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);
+            const gatewayTimings = { authorizationMs: gatewayElapsedMs(authorizationStarted), authorizationCache };
             let reported = false;
             const report = () => {
                 if (reported)
@@ -321,6 +318,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);
@@ -342,12 +340,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' });