@sequenceholdings/artifact-studio 0.4.0 → 0.6.1

package/dist/server/processes.d.ts

@@ -0,0 +1,290 @@
+import { type ArtifactProcessPrincipalType, type ArtifactProcessRunStatus, type ArtifactProcessTaskView, type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+/** A run of a process declared under `server.capabilities.processes.start`. */
+export interface ArtifactProcessStart {
+    process: string;
+    /** Idempotency key: starting the same run id again returns the existing run. */
+    runId?: string;
+    title?: string;
+    entity?: {
+        type: string;
+        id: string;
+    };
+    /** The run's input, readable by the process as `ctx.run.metadata`. */
+    metadata?: Record<string, unknown>;
+    /**
+     * Who works each human node of this run, keyed by node id (`execute`) or by a path into a
+     * nested subprocess (`application::qa_review`): the node's advancers when the run reaches it,
+     * over the process's own defaults. Users are Auth0 subjects, groups are chat group ids; Atlas
+     * refuses principals it has tombstoned. Reassign a parked step later with `assign`.
+     */
+    assignments?: Record<string, ArtifactProcessPrincipals>;
+}
+export interface ArtifactProcessRun {
+    run_id: string;
+    process_id: string;
+    process_version: string;
+    status: 'pending' | 'existing';
+    idempotent_replay: boolean;
+    /**
+     * created: a new run was dispatched · replayed: an undispatched run with this id was dispatched ·
+     * existing: the run already ran or is running, so nothing was dispatched · unclaimed: a run with
+     * this id exists and was not taken over · queued: the process is at its concurrency limit; the run
+     * is `pending` and starts when a slot frees.
+     */
+    outcome: 'created' | 'replayed' | 'existing' | 'unclaimed' | 'queued';
+}
+/** Which runs of a process declared under `server.capabilities.processes.read` to list. */
+export interface ArtifactProcessRunsQuery {
+    process: string;
+    status?: ArtifactProcessRunStatus;
+    /** Runs about one entity type, or one entity. */
+    entity?: {
+        type: string;
+        id?: string;
+    };
+    /** Newest first; Lattice caps a page at ARTIFACT_PROCESS_RUNS_LIMIT and defaults to 50. */
+    limit?: number;
+    /** Soft-archived runs only, instead of the default active ones. */
+    archived?: boolean;
+}
+/**
+ * The stable fields of a Lattice run row as the read API serves it (Atlas may serve more).
+ * `metadata` (the run's input) is redacted on read for every viewer, so an application keeps the
+ * data it needs back in its own ORM namespace. Timestamps are ISO strings.
+ */
+export interface ArtifactProcessRunRecord {
+    id: string;
+    processId: string;
+    processVersion: string;
+    status: ArtifactProcessRunStatus;
+    title: string | null;
+    entityType: string | null;
+    entityId: string | null;
+    startNodeId: string | null;
+    startedBy: string | null;
+    startedAt: string;
+    completedAt: string | null;
+    archivedAt: string | null;
+    error: string | null;
+    output: unknown;
+    /** Node-produced run state; its access boundary is the run's Viewer relation. */
+    state: Record<string, unknown>;
+}
+/** The stable fields of one step attempt of a run. Wait-token credentials and runner plumbing are redacted. */
+export interface ArtifactProcessStepRecord {
+    id: string;
+    runId: string;
+    nodeId: string;
+    kind: string;
+    attempt: number;
+    status: string;
+    startedAt: string;
+    completedAt: string | null;
+    input: unknown;
+    output: unknown;
+    error: string | null;
+    nextEdgeId: string | null;
+    waitTokenId: string | null;
+}
+/** The collapsed lifecycle of one node: its latest attempt with finished-branch events applied. */
+export type ArtifactProcessNodeState = 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'cancelled' | 'timed_out';
+/** One run as `GET /api/lattice/runs/[runId]` serves it. */
+export interface ArtifactProcessRunSnapshot {
+    run: ArtifactProcessRunRecord;
+    /** Raw step rows, one per attempt / fan-out branch. */
+    steps: ArtifactProcessStepRecord[];
+    states: Record<string, ArtifactProcessNodeState>;
+    /** Pass to the run's event stream as `?since=` to receive everything after this snapshot. */
+    event_cursor: string | null;
+}
+/** Which applied version of a process declared under `processes.read` to describe. */
+export interface ArtifactProcessDescribeQuery {
+    process: string;
+    /** A run's `processVersion`, to see the template that run was started from. Default: the active version. */
+    version?: string;
+}
+export interface ArtifactProcessEdge {
+    id: string;
+    /** The node this edge routes to. */
+    to: string;
+}
+/** A static Artifact Studio (or uri) reference a human node renders as its work surface. */
+export interface ArtifactProcessArtifactRef {
+    provider: string;
+    artifact_id: string;
+    project: string | null;
+    role: string | null;
+    uri: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface ArtifactProcessNodeBase {
+    id: string;
+    kind: 'automation' | 'agent' | 'human' | 'parallel' | 'subprocess' | 'delay' | 'managed_function' | 'managed_server' | (string & {});
+    title: string;
+    description: string | null;
+    outgoing_edges: ArtifactProcessEdge[];
+}
+/** A human node as the people who work it see it; the engine's own node configuration is not part of this. */
+export interface ArtifactProcessHumanNode extends ArtifactProcessNodeBase {
+    kind: 'human';
+    /** The manual advance choices: `outgoing_edges` less any dedicated timeout route. */
+    advance_edges: ArtifactProcessEdge[];
+    /** The author's label for the single completion action, or null for the surface's default. */
+    complete_label: string | null;
+    /** The author's app-facing metadata (`metadata` on `defineHumanNode`): surface hints, form fields, … */
+    metadata: Record<string, unknown>;
+    comments_enabled: boolean;
+    /** Static refs only; refs a mapper resolves per run are not listed. */
+    artifact_refs: ArtifactProcessArtifactRef[];
+}
+export type ArtifactProcessNode = ArtifactProcessNodeBase | ArtifactProcessHumanNode;
+/**
+ * One applied version of a process: the template its runs are filled in from. Automation, agent,
+ * managed-function, subprocess and parallel internals are the process's own and are never served here.
+ */
+export interface ArtifactProcessDefinition {
+    id: string;
+    name: string;
+    description: string | null;
+    version: string;
+    bundle_hash: string;
+    /** Process-level switch: `processes.start` is refused while set. */
+    new_runs_disabled: boolean;
+    start_node_id: string;
+    /** JSON Schema for the `metadata` a start accepts, when the author declared one. */
+    input_schema: Record<string, unknown> | null;
+    tags: string[];
+    /** Every node, flattened: a human node inside a parallel branch is listed beside the top-level nodes. */
+    nodes: ArtifactProcessNode[];
+}
+/** Which of the user's human steps to list, across processes declared under `processes.read`. */
+export interface ArtifactProcessTasksQuery {
+    /** A subset of the declared processes; default every declared one. */
+    processes?: string[];
+    /** `active` (default): parked and waiting on the user. `completed`: steps they were assigned that are done. */
+    view?: ArtifactProcessTaskView;
+    /** Newest first; Lattice caps a page at ARTIFACT_PROCESS_TASKS_LIMIT and defaults to 100. */
+    limit?: number;
+}
+/** One human step of the user's, with what the node's template says about working it. Timestamps are ISO strings. */
+export interface ArtifactProcessTask {
+    step_id: string;
+    run_id: string;
+    node_id: string;
+    process_id: string;
+    process_version: string;
+    process_name: string | null;
+    title: string;
+    description: string | null;
+    entity: {
+        type: string;
+        id: string;
+    } | null;
+    run_title: string | null;
+    advance_edges: ArtifactProcessEdge[];
+    complete_label: string | null;
+    metadata: Record<string, unknown>;
+    /** How the step reached the user: assigned to them, to one of their groups, or reassigned by them. */
+    assigned_via: 'user' | 'group' | 'reassigned';
+    started_at: string;
+    due_at: string | null;
+    /** Completed view only. */
+    completed_at?: string | null;
+    /** Completed view only: `completed`, or `timed_out` for a step that expired instead of being worked. */
+    step_status?: string;
+    /** Completed view only: the run's status at read time. */
+    run_status?: string;
+    /** The node's template could not be loaded; identity fields are still exact. */
+    template_unavailable?: boolean;
+}
+/** Completing one of the user's parked human steps on a run of a process declared under `processes.act`. */
+export interface ArtifactProcessAdvance {
+    runId: string;
+    /** Which parked step; required when a parallel block has several human branches parked at once. */
+    stepId?: string;
+    /** One of the node's `advance_edges`; omitted on a terminal human node. */
+    edgeId?: string;
+    /** The step's output: the node's form fields, as the process reads them. */
+    payload?: Record<string, unknown>;
+}
+export interface ArtifactProcessAdvanceResult {
+    step_id: string;
+    node_id: string;
+    edge_id: string | null;
+    /** The step had already been completed with this decision; nothing was re-run. */
+    idempotent_replay: boolean;
+}
+/** Users (Auth0 `sub`) and chat groups (group id) to name in an assignment or a share. */
+export interface ArtifactProcessPrincipals {
+    users?: string[];
+    groups?: string[];
+}
+/** Reassigning a parked human step: the step's advancers become exactly these principals. */
+export interface ArtifactProcessAssign extends ArtifactProcessPrincipals {
+    runId: string;
+    stepId: string;
+}
+export interface ArtifactProcessAssignResult {
+    step_id: string;
+    node_id: string;
+    assigned: {
+        users: string[];
+        groups: string[];
+    };
+}
+/** The explicit `viewer` grants stored on a run; access derived from the process or a step is not listed. */
+export interface ArtifactProcessRunViewers {
+    run_id: string;
+    users: string[];
+    groups: string[];
+}
+export interface ArtifactProcessRunViewerChange extends ArtifactProcessPrincipals {
+    runId: string;
+}
+export interface ArtifactProcessPrincipalSearch {
+    /** Empty browses the first `limit` users; 1–2 characters match groups only; 3+ search the directory. */
+    q: string;
+    /** Default both. */
+    types?: ArtifactProcessPrincipalType[];
+    /** Users and groups together; Lattice caps at ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT, default 20. */
+    limit?: number;
+}
+/** A principal the user may name. `id` is the value `assign` and the viewer grants consume. */
+export interface ArtifactProcessPrincipal {
+    type: ArtifactProcessPrincipalType;
+    id: string;
+    name: string;
+    email?: string;
+    picture?: string;
+    /** Groups: active members. */
+    memberCount?: number;
+}
+export interface ArtifactServerProcesses {
+    /** Start a run of a process declared under `processes.start`; the user's Invoker grant decides. */
+    start(input: ArtifactProcessStart): Promise<ArtifactProcessRun>;
+    /** List the runs of a process declared under `processes.read` that the user may view. */
+    listRuns(query: ArtifactProcessRunsQuery): Promise<ArtifactProcessRunRecord[]>;
+    /** Read one run of a process declared under `processes.read`; the user's Viewer relation on the run decides. */
+    getRun(runId: string): Promise<ArtifactProcessRunSnapshot>;
+    /** Describe a process declared under `processes.read`; the user's Viewer relation on the process decides. */
+    describe(query: ArtifactProcessDescribeQuery): Promise<ArtifactProcessDefinition>;
+    /** The user's own human steps across processes declared under `processes.read`. */
+    listTasks(query?: ArtifactProcessTasksQuery): Promise<ArtifactProcessTask[]>;
+    /** Complete a parked human step on a run of a process declared under `processes.act`; the user's own `advancer` grant decides. */
+    advance(input: ArtifactProcessAdvance): Promise<ArtifactProcessAdvanceResult>;
+    /** Reassign a parked human step; the user's `owner` relation on the run decides. */
+    assign(input: ArtifactProcessAssign): Promise<ArtifactProcessAssignResult>;
+    /** The explicit viewer grants on a run of a process declared under `processes.act`; owner-gated. */
+    listViewers(runId: string): Promise<ArtifactProcessRunViewers>;
+    /** Share a run with users and groups; owner-gated, additive, idempotent. */
+    grantViewers(input: ArtifactProcessRunViewerChange): Promise<ArtifactProcessRunViewers>;
+    /** Take a share back; owner-gated, idempotent. Returns the grants that remain. */
+    revokeViewers(input: ArtifactProcessRunViewerChange): Promise<ArtifactProcessRunViewers>;
+    /** Users in the user's own tenant and groups they may see, to name in `assign` or a share. */
+    searchPrincipals(query: ArtifactProcessPrincipalSearch): Promise<ArtifactProcessPrincipal[]>;
+}
+/** `client.processes`: Lattice through the broker's typed `lattice*` operations. Atlas owns validation and redaction. */
+export declare function createArtifactProcessesClient({ mode, json }: {
+    mode: ArtifactServerMode;
+    json: (operation: ArtifactServerRequest) => Promise<unknown>;
+}): ArtifactServerProcesses;

package/dist/server/processes.js

@@ -0,0 +1,56 @@
+import { artifactServerRequestSchema, } from './broker-contract.js';
+import { ArtifactServerError } from './errors.js';
+/** `client.processes`: Lattice through the broker's typed `lattice*` operations. Atlas owns validation and redaction. */
+export function createArtifactProcessesClient({ mode, json }) {
+    return {
+        start: async ({ process, ...run }) => {
+            // Atlas returns the started run's identifiers; the shape is the Lattice start response.
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice', mode, process, ...run }));
+        },
+        listRuns: async (query) => {
+            // The Lattice list response: `{ runs }`, already filtered to what the user may view.
+            const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_runs', mode, ...query }));
+            if (!Array.isArray(body?.runs))
+                throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed run list');
+            return body.runs;
+        },
+        getRun: async (runId) => {
+            // The Lattice run-detail response; Atlas owns redaction and node-state derivation.
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_run', mode, runId }));
+        },
+        describe: async (query) => {
+            // Atlas projects the applied bundle; engine internals never leave it.
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_process', mode, ...query }));
+        },
+        listTasks: async (query = {}) => {
+            // The Lattice inbox response shape: `{ items }`, already the user's own.
+            const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_tasks', mode, ...query }));
+            if (!Array.isArray(body?.items))
+                throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed task list');
+            return body.items;
+        },
+        advance: async (input) => {
+            // The Lattice advance response; Atlas owns the step resolution, the ACL and the walk.
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_advance', mode, ...input }));
+        },
+        assign: async (input) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_assign', mode, ...input }));
+        },
+        listViewers: async (runId) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_viewers', mode, runId }));
+        },
+        grantViewers: async (input) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_viewer_grant', mode, ...input }));
+        },
+        revokeViewers: async (input) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_viewer_revoke', mode, ...input }));
+        },
+        searchPrincipals: async (query) => {
+            // The Lattice picker response shape: `{ principals }`, already scoped to the user's tenant.
+            const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_principals', mode, ...query }));
+            if (!Array.isArray(body?.principals))
+                throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed principal list');
+            return body.principals;
+        },
+    };
+}

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

