@sequenceholdings/artifact-studio 0.3.0 → 0.4.0

package/README.md

@@ -3,6 +3,43 @@
 `@sequenceholdings/artifact-studio` exposes the host-provided `seq` client. Runtime
 requests use the current user's normal permissions.
 
+## Governed ORM 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:
+
+```ts
+import { createArtifactOrmExecutor } from '@sequenceholdings/artifact-studio'
+import manifest from './operations.manifest.json'
+
+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`:
+
+```yaml
+capabilities:
+  api:
+    write: ['/api/data/v2/team_directory']
+```
+
+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
+host authentication and requires no token, custom header, or environment URL.
+The namespace path above is a capability declaration, not a direct HTTP API
+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. Calls are never automatically retried. For
+several operations in one traced UI action, pass `withTraceAction`'s client as
+the optional `sdk` argument.
+
 Artifact Studio is a workflow-agnostic platform primitive. The host, SDK, and
 deployer provide generic application capabilities; each deployed artifact owns
 its product behavior. Primitive code must not branch on an artifact ID or import

package/VERSION-PIN.md

@@ -17,6 +17,10 @@ introduces; they do not inherit the static compiler's aliases. The new packages
 before a fresh external Next.js scaffold can be installed. A local candidate
 build is not evidence of registry availability.
 
+Artifact Studio 0.3.1 (Studio CLI 0.2.2) verifies the per-request `jti` that the
+gateway now signs into every request context. The 0.3.0 context schema predates
+that claim and rejects those contexts, so Next.js applications need 0.3.1 or newer.
+
 ## What this means
 
 `shared/services/artifact-studio/src/build.ts` force-aliases platform peers via

package/dist/build.js

