@sequenceholdings/artifact-studio 0.6.4 → 0.6.7

package/dist/server/external-context.js

@@ -6,11 +6,16 @@ import { verifyAnyArtifactContext } from './internal/verify-any.js';
  * bound to the one route it was signed for. Refuses a v1 context (`external_context_required`)
  * and a context from an ingress the handler did not name (`external_ingress_not_accepted`).
  */
-export function verifyArtifactExternalContext({ token, publicKeys, projectId, environment, method, path, accept, now }) {
+export function verifyArtifactExternalContext({ token, publicKeys, projectId, environment, method, path, accept, developmentSessionId, now }) {
     if (!method || !path)
         throw new ArtifactContextError();
     // verifyAnyArtifactContext canonicalises `path` (canonicalizeIngressPath) before comparing it.
-    const context = verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now });
+    // A direct property, not a conditional spread: a spread member escapes excess-property
+    // checks, so a renamed verifier option would silently refuse every development context.
+    const context = verifyAnyArtifactContext({
+        token, publicKeys, projectId, environment, method, path, now,
+        development: developmentSessionId ? { sessionId: developmentSessionId } : undefined,
+    });
     if (context.v !== 2)
         throw new ArtifactContextError('external_context_required');
     if (!accept.external.includes(context.principal.ingress))

package/dist/server/internal/v1-context.js

@@ -15,7 +15,7 @@ export function parseV1Context({ payload, projectId, environment, method, path,
     const context = parsed.data;
     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))
+        (method !== undefined && context.method !== method.toUpperCase()) || (path !== undefined && !sameRequestTarget({ signed: context.path, actual: path })))
         throw new ArtifactContextError();
     Object.freeze(context.bridge);
     Object.freeze(context.lattice);
@@ -24,3 +24,19 @@ export function parseV1Context({ payload, projectId, environment, method, path,
         Object.freeze(context.taskRoutes);
     return Object.freeze(context);
 }
+/**
+ * The gateway signs the raw request target; a hosted Next.js handler only sees its query
+ * re-serialized (`:` → `%3A`, a space → `+`). The pathname must match exactly; the query
+ * matches when it carries the same parameters, in the same order, however it is encoded.
+ */
+function sameRequestTarget({ signed, actual }) {
+    if (signed === actual)
+        return true;
+    const [signedPath, signedQuery = ''] = splitTarget(signed);
+    const [actualPath, actualQuery = ''] = splitTarget(actual);
+    return signedPath === actualPath && new URLSearchParams(signedQuery).toString() === new URLSearchParams(actualQuery).toString();
+}
+function splitTarget(target) {
+    const separator = target.indexOf('?');
+    return separator === -1 ? [target] : [target.slice(0, separator), target.slice(separator + 1)];
+}

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

@@ -1,5 +1,19 @@
 import { type ArtifactGatewayPublicKeys, type ArtifactRequestContext, type RequestContextV2External } from '../request-context.js';
 export type AnyArtifactRequestContext = ArtifactRequestContext | RequestContextV2External;
+/**
+ * Optional human-directory prefetch for hosted admission, never an authorization result. The
+ * signed project is not yet bound to the credential's database record. After loading that record,
+ * the caller must still run its ordinary verifier with the runtime's keys and authoritative
+ * project, rechecking the clock after the await. Ineligible or invalid contexts return null so
+ * credential failures and external admission keep their existing checks and error ordering.
+ */
+export declare function preverifyHostedBrowserContext({ token, publicKeys, environment, deploymentId, now }: {
+    token: string | null;
+    publicKeys: ArtifactGatewayPublicKeys;
+    environment: string;
+    deploymentId: string;
+    now?: number;
+}): ArtifactRequestContext | null;
 /**
  * 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
@@ -11,14 +25,23 @@ export type AnyArtifactRequestContext = ArtifactRequestContext | RequestContextV
  * context must be signed by an `external-` kid. This pairing is the only thing standing between
  * an `external-` kid and the v1 rules: the v1 branch goes straight to the shared v1 parser, not
  * through the public verifier's own external gate. A v2 context in `development` mode is refused
- * until development leases can admit it. The signature is checked once per call.
+ * unless the caller names the one development session it serves (`development`), and then only
+ * for that session; the kid pairing above already confines it to an `external-` kid. The
+ * signature is checked once per call.
  */
-export declare function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now }: {
+export declare function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, development, now }: {
     token: string | null;
     publicKeys: ArtifactGatewayPublicKeys;
     projectId: string;
     environment: string;
     method?: string;
     path?: string;
+    /**
+     * The development session this caller serves. Pass it only from a development lease (the SDK)
+     * or, in Atlas, only under APP_ENV=development; never from a value the request carries.
+     */
+    development?: {
+        sessionId: string;
+    };
     now?: number;
 }): AnyArtifactRequestContext;

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

