@sequenceholdings/artifact-studio 0.6.1 → 0.6.3

package/dist/server/ingress-routes.js

@@ -0,0 +1,150 @@
+import { isManagedServerInvokePath } from './managed-server-path.js';
+/**
+ * Inbound route grammar for an Artifact Next external ingress (design §(a) "Paths").
+ *
+ * One module owns the three steps every component must agree on: the gateway canonicalises the
+ * raw request target and matches it, Atlas re-matches the signed path on the active manifest, and
+ * the SDK binds the context to the route it serves. The static wildcard matcher
+ * (`manifest-static.ts`) is deliberately not used: it prefix-matches, and a route must not.
+ */
+export const INGRESS_ROUTE_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+/** Longest raw request target the canonicaliser looks at, the signed context path's own cap. */
+export const MAX_INGRESS_PATH_LENGTH = 8192;
+const MAX_TEMPLATE_LENGTH = 512;
+/** A request-time placeholder value: one segment, never `.` or `..`, no encoding. */
+const PLACEHOLDER_VALUE = /^(?!\.{1,2}$)[A-Za-z0-9._~-]{1,128}$/;
+const PLACEHOLDER_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+// Characters the signed context path refuses, or that a request target can only carry by mistake.
+const FORBIDDEN_TARGET_CHARACTERS = /[\\#\s\x00-\x1f\x7f]/;
+/**
+ * Canonicalises a raw origin-form request target (`/path?query`). Returns `null`, so the caller
+ * answers 404, when the pathname is not already canonical: it differs from what the URL parser
+ * makes of it, contains an empty, `.` or `..` segment (a trailing slash is an empty segment), or
+ * contains `%`; or when the query is not already in the form the URL parser serializes it to.
+ * The query string is never used for matching and is returned verbatim.
+ */
+export function canonicalizeIngressPath(raw) {
+    if (typeof raw !== 'string' || raw.length === 0 || raw.length > MAX_INGRESS_PATH_LENGTH)
+        return null;
+    if (FORBIDDEN_TARGET_CHARACTERS.test(raw))
+        return null;
+    const separator = raw.indexOf('?');
+    const path = separator === -1 ? raw : raw.slice(0, separator);
+    const query = separator === -1 ? '' : raw.slice(separator + 1);
+    if (!path.startsWith('/') || path.startsWith('//') || path.includes('%'))
+        return null;
+    let url;
+    try {
+        url = new URL(raw, 'http://ingress.invalid');
+    }
+    catch {
+        return null;
+    }
+    if (url.pathname !== path)
+        return null;
+    // A handler sees only the URL parser's serialization of the query (NextRequest builds a URL), so a
+    // raw query the parser would re-encode yields a signed path the handler can never reproduce.
+    if (url.search.replace(/^\?/, '') !== query)
+        return null;
+    if (!path.slice(1).split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..'))
+        return null;
+    return { path, query };
+}
+/** The single string the gateway signs, Atlas re-matches and the SDK binds: path plus raw query. */
+export function signedIngressPath({ path, query }) {
+    return query === '' ? path : `${path}?${query}`;
+}
+/**
+ * Parses a declared route template such as `/api/borrower/documents/{documentId}/notes`.
+ * Literal segments use the Lattice `managed_server` path grammar; a `{name}` placeholder is a
+ * whole segment. Returns `null` for anything else: no `/api/` prefix, a wildcard, `%`, a query,
+ * a trailing slash, an empty, `.` or `..` segment, or a repeated placeholder name.
+ */
+export function parseRouteTemplate(template) {
+    if (typeof template !== 'string' || template.length > MAX_TEMPLATE_LENGTH)
+        return null;
+    if (!template.startsWith('/api/') || /[*%?#]/.test(template))
+        return null;
+    const names = new Set();
+    const segments = [];
+    for (const segment of template.slice(1).split('/')) {
+        const placeholder = /^\{([^{}]*)\}$/.exec(segment);
+        if (placeholder) {
+            const name = placeholder[1];
+            if (!PLACEHOLDER_NAME.test(name) || names.has(name))
+                return null;
+            names.add(name);
+            segments.push({ kind: 'placeholder', name });
+        }
+        else {
+            if (!isManagedServerInvokePath(`/${segment}`))
+                return null;
+            segments.push({ kind: 'literal', value: segment });
+        }
+    }
+    return { template, segments };
+}
+export function ingressRouteId({ method, template }) {
+    return `${method} ${template}`;
+}
+function matchTemplate(parsed, parts) {
+    if (parsed.segments.length !== parts.length)
+        return null;
+    // No prototype: a lookup of a name the route does not declare is undefined, never an inherited function.
+    const params = Object.create(null);
+    for (const [index, segment] of parsed.segments.entries()) {
+        const part = parts[index];
+        if (segment.kind === 'literal') {
+            if (segment.value !== part)
+                return null;
+        }
+        else {
+            if (!PLACEHOLDER_VALUE.test(part))
+                return null;
+            params[segment.name] = part;
+        }
+    }
+    return params;
+}
+/**
+ * Exact-matches a method and a canonical pathname (from `canonicalizeIngressPath(...).path`, never
+ * the query) against declared routes. Methods compare exactly. An unparseable declaration never
+ * matches, and a path that two declarations both match returns `null`: the manifest refuses
+ * overlapping routes, so ambiguity here means the declarations did not come from a valid manifest.
+ */
+export function matchIngressRoute(routes, method, canonicalPath) {
+    if (!INGRESS_ROUTE_METHODS.includes(method))
+        return null;
+    const canonical = canonicalizeIngressPath(canonicalPath);
+    if (!canonical || canonical.query !== '' || canonicalPath.includes('?'))
+        return null;
+    const parts = canonical.path.slice(1).split('/');
+    let found = null;
+    for (const route of routes) {
+        if (!route.methods.includes(method))
+            continue;
+        const parsed = parseRouteTemplate(route.path);
+        if (!parsed)
+            continue;
+        const params = matchTemplate(parsed, parts);
+        if (!params)
+            continue;
+        if (found)
+            return null;
+        found = { routeId: ingressRouteId({ method, template: route.path }), params: Object.freeze(params), route };
+    }
+    return found;
+}
+/**
+ * Whether one request path could match both templates: same segment count, and at every position
+ * either equal literals or at least one placeholder. Conservative: a placeholder is treated as
+ * matching any literal opposite it.
+ */
+export function ingressRouteTemplatesOverlap({ left, right }) {
+    if (left.segments.length !== right.segments.length)
+        return false;
+    return left.segments.every((segment, index) => {
+        const other = right.segments[index];
+        return segment.kind === 'placeholder' || other.kind === 'placeholder' || segment.value === other.value;
+    });
+}

package/dist/server/internal/verify-any.d.ts

@@ -3,7 +3,9 @@ export type AnyArtifactRequestContext = ArtifactRequestContext | RequestContextV
 /**
  * Version-dispatching verifier for platform code that must accept both Atlas-user (v1) and
  * external (v2) contexts, such as the broker. Applications never get this: it is not exported
- * from `./server` or `./server/context`, and the exports map does not expose `server/internal`.
+ * from `./server` or `./server/context`, and the exports map names no `./server/internal` subpath,
+ * so a package import of it fails to resolve. Atlas, the only consumer, reaches the built file
+ * through its own resolver aliases (tsconfig `paths`, Next and Vitest `resolve.alias`).
  *
  * Kid and version are paired both ways: an `external-` kid must sign a v2 context, and a v2
  * context must be signed by an `external-` kid. This pairing is the only thing standing between

package/dist/server/internal/verify-any.js

@@ -1,10 +1,13 @@
 import { ArtifactContextError, requestContextV2ExternalSchema, } from '../request-context.js';
 import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX, verifySignedContext } from './signed-token.js';
 import { parseV1Context } from './v1-context.js';
+import { canonicalizeIngressPath, signedIngressPath } from '../ingress-routes.js';
 /**
  * Version-dispatching verifier for platform code that must accept both Atlas-user (v1) and
  * external (v2) contexts, such as the broker. Applications never get this: it is not exported
- * from `./server` or `./server/context`, and the exports map does not expose `server/internal`.
+ * from `./server` or `./server/context`, and the exports map names no `./server/internal` subpath,
+ * so a package import of it fails to resolve. Atlas, the only consumer, reaches the built file
+ * through its own resolver aliases (tsconfig `paths`, Next and Vitest `resolve.alias`).
  *
  * Kid and version are paired both ways: an `external-` kid must sign a v2 context, and a v2
  * context must be signed by an `external-` kid. This pairing is the only thing standing between
@@ -33,13 +36,20 @@ export function verifyAnyArtifactContext({ token, publicKeys, projectId, environ
     const context = parsed.data;
     if (context.mode !== 'published')
         throw new ArtifactContextError('external_mode_not_accepted');
+    // The gateway signs only a canonical path (plus its raw query); the caller's path is
+    // canonicalised the same way before comparing, so an encoded or dot-segment variant never binds.
+    if (signedPathOf(context.path) !== context.path)
+        throw new ArtifactContextError();
     if (context.projectId !== projectId || context.environment !== environment ||
         context.exp <= now || context.iat > now + 5 ||
-        // TODO(C1): canonicalizeIngressPath(path) at this comparison (external-context.ts passes the raw route path).
-        (method !== undefined && context.method !== method.toUpperCase()) || (path !== undefined && context.path !== path))
+        (method !== undefined && context.method !== method.toUpperCase()) || (path !== undefined && context.path !== signedPathOf(path)))
         throw new ArtifactContextError();
     return freezeExternalContext(context);
 }
+function signedPathOf(raw) {
+    const canonical = canonicalizeIngressPath(raw);
+    return canonical && signedIngressPath(canonical);
+}
 function freezeExternalContext(context) {
     const { principal } = context;
     Object.freeze(principal.pass);

package/dist/server/processes.d.ts

@@ -4,6 +4,11 @@ export interface ArtifactProcessStart {
     process: string;
     /** Idempotency key: starting the same run id again returns the existing run. */
     runId?: string;
+    /**
+     * Enter the graph at this node in place of the process's start node, as `start_node_id` does on
+     * `POST /api/lattice/runs`; Atlas refuses a node the process does not have.
+     */
+    startNodeId?: string;
     title?: string;
     entity?: {
         type: string;
@@ -214,6 +219,51 @@ export interface ArtifactProcessAdvanceResult {
     /** The step had already been completed with this decision; nothing was re-run. */
     idempotent_replay: boolean;
 }
+/** The result of cancelling a run. Cancelling an already-cancelled run replays without a second intervention. */
+export interface ArtifactProcessCancelResult {
+    /** The cancelled run, redacted as `getRun` returns it; null if Atlas could not reload it. */
+    run: ArtifactProcessRunRecord | null;
+    idempotent_replay: boolean;
+}
+/** Resetting a generating agent step: the step settles and the run re-parks at the node's reset edge. */
+export interface ArtifactProcessResetStep {
+    runId: string;
+    stepId: string;
+}
+export interface ArtifactProcessResetStepResult {
+    run_id: string;
+    step_id: string;
+    node_id: string;
+    reset_edge_id: string;
+    resume_node_id: string;
+    /** The resume node was dispatched again. */
+    redispatched: boolean;
+    /** The run's status after the reset. */
+    status: ArtifactProcessRunStatus | null;
+}
+/** A page of a run's events after a cursor. */
+export interface ArtifactProcessRunEventsQuery {
+    runId: string;
+    /** The `event_cursor` from `getRun`, or the `cursor` the previous page returned. Omitted reads from the run's first event. */
+    since?: string;
+    /** At most ARTIFACT_PROCESS_RUN_EVENTS_LIMIT; Lattice defaults to 500. */
+    limit?: number;
+}
+/** One event on a run, as the run's stream sends it. Payloads are redacted when the event is written. */
+export interface ArtifactProcessRunEvent {
+    id: string;
+    run_id: string;
+    node_id: string | null;
+    event_type: string;
+    source: string;
+    payload: unknown;
+    created_at: string;
+}
+export interface ArtifactProcessRunEvents {
+    events: ArtifactProcessRunEvent[];
+    /** Pass as `since` on the next poll. Null only when the run has no events yet and no `since` was given. */
+    cursor: string | null;
+}
 /** Users (Auth0 `sub`) and chat groups (group id) to name in an assignment or a share. */
 export interface ArtifactProcessPrincipals {
     users?: string[];
@@ -274,6 +324,12 @@ export interface ArtifactServerProcesses {
     advance(input: ArtifactProcessAdvance): Promise<ArtifactProcessAdvanceResult>;
     /** Reassign a parked human step; the user's `owner` relation on the run decides. */
     assign(input: ArtifactProcessAssign): Promise<ArtifactProcessAssignResult>;
+    /** Cancel a run of a process declared under `processes.act`; the user's `invoker` relation on the run decides. */
+    cancel(runId: string): Promise<ArtifactProcessCancelResult>;
+    /** Reset a generating agent step without cancelling its run; the user's `invoker` relation on the run decides. */
+    resetStep(input: ArtifactProcessResetStep): Promise<ArtifactProcessResetStepResult>;
+    /** A page of a run's events after a cursor, oldest first; poll with the returned cursor to see each event once. */
+    listEvents(query: ArtifactProcessRunEventsQuery): Promise<ArtifactProcessRunEvents>;
     /** 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. */

package/dist/server/processes.js

@@ -36,6 +36,19 @@ export function createArtifactProcessesClient({ mode, json }) {
         assign: async (input) => {
             return await json(artifactServerRequestSchema.parse({ operation: 'lattice_assign', mode, ...input }));
         },
+        cancel: async (runId) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_cancel', mode, runId }));
+        },
+        resetStep: async (input) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_reset_step', mode, ...input }));
+        },
+        listEvents: async (query) => {
+            const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_run_events', mode, ...query }));
+            if (!Array.isArray(body?.events) || !(typeof body.cursor === 'string' || body.cursor === null)) {
+                throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed event page');
+            }
+            return body;
+        },
         listViewers: async (runId) => {
             return await json(artifactServerRequestSchema.parse({ operation: 'lattice_viewers', mode, runId }));
         },

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

@@ -11,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>;
@@ -31,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;
@@ -70,6 +72,8 @@ export { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX };
 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">;
@@ -123,10 +127,10 @@ export declare const requestContextV2ExternalSchema: 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;

package/dist/server/request-context.js

@@ -13,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:' ||
@@ -46,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(),
@@ -69,7 +70,8 @@ export { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX };
 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()]);
+/** 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. */
@@ -87,12 +89,12 @@ export const artifactExternalPrincipalSchema = z.object({
     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(),
+    pass: z.object({ id: z.uuid(), kid: id, issuedAt: z.number().int().nonnegative(), exchangeIp: artifactIpAddressSchema }).strict(),
     client: z.object({
-        ip: ipAddress,
+        ip: artifactIpAddressSchema,
         userAgent: observedUserAgent,
         userAgentSha256: z.string().regex(/^[0-9a-f]{64}$/),
-        origin: originSchema.nullable(),
+        origin: artifactOriginSchema.nullable(),
     }).strict(),
 }).strict();
 /**

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/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/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',
+]);

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "SDK types and CLI library for building Artifact Studio apps. Driven via `seq-studio artifact <sub>` (@sequenceholdings/studio-cli), which runs the `./cli` runCli export.",
   "type": "module",
   "exports": {
@@ -101,6 +101,14 @@
       "types": "./dist/server/broker-contract.d.ts",
       "default": "./dist/server/broker-contract.js"
     },
+    "./server/ingress-control-contract": {
+      "types": "./dist/server/ingress-control-contract.d.ts",
+      "default": "./dist/server/ingress-control-contract.js"
+    },
+    "./server/ingress-routes": {
+      "types": "./dist/server/ingress-routes.d.ts",
+      "default": "./dist/server/ingress-routes.js"
+    },
     "./server/release-forms": {
       "types": "./dist/server/release-forms.d.ts",
       "default": "./dist/server/release-forms.js"

package/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