@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/dist/runtime-contracts.js

@@ -0,0 +1,224 @@
+import { z } from 'zod';
+import { ARTIFACT_NEXT_RUNTIME, artifactNextSecretNameSchema } from './manifest-next.js';
+import { MAX_STUDIO_PATH_LENGTH } from './paths.js';
+export { resolveArtifactNextImages } from './next-image-config.js';
+/** Shared by local collection, repository collection and the bounded source-upload API. */
+export const ARTIFACT_NEXT_SOURCE_LIMITS = Object.freeze({
+    maxFiles: 2_000,
+    maxFileBytes: 10 * 1024 * 1024,
+    maxTotalBytes: 32 * 1024 * 1024,
+});
+const identifierSchema = z.string().min(1).max(256).regex(/^[^\s\u0000-\u001f\u007f]+$/);
+const timestampSchema = z.iso.datetime();
+const exactVersionSchema = z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/, 'An exact, stable toolchain version is required');
+export const artifactSha256DigestSchema = z.string().regex(/^[a-f0-9]{64}$/, 'Expected a lowercase SHA-256 digest');
+/** Immutable Next deploymentId from compiled output; distinct from the Atlas activation ID. */
+export const artifactNextFrameworkBuildIdSchema = z.string().min(1).max(128).refine((value) => !/[^A-Za-z0-9_-]/.test(value), 'Expected a canonical Next.js deploymentId containing only letters, digits, underscores and hyphens');
+const imageDigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/, 'Expected a SHA-256 image digest');
+const imageReferenceSchema = z.string().max(1024).regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*(?::[1-9][0-9]{0,4})?(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)+@sha256:[a-f0-9]{64}$/, 'Expected a registry image reference pinned by digest');
+const excludedSourceSegments = new Set([
+    '.git', 'node_modules', '.next', '.npmrc', '.netrc', '.aws', '.ssh', '.config',
+    'dist', '.artifact-studio', '.git-credentials', '.pypirc', '.azure', '.gcloud', '.doppler',
+    '.turbo', 'coverage', '.docker',
+]);
+/** Shared upload exclusion policy. Content scanning and filesystem containment remain separate checks. */
+export function isExcludedArtifactSourcePath({ path }) {
+    return path.split('/').some((segment) => {
+        const normalized = segment.toLowerCase();
+        return excludedSourceSegments.has(normalized)
+            || normalized.startsWith('.env') || normalized.startsWith('.yarnrc')
+            || /(?:^|[-_.])(?:credentials?|service[-_]?account)(?:[-_.].*)?\.json$/.test(normalized)
+            || /\.(pem|key|p12|pfx|jks)$/.test(normalized);
+    });
+}
+/** POSIX source paths only; filesystem readers must additionally reject symlink escapes. */
+export const artifactSourcePathSchema = z.string().min(1).max(MAX_STUDIO_PATH_LENGTH).refine((path) => {
+    if (path !== path.trim() || /[\\%:\u0000-\u001f\u007f]/.test(path))
+        return false;
+    return !isExcludedArtifactSourcePath({ path })
+        && path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}, 'Source paths must be relative and exclude credentials, dependencies and build output');
+/** An exact browser origin, not a URL prefix or an allowlist wildcard. */
+export const artifactRuntimeOriginSchema = z.string().max(2048).refine((value) => {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && url.origin === value && !url.hostname.includes('*');
+    }
+    catch {
+        return false;
+    }
+}, 'Expected an exact, canonical HTTPS origin');
+const sourceFileSchema = z.strictObject({
+    path: artifactSourcePathSchema,
+    sha256: artifactSha256DigestSchema,
+    sizeBytes: z.number().int().nonnegative().max(ARTIFACT_NEXT_SOURCE_LIMITS.maxFileBytes),
+});
+/** Metadata points to an immutable snapshot; file bytes travel through the source-upload API. */
+export const artifactNextBuildInputSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    framework: z.literal('nextjs'),
+    projectId: identifierSchema,
+    source: z.strictObject({
+        snapshotId: identifierSchema,
+        sha256: artifactSha256DigestSchema,
+        git: z.strictObject({
+            repositoryId: identifierSchema,
+            commitSha: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/, 'Expected a full Git commit SHA'),
+        }),
+        files: z.array(sourceFileSchema).min(1).max(ARTIFACT_NEXT_SOURCE_LIMITS.maxFiles),
+    }),
+    lockfile: z.strictObject({ path: z.literal('pnpm-lock.yaml'), sha256: artifactSha256DigestSchema }),
+    toolchain: z.strictObject({
+        node: exactVersionSchema.refine((version) => version.startsWith(`${ARTIFACT_NEXT_RUNTIME.node}.`), 'Unsupported Node runtime'),
+        next: exactVersionSchema.refine((version) => version.startsWith(`${ARTIFACT_NEXT_RUNTIME.next}.`), 'Unsupported Next.js release line'),
+        react: exactVersionSchema.refine((version) => version.startsWith(`${ARTIFACT_NEXT_RUNTIME.react}.`), 'Unsupported React release line'),
+        packageManager: z.strictObject({ name: z.literal('pnpm'), version: exactVersionSchema }),
+        builderImageDigest: imageDigestSchema,
+    }),
+}).superRefine((value, ctx) => {
+    if (value.source.files.reduce((total, file) => total + file.sizeBytes, 0) > ARTIFACT_NEXT_SOURCE_LIMITS.maxTotalBytes) {
+        ctx.addIssue({ code: 'custom', path: ['source', 'files'], message: 'Source snapshot exceeds the upload size limit' });
+    }
+    const seen = new Set();
+    for (const [index, file] of value.source.files.entries()) {
+        if (seen.has(file.path)) {
+            ctx.addIssue({ code: 'custom', path: ['source', 'files', index, 'path'], message: 'Duplicate source path' });
+        }
+        seen.add(file.path);
+    }
+    for (const [index, file] of value.source.files.entries()) {
+        const segments = file.path.split('/');
+        for (let depth = 1; depth < segments.length; depth += 1) {
+            if (seen.has(segments.slice(0, depth).join('/'))) {
+                ctx.addIssue({ code: 'custom', path: ['source', 'files', index, 'path'], message: 'A source file cannot also be a directory' });
+                break;
+            }
+        }
+    }
+    const lockfile = value.source.files.find((file) => file.path === value.lockfile.path);
+    if (!lockfile || lockfile.sha256 !== value.lockfile.sha256) {
+        ctx.addIssue({ code: 'custom', path: ['lockfile'], message: 'The pinned lockfile must match a file in the source snapshot' });
+    }
+});
+const immutableObjectSchema = z.strictObject({ objectId: identifierSchema, sha256: artifactSha256DigestSchema });
+export const artifactDeploymentOutputSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('static'), bundle: immutableObjectSchema }),
+    z.strictObject({
+        kind: z.literal('next-server'),
+        frameworkBuildId: artifactNextFrameworkBuildIdSchema,
+        imageRef: imageReferenceSchema,
+        assets: immutableObjectSchema,
+        buildInputSha256: artifactSha256DigestSchema,
+    }),
+]);
+const operationFields = {
+    id: identifierSchema,
+    projectId: identifierSchema,
+    environment: identifierSchema,
+    kind: z.enum(['build', 'deploy', 'preview', 'rollback', 'suspend', 'delete']),
+    deploymentId: identifierSchema.optional(),
+    createdAt: timestampSchema,
+    updatedAt: timestampSchema,
+};
+const operationProgressSchema = z.strictObject({
+    stage: z.string().min(1).max(128),
+    percent: z.number().min(0).max(100).optional(),
+});
+export const artifactOperationSchema = z.discriminatedUnion('status', [
+    z.strictObject({ ...operationFields, status: z.literal('queued') }),
+    z.strictObject({ ...operationFields, status: z.literal('running'), progress: operationProgressSchema.optional() }),
+    z.strictObject({ ...operationFields, status: z.literal('succeeded'), completedAt: timestampSchema }),
+    z.strictObject({
+        ...operationFields,
+        status: z.literal('failed'),
+        completedAt: timestampSchema,
+        error: z.strictObject({ code: identifierSchema, message: z.string().min(1).max(4096) }),
+    }),
+    z.strictObject({ ...operationFields, status: z.literal('cancelled'), completedAt: timestampSchema }),
+]).superRefine((value, ctx) => {
+    if (Date.parse(value.updatedAt) < Date.parse(value.createdAt)) {
+        ctx.addIssue({ code: 'custom', path: ['updatedAt'], message: 'An operation cannot be updated before it was created' });
+    }
+    if ('completedAt' in value && (Date.parse(value.completedAt) < Date.parse(value.createdAt)
+        || Date.parse(value.completedAt) > Date.parse(value.updatedAt))) {
+        ctx.addIssue({ code: 'custom', path: ['completedAt'], message: 'Completion must be between creation and the last update' });
+    }
+});
+/** Runtime bootstrap is ephemeral. Do not persist bootstrap URLs in deployment history. */
+export const artifactRuntimeSessionSchema = z.strictObject({
+    id: identifierSchema,
+    projectId: identifierSchema,
+    environment: identifierSchema,
+    mode: z.enum(['local', 'preview', 'published']),
+    origin: artifactRuntimeOriginSchema,
+    parentOrigin: artifactRuntimeOriginSchema,
+    bootstrapUrl: z.url().max(4096),
+    bridge: z.strictObject({ protocolVersion: z.literal(1), channelId: identifierSchema }),
+    expiresAt: timestampSchema,
+}).superRefine((value, ctx) => {
+    let validBootstrap = false;
+    try {
+        const url = new URL(value.bootstrapUrl);
+        validBootstrap = url.origin === value.origin && !url.username && !url.password && !url.hash;
+    }
+    catch {
+        // URL syntax failures are also reported by the field schema; never throw from safeParse.
+    }
+    if (!validBootstrap) {
+        ctx.addIssue({ code: 'custom', path: ['bootstrapUrl'], message: 'Bootstrap must use the exact runtime origin without credentials or a fragment' });
+    }
+});
+/** Public session metadata contains no tunnel bearer, local credentials or managed secrets. */
+export const artifactLocalDevSessionSchema = z.strictObject({
+    id: identifierSchema,
+    ownerId: identifierSchema,
+    projectId: identifierSchema,
+    environment: identifierSchema,
+    origin: artifactRuntimeOriginSchema,
+    sourceRevision: artifactSha256DigestSchema.optional(),
+    revision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    state: z.enum(['starting', 'compiling', 'ready', 'reconnecting', 'failed', 'offline', 'revoked', 'expired']),
+    lease: z.strictObject({
+        id: identifierSchema,
+        fence: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+        expiresAt: timestampSchema,
+    }),
+    createdAt: timestampSchema,
+    updatedAt: timestampSchema,
+    expiresAt: timestampSchema,
+}).superRefine((value, ctx) => {
+    const created = Date.parse(value.createdAt);
+    const updated = Date.parse(value.updatedAt);
+    const expires = Date.parse(value.expiresAt);
+    const leaseExpires = Date.parse(value.lease.expiresAt);
+    if (updated < created || expires <= created || leaseExpires <= created || leaseExpires > expires) {
+        ctx.addIssue({ code: 'custom', path: ['lease', 'expiresAt'], message: 'Session timestamps must be ordered and the lease cannot outlive its session' });
+    }
+    if (['starting', 'compiling', 'ready', 'reconnecting'].includes(value.state) && updated >= leaseExpires) {
+        ctx.addIssue({ code: 'custom', path: ['updatedAt'], message: 'An active session must have an unexpired lease at its last update' });
+    }
+});
+export const artifactActivationSchema = z.strictObject({
+    id: identifierSchema,
+    projectId: identifierSchema,
+    environment: identifierSchema,
+    deploymentId: identifierSchema,
+    configurationSha256: artifactSha256DigestSchema,
+    policySha256: artifactSha256DigestSchema,
+    secretVersions: z.array(z.strictObject({
+        binding: artifactNextSecretNameSchema,
+        secretId: identifierSchema,
+        version: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    })).max(100),
+    cacheGeneration: identifierSchema,
+    activatedAt: timestampSchema,
+    activatedBy: identifierSchema,
+}).superRefine((value, ctx) => {
+    const bindings = new Set();
+    for (const [index, secret] of value.secretVersions.entries()) {
+        if (bindings.has(secret.binding)) {
+            ctx.addIssue({ code: 'custom', path: ['secretVersions', index, 'binding'], message: 'Secret binding names must be unique' });
+        }
+        bindings.add(secret.binding);
+    }
+});

