@sequenceholdings/artifact-studio 0.5.0 → 0.6.2

package/dist/server/broker-contract.js

@@ -31,6 +31,8 @@ const latticeVersion = z.string().min(1).max(128).regex(/^[A-Za-z0-9._-]+$/);
 export const ARTIFACT_PROCESS_RUN_STATUSES = ['pending', 'running', 'completed', 'failed', 'cancelled', 'timed_out'];
 /** Lattice lists at most this many runs per call. */
 export const ARTIFACT_PROCESS_RUNS_LIMIT = 500;
+/** A run-events read returns at most this many events per call, as the run's stream drains them. */
+export const ARTIFACT_PROCESS_RUN_EVENTS_LIMIT = 1000;
 /** Which of the user's human steps to list: parked and waiting on them, or already done. */
 export const ARTIFACT_PROCESS_TASK_VIEWS = ['active', 'completed'];
 /** Lattice lists at most this many human steps per call, as its own inbox does. */
@@ -106,10 +108,12 @@ export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
         }, '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(),
     // Starts a run of a declared process, as `POST /api/lattice/runs` does: the application names the
-    // run, passes its input and may seed who works each human node. The start node, version and
-    // engine stay with the process and its owning routes.
+    // run, passes its input, may seed who works each human node and may enter the graph at a node
+    // other than the process's start (the route's `start_node_id`). The version and engine stay with
+    // the process and its owning routes.
     z.object({
         operation: z.literal('lattice'), mode, process: latticeId, runId: latticeId.optional(),
+        startNodeId: z.string().min(1).max(255).regex(/^[A-Za-z0-9._-]+$/).optional(),
         title: z.string().max(500).optional(),
         entity: z.object({ type: entityRef, id: entityRef }).strict().optional(),
         metadata: z.record(z.string(), z.unknown()).optional(),
@@ -127,6 +131,14 @@ export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
     // Reads one run the user may view, as `GET /api/lattice/runs/[runId]` does: the run, its steps, the
     // collapsed per-node states and the event cursor to resume its stream from.
     z.object({ operation: z.literal('lattice_run'), mode, runId: latticeId }).strict(),
+    // A page of a run's events after a cursor, oldest first, as `GET /api/lattice/runs/[runId]/stream`
+    // sends them: `since` is the cursor `lattice_run` returned, or the one the previous page returned.
+    // Polling with it sees every event exactly once. The user's Viewer relation on the run decides.
+    z.object({
+        operation: z.literal('lattice_run_events'), mode, runId: latticeId,
+        since: z.string().min(1).max(512).optional(),
+        limit: z.number().int().min(1).max(ARTIFACT_PROCESS_RUN_EVENTS_LIMIT).optional(),
+    }).strict(),
     // Describes a declared process — the applied template its runs are filled in from: nodes, edges and
     // what a person working each human step is shown. The active version, or the one a run pinned.
     z.object({ operation: z.literal('lattice_process'), mode, process: latticeId, version: latticeVersion.optional() }).strict(),
@@ -150,6 +162,12 @@ export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
     // The user's run `owner` relation decides; the node's assignee allowlist still applies.
     z.object({ operation: z.literal('lattice_assign'), mode, runId: latticeId, stepId: latticeId, ...principalSet }).strict()
         .refine(namesPrincipals, PRINCIPAL_SET_MESSAGE),
+    // Cancels a run of a process declared under `processes.act`, with its forked lineage, as
+    // `POST /api/lattice/runs/[runId]/cancel` does. The user's Invoker relation on the run decides.
+    z.object({ operation: z.literal('lattice_cancel'), mode, runId: latticeId }).strict(),
+    // Resets a generating agent step without cancelling its run, as `POST .../steps/[stepId]/reset`
+    // does: the step settles and the run re-parks at the node's reset edge. Invoker-gated.
+    z.object({ operation: z.literal('lattice_reset_step'), mode, runId: latticeId, stepId: latticeId }).strict(),
     // The explicit viewer grants on a run, for its owner.
     z.object({ operation: z.literal('lattice_viewers'), mode, runId: latticeId }).strict(),
     // Shares a run with users and groups (grants `viewer`), or takes a share back. Owner-gated;

package/dist/server/client.d.ts

@@ -1,19 +1,17 @@
 import { storageClient } from '@sequenceholdings/storage';
 import { type OperationExecutor } from '@sequenceholdings/orm/client';
-import type { SequenceApiFetchResponse } from '../sdk.js';
-import { type ArtifactAuditAction, type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+import { type ArtifactAuditAction, type ArtifactServerMode } from './broker-contract.js';
 import { type ArtifactServerProcesses } from './processes.js';
 import { type ArtifactOrmJsonScalars } from '../orm-json-scalars.js';
 import { createArtifactLogger, type ArtifactLogRecord } from './logger.js';
-import { type ArtifactRequestContext } from './request-context.js';
+import { type ArtifactRequestContext, type RequestContextV2External } from './request-context.js';
+import { type ArtifactExternalAccept } from './external-context.js';
+import { createApiClient } from './api-client.js';
+import { type ArtifactPrincipal } from './principal.js';
 import { type ArtifactRuntimeConfig, type ArtifactRequestHeaders } from './runtime-config.js';
-export { ArtifactServerError } from './errors.js';
+export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './errors.js';
 export type * from './processes.js';
-export interface ArtifactServerFetchOptions {
-    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    body?: unknown;
-    signal?: AbortSignal;
-}
+export type { ArtifactServerFetchOptions } from './api-client.js';
 /**
  * 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.
@@ -71,8 +69,11 @@ export interface ArtifactAuditEvent {
 export interface ArtifactServerAudit {
     record(event: ArtifactAuditEvent): Promise<void>;
 }
-export interface ArtifactServerClient {
-    context: ArtifactRequestContext;
+export type ArtifactServerContext = ArtifactRequestContext | RequestContextV2External;
+export interface ArtifactServerClient<TContext extends ArtifactServerContext = ArtifactRequestContext> {
+    context: TContext;
+    /** Who the request acts for. An `external` principal reaches platform services only through `asService()`. */
+    principal: ArtifactPrincipal;
     mode: ArtifactServerMode;
     log: ReturnType<typeof createArtifactLogger>;
     api: ReturnType<typeof createApiClient>;
@@ -84,46 +85,32 @@ export interface ArtifactServerClient {
     flags: ArtifactServerFlags;
     audit: ArtifactServerAudit;
     orm(input: ArtifactOrmOptions): OperationExecutor;
-    asService(): ArtifactServerClient;
+    asService(): ArtifactServerClient<TContext>;
 }
-/** One instance per incoming request. Never cache it at module scope. */
-export declare function createArtifactServerClient({ headers, runtime, fetch: fetcher, method, path, logSink }: {
+export interface ArtifactServerClientOptions {
     headers: ArtifactRequestHeaders;
     /** Optional explicit platform config; otherwise reads SEQUENCE_ARTIFACT_RUNTIME_FILE. */
     runtime?: ArtifactRuntimeConfig;
     fetch?: typeof globalThis.fetch;
+    /** Required, with `path`, to accept an external caller. */
     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>;
-interface BrokerCallOptions {
-    signal?: AbortSignal;
-    /** Whether sending the call twice is harmless. Defaults to the operation's own answer (isReadOperation). */
-    replaySafe?: boolean;
 }
-declare function createBrokerTransport({ context, token, getRuntime, fetcher, log }: ClientArguments & {
-    log: ReturnType<typeof createArtifactLogger>;
-}): (input: ArtifactServerRequest, { signal, replaySafe }?: BrokerCallOptions) => 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>;
-};
+/**
+ * One instance per incoming request. Never cache it at module scope.
+ *
+ * Accepts Atlas-user and platform-service contexts. A handler that also serves external callers
+ * names their ingresses in `accept`; its client then carries an external context, whose
+ * `principal` reaches platform services only through `asService()`.
+ */
+export declare function createArtifactServerClient(options: ArtifactServerClientOptions & {
+    accept?: undefined;
+}): Promise<ArtifactServerClient>;
+export declare function createArtifactServerClient(options: ArtifactServerClientOptions & {
+    accept: ArtifactExternalAccept;
+}): Promise<ArtifactServerClient<ArtifactServerContext>>;
+/** For a helper that forwards an optional `accept`: the context may be either version. */
+export declare function createArtifactServerClient(options: ArtifactServerClientOptions & {
+    accept?: ArtifactExternalAccept;
+}): Promise<ArtifactServerClient<ArtifactServerContext>>;

package/dist/server/client.js

@@ -3,36 +3,40 @@ import { StorageApiError, storageClient, storageErrorSchema } from '@sequencehol
 import { OrmOperationError } from '@sequenceholdings/orm/client';
 import { z } from 'zod';
 import { artifactServerRequestSchema } from './broker-contract.js';
-import { ArtifactServerError, platformRequestError } from './errors.js';
 import { createArtifactProcessesClient } from './processes.js';
 import { assertJsonScalarsAcknowledged, ORM_JSON_SCALARS_HEADER } from '../orm-json-scalars.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 { verifyArtifactExternalContext } from './external-context.js';
+import { isExternalContextToken } from './internal/signed-token.js';
+import { createApiClient } from './api-client.js';
+import { pause, transientConnectionCode } from './connection-retry.js';
+import { principalFromContext } from './principal.js';
 import { artifactRuntimeConfigSchema, readArtifactRuntimeConfig } from './runtime-config.js';
-export { ArtifactServerError } from './errors.js';
+import { ArtifactPrincipalError, ArtifactServerError, refusalFromResponse, stepUpError, stepUpErrorFromResponse } from './errors.js';
+export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './errors.js';
 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 flagsResponseSchema = z.object({ flags: z.record(z.string(), z.boolean()) });
-const responseHeaders = ['content-type', 'content-disposition', 'content-length', 'retry-after'];
 const maxBodyBytes = 1024 * 1024;
 /** A read whose connection failed is sent at most three times, pausing up to 100 ms, then up to 200 ms. */
 const reconnect = { attempts: 3, baseDelayMs: 100 };
-/**
- * Socket and DNS errors after which Atlas never answered, and which clear by themselves: the
- * route to Atlas was briefly gone (an egress NAT out of ports drops new connections, which Node
- * reports as EHOSTUNREACH), Atlas's edge refused or reset the connection, or a lookup failed
- * transiently. Timeouts aren't here: a call that waited out its timeout shouldn't wait it out again.
- */
-const transientConnectionCodes = new Set(['ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'EADDRNOTAVAIL', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_SOCKET']);
-/** One instance per incoming request. Never cache it at module scope. */
-export async function createArtifactServerClient({ headers, runtime, fetch: fetcher = globalThis.fetch, method, path, logSink }) {
+export async function createArtifactServerClient({ headers, runtime, fetch: fetcher = globalThis.fetch, method, path, logSink, accept }) {
     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 });
+    let context;
+    if (accept && isExternalContextToken(token)) {
+        if (!method || !path)
+            throw new ArtifactServerError(401, 'invalid_request_context', 'An external request context is verified only against the route method and path');
+        context = verifyArtifactExternalContext({ token, publicKeys: config.publicKeys, projectId: config.projectId, environment: config.environment, method, path, accept });
+    }
+    else {
+        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');
@@ -42,24 +46,27 @@ export async function createArtifactServerClient({ headers, runtime, fetch: fetc
             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 });
+    return buildClient({ context, principal: principalFromContext(context), token, getRuntime, fetcher, mode: 'user', logSink });
 }
 function buildClient(args) {
-    const { context, mode, logSink } = args;
+    const { context, principal, mode, logSink } = args;
     const log = createArtifactLogger({ context, sink: logSink });
     const request = createBrokerTransport({ ...args, log });
     const json = async (operation, signal) => {
         const response = await request(operation, { signal });
+        // One read of the body: a step-up refusal keeps reason and maxAge, any other keeps Atlas's { detail, code }.
         if (!response.ok)
-            throw await platformRequestError({ response, operation: operation.operation });
+            throw await refusalFromResponse({ response, operation: operation.operation });
         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);
+        if (!response.ok) {
+            // A step-up refusal keeps its reason and maxAge; storageApiError reads the body, hence the clone.
+            throw (response.status === 401 ? await stepUpErrorFromResponse(response.clone()) : null) ?? await storageApiError(response);
+        }
         return response.status === 204 ? undefined : response.json();
     };
     const evaluateFlags = async (flagNames) => {
@@ -72,6 +79,7 @@ function buildClient(args) {
     };
     return {
         context,
+        principal,
         mode,
         log,
         api: createApiClient({ mode, request, json }),
@@ -97,7 +105,11 @@ function buildClient(args) {
                 const response = await request(artifactServerRequestSchema.parse({ operation: 'orm', mode, namespace, op: hash, variables, ...(jsonScalars ? { jsonScalars } : {}) }), 
                 // Only an operation the manifest lists as a query is known to change nothing.
                 { replaySafe: listed?.kind === 'query' });
-                const parsed = graphqlResponseSchema.safeParse(await response.json().catch(() => null));
+                const body = await response.json().catch(() => null);
+                const stepUp = stepUpError(response.status, body);
+                if (stepUp)
+                    throw stepUp;
+                const parsed = graphqlResponseSchema.safeParse(body);
                 if (!parsed.success)
                     throw new OrmOperationError('Malformed Data API response', response.status, 'invalid_response');
                 const first = parsed.data.errors?.[0];
@@ -139,7 +151,12 @@ async function recordAuditEvent({ request, mode, event }) {
             failure = new ArtifactServerError(503, 'audit_unavailable', 'Atlas did not answer the audit request');
             continue;
         }
-        await response.body?.cancel();
+        // A step-up refusal is the broker's answer, not a lost delivery: never resent.
+        const stepUp = await stepUpErrorFromResponse(response);
+        if (stepUp)
+            throw stepUp;
+        if (!response.bodyUsed)
+            await response.body?.cancel();
         if (response.ok)
             return;
         failure = new ArtifactServerError(response.status, response.status === 503 ? 'audit_unavailable' : 'platform_request_failed', `Atlas rejected the audit request (${response.status})`);
@@ -153,6 +170,8 @@ 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})`);
 }
+/** How long Atlas has to answer a broker call; for a stream, to send its first byte of headers. */
+const BROKER_RESPONSE_TIMEOUT_MS = 60_000;
 /**
  * Broker operations that change nothing in Atlas. An ORM call's caller decides from its manifest
  * kind; function invokes and process starts can act, and audit delivery resends on its own terms.
@@ -168,40 +187,11 @@ function isReadOperation(operation) {
             return false;
     }
 }
-/**
- * The transient connection code behind a failed fetch, or null. Node's fetch throws
- * `TypeError: fetch failed` with the socket error as its cause. When every address of the host
- * failed to connect, that cause is an AggregateError carrying the first address's code.
- */
-function transientConnectionCode(error) {
-    let current = error;
-    for (let depth = 0; depth < 8 && typeof current === 'object' && current !== null; depth++) {
-        if ('code' in current && typeof current.code === 'string' && transientConnectionCodes.has(current.code))
-            return current.code;
-        current = 'cause' in current ? current.cause : undefined;
-    }
-    return null;
-}
-/** Resolves after `ms`, or rejects with the caller's abort reason as soon as it aborts. */
-function pause({ ms, signal }) {
-    return new Promise((resolve, reject) => {
-        if (signal?.aborted) {
-            reject(signal.reason);
-            return;
-        }
-        const aborted = () => {
-            clearTimeout(timer);
-            reject(signal?.reason);
-        };
-        const timer = setTimeout(() => {
-            signal?.removeEventListener('abort', aborted);
-            resolve();
-        }, ms);
-        signal?.addEventListener('abort', aborted, { once: true });
-    });
-}
-function createBrokerTransport({ context, token, getRuntime, fetcher, log }) {
-    const send = async (input, signal) => {
+function createBrokerTransport({ context, principal, token, getRuntime, fetcher, log }) {
+    const send = async (input, signal, stream = false) => {
+        // The one choke point for every broker operation: an external caller never acts as a user.
+        if (input.mode === 'user' && principal.kind === 'external')
+            throw new ArtifactPrincipalError('external_requires_service');
         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);
@@ -211,19 +201,32 @@ function createBrokerTransport({ context, token, getRuntime, fetcher, log }) {
         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),
-        });
+        // The timeout covers the whole call, body included, except for a stream: its timer is cleared
+        // once Atlas answers, so a long body isn't cut off mid-read.
+        const expiry = new AbortController();
+        const timer = setTimeout(() => expiry.abort(new DOMException('Atlas did not answer in time', 'TimeoutError')), BROKER_RESPONSE_TIMEOUT_MS);
+        if (!stream)
+            timer.unref?.();
+        const timeout = expiry.signal;
+        try {
+            return await 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, timeout]) : timeout,
+            });
+        }
+        finally {
+            if (stream)
+                clearTimeout(timer);
+        }
     };
     /**
      * Sends a read again when its connection to Atlas failed before Atlas answered: such failures
@@ -231,10 +234,10 @@ function createBrokerTransport({ context, token, getRuntime, fetcher, log }) {
      * again, because a reset can come after Atlas acted on it. A response, whatever its status, is
      * Atlas's answer and is returned as is.
      */
-    return async (input, { signal, replaySafe = isReadOperation(input) } = {}) => {
+    return async (input, { signal, replaySafe = isReadOperation(input), stream = false } = {}) => {
         for (let attempt = 1;; attempt++) {
             try {
-                return await send(input, signal);
+                return await send(input, signal, stream);
             }
             catch (error) {
                 const code = replaySafe && attempt < reconnect.attempts ? transientConnectionCode(error) : null;
@@ -248,35 +251,3 @@ function createBrokerTransport({ context, token, getRuntime, fetcher, log }) {
         }
     };
 }
-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), { signal: 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/connection-retry.d.ts

@@ -0,0 +1,12 @@
+/** Recognising a lost connection to Atlas, and waiting before a broker read is resent. */
+/**
+ * The transient connection code behind a failed fetch, or null. Node's fetch throws
+ * `TypeError: fetch failed` with the socket error as its cause. When every address of the host
+ * failed to connect, that cause is an AggregateError carrying the first address's code.
+ */
+export declare function transientConnectionCode(error: unknown): string | null;
+/** Resolves after `ms`, or rejects with the caller's abort reason as soon as it aborts. */
+export declare function pause({ ms, signal }: {
+    ms: number;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/server/connection-retry.js

@@ -0,0 +1,40 @@
+/** Recognising a lost connection to Atlas, and waiting before a broker read is resent. */
+/**
+ * Socket and DNS errors after which Atlas never answered, and which clear by themselves: the
+ * route to Atlas was briefly gone (an egress NAT out of ports drops new connections, which Node
+ * reports as EHOSTUNREACH), Atlas's edge refused or reset the connection, or a lookup failed
+ * transiently. Timeouts aren't here: a call that waited out its timeout shouldn't wait it out again.
+ */
+const transientConnectionCodes = new Set(['ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'EADDRNOTAVAIL', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_SOCKET']);
+/**
+ * The transient connection code behind a failed fetch, or null. Node's fetch throws
+ * `TypeError: fetch failed` with the socket error as its cause. When every address of the host
+ * failed to connect, that cause is an AggregateError carrying the first address's code.
+ */
+export function transientConnectionCode(error) {
+    let current = error;
+    for (let depth = 0; depth < 8 && typeof current === 'object' && current !== null; depth++) {
+        if ('code' in current && typeof current.code === 'string' && transientConnectionCodes.has(current.code))
+            return current.code;
+        current = 'cause' in current ? current.cause : undefined;
+    }
+    return null;
+}
+/** Resolves after `ms`, or rejects with the caller's abort reason as soon as it aborts. */
+export function pause({ ms, signal }) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const aborted = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', aborted);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', aborted, { once: true });
+    });
+}

package/dist/server/errors.d.ts

@@ -1,3 +1,4 @@
+export declare const INSUFFICIENT_USER_AUTHENTICATION = "insufficient_user_authentication";
 /**
  * What Atlas's error envelope said about a refusal, when the response carried one. Atlas routes
  * answer `{ detail, code? }`: `detail` is the human-readable reason, `code` the route's machine
@@ -8,19 +9,53 @@ export interface ArtifactAtlasRefusal {
     code: string | null;
     detail: string | null;
 }
+export interface ArtifactServerErrorDetails {
+    reason?: string;
+    maxAge?: number;
+    atlas?: ArtifactAtlasRefusal;
+}
 export declare class ArtifactServerError extends Error {
     readonly status: number;
     readonly code: string;
+    /** A named refusal a handler can act on, such as `insufficient_user_authentication`. */
+    readonly reason: string | undefined;
+    /** With `insufficient_user_authentication`: the sign-in age, in seconds, the operation requires. */
+    readonly maxAge: number | undefined;
     /** Atlas's own account of the refusal; both null when the response had no readable envelope. */
     readonly atlas: ArtifactAtlasRefusal;
-    constructor(status: number, code: string, message: string, atlas?: ArtifactAtlasRefusal);
+    constructor(status: number, code: string, message: string, details?: ArtifactServerErrorDetails);
+}
+/** A user-mode call made for a caller that may act only through `asService()`. */
+export declare class ArtifactPrincipalError extends ArtifactServerError {
+    readonly reason: 'external_requires_service';
+    constructor(reason: 'external_requires_service');
 }
+/**
+ * The step-up refusal in a broker 401 body (`{reason|error: 'insufficient_user_authentication',
+ * maxAge|max_age}`), or null. A missing or malformed age asks for a fresh sign-in (0).
+ */
+export declare function stepUpError(status: number, body: unknown): ArtifactServerError | null;
+export declare function stepUpErrorFromResponse(response: Response): Promise<ArtifactServerError | null>;
 /**
  * A refused broker call, keeping what Atlas said: the message carries the route's `detail`
  * and `error.atlas` its machine `code`, so a consumer can branch on a Lattice refusal
  * (`EDGE_ID_MISMATCH`, `WORKFLOW_NOT_RUNNING`, …) the way a caller of the route itself would.
  */
-export declare function platformRequestError({ response, operation }: {
+export declare function platformRequestError({ status, body, operation }: {
+    status: number;
+    body: unknown;
+    operation: string;
+}): ArtifactServerError;
+/**
+ * The error for a refused broker response: a step-up refusal keeps its reason and maxAge, any other
+ * refusal keeps Atlas's `{ detail, code }`. The body is read once, so neither reading starves the other.
+ */
+export declare function refusalFromResponse({ response, operation }: {
     response: Response;
     operation: string;
 }): Promise<ArtifactServerError>;
+/**
+ * The RFC 9470 response for a step-up refusal, for the app to return as is: the caller signs in
+ * again with `max_age` and retries.
+ */
+export declare function stepUpResponse(error: ArtifactServerError): Response;

package/dist/server/errors.js

@@ -1,18 +1,53 @@
+/** Errors the server SDK raises, and the step-up (RFC 9470) mapping a handler returns. */
 import { z } from 'zod';
+export const INSUFFICIENT_USER_AUTHENTICATION = 'insufficient_user_authentication';
 const NO_REFUSAL = { code: null, detail: null };
 export class ArtifactServerError extends Error {
     status;
     code;
+    /** A named refusal a handler can act on, such as `insufficient_user_authentication`. */
+    reason;
+    /** With `insufficient_user_authentication`: the sign-in age, in seconds, the operation requires. */
+    maxAge;
     /** Atlas's own account of the refusal; both null when the response had no readable envelope. */
     atlas;
-    constructor(status, code, message, atlas = NO_REFUSAL) {
+    constructor(status, code, message, details = {}) {
         super(message);
         this.status = status;
         this.code = code;
         this.name = 'ArtifactServerError';
-        this.atlas = atlas;
+        this.reason = details.reason;
+        this.maxAge = details.maxAge;
+        this.atlas = details.atlas ?? NO_REFUSAL;
     }
 }
+/** A user-mode call made for a caller that may act only through `asService()`. */
+export class ArtifactPrincipalError extends ArtifactServerError {
+    constructor(reason) {
+        super(403, reason, 'External callers reach platform services only through asService()', { reason });
+        this.name = 'ArtifactPrincipalError';
+    }
+}
+/**
+ * The step-up refusal in a broker 401 body (`{reason|error: 'insufficient_user_authentication',
+ * maxAge|max_age}`), or null. A missing or malformed age asks for a fresh sign-in (0).
+ */
+export function stepUpError(status, body) {
+    if (status !== 401 || body === null || typeof body !== 'object')
+        return null;
+    const named = ('reason' in body && body.reason === INSUFFICIENT_USER_AUTHENTICATION) ||
+        ('error' in body && body.error === INSUFFICIENT_USER_AUTHENTICATION);
+    if (!named)
+        return null;
+    const age = 'maxAge' in body ? body.maxAge : 'max_age' in body ? body.max_age : undefined;
+    const maxAge = typeof age === 'number' && Number.isSafeInteger(age) && age >= 0 ? age : 0;
+    return new ArtifactServerError(401, INSUFFICIENT_USER_AUTHENTICATION, 'A more recent sign-in is required', { reason: INSUFFICIENT_USER_AUTHENTICATION, maxAge });
+}
+export async function stepUpErrorFromResponse(response) {
+    if (response.status !== 401)
+        return null;
+    return stepUpError(response.status, await response.json().catch(() => null));
+}
 /** Atlas answers a refusal as `{ detail, code? }`; anything else (a proxy page, an empty body) reads as no envelope. */
 const atlasRefusalSchema = z.object({ detail: z.string().optional(), code: z.string().optional() });
 /**
@@ -20,10 +55,35 @@ const atlasRefusalSchema = z.object({ detail: z.string().optional(), code: z.str
  * and `error.atlas` its machine `code`, so a consumer can branch on a Lattice refusal
  * (`EDGE_ID_MISMATCH`, `WORKFLOW_NOT_RUNNING`, …) the way a caller of the route itself would.
  */
-export async function platformRequestError({ response, operation }) {
-    const envelope = atlasRefusalSchema.safeParse(await response.json().catch(() => undefined));
+export function platformRequestError({ status, body, operation }) {
+    const envelope = atlasRefusalSchema.safeParse(body);
     const detail = envelope.success ? envelope.data.detail ?? null : null;
     const code = envelope.success ? envelope.data.code ?? null : null;
-    const message = `Atlas rejected the ${operation} request (${response.status})${detail ? `: ${detail}` : ''}`;
-    return new ArtifactServerError(response.status, 'platform_request_failed', message, { code, detail });
+    const message = `Atlas rejected the ${operation} request (${status})${detail ? `: ${detail}` : ''}`;
+    return new ArtifactServerError(status, 'platform_request_failed', message, { atlas: { code, detail } });
+}
+/**
+ * The error for a refused broker response: a step-up refusal keeps its reason and maxAge, any other
+ * refusal keeps Atlas's `{ detail, code }`. The body is read once, so neither reading starves the other.
+ */
+export async function refusalFromResponse({ response, operation }) {
+    const body = await response.json().catch(() => undefined);
+    return stepUpError(response.status, body) ?? platformRequestError({ status: response.status, body, operation });
+}
+/**
+ * The RFC 9470 response for a step-up refusal, for the app to return as is: the caller signs in
+ * again with `max_age` and retries.
+ */
+export function stepUpResponse(error) {
+    if (error.reason !== INSUFFICIENT_USER_AUTHENTICATION)
+        throw new TypeError('stepUpResponse requires an insufficient_user_authentication error');
+    const maxAge = error.maxAge !== undefined && Number.isSafeInteger(error.maxAge) && error.maxAge >= 0 ? error.maxAge : 0;
+    return new Response(JSON.stringify({ error: INSUFFICIENT_USER_AUTHENTICATION, max_age: maxAge }), {
+        status: 401,
+        headers: {
+            'content-type': 'application/json',
+            'cache-control': 'no-store',
+            'www-authenticate': `Bearer error="${INSUFFICIENT_USER_AUTHENTICATION}", max_age=${maxAge}`,
+        },
+    });
 }