@@ -1,7 +1,33 @@
-import { ArtifactContextError, requestContextV2ExternalSchema, } from '../request-context.js';
+import { ArtifactContextError, ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX, artifactRequestContextSchema, 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';
+/**
+ * Optional human-directory prefetch for hosted admission, never an authorization result. The
+ * signed project is not yet bound to the credential's database record. After loading that record,
+ * the caller must still run its ordinary verifier with the runtime's keys and authoritative
+ * project, rechecking the clock after the await. Ineligible or invalid contexts return null so
+ * credential failures and external admission keep their existing checks and error ordering.
+ */
+export function preverifyHostedBrowserContext({ token, publicKeys, environment, deploymentId, now = Math.floor(Date.now() / 1000) }) {
+    try {
+        const { kid, payload } = verifySignedContext({ token, publicKeys });
+        if (kid.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX))
+            return null;
+        const parsed = artifactRequestContextSchema.safeParse(payload);
+        if (!parsed.success)
+            return null;
+        const context = parsed.data;
+        if (context.mode === 'development' || context.deploymentId !== deploymentId ||
+            context.sub.startsWith(ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX))
+            return null;
+        // Self-binding is safe only for this prefetch: ordinary admission binds the stored project.
+        return parseV1Context({ payload: context, projectId: context.projectId, environment, now });
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * 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
@@ -13,9 +39,11 @@ import { canonicalizeIngressPath, signedIngressPath } from '../ingress-routes.js
  * context must be signed by an `external-` kid. This pairing is the only thing standing between
  * an `external-` kid and the v1 rules: the v1 branch goes straight to the shared v1 parser, not
  * through the public verifier's own external gate. A v2 context in `development` mode is refused
- * until development leases can admit it. The signature is checked once per call.
+ * unless the caller names the one development session it serves (`development`), and then only
+ * for that session; the kid pairing above already confines it to an `external-` kid. The
+ * signature is checked once per call.
  */
-export function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now = Math.floor(Date.now() / 1000) }) {
+export function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, development, now = Math.floor(Date.now() / 1000) }) {
     let kid;
     let payload;
     try {
@@ -34,7 +62,7 @@ export function verifyAnyArtifactContext({ token, publicKeys, projectId, environ
     if (!parsed.success)
         throw new ArtifactContextError();
     const context = parsed.data;
-    if (context.mode !== 'published')
+    if (!modeAccepted({ context, development }))
         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.
@@ -46,6 +74,12 @@ export function verifyAnyArtifactContext({ token, publicKeys, projectId, environ
         throw new ArtifactContextError();
     return freezeExternalContext(context);
 }
+/** `published` always; `development` only for the one development session the caller names. */
+function modeAccepted({ context, development }) {
+    if (context.mode === 'published')
+        return true;
+    return development !== undefined && context.devSessionId === development.sessionId;
+}
 function signedPathOf(raw) {
     const canonical = canonicalizeIngressPath(raw);
     return canonical && signedIngressPath(canonical);

package/dist/server/process-run-sharing.d.ts

@@ -0,0 +1,86 @@
+import { type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+/** Users (Auth0 `sub`) and chat groups (group id) to name in an assignment or a share. */
+export interface ArtifactProcessPrincipals {
+    users?: string[];
+    groups?: string[];
+}
+export interface ArtifactProcessRunViewerChange extends ArtifactProcessPrincipals {
+    runId: string;
+}
+/** Add collaborators to selected human nodes without replacing their existing run assignments. */
+export interface ArtifactProcessShareRun extends ArtifactProcessPrincipals {
+    runId: string;
+    /** Explicitly assigned human nodes of this run, at most ARTIFACT_PROCESS_SHARE_NODES_LIMIT. */
+    nodeIds: string[];
+    /** Explicitly permit these users to share full-run viewing and the same or fewer nodes within this app's live audience. */
+    delegateSharing?: {
+        audience: 'current_app';
+    };
+}
+export interface ArtifactProcessShareRunResult {
+    run_id: string;
+    nodes_updated: string[];
+    users: string[];
+    groups: string[];
+    /** True when the sharing grants have been applied; pending authorization rejects with 503. */
+    authorization_applied: boolean;
+    /** The root authority created or used by an explicitly delegated share. */
+    sharingAuthorityId?: string;
+}
+export interface ArtifactProcessRunSharingAuthoritiesQuery {
+    runId: string;
+    /** Default 20, at most ARTIFACT_PROCESS_SHARING_AUTHORITIES_LIMIT (50). */
+    limit?: number;
+    /** Authority id from the previous page's nextCursor. */
+    cursor?: string;
+}
+export interface ArtifactProcessRunSharingDelegate {
+    user_sub: string;
+    node_ids: string[];
+    granted_by: string;
+    granted_at: string;
+}
+export interface ArtifactProcessRunSharingAuthority {
+    id: string;
+    run_id: string;
+    bundle_hash: string;
+    node_ids: string[];
+    audience: {
+        kind: 'artifact_project';
+        project_id: string;
+    };
+    created_by: string;
+    created_at: string;
+    revoked_at: string | null;
+    /** At most 100 individual delegates under this root authority. */
+    delegates: ArtifactProcessRunSharingDelegate[];
+}
+export interface ArtifactProcessRunSharingAuthoritiesPage {
+    authorities: ArtifactProcessRunSharingAuthority[];
+    nextCursor: string | null;
+}
+export interface ArtifactProcessRevokeRunSharingAuthority {
+    runId: string;
+    authorityId: string;
+}
+export interface ArtifactProcessRevokeRunSharingAuthorityResult {
+    authority_id: string;
+    revoked: true;
+}
+export interface ArtifactRunSharingOperations {
+    /** Add collaborators and full-run viewing; owners may explicitly authorize scoped onward sharing. */
+    shareRun(input: ArtifactProcessShareRun): Promise<ArtifactProcessShareRunResult>;
+    /** Owner-only, user-mode page of this run's sharing authorities and their delegates. */
+    listRunSharingAuthorities(query: ArtifactProcessRunSharingAuthoritiesQuery): Promise<ArtifactProcessRunSharingAuthoritiesPage>;
+    /** Owner-only, idempotent revocation of onward sharing; existing viewing and step access remain. */
+    revokeRunSharingAuthority(input: ArtifactProcessRevokeRunSharingAuthority): Promise<ArtifactProcessRevokeRunSharingAuthorityResult>;
+}
+export declare function shareArtifactProcessRun({ mode, json, input }: {
+    mode: ArtifactServerMode;
+    json: (operation: ArtifactServerRequest) => Promise<unknown>;
+    input: ArtifactProcessShareRun;
+}): Promise<ArtifactProcessShareRunResult>;
+export declare function createArtifactProcessSharingClient({ mode, json }: {
+    mode: ArtifactServerMode;
+    json: (operation: ArtifactServerRequest) => Promise<unknown>;
+}): ArtifactRunSharingOperations;

package/dist/server/process-run-sharing.js

@@ -0,0 +1,29 @@
+import { artifactServerRequestSchema } from './broker-contract.js';
+import { ArtifactServerError } from './errors.js';
+export async function shareArtifactProcessRun({ mode, json, input }) {
+    // Atlas owns assignment validation; its wire result names the optional authority in snake case.
+    const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_share_run', mode, ...input }));
+    const { sharing_authority_id, ...shared } = body;
+    if (sharing_authority_id !== undefined && typeof sharing_authority_id !== 'string') {
+        throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed sharing authority id');
+    }
+    return { ...shared, ...(sharing_authority_id === undefined ? {} : { sharingAuthorityId: sharing_authority_id }) };
+}
+export function createArtifactProcessSharingClient({ mode, json }) {
+    return {
+        shareRun: (input) => shareArtifactProcessRun({ mode, json, input }),
+        listRunSharingAuthorities: async (query) => {
+            // Atlas returns the owner-authorized records; the SDK maps only the continuation envelope.
+            const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_sharing_authorities', mode, ...query }));
+            if (!Array.isArray(body?.authorities) || !(typeof body.next_cursor === 'string' || body.next_cursor === null)) {
+                throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed sharing authority page');
+            }
+            // Record projection and authority checks belong to Atlas, as with the other process lists.
+            return { authorities: body.authorities, nextCursor: body.next_cursor };
+        },
+        revokeRunSharingAuthority: async (input) => {
+            // The owner-authorized service returns its idempotent revocation receipt.
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_sharing_authority_revoke', mode, ...input }));
+        },
+    };
+}

package/dist/server/process-runs-page.d.ts

@@ -0,0 +1,39 @@
+import { type ArtifactProcessRunStatus, type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+import type { ArtifactProcessRunRecord } from './processes.js';
+/**
+ * Page visible runs of one declared process; filters stay the same while following its cursor.
+ * Atlas establishes the caller's complete authorization scope before selecting run rows.
+ * Unavailable authorization, an unsupported authorization model, or an incomplete grant scope
+ * returns 503 without partial runs or a cursor.
+ */
+export interface ArtifactProcessRunsPageQuery {
+    process: string;
+    statuses?: ArtifactProcessRunStatus[];
+    /** One entity type, optionally narrowed to one id or a set of up to 500 ids. */
+    entity?: {
+        type: string;
+        id?: string;
+        ids?: string[];
+    };
+    /** Maximum returned visible runs per page, default 100 and at most ARTIFACT_PROCESS_RUNS_LIMIT (500). */
+    limit?: number;
+    /** Encrypted continuation bound to this principal and these filters; expires after one hour. */
+    cursor?: string;
+    /** Soft-archived runs only, instead of the default active ones. */
+    archived?: boolean;
+}
+/** A compact activity-list row; read the run separately for its state, output and steps. */
+export type ArtifactProcessRunSummary = Pick<ArtifactProcessRunRecord, 'id' | 'processId' | 'status' | 'entityType' | 'entityId' | 'startedAt' | 'completedAt' | 'error'>;
+export interface ArtifactProcessRunsPage {
+    runs: ArtifactProcessRunSummary[];
+    /**
+     * Continues after the last returned visible run only when another visible run exists.
+     * Null ends the list; a successful empty page always has null.
+     */
+    nextCursor: string | null;
+}
+export declare function readArtifactProcessRunsPage({ mode, json, query }: {
+    mode: ArtifactServerMode;
+    json: (operation: ArtifactServerRequest) => Promise<unknown>;
+    query: ArtifactProcessRunsPageQuery;
+}): Promise<ArtifactProcessRunsPage>;

package/dist/server/process-runs-page.js

@@ -0,0 +1,10 @@
+import { artifactServerRequestSchema } from './broker-contract.js';
+import { ArtifactServerError } from './errors.js';
+export async function readArtifactProcessRunsPage({ mode, json, query }) {
+    const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_runs_page', mode, ...query }));
+    if (!Array.isArray(body?.runs) || !(typeof body.nextCursor === 'string' || body.nextCursor === null)) {
+        throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed run page');
+    }
+    // Atlas owns row projection and visibility filtering; the SDK preserves its continuation.
+    return body;
+}

package/dist/server/processes.d.ts

@@ -1,4 +1,9 @@
 import { type ArtifactProcessPrincipalType, type ArtifactProcessRunStatus, type ArtifactProcessTaskView, type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+import { type ArtifactProcessRunsPage, type ArtifactProcessRunsPageQuery } from './process-runs-page.js';
+import { type ArtifactProcessPrincipals, type ArtifactProcessRunViewerChange, type ArtifactRunSharingOperations } from './process-run-sharing.js';
+export type { ArtifactProcessRunSummary, ArtifactProcessRunsPage, ArtifactProcessRunsPageQuery } from './process-runs-page.js';
+export type { ArtifactProcessPrincipals, ArtifactProcessRunViewerChange, ArtifactProcessShareRun, ArtifactProcessShareRunResult } from './process-run-sharing.js';
+export type { ArtifactProcessRunSharingAuthoritiesQuery, ArtifactProcessRunSharingAuthoritiesPage, ArtifactProcessRunSharingAuthority, ArtifactProcessRunSharingDelegate, ArtifactProcessRevokeRunSharingAuthority, ArtifactProcessRevokeRunSharingAuthorityResult } from './process-run-sharing.js';
 /** A run of a process declared under `server.capabilities.processes.start`. */
 export interface ArtifactProcessStart {
     process: string;
@@ -264,11 +269,6 @@ export interface ArtifactProcessRunEvents {
     /** 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[];
-    groups?: string[];
-}
 /** Reassigning a parked human step: the step's advancers become exactly these principals. */
 export interface ArtifactProcessAssign extends ArtifactProcessPrincipals {
     runId: string;
@@ -288,9 +288,6 @@ export interface ArtifactProcessRunViewers {
     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;
@@ -309,11 +306,13 @@ export interface ArtifactProcessPrincipal {
     /** Groups: active members. */
     memberCount?: number;
 }
-export interface ArtifactServerProcesses {
+export interface ArtifactServerProcesses extends ArtifactRunSharingOperations {
     /** 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[]>;
+    /** Page compact run summaries the user may view; nextCursor names a continuation only when more visible runs exist. */
+    listRunsPage(query: ArtifactProcessRunsPageQuery): Promise<ArtifactProcessRunsPage>;
     /** 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. */

package/dist/server/processes.js

@@ -1,5 +1,7 @@
 import { artifactServerRequestSchema, } from './broker-contract.js';
 import { ArtifactServerError } from './errors.js';
+import { readArtifactProcessRunsPage } from './process-runs-page.js';
+import { createArtifactProcessSharingClient } from './process-run-sharing.js';
 /** `client.processes`: Lattice through the broker's typed `lattice*` operations. Atlas owns validation and redaction. */
 export function createArtifactProcessesClient({ mode, json }) {
     return {
@@ -14,6 +16,7 @@ export function createArtifactProcessesClient({ mode, json }) {
                 throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed run list');
             return body.runs;
         },
+        listRunsPage: (query) => readArtifactProcessRunsPage({ mode, json, query }),
         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 }));
@@ -36,6 +39,7 @@ export function createArtifactProcessesClient({ mode, json }) {
         assign: async (input) => {
             return await json(artifactServerRequestSchema.parse({ operation: 'lattice_assign', mode, ...input }));
         },
+        ...createArtifactProcessSharingClient({ mode, json }),
         cancel: async (runId) => {
             return await json(artifactServerRequestSchema.parse({ operation: 'lattice_cancel', mode, runId }));
         },

package/dist/server/request-context.js

@@ -72,8 +72,15 @@ export const ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX = 'service-account|';
 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()]);
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
 /** 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');
+const observedUserAgent = z.string().max(512).refine(value => !CONTROL_CHARACTERS.test(value), 'Expected a user agent without control characters');
+/**
+ * The principal's subject and email become the ORM's row-policy claims (`ext_subject`, `ext_email`),
+ * which refuse control characters; refusing them here keeps such a context a 401 at verification
+ * rather than a failure in the middle of a request.
+ */
+const externalSubject = id.refine(value => !CONTROL_CHARACTERS.test(value), 'Expected a subject 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'),
@@ -81,10 +88,10 @@ export const artifactExternalPrincipalSchema = z.object({
     ingress: id,
     provider: id,
     issuer: z.string().min(1).max(2048),
-    subject: id,
+    subject: externalSubject,
     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'),
+    email: z.string().min(3).max(320).refine(value => value === value.trim().toLowerCase() && value.includes('@') && !CONTROL_CHARACTERS.test(value), '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(),

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

@@ -8,7 +8,16 @@ export declare const artifactRuntimeConfigSchema: z.ZodObject<{
     devSessionId: z.ZodOptional<z.ZodString>;
     deploymentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-export type ArtifactRuntimeConfig = z.infer<typeof artifactRuntimeConfigSchema>;
+export type ArtifactRuntimeConfig = z.infer<typeof artifactRuntimeConfigSchema> & {
+    /**
+     * True only on a configuration read from a development lease: the owner-only file `artifact dev`
+     * writes and names in SEQUENCE_ARTIFACT_RUNTIME_FILE (`next-project.ts`), for one development
+     * session. Never parsed from JSON, so neither the lease file, the hosted configuration nor an
+     * explicit `runtime` option can claim it, and it does not survive a re-parse. Only under it does
+     * the SDK accept an external context in `development` mode.
+     */
+    readonly development?: true;
+};
 export type ArtifactRequestHeaders = Pick<Headers, 'get'>;
 /** Credentials are platform-provided and rotated by the CLI, never inferred from ambient cloud auth. */
 export declare function readArtifactRuntimeConfig({ file }?: {

package/dist/server/runtime-config.js

@@ -22,6 +22,16 @@ export const artifactRuntimeConfigSchema = z.object({
     devSessionId: z.string().min(1).max(255).optional(),
     deploymentId: z.string().min(1).max(255).optional(),
 }).strict().refine(value => !(value.devSessionId && value.deploymentId), 'Runtime cannot be both local and hosted');
+/**
+ * Marks a lease file's configuration. Non-enumerable, so the strict schema still accepts the
+ * object if a caller hands it back as an explicit `runtime` (which then drops the marker).
+ */
+function developmentLease(config) {
+    // A lease belongs to exactly one development session; anything else is not a development lease.
+    if (!config.devSessionId || config.deploymentId)
+        return config;
+    return Object.defineProperty(config, 'development', { value: true, enumerable: false, writable: false, configurable: false });
+}
 /** Credentials are platform-provided and rotated by the CLI, never inferred from ambient cloud auth. */
 export async function readArtifactRuntimeConfig({ file = process.env.SEQUENCE_ARTIFACT_RUNTIME_FILE } = {}) {
     if (!file) {
@@ -42,7 +52,7 @@ export async function readArtifactRuntimeConfig({ file = process.env.SEQUENCE_AR
         const stat = await handle.stat();
         if (!stat.isFile() || stat.size > 65536 || (process.platform !== 'win32' && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())))
             throw new Error('Artifact runtime credential file must be owner-readable only, regular, and no larger than 64 KiB');
-        return artifactRuntimeConfigSchema.parse(JSON.parse(await handle.readFile('utf8')));
+        return developmentLease(artifactRuntimeConfigSchema.parse(JSON.parse(await handle.readFile('utf8'))));
     }
     finally {
         await handle.close();

package/dist/server/testing.d.ts

@@ -19,7 +19,7 @@ export interface SignTestExternalContextInput {
     /** 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. */
+    /** Defaults to `published`. Verifiers accept `development` only under a development lease, for its session. */
     mode?: RequestContextV2External['mode'];
     deploymentId?: string | null;
     devSessionId?: string | null;

package/dist/server.d.ts

@@ -2,8 +2,8 @@ import 'server-only';
 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, 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 { ArtifactAuditEvent, ArtifactOrmOperations, ArtifactOrmOptions, ArtifactProcessAdvance, ArtifactProcessAdvanceResult, ArtifactProcessArtifactRef, ArtifactProcessAssign, ArtifactProcessAssignResult, ArtifactProcessDefinition, ArtifactProcessDescribeQuery, ArtifactProcessEdge, ArtifactProcessHumanNode, ArtifactProcessNode, ArtifactProcessNodeBase, ArtifactProcessNodeState, ArtifactProcessPrincipal, ArtifactProcessPrincipalSearch, ArtifactProcessPrincipals, ArtifactProcessRun, ArtifactProcessRunRecord, ArtifactProcessRunSnapshot, ArtifactProcessRunSummary, ArtifactProcessRunsPage, ArtifactProcessRunsPageQuery, ArtifactProcessRunsQuery, ArtifactProcessRunViewerChange, ArtifactProcessRunViewers, ArtifactProcessStart, ArtifactProcessStepRecord, ArtifactProcessShareRun, ArtifactProcessShareRunResult, ArtifactProcessRunSharingAuthoritiesQuery, ArtifactProcessRunSharingAuthoritiesPage, ArtifactProcessRunSharingAuthority, ArtifactProcessRunSharingDelegate, ArtifactProcessRevokeRunSharingAuthority, ArtifactProcessRevokeRunSharingAuthorityResult, 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_RUN_ENTITIES_LIMIT, ARTIFACT_PROCESS_SHARE_NODES_LIMIT, ARTIFACT_PROCESS_SHARING_AUTHORITIES_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';

package/dist/server.js

@@ -1,7 +1,7 @@
 import 'server-only';
 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 { 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_RUN_ENTITIES_LIMIT, ARTIFACT_PROCESS_SHARE_NODES_LIMIT, ARTIFACT_PROCESS_SHARING_AUTHORITIES_LIMIT, ARTIFACT_PROCESS_TASK_VIEWS, ARTIFACT_PROCESS_TASKS_LIMIT, } from './server/broker-contract.js';
 export { getArtifactRequestContext, readArtifactRuntimeConfig } from './server/runtime-config.js';
 export { ArtifactContextError, getArtifactBrowserBootstrap } from './server/request-context.js';
 export { verifyArtifactExternalContext } from './server/external-context.js';

package/dist/tunnel/broker.d.ts

@@ -2,6 +2,8 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Duplex } from 'node:stream';
 import { type TunnelLimits } from './peer.js';
 import type { TunnelRelay } from './transport.js';
+import { type TunnelExternalRequest } from './external.js';
+export type { TunnelExternalFailure, TunnelExternalRequest } from './external.js';
 export interface TunnelLease {
     sessionId: string;
     epoch: number;
@@ -53,12 +55,28 @@ export declare class ArtifactTunnelBroker {
     constructor(options: TunnelBrokerOptions);
     handleTunnelUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
     handleHttp(request: IncomingMessage, response: ServerResponse, sessionId: string): Promise<void>;
+    /** Proxies an admitted external ingress request over the session's tunnel. Never throws. */
+    handleExternalHttp(input: TunnelExternalRequest): Promise<void>;
     handleWebSocketUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, sessionId: string): Promise<void>;
     private authorize;
+    /**
+     * The live tunnel for an external request: the session's current lease, for the granted project
+     * and environment, still valid. Null otherwise. No browser owner is compared: Atlas's grant
+     * already checked the session and its owner's grant on the ingress service account.
+     */
+    private externalConnection;
     private valid;
     private remoteConnection;
     private attach;
     private receive;
+    private receiveHead;
+    private receiveBody;
+    /**
+     * Backpressure from an external caller abandons the request after the idle timeout instead of
+     * holding its stream (and the caller's admission permit) until the request timeout. A write the
+     * abort interrupted is not a tunnel failure, so the session's other streams carry on.
+     */
+    private writeExternalChunk;
     private finish;
     private abort;
     /** Immediate revocation and graceful service shutdown hook. */