@@ -1,9 +1,16 @@
 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";
 export declare const ARTIFACT_CONTEXT_MAX_AGE_SECONDS = 60;
+/**
+ * Lattice managed-server invocations last up to the node timeout (300s). A
+ * browser context stays at {@link ARTIFACT_CONTEXT_MAX_AGE_SECONDS}. The longer
+ * window applies only when the signed context names a Lattice run.
+ */
+export declare const ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS = 300;
 /** Public request context. No bearer credentials or secret values belong here. */
 export declare const artifactRequestContextSchema: z.ZodObject<{
     v: z.ZodLiteral<1>;
@@ -55,10 +62,121 @@ 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;
+/** 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";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        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;
@@ -70,6 +188,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,10 +1,17 @@
-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';
 export const ARTIFACT_CONTEXT_MAX_AGE_SECONDS = 60;
+/**
+ * Lattice managed-server invocations last up to the node timeout (300s). A
+ * browser context stays at {@link ARTIFACT_CONTEXT_MAX_AGE_SECONDS}. The longer
+ * window applies only when the signed context names a Lattice run.
+ */
+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 => {
     try {
@@ -46,54 +53,125 @@ export const artifactRequestContextSchema = z.object({
 }).strict().superRefine((value, ctx) => {
     if (value.aud !== `artifact:${value.projectId}`)
         ctx.addIssue({ code: 'custom', message: 'Invalid Artifact audience' });
-    if (value.exp <= value.iat || value.exp - value.iat > ARTIFACT_CONTEXT_MAX_AGE_SECONDS)
+    const maxAge = value.lattice.runId !== null
+        ? ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS
+        : ARTIFACT_CONTEXT_MAX_AGE_SECONDS;
+    if (value.exp <= value.iat || value.exp - value.iat > maxAge)
+        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 { 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;
+const ipAddress = 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: ipAddress }).strict(),
+    client: z.object({
+        ip: ipAddress,
+        userAgent: observedUserAgent,
+        userAgentSha256: z.string().regex(/^[0-9a-f]{64}$/),
+        origin: originSchema.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,