@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/dist/gateway/admission.js

@@ -0,0 +1,134 @@
+import { randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { z } from 'zod';
+import { artifactNextResourceLimitsSchema } from '../manifest-next.js';
+import { redisNamespaceSchema } from '../tunnel/redis-ownership.js';
+export class ArtifactAdmissionError extends Error {
+    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';
+    }
+}
+// The tunnel's APP_ENV namespace format, so both Redis key spaces accept the same deployment identities.
+const namespace = redisNamespaceSchema;
+const identifier = z.string().min(1).max(128).regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/);
+const resourceFields = artifactNextResourceLimitsSchema.unwrap().shape;
+const resources = z.object({
+    concurrency: resourceFields.concurrency,
+    max_instances: resourceFields.max_instances,
+    timeout_seconds: resourceFields.timeout_seconds,
+});
+// Both keys have the same Redis Cluster hash tag. A lease can never exist in
+// only one set, and previews/retained releases consume the same application cap.
+const ACQUIRE = `-- artifact-request-admission-acquire-v1
+local time = redis.call('TIME')
+local now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+local maximum = tonumber(ARGV[2])
+local deadline = now + tonumber(ARGV[3])
+for _, key in ipairs(KEYS) do
+  redis.call('ZREMRANGEBYSCORE', key, '-inf', now)
+  if redis.call('ZCARD', key) >= maximum then return {0, now} end
+end
+for _, key in ipairs(KEYS) do
+  redis.call('ZADD', key, deadline, ARGV[1])
+  local latest = redis.call('ZREVRANGE', key, 0, 0, 'WITHSCORES')
+  redis.call('PEXPIRE', key, tonumber(latest[2]) - now + 1000)
+end
+return {1, deadline}`;
+const RELEASE = `-- artifact-request-admission-release-v1
+for _, key in ipairs(KEYS) do
+  redis.call('ZREM', key, ARGV[1])
+  if redis.call('ZCARD', key) == 0 then redis.call('DEL', key) end
+end
+return 1`;
+/** Fail-closed admission with no command retries. An uncertain acquisition is
+ * never used; its unique permit expires even if Redis accepted it before loss. */
+export class ArtifactRequestAdmission {
+    options;
+    namespace;
+    ceiling;
+    constructor(options) {
+        this.options = options;
+        this.namespace = namespace.parse(options.namespace);
+        this.ceiling = z.number().int().min(1).max(256).parse(options.platformCeiling ?? 256);
+        const policy = options.redis.options;
+        if (policy.enableOfflineQueue !== false || policy.autoResendUnfulfilledCommands !== false || policy.maxRetriesPerRequest !== 0) {
+            throw new Error('Admission Redis must disable offline queues, command replay and retries');
+        }
+    }
+    async acquire(target) {
+        if (namespace.parse(target.environment) !== this.namespace)
+            throw new Error('Admission environment mismatch');
+        const projectId = identifier.parse(target.projectId), deploymentId = identifier.parse(target.deploymentId);
+        const limits = resources.parse(target.resources ?? {});
+        const maximum = Math.min(limits.concurrency * limits.max_instances, this.ceiling);
+        const timeoutMs = limits.timeout_seconds * 1000;
+        const requestId = randomUUID();
+        const prefix = `artifact-admission:${this.namespace}:{${this.namespace}:${projectId}}`;
+        const keys = [`${prefix}:app`, `${prefix}:deployment:${deploymentId}`];
+        const began = performance.now();
+        let result;
+        try {
+            result = z.tuple([z.number().int().min(0).max(1), z.number().int().positive()]).parse(await this.options.redis.eval(ACQUIRE, 2, ...keys, requestId, maximum, timeoutMs));
+        }
+        catch {
+            throw new ArtifactAdmissionError(503, 'admission_unavailable');
+        }
+        if (result[0] === 0)
+            throw new ArtifactAdmissionError(429, 'capacity_exceeded');
+        // Never start work under an admission whose local request budget already
+        // elapsed while Redis was unavailable or stalled. Redis TTL reclaims it.
+        if (performance.now() - began >= timeoutMs)
+            throw new ArtifactAdmissionError(503, 'admission_unavailable');
+        let releasePromise;
+        let cleanup;
+        let bound = false;
+        const release = () => {
+            cleanup?.();
+            // Repeated finish/close/error notifications must never free another
+            // request's permit, nor cause a failed command to be retried.
+            releasePromise ??= this.options.redis.eval(RELEASE, 2, ...keys, requestId).then(() => undefined, () => { throw new ArtifactAdmissionError(503, 'admission_unavailable'); });
+            return releasePromise;
+        };
+        const releaseQuietly = () => {
+            void release().catch(() => this.options.onError?.({ kind: 'admission_release_failed' }));
+        };
+        return {
+            requestId, deadline: result[1], timeoutMs, release,
+            bind: (response, onTimeout) => {
+                if (bound || releasePromise)
+                    throw new Error('Admission lease already bound or released');
+                bound = true;
+                const timer = setTimeout(() => {
+                    try {
+                        onTimeout();
+                    }
+                    catch {
+                        this.options.onError?.({ kind: 'admission_timeout_callback_failed' });
+                    }
+                    finally {
+                        releaseQuietly();
+                    }
+                }, Math.max(0, timeoutMs - (performance.now() - began)));
+                timer.unref();
+                cleanup = () => {
+                    clearTimeout(timer);
+                    response.off('finish', releaseQuietly);
+                    response.off('close', releaseQuietly);
+                };
+                response.once('finish', releaseQuietly);
+                response.once('close', releaseQuietly);
+                if (response.writableFinished || response.destroyed)
+                    releaseQuietly();
+                // Detaching also releases; callers cannot strand an admitted permit.
+                return releaseQuietly;
+            },
+        };
+    }
+}

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

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import type { TunnelLease } from '../tunnel/index.js';
+import type { GatewaySession } from './session.js';
+import type { GatewayUsageEvent } from './usage.js';
+export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"development">;
+    sessionId: z.ZodString;
+    epoch: z.ZodNumber;
+    projectId: z.ZodString;
+    ownerId: z.ZodString;
+    environment: z.ZodString;
+    publicOrigin: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    expiresAt: z.ZodNumber;
+    maxExpiresAt: z.ZodOptional<z.ZodNumber>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    serviceAccountId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    lattice: z.ZodOptional<z.ZodObject<{
+        runId: z.ZodNullable<z.ZodString>;
+        nodeId: z.ZodNullable<z.ZodString>;
+        stepId: z.ZodNullable<z.ZodString>;
+        processId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    manifest: z.ZodOptional<z.ZodObject<{
+        server: z.ZodObject<{
+            resources: z.ZodObject<{
+                concurrency: z.ZodNumber;
+                max_instances: z.ZodNumber;
+                timeout_seconds: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"hosted">;
+    deploymentId: z.ZodString;
+    frameworkBuildId: z.ZodString;
+    upstreamUrl: z.ZodString;
+    upstreamAudience: z.ZodOptional<z.ZodString>;
+    active: z.ZodBoolean;
+    published: z.ZodOptional<z.ZodBoolean>;
+    projectId: z.ZodString;
+    ownerId: z.ZodString;
+    environment: z.ZodString;
+    publicOrigin: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    expiresAt: z.ZodNumber;
+    maxExpiresAt: z.ZodOptional<z.ZodNumber>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    serviceAccountId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    lattice: z.ZodOptional<z.ZodObject<{
+        runId: z.ZodNullable<z.ZodString>;
+        nodeId: z.ZodNullable<z.ZodString>;
+        stepId: z.ZodNullable<z.ZodString>;
+        processId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    manifest: z.ZodOptional<z.ZodObject<{
+        server: z.ZodObject<{
+            resources: z.ZodObject<{
+                concurrency: z.ZodNumber;
+                max_instances: z.ZodNumber;
+                timeout_seconds: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "kind">;
+export type GatewayTarget = z.infer<typeof gatewayTargetSchema>;
+export declare class GatewayControlError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+export declare class ArtifactGatewayControl {
+    private readonly options;
+    private readonly origin;
+    constructor(options: {
+        url: string;
+        token: string;
+        fetch?: typeof fetch;
+    });
+    private call;
+    /** 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;
+    }>;
+    authorize(session: GatewaySession): Promise<GatewayTarget>;
+    tunnel({ token, sessionId, epoch }: {
+        token: string;
+        sessionId: string;
+        epoch: number;
+    }): Promise<TunnelLease>;
+}