package/dist/sdk.d.ts

@@ -161,7 +161,7 @@ export declare function createArtifactStorageClient(sdk?: SequenceArtifactSdk):
                 fileId: string;
                 uploadUrl: string | null;
                 expiresAt: string;
-                state: "aborted" | "pending" | "complete";
+                state: "aborted" | "complete" | "pending";
                 versionId: string | null;
                 maxBytes: number;
             }>;
@@ -170,7 +170,7 @@ export declare function createArtifactStorageClient(sdk?: SequenceArtifactSdk):
                 fileId: string;
                 uploadUrl: string | null;
                 expiresAt: string;
-                state: "aborted" | "pending" | "complete";
+                state: "aborted" | "complete" | "pending";
                 versionId: string | null;
                 maxBytes: number;
             }>;

package/dist/server/broker-contract.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+export declare const artifactServerMethodSchema: z.ZodEnum<{
+    GET: "GET";
+    POST: "POST";
+    DELETE: "DELETE";
+    HEAD: "HEAD";
+    PUT: "PUT";
+    PATCH: "PATCH";
+}>;
+export declare const artifactServerModeSchema: z.ZodDefault<z.ZodEnum<{
+    user: "user";
+    service: "service";
+}>>;
+/** Reject paths that intermediaries can normalize into a different authorization target. */
+export declare function isArtifactApiPath(path: string): boolean;
+/** Atlas validates these operations against current manifest, bindings and principal grants. */
+export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<"api">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        user: "user";
+        service: "service";
+    }>>;
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
+        PUT: "PUT";
+        PATCH: "PATCH";
+    }>;
+    path: z.ZodString;
+    body: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"orm">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        user: "user";
+        service: "service";
+    }>>;
+    namespace: z.ZodString;
+    op: z.ZodString;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"storage">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        user: "user";
+        service: "service";
+    }>>;
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
+        PUT: "PUT";
+        PATCH: "PATCH";
+    }>;
+    path: z.ZodString;
+    body: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"function">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        user: "user";
+        service: "service";
+    }>>;
+    id: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>], "operation">;
+export type ArtifactServerRequest = z.infer<typeof artifactServerRequestSchema>;
+export type ArtifactServerMode = z.infer<typeof artifactServerModeSchema>;

