@sequenceholdings/artifact-studio 0.5.0 → 0.6.1

package/dist/server/errors.js

@@ -1,18 +1,53 @@
+/** Errors the server SDK raises, and the step-up (RFC 9470) mapping a handler returns. */
 import { z } from 'zod';
+export const INSUFFICIENT_USER_AUTHENTICATION = 'insufficient_user_authentication';
 const NO_REFUSAL = { code: null, detail: null };
 export class ArtifactServerError extends Error {
     status;
     code;
+    /** A named refusal a handler can act on, such as `insufficient_user_authentication`. */
+    reason;
+    /** With `insufficient_user_authentication`: the sign-in age, in seconds, the operation requires. */
+    maxAge;
     /** Atlas's own account of the refusal; both null when the response had no readable envelope. */
     atlas;
-    constructor(status, code, message, atlas = NO_REFUSAL) {
+    constructor(status, code, message, details = {}) {
         super(message);
         this.status = status;
         this.code = code;
         this.name = 'ArtifactServerError';
-        this.atlas = atlas;
+        this.reason = details.reason;
+        this.maxAge = details.maxAge;
+        this.atlas = details.atlas ?? NO_REFUSAL;
     }
 }
+/** A user-mode call made for a caller that may act only through `asService()`. */
+export class ArtifactPrincipalError extends ArtifactServerError {
+    constructor(reason) {
+        super(403, reason, 'External callers reach platform services only through asService()', { reason });
+        this.name = 'ArtifactPrincipalError';
+    }
+}
+/**
+ * The step-up refusal in a broker 401 body (`{reason|error: 'insufficient_user_authentication',
+ * maxAge|max_age}`), or null. A missing or malformed age asks for a fresh sign-in (0).
+ */
+export function stepUpError(status, body) {
+    if (status !== 401 || body === null || typeof body !== 'object')
+        return null;
+    const named = ('reason' in body && body.reason === INSUFFICIENT_USER_AUTHENTICATION) ||
+        ('error' in body && body.error === INSUFFICIENT_USER_AUTHENTICATION);
+    if (!named)
+        return null;
+    const age = 'maxAge' in body ? body.maxAge : 'max_age' in body ? body.max_age : undefined;
+    const maxAge = typeof age === 'number' && Number.isSafeInteger(age) && age >= 0 ? age : 0;
+    return new ArtifactServerError(401, INSUFFICIENT_USER_AUTHENTICATION, 'A more recent sign-in is required', { reason: INSUFFICIENT_USER_AUTHENTICATION, maxAge });
+}
+export async function stepUpErrorFromResponse(response) {
+    if (response.status !== 401)
+        return null;
+    return stepUpError(response.status, await response.json().catch(() => null));
+}
 /** Atlas answers a refusal as `{ detail, code? }`; anything else (a proxy page, an empty body) reads as no envelope. */
 const atlasRefusalSchema = z.object({ detail: z.string().optional(), code: z.string().optional() });
 /**
@@ -20,10 +55,35 @@ const atlasRefusalSchema = z.object({ detail: z.string().optional(), code: z.str
  * and `error.atlas` its machine `code`, so a consumer can branch on a Lattice refusal
  * (`EDGE_ID_MISMATCH`, `WORKFLOW_NOT_RUNNING`, …) the way a caller of the route itself would.
  */
-export async function platformRequestError({ response, operation }) {
-    const envelope = atlasRefusalSchema.safeParse(await response.json().catch(() => undefined));
+export function platformRequestError({ status, body, operation }) {
+    const envelope = atlasRefusalSchema.safeParse(body);
     const detail = envelope.success ? envelope.data.detail ?? null : null;
     const code = envelope.success ? envelope.data.code ?? null : null;
-    const message = `Atlas rejected the ${operation} request (${response.status})${detail ? `: ${detail}` : ''}`;
-    return new ArtifactServerError(response.status, 'platform_request_failed', message, { code, detail });
+    const message = `Atlas rejected the ${operation} request (${status})${detail ? `: ${detail}` : ''}`;
+    return new ArtifactServerError(status, 'platform_request_failed', message, { atlas: { code, detail } });
+}
+/**
+ * The error for a refused broker response: a step-up refusal keeps its reason and maxAge, any other
+ * refusal keeps Atlas's `{ detail, code }`. The body is read once, so neither reading starves the other.
+ */
+export async function refusalFromResponse({ response, operation }) {
+    const body = await response.json().catch(() => undefined);
+    return stepUpError(response.status, body) ?? platformRequestError({ status: response.status, body, operation });
+}
+/**
+ * The RFC 9470 response for a step-up refusal, for the app to return as is: the caller signs in
+ * again with `max_age` and retries.
+ */
+export function stepUpResponse(error) {
+    if (error.reason !== INSUFFICIENT_USER_AUTHENTICATION)
+        throw new TypeError('stepUpResponse requires an insufficient_user_authentication error');
+    const maxAge = error.maxAge !== undefined && Number.isSafeInteger(error.maxAge) && error.maxAge >= 0 ? error.maxAge : 0;
+    return new Response(JSON.stringify({ error: INSUFFICIENT_USER_AUTHENTICATION, max_age: maxAge }), {
+        status: 401,
+        headers: {
+            'content-type': 'application/json',
+            'cache-control': 'no-store',
+            'www-authenticate': `Bearer error="${INSUFFICIENT_USER_AUTHENTICATION}", max_age=${maxAge}`,
+        },
+    });
 }

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

@@ -0,0 +1,21 @@
+import { type ArtifactGatewayPublicKeys, type RequestContextV2External } from './request-context.js';
+/** The ingresses (manifest `server.ingress` names) whose external callers a handler accepts. */
+export interface ArtifactExternalAccept {
+    external: readonly string[];
+}
+/**
+ * Verifies an external (v2) request context for a handler that explicitly accepts external
+ * callers. Unlike the v1 verifier, `method` and `path` are mandatory: an external context is
+ * 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 declare function verifyArtifactExternalContext({ token, publicKeys, projectId, environment, method, path, accept, now }: {
+    token: string | null;
+    publicKeys: ArtifactGatewayPublicKeys;
+    projectId: string;
+    environment: string;
+    method: string;
+    path: string;
+    accept: ArtifactExternalAccept;
+    now?: number;
+}): RequestContextV2External;

package/dist/server/external-context.js

@@ -0,0 +1,19 @@
+import { ArtifactContextError } from './request-context.js';
+import { verifyAnyArtifactContext } from './internal/verify-any.js';
+/**
+ * Verifies an external (v2) request context for a handler that explicitly accepts external
+ * callers. Unlike the v1 verifier, `method` and `path` are mandatory: an external context is
+ * 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 }) {
+    if (!method || !path)
+        throw new ArtifactContextError();
+    // TODO(C1): canonicalizeIngressPath(path) at the path comparison in internal/verify-any.ts, which the broker shares.
+    const context = verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now });
+    if (context.v !== 2)
+        throw new ArtifactContextError('external_context_required');
+    if (!accept.external.includes(context.principal.ingress))
+        throw new ArtifactContextError('external_ingress_not_accepted');
+    return context;
+}

package/dist/server/internal/signed-token.d.ts

@@ -0,0 +1,15 @@
+/** Kids of keys that sign external (v2) contexts carry this prefix, and only those kids do. */
+export declare const ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX = "external-";
+/**
+ * True when the token names an external key or claims the external version. Unverified: only the
+ * SDK's own refusal and verifier dispatch may use it, never a trust decision, so it stays internal.
+ */
+export declare function isExternalContextToken(token: string | null): boolean;
+/** Verifies the EdDSA signature against the pinned key set and returns the still-untyped payload. */
+export declare function verifySignedContext({ token, publicKeys }: {
+    token: string | null;
+    publicKeys: Readonly<Record<string, string>>;
+}): {
+    kid: string;
+    payload: unknown;
+};

package/dist/server/internal/signed-token.js

@@ -0,0 +1,67 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { z } from 'zod';
+/**
+ * Signature handling shared by every Artifact context verifier. It decides nothing about which
+ * context versions a caller accepts: the public v1 verifier, the external verifier and the
+ * broker's dispatching verifier each apply their own version and kid rules on top of it.
+ *
+ * Lives under `server/internal/`, which the package exports map does not expose.
+ */
+const MAX_CONTEXT_TOKEN_LENGTH = 32768;
+/** Kids of keys that sign external (v2) contexts carry this prefix, and only those kids do. */
+export const ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX = 'external-';
+const headerSchema = z.object({ alg: z.literal('EdDSA'), typ: z.literal('JWT'), kid: z.string().min(1).max(255) }).strict();
+class SignedContextError extends Error {
+    constructor() { super('Invalid signed Artifact context'); this.name = 'SignedContextError'; }
+}
+function decodeSegment(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        throw new SignedContextError();
+    return JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+}
+function splitToken(token) {
+    if (!token || token.length > MAX_CONTEXT_TOKEN_LENGTH)
+        throw new SignedContextError();
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new SignedContextError();
+    const [header, payload, signature] = parts;
+    return [header, payload, signature];
+}
+/**
+ * Reads the kid and the version claim WITHOUT verifying the signature. Use it only to refuse
+ * early or to choose which verifier runs; never to trust a claim. Null when the token is malformed.
+ */
+function peekSignedContext(token) {
+    try {
+        const [encodedHeader, encodedPayload] = splitToken(token);
+        const header = headerSchema.parse(decodeSegment(encodedHeader));
+        const payload = decodeSegment(encodedPayload);
+        const v = payload !== null && typeof payload === 'object' && 'v' in payload ? payload.v : undefined;
+        return { kid: header.kid, v };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when the token names an external key or claims the external version. Unverified: only the
+ * SDK's own refusal and verifier dispatch may use it, never a trust decision, so it stays internal.
+ */
+export function isExternalContextToken(token) {
+    const peeked = peekSignedContext(token);
+    return peeked !== null && (peeked.kid.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX) || peeked.v === 2);
+}
+/** Verifies the EdDSA signature against the pinned key set and returns the still-untyped payload. */
+export function verifySignedContext({ token, publicKeys }) {
+    const [encodedHeader, encodedPayload, signature] = splitToken(token);
+    const header = headerSchema.parse(decodeSegment(encodedHeader));
+    const pem = Object.hasOwn(publicKeys, header.kid) ? publicKeys[header.kid] : undefined;
+    if (!pem || !/^[A-Za-z0-9_-]+$/.test(signature))
+        throw new SignedContextError();
+    const key = createPublicKey(pem);
+    if (key.asymmetricKeyType !== 'ed25519' ||
+        !verify(null, Buffer.from(`${encodedHeader}.${encodedPayload}`), key, Buffer.from(signature, 'base64url')))
+        throw new SignedContextError();
+    return { kid: header.kid, payload: decodeSegment(encodedPayload) };
+}

package/dist/server/internal/v1-context.d.ts

@@ -0,0 +1,18 @@
+import { type ArtifactRequestContext } from '../request-context.js';
+/**
+ * The v1 rules that apply once a signature has been verified and the caller has applied its own
+ * kid and version rules: schema, then the project, environment, clock and route bindings. Every
+ * failure is an ArtifactContextError. Internal: it trusts `payload`, so it must only ever see a
+ * payload whose signature was just verified.
+ *
+ * Shared by the public v1 verifier and the broker's dispatching verifier, so each applies its own
+ * gate in front of it and pays for one signature check.
+ */
+export declare function parseV1Context({ payload, projectId, environment, method, path, now }: {
+    payload: unknown;
+    projectId: string;
+    environment: string;
+    method?: string;
+    path?: string;
+    now: number;
+}): ArtifactRequestContext;

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

@@ -0,0 +1,26 @@
+import { ArtifactContextError, artifactRequestContextSchema } from '../request-context.js';
+/**
+ * The v1 rules that apply once a signature has been verified and the caller has applied its own
+ * kid and version rules: schema, then the project, environment, clock and route bindings. Every
+ * failure is an ArtifactContextError. Internal: it trusts `payload`, so it must only ever see a
+ * payload whose signature was just verified.
+ *
+ * Shared by the public v1 verifier and the broker's dispatching verifier, so each applies its own
+ * gate in front of it and pays for one signature check.
+ */
+export function parseV1Context({ payload, projectId, environment, method, path, now }) {
+    const parsed = artifactRequestContextSchema.safeParse(payload);
+    if (!parsed.success)
+        throw new ArtifactContextError();
+    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))
+        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);
+}

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