@@ -78,6 +78,7 @@ function createPeerResolveAlias({ atlasUiPackageDir = atlasUiDir } = {}) {
         'react-router-dom': reactRouterDomDir,
         sonner: sonnerDir,
         '@sequenceholdings/storage': cliRequire.resolve('@sequenceholdings/storage'),
+        '@sequenceholdings/orm/client': cliRequire.resolve('@sequenceholdings/orm/client'),
         // Candidate Atlas UI exposes canonical tokens at the package root; released
         // 2.0.1 keeps them in dist. Preserve explicit alias resolution so legacy
         // source reaches the normalizer instead of falling through to the bare alias.

package/dist/cli.js

@@ -1,5 +1,5 @@
-import { cp, mkdir, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { copyFile, cp, mkdir, writeFile } from 'node:fs/promises';
+import { constants, existsSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getJson, getJsonOr404, postJson } from './api.js';
@@ -18,6 +18,7 @@ import { lintArtifactSandbox, reportSandboxWarnings } from './sandbox-lint.js';
 import { assertActiveDeployProvenance } from './active-deploy-policy.js';
 import { normalizeArtifactPath } from './paths.js';
 import yaml from 'js-yaml';
+import { warnOnRoleDefinitions } from './role-definitions-notice.js';
 const COMMANDS = [
     'init', 'whoami', 'link', 'env', 'status', 'list', 'show',
     'validate', 'build', 'plan', 'deploy', 'dev', 'promote', 'pull', 'rollback',
@@ -39,6 +40,8 @@ const USAGE = `usage:
   seq-studio artifact pull <project-id> --env <env> --out <dir>
   seq-studio artifact rollback <deployment-id> --env <env>
 
+  Add --help or -h to any artifact command to print this usage without running it.
+
   Source: a local [dir] (default), a platform git-service repo (--repo <ns>/<name>),
   or a public HTTPS git URL (--git-url <url>). --ref picks a branch/tag/commit (default: the
   repo's default branch). The target project comes from the source's
@@ -71,6 +74,10 @@ export async function runCli(argv = process.argv.slice(2)) {
             'Authenticate with seq-studio login.');
         return 1;
     }
+    if (argv.some((arg) => arg === '--help' || arg === '-h')) {
+        console.log(USAGE);
+        return 0;
+    }
     const parsed = parseArgs(argv);
     if ('error' in parsed) {
         console.error(parsed.error);
@@ -134,7 +141,12 @@ async function initCommand(args) {
         ? resolve(moduleDir, 'templates', template)
         : resolve(moduleDir, '..', 'templates', template);
     await mkdir(dir, { recursive: true });
-    await cp(templateRoot, dir, { recursive: true, force: false, errorOnExist: false });
+    const templateGitignore = join(templateRoot, 'gitignore');
+    await cp(templateRoot, dir, {
+        recursive: true, force: false, errorOnExist: false,
+        filter: (source) => source !== templateGitignore,
+    });
+    await installTemplateGitignore({ source: templateGitignore, dir });
     await replaceInFile(join(dir, 'artifact.bundle.yml'), /\{\{slug\}\}/g, slug);
     await replaceInFile(join(dir, 'artifact.bundle.yml'), /\{\{title\}\}/g, titleize(slug));
     await replaceInFile(join(dir, 'package.json'), /\{\{slug\}\}/g, slug);
@@ -494,7 +506,10 @@ async function deployCommand(args) {
         // the current branch and dirty working tree.
         if (env.name !== 'local')
             assertActiveDeployProvenance(source.provenance);
-        if (isNextArtifactManifest(await readArtifactStudioManifest(source.dir))) {
+        const manifest = await readArtifactStudioManifest(source.dir);
+        // After source resolution, so --repo / --git-url deploys check the fetched manifest.
+        warnOnRoleDefinitions(manifest);
+        if (isNextArtifactManifest(manifest)) {
             return await buildNextCommand({ args, source, active: true });
         }
         // --skip-unchanged: hash the raw source (no build needed) and no-op when
@@ -989,6 +1004,21 @@ async function resolveAuth(options) {
     }
     return null;
 }
+/**
+ * npm always leaves `.gitignore` out of published tarballs, so templates ship it
+ * as `gitignore`. Install it without replacing an ignore file the directory has.
+ */
+async function installTemplateGitignore({ source, dir }) {
+    if (!existsSync(source))
+        return;
+    try {
+        await copyFile(source, join(dir, '.gitignore'), constants.COPYFILE_EXCL);
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+            throw error;
+    }
+}
 async function replaceInFile(path, pattern, value) {
     const content = await import('node:fs/promises').then((fs) => fs.readFile(path, 'utf8'));
     await writeFile(path, content.replace(pattern, value), 'utf8');

package/dist/dev-link.js

@@ -8,7 +8,7 @@ import { dirname, join, relative, resolve } from 'node:path';
 export function hasLinkedAtlasUiToolchain({ deps }) {
     return deps.some((dep) => dep.name === '@sequenceholdings/atlas-ui');
 }
-const WATCHED_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.css', '.json']);
+const WATCHED_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.css', '.json']);
 const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', '.next', '.turbo', '.cache']);
 const defaultResolver = createRequire(import.meta.url).resolve;
 /** Split a `--link a,b` flag value into trimmed, non-empty paths. */

package/dist/gateway/admission.d.ts

@@ -34,7 +34,8 @@ export interface AdmissionLease {
 export declare class ArtifactAdmissionError extends Error {
     readonly status: 429 | 503;
     readonly code: 'capacity_exceeded' | 'admission_unavailable';
-    constructor(status: 429 | 503, code: 'capacity_exceeded' | 'admission_unavailable');
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(status: 429 | 503, code: 'capacity_exceeded' | 'admission_unavailable', retryAfterSeconds?: number | undefined);
 }
 /** Fail-closed admission with no command retries. An uncertain acquisition is
  * never used; its unique permit expires even if Redis accepted it before loss. */

package/dist/gateway/admission.js

@@ -6,10 +6,12 @@ import { redisNamespaceSchema } from '../tunnel/redis-ownership.js';
 export class ArtifactAdmissionError extends Error {
     status;
     code;
-    constructor(status, code) {
+    retryAfterSeconds;
+    constructor(status, code, retryAfterSeconds) {
         super(status === 429 ? 'Application request capacity exceeded' : 'Application request admission unavailable');
         this.status = status;
         this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
         this.name = 'ArtifactAdmissionError';
     }
 }

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

@@ -0,0 +1,52 @@
+import type { GatewaySession } from './session.js';
+/**
+ * How long the gateway reuses an Atlas "allow" for the same session and target. Revocation,
+ * suspension, rollback, retirement, rollout disablement and actor deactivation reach browsers
+ * that are already admitted within this window. Denials are never cached.
+ */
+export declare const GATEWAY_AUTHORIZATION_TTL_MS = 5000;
+type Lookup<T> = {
+    key: string;
+    load: () => Promise<T>;
+    notAfter: (value: T) => 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.
+ * An entry never outlives the decision's own expiry. Every answer is ordered by when it was
+ * asked, so an older allow that resolves late can never replace a newer answer, and a refusal
+ * also detaches any older lookup still in flight.
+ */
+export declare class PositiveDecisionCache<T> {
+    private readonly entries;
+    private readonly pending;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private readonly now;
+    private sequence;
+    constructor(options?: {
+        ttlMs?: number;
+        maxEntries?: number;
+        now?: () => number;
+    });
+    /** `notAfter` bounds the entry by the decision's own validity, such as a session's expiry. */
+    get(lookup: Lookup<T>): Promise<T>;
+    /**
+     * 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>;
+    clear(): void;
+    private ask;
+    private record;
+}
+/** Every session field Atlas authorizes or the gateway checks the answer against. Tab-local
+ * bridge values and the cookie's own expiry do not change the decision. */
+export declare function gatewayAuthorizationKey(session: GatewaySession): string;
+/** A tunnel credential is keyed by its hash, never retained in the key itself. */
+export declare function tunnelAuthorizationKey({ token, sessionId, epoch }: {
+    token: string;
+    sessionId: string;
+    epoch: number;
+}): string;
+export {};

package/dist/gateway/authorization-cache.js

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+/**
+ * How long the gateway reuses an Atlas "allow" for the same session and target. Revocation,
+ * suspension, rollback, retirement, rollout disablement and actor deactivation reach browsers
+ * that are already admitted within this window. Denials are never cached.
+ */
+export const GATEWAY_AUTHORIZATION_TTL_MS = 5_000;
+const DEFAULT_MAX_ENTRIES = 10_000;
+/**
+ * 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.
+ * An entry never outlives the decision's own expiry. Every answer is ordered by when it was
+ * asked, so an older allow that resolves late can never replace a newer answer, and a refusal
+ * also detaches any older lookup still in flight.
+ */
+export class PositiveDecisionCache {
+    entries = new Map();
+    pending = new Map();
+    ttlMs;
+    maxEntries;
+    now;
+    sequence = 0;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? GATEWAY_AUTHORIZATION_TTL_MS;
+        this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.now = options.now ?? (() => Date.now());
+        if (!Number.isSafeInteger(this.ttlMs) || this.ttlMs < 0 || this.ttlMs > 30_000)
+            throw new Error('Authorization cache TTL must be between 0 and 30 seconds');
+        if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries < 1)
+            throw new Error('Authorization cache size must be positive');
+    }
+    /** `notAfter` bounds the entry by the decision's own validity, such as a session's expiry. */
+    get(lookup) {
+        const cached = this.entries.get(lookup.key);
+        if (cached && !cached.refused && cached.expiresAt > this.now())
+            return Promise.resolve(cached.value);
+        const inFlight = this.pending.get(lookup.key);
+        if (inFlight)
+            return inFlight.promise;
+        return this.ask({ lookup, share: true });
+    }
+    /**
+     * 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) {
+        return this.ask({ lookup, share: false });
+    }
+    clear() {
+        this.entries.clear();
+        this.pending.clear();
+    }
+    ask({ lookup: { key, load, notAfter }, share }) {
+        const sequence = ++this.sequence;
+        const askedAt = this.now();
+        const promise = load().then((value) => {
+            // Expiry counts from when the question was asked, so an answer is never reused past the TTL.
+            this.record({ key, entry: { sequence, refused: false, value, expiresAt: Math.min(askedAt + this.ttlMs, notAfter(value)) } });
+            return value;
+        }, (error) => {
+            this.record({ key, entry: { sequence, refused: true, expiresAt: this.now() + this.ttlMs } });
+            throw error;
+        });
+        if (share) {
+            const flight = { sequence, promise };
+            this.pending.set(key, flight);
+            void promise.finally(() => { if (this.pending.get(key) === flight)
+                this.pending.delete(key); }).catch(() => undefined);
+        }
+        return promise;
+    }
+    record({ key, entry }) {
+        const current = this.entries.get(key);
+        // A newer answer, allow or refusal, always wins over one that was asked earlier.
+        if (current && current.sequence > entry.sequence)
+            return;
+        this.entries.delete(key);
+        if (entry.refused) {
+            // New readers must not join a lookup that started before this refusal.
+            const flight = this.pending.get(key);
+            if (flight && flight.sequence < entry.sequence)
+                this.pending.delete(key);
+            // An older allow could only have been reused for one TTL, so the fence lives that long.
+            if (this.ttlMs === 0)
+                return;
+        }
+        else if (entry.expiresAt <= this.now())
+            return;
+        this.entries.set(key, entry);
+        // Maps iterate in insertion order, so the first key is the least recently stored.
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+}
+function digest(parts) {
+    return createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+}
+/** Every session field Atlas authorizes or the gateway checks the answer against. Tab-local
+ * bridge values and the cookie's own expiry do not change the decision. */
+export function gatewayAuthorizationKey(session) {
+    return digest(['session-v1', session.kind, session.projectId, session.ownerId, session.environment, session.publicOrigin,
+        session.sessionId, session.deploymentId, session.frameworkBuildId, session.published, session.lattice ?? null, session.taskRoutes ?? null]);
+}
+/** A tunnel credential is keyed by its hash, never retained in the key itself. */
+export function tunnelAuthorizationKey({ token, sessionId, epoch }) {
+    return digest(['tunnel-v1', sessionId, epoch, createHash('sha256').update(token).digest('hex')]);
+}

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

@@ -0,0 +1,48 @@
+import type { IncomingMessage } from 'node:http';
+import { type AdmissionRedis } from './admission.js';
+export type GatewayControlEndpoint = 'session' | 'tunnel';
+type EndpointLimits = {
+    perClient: number;
+    global: number;
+};
+export interface GatewayControlAdmissionLimits {
+    /** Fixed Redis-clock window shared by the per-client and environment-wide counters. */
+    windowMs: number;
+    session: EndpointLimits;
+    tunnel: EndpointLimits;
+    /** Unauthenticated control calls one gateway process may have outstanding against Atlas. */
+    maxInFlight: number;
+}
+/**
+ * Budgets for the only gateway endpoints that reach Atlas before a session exists. The per-client
+ * allowance tolerates many users behind one corporate egress address; the environment-wide budget
+ * bounds what any number of sources can cost Atlas, whatever their addresses.
+ */
+export declare const GATEWAY_CONTROL_ADMISSION_LIMITS: Readonly<GatewayControlAdmissionLimits>;
+/**
+ * Admits `/_sequence/session` and `/_sequence/tunnel` before they call Atlas. Fails closed, with no
+ * command retries: when Redis cannot answer, nothing unauthenticated reaches the control plane.
+ */
+export declare class GatewayControlAdmission {
+    private readonly options;
+    private readonly namespace;
+    private readonly limits;
+    private inFlight;
+    constructor(options: {
+        redis: AdmissionRedis;
+        namespace: string;
+        limits?: GatewayControlAdmissionLimits;
+    });
+    /** Resolves to the in-flight permit's release; throws ArtifactAdmissionError (429 or 503). */
+    admit({ endpoint, client }: {
+        endpoint: GatewayControlEndpoint;
+        client: string;
+    }): Promise<() => void>;
+}
+/**
+ * The address a control call is budgeted against. Cloudflare sets CF-Connecting-IP and the edge
+ * Cloud Armor policy admits only Cloudflare. If that policy were bypassed, a forged address could
+ * only move a caller between per-client buckets: the environment-wide budget still applies.
+ */
+export declare function gatewayClientAddress(request: IncomingMessage): string;
+export {};

package/dist/gateway/control-admission.js

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+import { isIP, isIPv6 } from 'node:net';
+import { z } from 'zod';
+import { redisNamespaceSchema } from '../tunnel/redis-ownership.js';
+import { ArtifactAdmissionError } from './admission.js';
+/**
+ * Budgets for the only gateway endpoints that reach Atlas before a session exists. The per-client
+ * allowance tolerates many users behind one corporate egress address; the environment-wide budget
+ * bounds what any number of sources can cost Atlas, whatever their addresses.
+ */
+export const GATEWAY_CONTROL_ADMISSION_LIMITS = Object.freeze({
+    windowMs: 10_000,
+    session: Object.freeze({ perClient: 60, global: 600 }),
+    tunnel: Object.freeze({ perClient: 30, global: 300 }),
+    maxInFlight: 64,
+});
+// Both keys share one hash tag, so the script stays single-slot on Redis Cluster. A rejected
+// attempt consumes nothing: one noisy client cannot spend the environment-wide budget.
+const ADMIT = `-- artifact-gateway-control-admission-v1
+local window = tonumber(ARGV[3])
+for index, key in ipairs(KEYS) do
+  if tonumber(redis.call('GET', key) or '0') >= tonumber(ARGV[index]) then
+    local ttl = redis.call('PTTL', key)
+    if ttl < 0 then
+      redis.call('PEXPIRE', key, window)
+      ttl = window
+    end
+    return {0, ttl}
+  end
+end
+for _, key in ipairs(KEYS) do
+  if redis.call('INCR', key) == 1 or redis.call('PTTL', key) < 0 then redis.call('PEXPIRE', key, window) end
+end
+return {1, 0}`;
+const limitSchema = z.number().int().min(1).max(1_000_000);
+const limitsSchema = z.object({
+    windowMs: z.number().int().min(1_000).max(3_600_000),
+    session: z.object({ perClient: limitSchema, global: limitSchema }),
+    tunnel: z.object({ perClient: limitSchema, global: limitSchema }),
+    maxInFlight: z.number().int().min(1).max(10_000),
+});
+const replySchema = z.tuple([z.number().int().min(0).max(1), z.number().int().min(0)]);
+/**
+ * Admits `/_sequence/session` and `/_sequence/tunnel` before they call Atlas. Fails closed, with no
+ * command retries: when Redis cannot answer, nothing unauthenticated reaches the control plane.
+ */
+export class GatewayControlAdmission {
+    options;
+    namespace;
+    limits;
+    inFlight = 0;
+    constructor(options) {
+        this.options = options;
+        this.namespace = redisNamespaceSchema.parse(options.namespace);
+        this.limits = limitsSchema.parse(options.limits ?? GATEWAY_CONTROL_ADMISSION_LIMITS);
+        const policy = options.redis.options;
+        if (policy.enableOfflineQueue !== false || policy.autoResendUnfulfilledCommands !== false || policy.maxRetriesPerRequest !== 0) {
+            throw new Error('Control admission Redis must disable offline queues, command replay and retries');
+        }
+    }
+    /** Resolves to the in-flight permit's release; throws ArtifactAdmissionError (429 or 503). */
+    async admit({ endpoint, client }) {
+        if (this.inFlight >= this.limits.maxInFlight)
+            throw new ArtifactAdmissionError(503, 'admission_unavailable');
+        this.inFlight++;
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            this.inFlight--;
+        };
+        try {
+            const limits = this.limits[endpoint];
+            const prefix = `artifact-gateway-control:{${this.namespace}}:${endpoint}`;
+            const bucket = createHash('sha256').update(clientBucket(client)).digest('hex').slice(0, 32);
+            let reply;
+            try {
+                reply = replySchema.parse(await this.options.redis.eval(ADMIT, 2, `${prefix}:client:${bucket}`, `${prefix}:global`, limits.perClient, limits.global, this.limits.windowMs));
+            }
+            catch {
+                throw new ArtifactAdmissionError(503, 'admission_unavailable');
+            }
+            if (reply[0] !== 1) {
+                throw new ArtifactAdmissionError(429, 'capacity_exceeded', Math.max(1, Math.ceil(reply[1] / 1000)));
+            }
+            return release;
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+    }
+}
+/** One IPv6 host usually controls a whole /64, so it shares one allowance. */
+function clientBucket(address) {
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(address);
+    if (mapped)
+        return mapped[1];
+    if (!isIPv6(address))
+        return address;
+    const [head = '', tail] = address.toLowerCase().split('::');
+    const leading = head ? head.split(':') : [];
+    const trailing = tail ? tail.split(':') : [];
+    const groups = tail === undefined ? leading : [...leading, ...Array(Math.max(0, 8 - leading.length - trailing.length)).fill('0'), ...trailing];
+    return `${groups.slice(0, 4).map((group) => group.padStart(4, '0')).join(':')}::/64`;
+}
+function forwardedClient(request) {
+    const value = request.headers['x-forwarded-for'];
+    if (typeof value !== 'string')
+        return undefined;
+    // Google's external load balancer appends "<connecting client>, <load balancer>".
+    const hops = value.split(',').map((hop) => hop.trim()).filter(Boolean);
+    const candidate = hops.at(-2);
+    return candidate && isIP(candidate) ? candidate : undefined;
+}
+/**
+ * The address a control call is budgeted against. Cloudflare sets CF-Connecting-IP and the edge
+ * Cloud Armor policy admits only Cloudflare. If that policy were bypassed, a forged address could
+ * only move a caller between per-client buckets: the environment-wide budget still applies.
+ */
+export function gatewayClientAddress(request) {
+    const cloudflare = request.headers['cf-connecting-ip'];
+    if (typeof cloudflare === 'string' && isIP(cloudflare.trim()))
+        return cloudflare.trim();
+    return forwardedClient(request) ?? request.socket.remoteAddress ?? 'unknown';
+}

package/dist/gateway/control.d.ts

@@ -77,7 +77,10 @@ export declare class ArtifactGatewayControl {
         fetch?: typeof fetch;
     });
     private call;
-    usage(event: GatewayUsageEvent): Promise<void>;
+    /** One idempotent batch; Atlas reports events it refused (for example, a retired target). */
+    usage(events: GatewayUsageEvent[]): Promise<{
+        rejected: number;
+    }>;
     bootstrap(ticket: string): Promise<{
         session: GatewaySession;
         target: GatewayTarget;

package/dist/gateway/control.js

@@ -19,6 +19,7 @@ export const gatewayTargetSchema = z.discriminatedUnion('kind', [
     z.object({ ...base, kind: z.literal('hosted'), deploymentId: id, frameworkBuildId: artifactNextFrameworkBuildIdSchema, upstreamUrl: z.string().url(), upstreamAudience: z.string().url().optional(), active: z.boolean(), published: z.boolean().optional() }),
 ]);
 const bootstrapSchema = z.object({ parentOrigin: z.string().transform(normalizePublicOrigin), channelId: id, nonce: z.string().min(16).max(255) });
+const usageResultSchema = z.object({ rejected: z.number().int().nonnegative() });
 export class GatewayControlError extends Error {
     status;
     constructor(status) {
@@ -69,8 +70,10 @@ export class ArtifactGatewayControl {
             await reader.cancel().catch(() => undefined);
         }
     }
-    async usage(event) {
-        await this.call('usage', event, 2_000);
+    /** One idempotent batch; Atlas reports events it refused (for example, a retired target). */
+    async usage(events) {
+        const value = await this.call('usage', { events }, 5_000);
+        return usageResultSchema.parse(value);
     }
     async bootstrap(ticket) {
         const value = await this.call('bootstrap', { ticket });

package/dist/gateway/hosted-proxy.js

@@ -3,7 +3,7 @@ import { request as httpsRequest } from 'node:https';
 import { Duplex, Readable, Transform } from 'node:stream';
 import { createBrotliDecompress, createGunzip, createInflate } from 'node:zlib';
 import { GoogleAuth } from 'google-auth-library';
-import { assertSafeRequest, normalizePublicOrigin, sanitizeRequestHeaders, sanitizeResponseHeaders } from '../tunnel/protocol.js';
+import { assertSafeRequest, isSharedCacheDirective, normalizePublicOrigin, sanitizeRequestHeaders, sanitizeResponseHeaders, SHARED_CACHE_REFUSAL } from '../tunnel/protocol.js';
 import { createReleaseFormTransform } from '../server/release-forms.js';
 export const HOSTED_ARTIFACT_PROXY_LIMITS = Object.freeze({ maxBodyBytes: 32 * 1024 * 1024, timeoutMs: 60_000, maxTimeoutMs: 300_000 });
 const googleAuth = new GoogleAuth();
@@ -77,15 +77,12 @@ function enforceBrowserCachePolicy({ request, response }) {
     // Every protected reuse must reach authorization. Retain only private static
     // JS/CSS bytes and validators; app output may never opt into browser/CDN TTLs.
     for (const name of response.getHeaderNames()) {
-        if (/(?:^|-)cdn-cache-control$/.test(name) || ['surrogate-control', 'x-accel-expires', 'expires', 'age'].includes(name)) {
+        if (isSharedCacheDirective(name))
             response.removeHeader(name);
-        }
     }
     response.setHeader('cache-control', revalidateAsset ? 'private, no-cache' : 'private, no-store');
-    response.setHeader('cdn-cache-control', 'no-store');
-    response.setHeader('surrogate-control', 'no-store');
-    response.setHeader('pragma', 'no-cache');
-    response.setHeader('expires', '0');
+    for (const [name, value] of Object.entries(SHARED_CACHE_REFUSAL))
+        response.setHeader(name, value);
 }
 /** HTTP-only streaming hop. Authentication, CSRF and release admission happen before calling this. */
 export function proxyHostedArtifact(options) {

package/dist/gateway/server.d.ts

@@ -1,13 +1,17 @@
 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 {
     control: ArtifactGatewayControl;
     runtimeDomain: string;
     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. */
@@ -18,12 +22,20 @@ export interface ArtifactGatewayOptions {
     renewLease?: (lease: TunnelLease) => Promise<boolean>;
     ready?: () => boolean;
     admission?: Pick<ArtifactRequestAdmission, 'acquire'>;
+    /** Rate limits `/_sequence/session` and `/_sequence/tunnel` before they reach Atlas. Without it
+     * both endpoints fail closed. */
+    controlAdmission?: Pick<GatewayControlAdmission, 'admit'>;
+    /** Reuse of a positive Atlas authorization (default GATEWAY_AUTHORIZATION_TTL_MS; 0 disables). */
+    authorizationCacheTtlMs?: number;
     onError?: (event: {
         kind: string;
         requestId?: string;
+        count?: number;
     }) => void;
 }
 export declare function createArtifactGateway(options: ArtifactGatewayOptions): {
     server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
+    /** Observations recorded but not yet confirmed by Atlas: what a forced exit would lose. */
+    readonly pendingUsage: number;
     drain(): Promise<void>;
 };