@sequenceholdings/artifact-studio 0.5.0 → 0.6.1

package/VERSION-PIN.md

@@ -21,6 +21,26 @@ Artifact Studio 0.3.1 (Studio CLI 0.2.2) verifies the per-request `jti` that the
 gateway now signs into every request context. The 0.3.0 context schema predates
 that claim and rejects those contexts, so Next.js applications need 0.3.1 or newer.
 
+Artifact Studio 0.6.0 (Studio CLI 0.4.2) adds external request contexts (v2)
+for callers that are not Atlas users, admitted through a manifest-declared
+ingress. 0.5.0 was never published; 0.6.0 also ships its server `flags`,
+`audit` and `jsonScalars` surface and the Lattice `processes.read` reads
+(`listRuns`, `getRun`, `describe`, `listTasks`) and `processes.act` writes
+(`advance`, `assign`, run viewers, `searchPrincipals`). The public verifiers
+(`verifyArtifactRequestContext`, `getArtifactRequestContext`) stay v1-only and
+refuse a v2 context, or any token signed with an `external-` kid, with reason
+`external_context_not_accepted`. A handler accepts external callers only
+through `verifyArtifactExternalContext` or `createArtifactServerClient({ accept })`,
+and an external principal reaches platform services only through `asService()`.
+`@sequenceholdings/artifact-studio/server/testing` signs test contexts.
+0.6.0 also carries `error.atlas` (`{ code, detail }`) on a refused broker call
+(#13398); a step-up 401 still surfaces as `insufficient_user_authentication`.
+
+Context version policy: a context verifier rejects any unknown top-level or
+`principal` key unless it sits under `ext` or is named in `crit` (and `crit`
+names only extensions the verifier understands; today none, so it is empty).
+Security-relevant additions bump `v`; they are never added as optional keys.
+
 The Artifact mobile-pattern source adds new atlas-ui exports. Roll that surface
 out in dependency order: publish atlas-ui from its changeset, update the exact
 `@sequenceholdings/atlas-ui` dependency in `artifact-studio/package.json`,

package/dist/cli.js

@@ -197,7 +197,7 @@ async function initCommand(args) {
     console.log(`[seq-studio] initialized ${dir}`);
     console.log('AGENTS.md points to your environment\'s live docs; CLAUDE.md imports it.');
     console.log(template === 'nextjs'
-        ? 'Next: cd into the app, run pnpm install, then seq-studio login && seq-studio artifact dev --env <env>. Commit pnpm-lock.yaml before deploying. No cloud credentials are required.'
+        ? 'Next: use Node.js 24, cd into the app and run pnpm install, then pnpm run lint && pnpm run type-check && pnpm test. Commit pnpm-lock.yaml before deploying. seq-studio login && seq-studio artifact dev --env <env> starts development; repository CI and hosted builds use Buildkite. No cloud credentials are required.'
         : 'Next: seq-studio login && seq-studio artifact dev --env <env>  (see: seq-studio envs list)');
     return 0;
 }

package/dist/offline/connector.d.ts

@@ -2,9 +2,11 @@ import type { SequenceOfflineRequest, SequenceOfflineRequestConnector } from '..
 import type { OfflineReplayEngine } from './replay.js';
 import type { OfflineCache, OfflineMutationPolicy, OfflineReadPolicy } from './types.js';
 export declare class OfflineDataUnavailableError extends Error {
+    readonly path: string;
     constructor(path: string);
 }
 export declare class OfflineWriteBlockedError extends Error {
+    readonly path: string;
     constructor(path: string);
 }
 export interface ArtifactOfflineConnector {

package/dist/offline/connector.js

@@ -1,13 +1,17 @@
 export class OfflineDataUnavailableError extends Error {
+    path;
     constructor(path) {
-        super(`No current offline data is available for ${path}`);
+        super('No offline data available');
         this.name = 'OfflineDataUnavailableError';
+        this.path = path;
     }
 }
 export class OfflineWriteBlockedError extends Error {
+    path;
     constructor(path) {
-        super(`Reconnect to complete this action: ${path}`);
+        super('Reconnect to complete this action');
         this.name = 'OfflineWriteBlockedError';
+        this.path = path;
     }
 }
 function canUseCachedFallback(response) {

package/dist/offline/management-types.d.ts

@@ -0,0 +1,25 @@
+export interface SequenceOfflineManagementStatus {
+    supported: boolean;
+    enrolled: boolean;
+    online: boolean;
+    pending: number;
+    failed: number;
+    syncing: boolean;
+    lastSyncAt: number | null;
+    itemCount?: number;
+    itemLabel?: string;
+}
+export interface SequenceOfflineManagementIssue {
+    id: string;
+    label: string;
+    message: string;
+}
+export interface SequenceOfflineManagement {
+    status(): Promise<SequenceOfflineManagementStatus>;
+    setEnrolled(enrolled: boolean): Promise<void>;
+    sync(): Promise<void>;
+    issues(): Promise<SequenceOfflineManagementIssue[]>;
+    retry(id: string): Promise<void>;
+    discard(id: string): Promise<void>;
+    subscribe(listener: () => void): () => void;
+}

package/dist/offline/management-types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime-contracts.js

@@ -20,7 +20,7 @@ const imageReferenceSchema = z.string().max(1024).regex(/^[a-z0-9]+(?:[.-][a-z0-
 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',
+    '.turbo', 'coverage', '.docker', '.seq-next-output.json',
 ]);
 /** Shared upload exclusion policy. Content scanning and filesystem containment remain separate checks. */
 export function isExcludedArtifactSourcePath({ path }) {

package/dist/sdk.d.ts

@@ -1,3 +1,5 @@
+import type { SequenceOfflineManagement } from './offline/management-types.js';
+export type { SequenceOfflineManagement, SequenceOfflineManagementStatus, SequenceOfflineManagementIssue } from './offline/management-types.js';
 import { type StartStorageUpload, type StorageUploadSession } from '@sequenceholdings/storage';
 export { createArtifactOrmExecutor, type ArtifactOrmExecutorConfig } from './sdk-orm.js';
 export type { ArtifactOrmJsonScalars } from './orm-json-scalars.js';
@@ -78,6 +80,9 @@ export interface SequenceOfflineRequestConnector {
     }): void | (() => void);
 }
 export interface SequenceOffline {
+    registerManagement(adapter: SequenceOfflineManagement): () => void;
+    openSettings(): Promise<void>;
+    isManagementSession(): boolean;
     /**
      * Install the artifact's request policy beneath seq.api. Returns a disposer
      * that restores the network-only default when it still owns registration.
@@ -395,7 +400,9 @@ export declare function createArtifactStorageClient(sdk?: SequenceArtifactSdk):
             size: number | null;
             contentType: string | null;
         }>;
-        createFolder: (name: string, parentId?: string | null, { idempotencyKey, }?: {
+        createFolder: (name: string, parentId
+        /** The specific step run (the assignee's task) — the step-scoped id reviewers hold access to. */
+        ? /** The specific step run (the assignee's task) — the step-scoped id reviewers hold access to. */: string | null, { idempotencyKey, }?: {
             idempotencyKey?: string;
         }) => Promise<{
             id: string;

package/dist/server/api-client.d.ts

@@ -0,0 +1,26 @@
+import type { SequenceApiFetchResponse } from '../sdk.js';
+import { type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+export interface ArtifactServerFetchOptions {
+    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    signal?: AbortSignal;
+}
+/** Sends one broker operation; the client's transport (retries, the external-principal gate). */
+export type ArtifactBrokerRequest = (operation: ArtifactServerRequest, options?: {
+    signal?: AbortSignal;
+}) => Promise<Response>;
+/** `client.api`: Atlas routes reached through the broker as `api` operations. */
+export declare function createApiClient({ mode, request, json }: {
+    mode: ArtifactServerMode;
+    request: ArtifactBrokerRequest;
+    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>;
+};

package/dist/server/api-client.js

@@ -0,0 +1,38 @@
+import { artifactServerRequestSchema } from './broker-contract.js';
+import { ArtifactServerError, stepUpErrorFromResponse } from './errors.js';
+const responseHeaders = ['content-type', 'content-disposition', 'content-length', 'retry-after'];
+/** `client.api`: Atlas routes reached through the broker as `api` operations. */
+export 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 await stepUpErrorFromResponse(response) ??
+                    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/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})`);
@@ -168,40 +185,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 }) {
+function createBrokerTransport({ context, principal, token, getRuntime, fetcher, log }) {
     const send = async (input, signal) => {
+        // 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);
@@ -248,35 +236,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;