@@ -0,0 +1,22 @@
+import { type ArtifactGatewayPublicKeys, type ArtifactRequestContext, type RequestContextV2External } from '../request-context.js';
+export type AnyArtifactRequestContext = ArtifactRequestContext | RequestContextV2External;
+/**
+ * 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`.
+ *
+ * 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
+ * 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.
+ */
+export declare function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now }: {
+    token: string | null;
+    publicKeys: ArtifactGatewayPublicKeys;
+    projectId: string;
+    environment: string;
+    method?: string;
+    path?: string;
+    now?: number;
+}): AnyArtifactRequestContext;

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

@@ -0,0 +1,53 @@
+import { ArtifactContextError, requestContextV2ExternalSchema, } from '../request-context.js';
+import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX, verifySignedContext } from './signed-token.js';
+import { parseV1Context } from './v1-context.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`.
+ *
+ * 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
+ * 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.
+ */
+export function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now = Math.floor(Date.now() / 1000) }) {
+    let kid;
+    let payload;
+    try {
+        ({ kid, payload } = verifySignedContext({ token, publicKeys }));
+    }
+    catch {
+        throw new ArtifactContextError();
+    }
+    const external = kid.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX);
+    const claimsV2 = payload !== null && typeof payload === 'object' && 'v' in payload && payload.v === 2;
+    if (external !== claimsV2)
+        throw new ArtifactContextError();
+    if (!claimsV2)
+        return parseV1Context({ payload, projectId, environment, method, path, now });
+    const parsed = requestContextV2ExternalSchema.safeParse(payload);
+    if (!parsed.success)
+        throw new ArtifactContextError();
+    const context = parsed.data;
+    if (context.mode !== 'published')
+        throw new ArtifactContextError('external_mode_not_accepted');
+    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))
+        throw new ArtifactContextError();
+    return freezeExternalContext(context);
+}
+function freezeExternalContext(context) {
+    const { principal } = context;
+    Object.freeze(principal.pass);
+    Object.freeze(principal.client);
+    if (principal.amr)
+        Object.freeze(principal.amr);
+    Object.freeze(principal);
+    Object.freeze(context.crit);
+    Object.freeze(context.ext);
+    return Object.freeze(context);
+}

