@sequenceholdings/artifact-studio 0.5.0 → 0.6.2

package/dist/server/request-context.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { NextArtifactBridgeBootstrap, NextArtifactInitialContext } from '../next/protocol.js';
+import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX } from './internal/signed-token.js';
 export declare const ARTIFACT_REQUEST_CONTEXT_HEADER = "x-sequence-artifact-context";
 export declare const ARTIFACT_RUNTIME_TOKEN_HEADER = "x-sequence-artifact-runtime";
 export declare const ARTIFACT_SERVER_REQUEST_PATH = "/api/artifact-studio/server/request";
@@ -10,6 +11,8 @@ export declare const ARTIFACT_CONTEXT_MAX_AGE_SECONDS = 60;
  * window applies only when the signed context names a Lattice run.
  */
 export declare const ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS = 300;
+/** An exact origin: HTTPS, or HTTP on a loopback host. */
+export declare const artifactOriginSchema: z.ZodString;
 /** Public request context. No bearer credentials or secret values belong here. */
 export declare const artifactRequestContextSchema: z.ZodObject<{
     v: z.ZodLiteral<1>;
@@ -30,10 +33,10 @@ export declare const artifactRequestContextSchema: z.ZodObject<{
     method: z.ZodEnum<{
         GET: "GET";
         POST: "POST";
-        DELETE: "DELETE";
-        HEAD: "HEAD";
         PUT: "PUT";
         PATCH: "PATCH";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
         OPTIONS: "OPTIONS";
     }>;
     path: z.ZodString;
@@ -61,10 +64,123 @@ export declare const artifactRequestContextSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type ArtifactRequestContext = z.infer<typeof artifactRequestContextSchema>;
 export type ArtifactGatewayPublicKeys = Readonly<Record<string, string>>;
+export { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX };
+/**
+ * Prefix of a platform service account's `sub`. Mirrors Atlas's `SERVICE_ACCOUNT_SUB_PREFIX`
+ * (atlas/src/server/lib/auth0-sub.ts); Atlas's auth0-sub test pins the two together.
+ */
+export declare const ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX = "service-account|";
+/** An external context's lifetime cap. External contexts never carry a Lattice run. */
+export declare const ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS = 60;
+/** An IPv4 or IPv6 address, as the gateway observed it. The control contract reuses it. */
+export declare const artifactIpAddressSchema: z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>;
+/** The external caller as the gateway verified it at pass exchange. Strict: see the v2 key policy below. */
+export declare const artifactExternalPrincipalSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"external">;
+    ingress: z.ZodString;
+    provider: z.ZodString;
+    issuer: z.ZodString;
+    subject: z.ZodString;
+    clientId: z.ZodString;
+    email: z.ZodString;
+    emailVerified: z.ZodLiteral<true>;
+    authTime: z.ZodNullable<z.ZodNumber>;
+    amr: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    tokenIssuedAt: z.ZodNumber;
+    pass: z.ZodObject<{
+        id: z.ZodUUID;
+        kid: z.ZodString;
+        issuedAt: z.ZodNumber;
+        exchangeIp: z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>;
+    }, z.core.$strict>;
+    client: z.ZodObject<{
+        ip: z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>;
+        userAgent: z.ZodString;
+        userAgentSha256: z.ZodString;
+        origin: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * External request context (v2): a caller that is not an Atlas user, admitted through a
+ * manifest-declared ingress. Key policy: any unknown top-level or `principal` key is refused
+ * unless it sits under `ext`. `crit` is reserved for extensions a verifier must understand; this
+ * verifier understands none, so it must be empty. Security-relevant additions bump `v`.
+ *
+ * Public verifiers ({@link verifyArtifactRequestContext}) never accept this version; only the
+ * explicit external APIs do.
+ */
+export declare const requestContextV2ExternalSchema: z.ZodObject<{
+    v: z.ZodLiteral<2>;
+    iss: z.ZodLiteral<"atlas-artifact-gateway">;
+    aud: z.ZodString;
+    sub: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    mode: z.ZodEnum<{
+        published: "published";
+        development: "development";
+    }>;
+    deploymentId: z.ZodNullable<z.ZodString>;
+    devSessionId: z.ZodNullable<z.ZodString>;
+    requestId: z.ZodString;
+    jti: z.ZodUUID;
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
+        OPTIONS: "OPTIONS";
+    }>;
+    path: z.ZodString;
+    iat: z.ZodNumber;
+    exp: z.ZodNumber;
+    serviceAccountId: z.ZodString;
+    principal: z.ZodObject<{
+        kind: z.ZodLiteral<"external">;
+        ingress: z.ZodString;
+        provider: z.ZodString;
+        issuer: z.ZodString;
+        subject: z.ZodString;
+        clientId: z.ZodString;
+        email: z.ZodString;
+        emailVerified: z.ZodLiteral<true>;
+        authTime: z.ZodNullable<z.ZodNumber>;
+        amr: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        tokenIssuedAt: z.ZodNumber;
+        pass: z.ZodObject<{
+            id: z.ZodUUID;
+            kid: z.ZodString;
+            issuedAt: z.ZodNumber;
+            exchangeIp: z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>;
+        }, z.core.$strict>;
+        client: z.ZodObject<{
+            ip: z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>;
+            userAgent: z.ZodString;
+            userAgentSha256: z.ZodString;
+            origin: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    crit: z.ZodArray<z.ZodString>;
+    ext: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export type RequestContextV2External = z.infer<typeof requestContextV2ExternalSchema>;
+/** Why a context was refused, when the refusal has a name a handler can act on. */
+export type ArtifactContextErrorReason = 'external_context_not_accepted' | 'external_context_required' | 'external_ingress_not_accepted' | 'external_mode_not_accepted';
 export declare class ArtifactContextError extends Error {
-    constructor();
+    readonly reason: ArtifactContextErrorReason | undefined;
+    constructor(reason?: ArtifactContextErrorReason);
 }
-/** Only the gateway owns private keys. Applications pin platform-provided public keys. */
+/**
+ * Only the gateway owns private keys. Applications pin platform-provided public keys.
+ *
+ * Accepts v1 (Atlas user and platform service) contexts only. An external (v2) context, or any
+ * token signed with an `external-` kid, is refused with reason `external_context_not_accepted`
+ * before any other check, so a borrower context can never reach a handler that reads `sub` and
+ * `capabilities` as an Atlas user. External contexts are verified only through
+ * `verifyArtifactExternalContext` or `createArtifactServerClient({ accept })`.
+ */
 export declare function verifyArtifactRequestContext({ token, publicKeys, projectId, environment, method, path, now }: {
     token: string | null;
     publicKeys: ArtifactGatewayPublicKeys;
@@ -76,6 +192,6 @@ export declare function verifyArtifactRequestContext({ token, publicKeys, projec
     now?: number;
 }): ArtifactRequestContext;
 /** Safe props for the client bridge; intentionally excludes actor and runtime credentials. */
-export declare function getArtifactBrowserBootstrap(context: ArtifactRequestContext): NextArtifactBridgeBootstrap & {
+export declare function getArtifactBrowserBootstrap(context: ArtifactRequestContext | RequestContextV2External): NextArtifactBridgeBootstrap & {
     initialContext: NextArtifactInitialContext;
 };

package/dist/server/request-context.js

@@ -1,6 +1,7 @@
-import { createPublicKey, verify } from 'node:crypto';
 import { z } from 'zod';
 import { isLoopbackHostname } from '../loopback.js';
+import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX, isExternalContextToken, verifySignedContext } from './internal/signed-token.js';
+import { parseV1Context } from './internal/v1-context.js';
 export const ARTIFACT_REQUEST_CONTEXT_HEADER = 'x-sequence-artifact-context';
 export const ARTIFACT_RUNTIME_TOKEN_HEADER = 'x-sequence-artifact-runtime';
 export const ARTIFACT_SERVER_REQUEST_PATH = '/api/artifact-studio/server/request';
@@ -12,7 +13,8 @@ export const ARTIFACT_CONTEXT_MAX_AGE_SECONDS = 60;
  */
 export const ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS = 300;
 const id = z.string().min(1).max(255);
-const originSchema = z.string().max(2048).refine(value => {
+/** An exact origin: HTTPS, or HTTP on a loopback host. */
+export const artifactOriginSchema = z.string().max(2048).refine(value => {
     try {
         const url = new URL(value);
         return value === url.origin && (url.protocol === 'https:' ||
@@ -45,7 +47,7 @@ export const artifactRequestContextSchema = z.object({
     exp: z.number().int().positive(),
     capabilities: z.array(id).max(256),
     serviceAccountId: id.nullable(),
-    bridge: z.object({ parentOrigin: originSchema, channelId: id, nonce: z.string().min(16).max(255) }).strict(),
+    bridge: z.object({ parentOrigin: artifactOriginSchema, channelId: id, nonce: z.string().min(16).max(255) }).strict(),
     theme: z.enum(['light', 'dark', 'system']),
     lattice: z.object({ runId: id.nullable(), nodeId: id.nullable(), stepId: id.nullable(), processId: id.nullable() }).strict(),
     taskRoutes: z.array(z.string().min(1).max(512)).max(16).refine(routes => routes.join('').length <= 1024).optional(),
@@ -60,49 +62,118 @@ export const artifactRequestContextSchema = z.object({
     if (value.mode === 'development' ? !value.devSessionId || value.deploymentId !== null : !value.deploymentId || value.devSessionId !== null)
         ctx.addIssue({ code: 'custom', message: 'Artifact runtime identity does not match its mode' });
 });
+export { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX };
+/**
+ * Prefix of a platform service account's `sub`. Mirrors Atlas's `SERVICE_ACCOUNT_SUB_PREFIX`
+ * (atlas/src/server/lib/auth0-sub.ts); Atlas's auth0-sub test pins the two together.
+ */
+export const ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX = 'service-account|';
+/** An external context's lifetime cap. External contexts never carry a Lattice run. */
+export const ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS = 60;
+/** An IPv4 or IPv6 address, as the gateway observed it. The control contract reuses it. */
+export const artifactIpAddressSchema = z.union([z.ipv4(), z.ipv6()]);
+/** Signed by the gateway after it strips control characters and truncates; refused here otherwise. */
+const observedUserAgent = z.string().max(512).refine(value => !/[\u0000-\u001f\u007f]/.test(value), 'Expected a user agent without control characters');
+/** The external caller as the gateway verified it at pass exchange. Strict: see the v2 key policy below. */
+export const artifactExternalPrincipalSchema = z.object({
+    kind: z.literal('external'),
+    /** Routing label for the manifest's ingress declaration. Not an authorization attribute. */
+    ingress: id,
+    provider: id,
+    issuer: z.string().min(1).max(2048),
+    subject: id,
+    clientId: id,
+    /** Normalized (trimmed, lowercase) by Atlas at exchange. */
+    email: z.string().min(3).max(320).refine(value => value === value.trim().toLowerCase() && value.includes('@'), 'Expected a normalized email'),
+    emailVerified: z.literal(true),
+    authTime: z.number().int().nonnegative().nullable(),
+    amr: z.array(z.string().min(1).max(64)).max(16).nullable(),
+    tokenIssuedAt: z.number().int().nonnegative(),
+    pass: z.object({ id: z.uuid(), kid: id, issuedAt: z.number().int().nonnegative(), exchangeIp: artifactIpAddressSchema }).strict(),
+    client: z.object({
+        ip: artifactIpAddressSchema,
+        userAgent: observedUserAgent,
+        userAgentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+        origin: artifactOriginSchema.nullable(),
+    }).strict(),
+}).strict();
+/**
+ * External request context (v2): a caller that is not an Atlas user, admitted through a
+ * manifest-declared ingress. Key policy: any unknown top-level or `principal` key is refused
+ * unless it sits under `ext`. `crit` is reserved for extensions a verifier must understand; this
+ * verifier understands none, so it must be empty. Security-relevant additions bump `v`.
+ *
+ * Public verifiers ({@link verifyArtifactRequestContext}) never accept this version; only the
+ * explicit external APIs do.
+ */
+export const requestContextV2ExternalSchema = z.object({
+    v: z.literal(2),
+    iss: z.literal('atlas-artifact-gateway'),
+    aud: z.string().min(1).max(300),
+    sub: id.refine(value => value.startsWith('ext|'), 'External subjects are namespaced ext|<provider>|<subject>'),
+    projectId: id,
+    environment: id,
+    mode: z.enum(['published', 'development']),
+    deploymentId: id.nullable(),
+    devSessionId: id.nullable(),
+    requestId: id,
+    jti: z.uuid(),
+    method: artifactRequestContextSchema.shape.method,
+    path: artifactRequestContextSchema.shape.path,
+    iat: z.number().int().nonnegative(),
+    exp: z.number().int().positive(),
+    /** The ingress's own service account; external principals act only through service mode. */
+    serviceAccountId: id,
+    principal: artifactExternalPrincipalSchema,
+    crit: z.array(z.string()).length(0),
+    ext: z.record(z.string().min(1).max(64), z.unknown()),
+}).strict().superRefine((value, ctx) => {
+    if (value.aud !== `artifact:${value.projectId}`)
+        ctx.addIssue({ code: 'custom', message: 'Invalid Artifact audience' });
+    if (value.sub !== `ext|${value.principal.provider}|${value.principal.subject}`)
+        ctx.addIssue({ code: 'custom', message: 'External subject does not match its principal' });
+    if (value.exp <= value.iat || value.exp - value.iat > ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS)
+        ctx.addIssue({ code: 'custom', message: 'Invalid Artifact context lifetime' });
+    if (value.mode === 'development' ? !value.devSessionId || value.deploymentId !== null : !value.deploymentId || value.devSessionId !== null)
+        ctx.addIssue({ code: 'custom', message: 'Artifact runtime identity does not match its mode' });
+});
 export class ArtifactContextError extends Error {
-    constructor() { super('Missing or invalid Artifact gateway request context'); this.name = 'ArtifactContextError'; }
-}
-function decode(value) {
-    if (!/^[A-Za-z0-9_-]+$/.test(value))
-        throw new ArtifactContextError();
-    return JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+    reason;
+    constructor(reason) {
+        super('Missing or invalid Artifact gateway request context');
+        this.name = 'ArtifactContextError';
+        this.reason = reason;
+    }
 }
-/** Only the gateway owns private keys. Applications pin platform-provided public keys. */
+/**
+ * Only the gateway owns private keys. Applications pin platform-provided public keys.
+ *
+ * Accepts v1 (Atlas user and platform service) contexts only. An external (v2) context, or any
+ * token signed with an `external-` kid, is refused with reason `external_context_not_accepted`
+ * before any other check, so a borrower context can never reach a handler that reads `sub` and
+ * `capabilities` as an Atlas user. External contexts are verified only through
+ * `verifyArtifactExternalContext` or `createArtifactServerClient({ accept })`.
+ */
 export function verifyArtifactRequestContext({ token, publicKeys, projectId, environment, method, path, now = Math.floor(Date.now() / 1000) }) {
+    if (isExternalContextToken(token))
+        throw new ArtifactContextError('external_context_not_accepted');
+    let payload;
     try {
-        if (!token || token.length > 32768)
-            throw new ArtifactContextError();
-        const parts = token.split('.');
-        if (parts.length !== 3)
-            throw new ArtifactContextError();
-        const [encodedHeader, encodedPayload, signature] = parts;
-        const header = z.object({ alg: z.literal('EdDSA'), typ: z.literal('JWT'), kid: id }).strict().parse(decode(encodedHeader));
-        const pem = Object.hasOwn(publicKeys, header.kid) ? publicKeys[header.kid] : undefined;
-        if (!pem || !/^[A-Za-z0-9_-]+$/.test(signature))
-            throw new ArtifactContextError();
-        const key = createPublicKey(pem);
-        if (key.asymmetricKeyType !== 'ed25519' ||
-            !verify(null, Buffer.from(`${encodedHeader}.${encodedPayload}`), key, Buffer.from(signature, 'base64url')))
-            throw new ArtifactContextError();
-        const context = artifactRequestContextSchema.parse(decode(encodedPayload));
-        if (context.projectId !== projectId || context.environment !== environment ||
-            context.exp <= now || context.iat > now + 5 ||
-            (method !== undefined && context.method !== method.toUpperCase()) || (path !== undefined && context.path !== path))
+        const verified = verifySignedContext({ token, publicKeys });
+        if (verified.kid.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX))
             throw new ArtifactContextError();
-        Object.freeze(context.bridge);
-        Object.freeze(context.lattice);
-        Object.freeze(context.capabilities);
-        if (context.taskRoutes)
-            Object.freeze(context.taskRoutes);
-        return Object.freeze(context);
+        payload = verified.payload;
     }
     catch {
         throw new ArtifactContextError();
     }
+    return parseV1Context({ payload, projectId, environment, method, path, now });
 }
 /** Safe props for the client bridge; intentionally excludes actor and runtime credentials. */
 export function getArtifactBrowserBootstrap(context) {
+    // An external caller has no Atlas bridge, theme or Lattice run to hand to a browser.
+    if (context.v !== 1)
+        throw new ArtifactContextError('external_context_not_accepted');
     return {
         parentOrigin: context.bridge.parentOrigin,
         channelId: context.bridge.channelId,

package/dist/server/runtime-config.d.ts

@@ -32,7 +32,7 @@ export declare function getArtifactRequestContext({ headers, runtime, method, pa
     devSessionId: string | null;
     requestId: string;
     jti: string;
-    method: "GET" | "POST" | "DELETE" | "HEAD" | "PUT" | "PATCH" | "OPTIONS";
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
     path: string;
     iat: number;
     exp: number;

package/dist/server/testing.d.ts

@@ -0,0 +1,40 @@
+import { type KeyObject } from 'node:crypto';
+import { type RequestContextV2External } from './request-context.js';
+import { type ArtifactRuntimeConfig } from './runtime-config.js';
+/**
+ * Test helpers for applications that accept external callers: sign an external (v2) context
+ * with a test key, and run code against an explicit runtime configuration. For unit tests and
+ * local `next dev` only. A context signed here verifies only against the matching public key,
+ * which a hosted runtime never pins.
+ */
+type ExternalPrincipalClaims = RequestContextV2External['principal'];
+export interface SignTestExternalContextInput {
+    privateKey: KeyObject | string;
+    /** Use an `external-` kid; verifiers refuse any other kid on an external context. */
+    kid: string;
+    projectId: string;
+    environment: string;
+    method: string;
+    path: string;
+    /** Overrides on a verified-borrower default principal. */
+    principal?: Partial<Omit<ExternalPrincipalClaims, 'kind'>>;
+    serviceAccountId: string;
+    /** Defaults to `published`. Verifiers refuse `development` until development leases admit it. */
+    mode?: RequestContextV2External['mode'];
+    deploymentId?: string | null;
+    devSessionId?: string | null;
+    /** Seconds since the epoch; defaults to now. */
+    now?: number;
+    /** Defaults to and may not exceed 60. */
+    ttlSeconds?: number;
+    /** Overrides applied after the defaults, unvalidated, for negative tests. */
+    claims?: Record<string, unknown>;
+}
+export declare function signTestExternalContext({ privateKey, kid, projectId, environment, method, path, principal, serviceAccountId, mode, deploymentId, devSessionId, now, ttlSeconds, claims, }: SignTestExternalContextInput): string;
+/**
+ * Runs `fn` with the hosted runtime configuration set to `config` (and no runtime file), then
+ * restores the previous environment. The override is process-wide: do not run overlapping calls.
+ * Refuses to run in a production build.
+ */
+export declare function withTestRuntimeConfig<T>(config: ArtifactRuntimeConfig, fn: () => Promise<T> | T): Promise<T>;
+export {};

package/dist/server/testing.js

@@ -0,0 +1,86 @@
+import { createHash, createPrivateKey, randomUUID, sign } from 'node:crypto';
+import { ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS, requestContextV2ExternalSchema } from './request-context.js';
+import { artifactRuntimeConfigSchema } from './runtime-config.js';
+const defaultUserAgent = 'Mozilla/5.0 (test)';
+export function signTestExternalContext({ privateKey, kid, projectId, environment, method, path, principal = {}, serviceAccountId, mode = 'published', deploymentId, devSessionId, now = Math.floor(Date.now() / 1000), ttlSeconds = ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS, claims = {}, }) {
+    const userAgent = principal.client?.userAgent ?? defaultUserAgent;
+    const resolvedPrincipal = {
+        kind: 'external',
+        ingress: 'borrower',
+        provider: 'test-provider',
+        issuer: 'https://idp.example.test/',
+        subject: 'test|borrower-1',
+        clientId: 'test-client',
+        email: 'borrower@example.test',
+        emailVerified: true,
+        authTime: now - 30,
+        amr: ['pwd'],
+        tokenIssuedAt: now - 30,
+        ...principal,
+        pass: { id: randomUUID(), kid: 'pass-1', issuedAt: now - 10, exchangeIp: '203.0.113.10', ...principal.pass },
+        client: {
+            ip: '203.0.113.10',
+            userAgentSha256: createHash('sha256').update(userAgent).digest('hex'),
+            origin: 'https://borrower.example.test',
+            ...principal.client,
+            userAgent,
+        },
+    };
+    const published = mode === 'published';
+    const payload = {
+        v: 2,
+        iss: 'atlas-artifact-gateway',
+        aud: `artifact:${projectId}`,
+        sub: `ext|${resolvedPrincipal.provider}|${resolvedPrincipal.subject}`,
+        projectId,
+        environment,
+        mode,
+        deploymentId: deploymentId !== undefined ? deploymentId : published ? 'test-deployment' : null,
+        devSessionId: devSessionId !== undefined ? devSessionId : published ? null : 'test-dev-session',
+        requestId: randomUUID(),
+        jti: randomUUID(),
+        method: method.toUpperCase(),
+        path,
+        iat: now,
+        exp: now + ttlSeconds,
+        serviceAccountId,
+        principal: resolvedPrincipal,
+        crit: [],
+        ext: {},
+        ...claims,
+    };
+    // Catch a mistaken default early; `claims` overrides are for deliberately invalid contexts.
+    if (Object.keys(claims).length === 0)
+        requestContextV2ExternalSchema.parse(payload);
+    const key = typeof privateKey === 'string' ? createPrivateKey(privateKey) : privateKey;
+    const unsigned = [{ alg: 'EdDSA', typ: 'JWT', kid }, payload]
+        .map(part => Buffer.from(JSON.stringify(part)).toString('base64url')).join('.');
+    return `${unsigned}.${sign(null, Buffer.from(unsigned), key).toString('base64url')}`;
+}
+const runtimeEnvironmentKeys = ['SEQUENCE_ARTIFACT_RUNTIME_FILE', 'SEQUENCE_ARTIFACT_RUNTIME_CONFIG', 'SEQUENCE_ARTIFACT_RUNTIME_TOKEN'];
+/**
+ * Runs `fn` with the hosted runtime configuration set to `config` (and no runtime file), then
+ * restores the previous environment. The override is process-wide: do not run overlapping calls.
+ * Refuses to run in a production build.
+ */
+export async function withTestRuntimeConfig(config, fn) {
+    if (process.env.NODE_ENV === 'production')
+        throw new Error('withTestRuntimeConfig is for tests and local development only');
+    const { sessionToken, ...hosted } = artifactRuntimeConfigSchema.parse(config);
+    const previous = Object.fromEntries(runtimeEnvironmentKeys.map(key => [key, process.env[key]]));
+    delete process.env.SEQUENCE_ARTIFACT_RUNTIME_FILE;
+    process.env.SEQUENCE_ARTIFACT_RUNTIME_CONFIG = JSON.stringify(hosted);
+    process.env.SEQUENCE_ARTIFACT_RUNTIME_TOKEN = sessionToken;
+    try {
+        return await fn();
+    }
+    finally {
+        for (const key of runtimeEnvironmentKeys) {
+            const value = previous[key];
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+    }
+}

package/dist/server.d.ts

@@ -1,12 +1,17 @@
 import 'server-only';
-export { createArtifactServerClient, ArtifactServerError } from './server/client.js';
+export { createArtifactServerClient } from './server/client.js';
+export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './server/errors.js';
 export type { ArtifactAtlasRefusal } from './server/errors.js';
-export type { ArtifactAuditEvent, ArtifactOrmOperations, ArtifactOrmOptions, ArtifactProcessAdvance, ArtifactProcessAdvanceResult, ArtifactProcessArtifactRef, ArtifactProcessAssign, ArtifactProcessAssignResult, ArtifactProcessDefinition, ArtifactProcessDescribeQuery, ArtifactProcessEdge, ArtifactProcessHumanNode, ArtifactProcessNode, ArtifactProcessNodeBase, ArtifactProcessNodeState, ArtifactProcessPrincipal, ArtifactProcessPrincipalSearch, ArtifactProcessPrincipals, ArtifactProcessRun, ArtifactProcessRunRecord, ArtifactProcessRunSnapshot, ArtifactProcessRunsQuery, ArtifactProcessRunViewerChange, ArtifactProcessRunViewers, ArtifactProcessStart, ArtifactProcessStepRecord, ArtifactProcessTask, ArtifactProcessTasksQuery, ArtifactServerAudit, ArtifactServerClient, ArtifactServerFetchOptions, ArtifactServerFlags, ArtifactServerProcesses, } from './server/client.js';
+export type { ArtifactAuditEvent, ArtifactOrmOperations, ArtifactOrmOptions, ArtifactProcessAdvance, ArtifactProcessAdvanceResult, ArtifactProcessArtifactRef, ArtifactProcessAssign, ArtifactProcessAssignResult, ArtifactProcessDefinition, ArtifactProcessDescribeQuery, ArtifactProcessEdge, ArtifactProcessHumanNode, ArtifactProcessNode, ArtifactProcessNodeBase, ArtifactProcessNodeState, ArtifactProcessPrincipal, ArtifactProcessPrincipalSearch, ArtifactProcessPrincipals, ArtifactProcessRun, ArtifactProcessRunRecord, ArtifactProcessRunSnapshot, ArtifactProcessRunsQuery, ArtifactProcessRunViewerChange, ArtifactProcessRunViewers, ArtifactProcessStart, ArtifactProcessStepRecord, ArtifactProcessTask, ArtifactProcessTasksQuery, ArtifactServerAudit, ArtifactServerClient, ArtifactServerClientOptions, ArtifactServerContext, ArtifactServerFetchOptions, ArtifactServerFlags, ArtifactServerProcesses, } from './server/client.js';
 export { ARTIFACT_AUDIT_ACTIONS, ARTIFACT_AUDIT_RESOURCES_PER_EVENT, ARTIFACT_FLAGS_PER_REQUEST, ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT, ARTIFACT_PROCESS_PRINCIPAL_TYPES, ARTIFACT_PROCESS_PRINCIPALS_PER_CALL, ARTIFACT_PROCESS_RUN_STATUSES, ARTIFACT_PROCESS_RUNS_LIMIT, ARTIFACT_PROCESS_TASK_VIEWS, ARTIFACT_PROCESS_TASKS_LIMIT, } from './server/broker-contract.js';
 export type { ArtifactAuditAction, ArtifactProcessPrincipalType, ArtifactProcessRunStatus, ArtifactProcessTaskView, } from './server/broker-contract.js';
 export { getArtifactRequestContext, readArtifactRuntimeConfig } from './server/runtime-config.js';
 export type { ArtifactRuntimeConfig, ArtifactRequestHeaders } from './server/runtime-config.js';
-export { getArtifactBrowserBootstrap } from './server/request-context.js';
-export type { ArtifactRequestContext } from './server/request-context.js';
+export { ArtifactContextError, getArtifactBrowserBootstrap } from './server/request-context.js';
+export type { ArtifactContextErrorReason, ArtifactRequestContext, RequestContextV2External } from './server/request-context.js';
+export { verifyArtifactExternalContext } from './server/external-context.js';
+export type { ArtifactExternalAccept } from './server/external-context.js';
+export { externalEvidence } from './server/principal.js';
+export type { ArtifactExternalEvidence, ArtifactExternalPrincipal, ArtifactPrincipal } from './server/principal.js';
 export type { ArtifactLogMetadata, ArtifactLogRecord } from './server/logger.js';
 export type { ArtifactOrmJsonScalars } from './orm-json-scalars.js';

package/dist/server.js

@@ -1,5 +1,8 @@
 import 'server-only';
-export { createArtifactServerClient, ArtifactServerError } from './server/client.js';
+export { createArtifactServerClient } from './server/client.js';
+export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './server/errors.js';
 export { ARTIFACT_AUDIT_ACTIONS, ARTIFACT_AUDIT_RESOURCES_PER_EVENT, ARTIFACT_FLAGS_PER_REQUEST, ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT, ARTIFACT_PROCESS_PRINCIPAL_TYPES, ARTIFACT_PROCESS_PRINCIPALS_PER_CALL, ARTIFACT_PROCESS_RUN_STATUSES, ARTIFACT_PROCESS_RUNS_LIMIT, ARTIFACT_PROCESS_TASK_VIEWS, ARTIFACT_PROCESS_TASKS_LIMIT, } from './server/broker-contract.js';
 export { getArtifactRequestContext, readArtifactRuntimeConfig } from './server/runtime-config.js';
-export { getArtifactBrowserBootstrap } from './server/request-context.js';
+export { ArtifactContextError, getArtifactBrowserBootstrap } from './server/request-context.js';
+export { verifyArtifactExternalContext } from './server/external-context.js';
+export { externalEvidence } from './server/principal.js';

package/dist/templates/nextjs/README.md

@@ -97,6 +97,11 @@ only runs that user may view, `getRun` needs Viewer on the run and returns
 every viewer — keep the data your pages need in your own ORM namespace. Reads
 work from pages and GET route handlers; starting a run does not.
 
+To follow a run as it moves, poll `processes.listEvents({ runId, since, limit })`
+with the `event_cursor` from `getRun`, then with the `cursor` each page returns:
+every event arrives once, oldest first, in the shape the run's stream sends. It
+needs Viewer on the run, like `getRun`.
+
 The same `processes.read` declaration lets you render the process itself.
 `processes.describe({ process, version })` returns the applied template a run
 is filled in from — `{ id, name, version, new_runs_disabled, start_node_id,
@@ -128,6 +133,10 @@ groups })` reassigns a parked step (its advancers become exactly those
 principals) and `processes.grantViewers` / `processes.revokeViewers({ runId,
 users, groups })` share a run or take a share back; all three need the user to
 own the run, and `processes.listViewers(runId)` shows the run's stored shares.
+`processes.cancel(runId)` cancels a run, and `processes.resetStep({ runId,
+stepId })` stops a generating agent step without cancelling its run (the run
+re-parks at the node's reset edge); both need the user's `invoker` relation on
+the run, as the Lattice routes do.
 Users are Auth0 subs and groups are chat-group ids — take them from
 `processes.searchPrincipals({ q, types, limit })`, which finds people in the
 user's own tenant and groups they can see, as the Lattice picker does. The

package/dist/templates/nextjs/package.json

@@ -10,7 +10,9 @@
     "dev": "next dev --webpack --hostname 127.0.0.1",
     "build": "next build",
     "start": "next start --hostname 127.0.0.1",
-    "type-check": "next typegen && tsc --noEmit"
+    "lint": "next typegen && tsc --noEmit --noUnusedLocals --noUnusedParameters --noFallthroughCasesInSwitch",
+    "type-check": "next typegen && tsc --noEmit",
+    "test": "node --test tests/*.test.mjs"
   },
   "dependencies": {
     "@sequenceholdings/artifact-studio": "{{artifactStudioVersion}}",

package/dist/templates/nextjs/tests/server.test.mjs

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { greet } from '../app/actions.ts'
+import { GET } from '../app/api/health/route.ts'
+
+test('greeting validates input and returns the server action result', async () => {
+  const data = new FormData()
+  data.set('name', '  Atlas  ')
+  assert.deepEqual(await greet({ message: '', error: null }, data), {
+    message: 'Hello, Atlas. Your server action ran successfully.', error: null,
+  })
+  for (const name of ['', ' '.repeat(3), 'a'.repeat(81)]) {
+    data.set('name', name)
+    const result = await greet({ message: '', error: null }, data)
+    assert.equal(result.message, '')
+    assert.equal(result.error, 'Enter a name between 1 and 80 characters.')
+  }
+})
+
+test('health route returns uncached JSON without any runtime bindings', async () => {
+  const response = GET()
+  assert.equal(response.status, 200)
+  assert.equal(response.headers.get('cache-control'), 'no-store')
+  assert.deepEqual(await response.json(), { ok: true, framework: 'nextjs' })
+})

package/dist/templates/react-vite/package.json

@@ -9,7 +9,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@sequenceholdings/artifact-studio": "^0.5.0",
+    "@sequenceholdings/artifact-studio": "^0.6.0",
     "@sequenceholdings/atlas-ui": "^3.1.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",

package/dist/tunnel/protocol.js

@@ -1,6 +1,7 @@
 import { Buffer } from 'node:buffer';
 import { z } from 'zod';
 import { isLoopbackHostname } from '../loopback.js';
+import { isPrivateRequestHeader } from './reserved-headers.js';
 /** Version 1 is negotiated by the tunnel connection, not by individual streams. */
 export const TUNNEL_PROTOCOL = 'artifact-tunnel.v1';
 export const DEFAULT_TUNNEL_LIMITS = Object.freeze({
@@ -143,10 +144,7 @@ function removePrivateHeaders(headers) {
     const nominated = new Set((Array.isArray(connection) ? connection.join(',') : connection ?? '')
         .split(',').map((name) => name.trim().toLowerCase()));
     for (const name of headers.keys()) {
-        if (HOP_HEADERS.has(name) || nominated.has(name) || name === 'forwarded' ||
-            name === 'authorization' || name === 'remote-user' || name === 'x-remote-user' ||
-            name === 'x-serverless-authorization' || name === 'x-goog-iap-jwt-assertion' ||
-            /^(?:x-forwarded-|x-sequence-|x-artifact-|x-atlas-|x-user-|x-auth-|x-authenticated-|x-goog-authenticated-|proxy-)/.test(name))
+        if (HOP_HEADERS.has(name) || nominated.has(name) || isPrivateRequestHeader(name))
             headers.delete(name);
     }
 }

package/dist/tunnel/reserved-headers.d.ts

@@ -0,0 +1,7 @@
+/** Lowercase header name the proxy strips from every request it forwards to an app. */
+export declare function isPrivateRequestHeader(name: string): boolean;
+/**
+ * Client-address headers an external ingress drops: on an ingress the client address comes only
+ * from the edge-verified `CF-Connecting-IP`, never from a header the caller can set.
+ */
+export declare const INGRESS_CLIENT_ADDRESS_HEADERS: readonly string[];

package/dist/tunnel/reserved-headers.js

@@ -0,0 +1,20 @@
+/**
+ * Request headers the platform owns. The proxy strips them before a request reaches app code
+ * (`removePrivateHeaders` in `protocol.ts`), so a manifest may never declare one as an app header.
+ * Dependency-free: browser code that parses manifests imports it.
+ */
+const PRIVATE_REQUEST_HEADER_NAMES = new Set([
+    'forwarded', 'authorization', 'remote-user', 'x-remote-user', 'x-serverless-authorization', 'x-goog-iap-jwt-assertion',
+]);
+const PRIVATE_REQUEST_HEADER_PREFIX = /^(?:x-forwarded-|x-sequence-|x-artifact-|x-atlas-|x-user-|x-auth-|x-authenticated-|x-goog-authenticated-|proxy-)/;
+/** Lowercase header name the proxy strips from every request it forwards to an app. */
+export function isPrivateRequestHeader(name) {
+    return PRIVATE_REQUEST_HEADER_NAMES.has(name) || PRIVATE_REQUEST_HEADER_PREFIX.test(name);
+}
+/**
+ * Client-address headers an external ingress drops: on an ingress the client address comes only
+ * from the edge-verified `CF-Connecting-IP`, never from a header the caller can set.
+ */
+export const INGRESS_CLIENT_ADDRESS_HEADERS = Object.freeze([
+    'true-client-ip', 'x-real-ip', 'x-client-ip', 'client-ip', 'x-cluster-client-ip',
+]);