package/dist/server/broker-contract.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+export const artifactServerMethodSchema = z.enum(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']);
+export const artifactServerModeSchema = z.enum(['user', 'service']).default('user');
+/** Reject paths that intermediaries can normalize into a different authorization target. */
+export function isArtifactApiPath(path) {
+    if (!path.startsWith('/api/') || path.startsWith('//') || /[\\\r\n\u0000#]/.test(path))
+        return false;
+    const pathname = path.split('?')[0];
+    if (/%(?:2e|2f|5c|25)/i.test(pathname) || pathname.includes('//'))
+        return false;
+    if (pathname.split('/').some(part => part === '.' || part === '..'))
+        return false;
+    try {
+        return new URL(path, 'https://artifact.invalid').pathname === pathname;
+    }
+    catch {
+        return false;
+    }
+}
+const path = z.string().min(6).max(8192).refine(isArtifactApiPath, 'Expected a canonical Atlas API path');
+const method = artifactServerMethodSchema;
+const mode = artifactServerModeSchema;
+const id = z.string().min(1).max(255).regex(/^[a-zA-Z0-9_-]+$/);
+/** Atlas validates these operations against current manifest, bindings and principal grants. */
+export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
+    z.object({ operation: z.literal('api'), mode, method, path, body: z.unknown().optional() }).strict(),
+    z.object({ operation: z.literal('orm'), mode, namespace: id, op: z.string().regex(/^sha256:[a-f0-9]{64}$/), variables: z.record(z.string(), z.unknown()).optional() }).strict(),
+    z.object({ operation: z.literal('storage'), mode, method, path: path.refine(value => {
+            const pathname = value.split('?')[0];
+            return pathname === '/api/storage' || pathname.startsWith('/api/storage/');
+        }, 'Expected a Storage API path'), body: z.unknown().optional() }).strict(),
+    z.object({ operation: z.literal('function'), mode, id, params: z.record(z.string(), z.unknown()).optional() }).strict(),
+]);

package/dist/server/client.d.ts

@@ -0,0 +1,81 @@
+import { storageClient } from '@sequenceholdings/storage';
+import { type OperationExecutor } from '@sequenceholdings/orm/client';
+import type { SequenceApiFetchResponse } from '../sdk.js';
+import { type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+import { createArtifactLogger, type ArtifactLogRecord } from './logger.js';
+import { type ArtifactRequestContext } from './request-context.js';
+import { type ArtifactRuntimeConfig, type ArtifactRequestHeaders } from './runtime-config.js';
+export declare class ArtifactServerError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface ArtifactServerFetchOptions {
+    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    signal?: AbortSignal;
+}
+/**
+ * The namespace's generated operations.manifest.json. Only each operation's persisted hash
+ * is read, so the file can be passed as imported: a JSON import types `kind` as string.
+ */
+export interface ArtifactOrmOperations {
+    readonly manifestVersion?: number;
+    readonly schemaHash?: string;
+    readonly opsHash?: string;
+    readonly operations: Readonly<Record<string, {
+        readonly hash: string;
+        readonly kind?: string;
+        readonly requires?: unknown;
+    }>>;
+}
+export interface ArtifactServerClient {
+    context: ArtifactRequestContext;
+    mode: ArtifactServerMode;
+    log: ReturnType<typeof createArtifactLogger>;
+    api: ReturnType<typeof createApiClient>;
+    storage: ReturnType<typeof storageClient>;
+    functions: {
+        invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>): Promise<TOutput>;
+    };
+    orm(input: {
+        namespace: string;
+        manifest: ArtifactOrmOperations;
+    }): OperationExecutor;
+    asService(): ArtifactServerClient;
+}
+/** One instance per incoming request. Never cache it at module scope. */
+export declare function createArtifactServerClient({ headers, runtime, fetch: fetcher, method, path, logSink }: {
+    headers: ArtifactRequestHeaders;
+    /** Optional explicit platform config; otherwise reads SEQUENCE_ARTIFACT_RUNTIME_FILE. */
+    runtime?: ArtifactRuntimeConfig;
+    fetch?: typeof globalThis.fetch;
+    method?: string;
+    path?: string;
+    logSink?: (record: ArtifactLogRecord) => void;
+}): Promise<ArtifactServerClient>;
+type ClientArguments = {
+    context: ArtifactRequestContext;
+    token: string;
+    getRuntime: () => Promise<ArtifactRuntimeConfig>;
+    fetcher: typeof globalThis.fetch;
+    mode: ArtifactServerMode;
+    logSink?: (record: ArtifactLogRecord) => void;
+};
+type BrokerTransport = ReturnType<typeof createBrokerTransport>;
+declare function createBrokerTransport({ context, token, getRuntime, fetcher }: ClientArguments): (input: ArtifactServerRequest, signal?: AbortSignal) => Promise<Response>;
+declare function createApiClient({ mode, request, json }: {
+    mode: ArtifactServerMode;
+    request: BrokerTransport;
+    json: (operation: ArtifactServerRequest, signal?: AbortSignal) => Promise<unknown>;
+}): {
+    request: (path: string, options?: ArtifactServerFetchOptions) => Promise<Response>;
+    fetch<TBody = unknown>(path: string, options?: ArtifactServerFetchOptions): Promise<SequenceApiFetchResponse<TBody>>;
+    stream(path: string, options?: ArtifactServerFetchOptions): Promise<ReadableStream<Uint8Array<ArrayBuffer>>>;
+    get: <T = unknown>(path: string) => Promise<T>;
+    post: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+    put: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+    patch: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+    delete: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+};
+export {};

package/dist/server/client.js

@@ -0,0 +1,159 @@
+import { StorageApiError, storageClient, storageErrorSchema } from '@sequenceholdings/storage';
+import { OrmOperationError } from '@sequenceholdings/orm/client';
+import { z } from 'zod';
+import { artifactServerRequestSchema } from './broker-contract.js';
+import { createArtifactLogger } from './logger.js';
+import { ARTIFACT_REQUEST_CONTEXT_HEADER, ARTIFACT_RUNTIME_TOKEN_HEADER, ARTIFACT_SERVER_REQUEST_PATH, verifyArtifactRequestContext } from './request-context.js';
+import { artifactRuntimeConfigSchema, readArtifactRuntimeConfig } from './runtime-config.js';
+export class ArtifactServerError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'ArtifactServerError';
+    }
+}
+const graphqlResponseSchema = z.object({
+    data: z.unknown().optional(),
+    errors: z.array(z.object({ message: z.string(), extensions: z.object({ code: z.string().optional() }).passthrough().optional() })).optional(),
+});
+const responseHeaders = ['content-type', 'content-disposition', 'content-length', 'retry-after'];
+const maxBodyBytes = 1024 * 1024;
+/** One instance per incoming request. Never cache it at module scope. */
+export async function createArtifactServerClient({ headers, runtime, fetch: fetcher = globalThis.fetch, method, path, logSink }) {
+    const config = runtime ? artifactRuntimeConfigSchema.parse(runtime) : await readArtifactRuntimeConfig();
+    if (!config)
+        throw new ArtifactServerError(401, 'runtime_not_connected', 'Run seq-studio artifact dev to connect platform services, or use a hosted preview.');
+    const token = headers.get(ARTIFACT_REQUEST_CONTEXT_HEADER);
+    const context = verifyArtifactRequestContext({ token, publicKeys: config.publicKeys, projectId: config.projectId, environment: config.environment, method, path });
+    if (!token || (config.devSessionId && context.devSessionId !== config.devSessionId) ||
+        (config.deploymentId && context.deploymentId !== config.deploymentId))
+        throw new ArtifactServerError(401, 'invalid_runtime_session', 'Artifact request does not belong to this runtime');
+    const getRuntime = async () => {
+        const current = runtime ? config : await readArtifactRuntimeConfig();
+        if (!current || current.projectId !== config.projectId || current.environment !== config.environment || current.atlasUrl !== config.atlasUrl || current.devSessionId !== config.devSessionId || current.deploymentId !== config.deploymentId)
+            throw new ArtifactServerError(401, 'runtime_changed', 'Artifact runtime disconnected or changed; reload the preview');
+        return current;
+    };
+    return buildClient({ context, token, getRuntime, fetcher, mode: 'user', logSink });
+}
+function buildClient(args) {
+    const { context, mode, logSink } = args;
+    const request = createBrokerTransport(args);
+    const json = async (operation, signal) => {
+        const response = await request(operation, signal);
+        if (!response.ok)
+            throw new ArtifactServerError(response.status, 'platform_request_failed', `Atlas rejected the ${operation.operation} request (${response.status})`);
+        return response.status === 204 ? undefined : response.json();
+    };
+    // storageClient retries replay-safe calls on 503 permissions_pending / storage_busy, so Storage
+    // failures keep the envelope's status and code rather than collapsing into platform_request_failed.
+    const storageJson = async (operation) => {
+        const response = await request(operation);
+        if (!response.ok)
+            throw await storageApiError(response);
+        return response.status === 204 ? undefined : response.json();
+    };
+    return {
+        context,
+        mode,
+        log: createArtifactLogger({ context, sink: logSink }),
+        api: createApiClient({ mode, request, json }),
+        storage: storageClient({ request: (method, path, body) => storageJson(artifactServerRequestSchema.parse({ operation: 'storage', mode, method, path, body })) }),
+        functions: {
+            invoke: async (id, params) => {
+                // The caller supplies its application's function output type; Atlas owns runtime validation.
+                return await json(artifactServerRequestSchema.parse({ operation: 'function', mode, id, params }));
+            },
+        },
+        orm: ({ namespace, manifest }) => ({
+            async execute(op, variables = {}) {
+                const hash = op.startsWith('sha256:') ? op : manifest.operations[op]?.hash;
+                if (!hash)
+                    throw new ArtifactServerError(400, 'unknown_orm_operation', 'ORM operation is not in the generated manifest; run seq-studio orm generate');
+                const response = await request(artifactServerRequestSchema.parse({ operation: 'orm', mode, namespace, op: hash, variables }));
+                const parsed = graphqlResponseSchema.safeParse(await response.json().catch(() => null));
+                if (!parsed.success)
+                    throw new OrmOperationError('Malformed Data API response', response.status, 'invalid_response');
+                const first = parsed.data.errors?.[0];
+                if (!response.ok || first)
+                    throw new OrmOperationError(first?.message ?? `Data API request failed (${response.status})`, response.status, first?.extensions?.code ?? null, parsed.data.errors);
+                if (parsed.data.data === undefined || parsed.data.data === null)
+                    throw new OrmOperationError('Malformed Data API response: missing data', response.status, 'invalid_response');
+                // Mirrors the generated ORM executor contract: consumers provide their generated result type.
+                return parsed.data.data;
+            },
+        }),
+        /** Deliberate escalation, still clamped to a separately attached service identity. */
+        asService() {
+            if (!context.serviceAccountId)
+                throw new ArtifactServerError(403, 'service_identity_unavailable', 'No service identity is attached to this runtime');
+            return buildClient({ ...args, mode: 'service' });
+        },
+    };
+}
+/** Mirrors createStorageClient: Storage's `{ error: { code, message } }` envelope survives the broker. */
+async function storageApiError(response) {
+    const envelope = storageErrorSchema.safeParse(await response.json().catch(() => undefined));
+    return new StorageApiError(response.status, envelope.success ? envelope.data.error.code : 'request_failed', envelope.success ? envelope.data.error.message : `Storage request failed (${response.status})`);
+}
+function createBrokerTransport({ context, token, getRuntime, fetcher }) {
+    return async (input, signal) => {
+        if (context.exp <= Math.floor(Date.now() / 1000))
+            throw new ArtifactServerError(401, 'request_context_expired', 'Artifact request context expired; begin a new request');
+        const operation = artifactServerRequestSchema.parse(input);
+        if (operation.mode === 'service' && !context.serviceAccountId)
+            throw new ArtifactServerError(403, 'service_identity_unavailable', 'No service identity is attached to this runtime');
+        const body = JSON.stringify(operation);
+        if (Buffer.byteLength(body, 'utf8') > maxBodyBytes)
+            throw new ArtifactServerError(413, 'request_too_large', 'Server SDK requests are limited to 1 MiB; use Storage uploads for files');
+        const runtime = await getRuntime();
+        return fetcher(`${runtime.atlasUrl}${ARTIFACT_SERVER_REQUEST_PATH}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                [ARTIFACT_RUNTIME_TOKEN_HEADER]: runtime.sessionToken,
+                [ARTIFACT_REQUEST_CONTEXT_HEADER]: token,
+            },
+            body,
+            cache: 'no-store',
+            redirect: 'error',
+            credentials: 'omit',
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(60_000)]) : AbortSignal.timeout(60_000),
+        });
+    };
+}
+function createApiClient({ mode, request, json }) {
+    const operation = (path, options = {}) => artifactServerRequestSchema.parse({ operation: 'api', mode, method: options.method ?? 'GET', path, body: options.body });
+    const fetchResponse = (path, options = {}) => request(operation(path, options), options.signal);
+    const typedJson = async (path, options = {}) => {
+        // Explicit caller result types match the existing browser SDK; the server validates endpoint schemas.
+        return await json(operation(path, options), options.signal);
+    };
+    return {
+        request: fetchResponse,
+        async fetch(path, options = {}) {
+            const response = await fetchResponse(path, options);
+            const contentType = response.headers.get('content-type') ?? '';
+            const body = response.status === 204 ? undefined : contentType.includes('json') ? await response.json() : await response.arrayBuffer();
+            // The caller declares the endpoint's response type, consistent with SequenceApiFetchResponse.
+            return { ok: response.ok, status: response.status, body: body, headers: Object.fromEntries(responseHeaders.flatMap(key => {
+                    const value = response.headers.get(key);
+                    return value === null ? [] : [[key, value]];
+                })) };
+        },
+        async stream(path, options = {}) {
+            const response = await fetchResponse(path, options);
+            if (!response.ok || !response.body)
+                throw new ArtifactServerError(response.status, 'stream_unavailable', 'Atlas did not return a readable response');
+            return response.body;
+        },
+        get: (path) => typedJson(path),
+        post: (path, body) => typedJson(path, { method: 'POST', body }),
+        put: (path, body) => typedJson(path, { method: 'PUT', body }),
+        patch: (path, body) => typedJson(path, { method: 'PATCH', body }),
+        delete: (path, body) => typedJson(path, { method: 'DELETE', body }),
+    };
+}

package/dist/server/logger.d.ts

@@ -0,0 +1,26 @@
+import type { ArtifactRequestContext } from './request-context.js';
+export interface ArtifactLogMetadata {
+    resourceId?: string;
+    operationId?: string;
+    durationMs?: number;
+    count?: number;
+    status?: number;
+    errorCode?: string;
+}
+export interface ArtifactLogRecord extends ArtifactLogMetadata {
+    event: string;
+    level: 'info' | 'warn' | 'error';
+    projectId: string;
+    requestId: string;
+    deploymentId: string | null;
+    devSessionId: string | null;
+}
+/** Structured events deliberately exclude request bodies, URLs, arbitrary messages and error objects. */
+export declare function createArtifactLogger({ context, sink }: {
+    context: ArtifactRequestContext;
+    sink?: (record: ArtifactLogRecord) => void;
+}): {
+    info: (event: string, metadata?: ArtifactLogMetadata) => void;
+    warn: (event: string, metadata?: ArtifactLogMetadata) => void;
+    error: (event: string, metadata?: ArtifactLogMetadata) => void;
+};

package/dist/server/logger.js

@@ -0,0 +1,24 @@
+/** Structured events deliberately exclude request bodies, URLs, arbitrary messages and error objects. */
+export function createArtifactLogger({ context, sink = record => console[record.level](record) }) {
+    const write = (level, event, metadata = {}) => {
+        if (!/^[a-z][a-z0-9_.-]{0,95}$/.test(event))
+            throw new Error('Log event must be a static dot-separated identifier');
+        const safe = {};
+        for (const key of ['durationMs', 'count', 'status']) {
+            const value = metadata[key];
+            if (typeof value === 'number' && Number.isFinite(value))
+                safe[key] = value;
+        }
+        for (const key of ['resourceId', 'operationId', 'errorCode']) {
+            const value = metadata[key];
+            if (typeof value === 'string' && /^[a-zA-Z0-9_.:-]{1,128}$/.test(value))
+                safe[key] = value;
+        }
+        sink({ ...safe, event, level, projectId: context.projectId, requestId: context.requestId, deploymentId: context.deploymentId, devSessionId: context.devSessionId });
+    };
+    return {
+        info: (event, metadata) => write('info', event, metadata),
+        warn: (event, metadata) => write('warn', event, metadata),
+        error: (event, metadata) => write('error', event, metadata),
+    };
+}

package/dist/server/release-forms.d.ts

@@ -0,0 +1,13 @@
+import { TransformStream } from 'node:stream/web';
+/**
+ * Stamp forms with the document's release identity, including GET forms whose
+ * submitter can override the method to POST. The gateway removes the reserved
+ * field from GET query strings before forwarding them to application code.
+ * Only use on decompressed UTF-8 HTML; remove Content-Length and ETag upstream.
+ * Named hidden inputs are skipped by React 19 hydration, preserving RSC markup.
+ * The gateway must reject missing/conflicting markers before admitting mutations.
+ */
+export declare function createReleaseFormTransform({ deploymentId, documentUrl }: {
+    deploymentId: string;
+    documentUrl: string;
+}): TransformStream<Uint8Array, Uint8Array>;