package/dist/server/logger.d.ts

@@ -17,7 +17,7 @@ export interface ArtifactLogRecord extends ArtifactLogMetadata {
 }
 /** Structured events deliberately exclude request bodies, URLs, arbitrary messages and error objects. */
 export declare function createArtifactLogger({ context, sink }: {
-    context: ArtifactRequestContext;
+    context: Pick<ArtifactRequestContext, 'projectId' | 'requestId' | 'deploymentId' | 'devSessionId'>;
     sink?: (record: ArtifactLogRecord) => void;
 }): {
     info: (event: string, metadata?: ArtifactLogMetadata) => void;

package/dist/server/principal.d.ts

@@ -0,0 +1,48 @@
+import { type ArtifactRequestContext, type RequestContextV2External } from './request-context.js';
+/** A caller admitted through a manifest-declared ingress, as the gateway verified it. */
+export interface ArtifactExternalPrincipal {
+    readonly kind: 'external';
+    /** Routing label of the ingress that admitted the caller. Not an authorization attribute. */
+    readonly ingress: string;
+    readonly provider: string;
+    readonly issuer: string;
+    /** The identity provider's raw subject (not `ext|`-namespaced). */
+    readonly subject: string;
+    /** Normalized and verified. */
+    readonly email: string;
+    readonly emailVerified: true;
+    readonly authTime: number | null;
+    readonly amr: readonly string[] | null;
+    readonly tokenIssuedAt: number;
+    readonly client: {
+        readonly ip: string;
+        /** Observed, not proven: the browser chooses it. */
+        readonly userAgent: string;
+        readonly userAgentSha256: string;
+        readonly origin: string | null;
+    };
+}
+/** Who this request acts for. Only `external` callers come through an ingress. */
+export type ArtifactPrincipal = {
+    readonly kind: 'atlas_user';
+    readonly sub: string;
+} | {
+    readonly kind: 'platform_service';
+    readonly sub: string;
+} | ArtifactExternalPrincipal;
+export declare function principalFromContext(context: ArtifactRequestContext | RequestContextV2External): ArtifactPrincipal;
+/** The evidence variables an external caller's verified sign-in supplies. */
+export interface ArtifactExternalEvidence {
+    authSubject: string;
+    actorEmail: string;
+    authTime: number | null;
+    authMethods: readonly string[] | null;
+    ipAddress: string;
+    userAgent: string;
+}
+/**
+ * The sanctioned mapping from a verified external principal to evidence variables. On
+ * manifest-declared evidence operations the broker overwrites (or refuses) these from the same
+ * principal, so a mistake here cannot misattribute evidence there.
+ */
+export declare function externalEvidence(principal: ArtifactPrincipal): ArtifactExternalEvidence;

package/dist/server/principal.js

@@ -0,0 +1,39 @@
+import { ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX } from './request-context.js';
+export function principalFromContext(context) {
+    if (context.v === 1) {
+        return Object.freeze(context.sub.startsWith(ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX)
+            ? { kind: 'platform_service', sub: context.sub }
+            : { kind: 'atlas_user', sub: context.sub });
+    }
+    const { principal } = context;
+    return Object.freeze({
+        kind: 'external',
+        ingress: principal.ingress,
+        provider: principal.provider,
+        issuer: principal.issuer,
+        subject: principal.subject,
+        email: principal.email,
+        emailVerified: principal.emailVerified,
+        authTime: principal.authTime,
+        amr: principal.amr,
+        tokenIssuedAt: principal.tokenIssuedAt,
+        client: Object.freeze({ ...principal.client }),
+    });
+}
+/**
+ * The sanctioned mapping from a verified external principal to evidence variables. On
+ * manifest-declared evidence operations the broker overwrites (or refuses) these from the same
+ * principal, so a mistake here cannot misattribute evidence there.
+ */
+export function externalEvidence(principal) {
+    if (principal.kind !== 'external')
+        throw new TypeError('externalEvidence requires an external principal');
+    return {
+        authSubject: principal.subject,
+        actorEmail: principal.email,
+        authTime: principal.authTime,
+        authMethods: principal.amr,
+        ipAddress: principal.client.ip,
+        userAgent: principal.client.userAgent,
+    };
+}

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { NextArtifactBridgeBootstrap, NextArtifactInitialContext } from '../next/protocol.js';
+import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX } from './internal/signed-token.js';
 export declare const ARTIFACT_REQUEST_CONTEXT_HEADER = "x-sequence-artifact-context";
 export declare const ARTIFACT_RUNTIME_TOKEN_HEADER = "x-sequence-artifact-runtime";
 export declare const ARTIFACT_SERVER_REQUEST_PATH = "/api/artifact-studio/server/request";
@@ -61,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;
@@ -76,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;
 };