@sequenceholdings/artifact-studio 0.4.0 → 0.6.1

package/dist/server/connection-retry.js

@@ -0,0 +1,40 @@
+/** Recognising a lost connection to Atlas, and waiting before a broker read is resent. */
+/**
+ * Socket and DNS errors after which Atlas never answered, and which clear by themselves: the
+ * route to Atlas was briefly gone (an egress NAT out of ports drops new connections, which Node
+ * reports as EHOSTUNREACH), Atlas's edge refused or reset the connection, or a lookup failed
+ * transiently. Timeouts aren't here: a call that waited out its timeout shouldn't wait it out again.
+ */
+const transientConnectionCodes = new Set(['ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'EADDRNOTAVAIL', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_SOCKET']);
+/**
+ * The transient connection code behind a failed fetch, or null. Node's fetch throws
+ * `TypeError: fetch failed` with the socket error as its cause. When every address of the host
+ * failed to connect, that cause is an AggregateError carrying the first address's code.
+ */
+export function transientConnectionCode(error) {
+    let current = error;
+    for (let depth = 0; depth < 8 && typeof current === 'object' && current !== null; depth++) {
+        if ('code' in current && typeof current.code === 'string' && transientConnectionCodes.has(current.code))
+            return current.code;
+        current = 'cause' in current ? current.cause : undefined;
+    }
+    return null;
+}
+/** Resolves after `ms`, or rejects with the caller's abort reason as soon as it aborts. */
+export function pause({ ms, signal }) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const aborted = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', aborted);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', aborted, { once: true });
+    });
+}

package/dist/server/errors.d.ts

@@ -0,0 +1,61 @@
+export declare const INSUFFICIENT_USER_AUTHENTICATION = "insufficient_user_authentication";
+/**
+ * What Atlas's error envelope said about a refusal, when the response carried one. Atlas routes
+ * answer `{ detail, code? }`: `detail` is the human-readable reason, `code` the route's machine
+ * code when it has one (`RUN_TERMINAL`, `EDGE_ID_MISMATCH`, `WORKFLOW_NOT_RUNNING`, …), so an
+ * application can branch on a refusal the way a caller of the route itself would.
+ */
+export interface ArtifactAtlasRefusal {
+    code: string | null;
+    detail: string | null;
+}
+export interface ArtifactServerErrorDetails {
+    reason?: string;
+    maxAge?: number;
+    atlas?: ArtifactAtlasRefusal;
+}
+export declare class ArtifactServerError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** A named refusal a handler can act on, such as `insufficient_user_authentication`. */
+    readonly reason: string | undefined;
+    /** With `insufficient_user_authentication`: the sign-in age, in seconds, the operation requires. */
+    readonly maxAge: number | undefined;
+    /** Atlas's own account of the refusal; both null when the response had no readable envelope. */
+    readonly atlas: ArtifactAtlasRefusal;
+    constructor(status: number, code: string, message: string, details?: ArtifactServerErrorDetails);
+}
+/** A user-mode call made for a caller that may act only through `asService()`. */
+export declare class ArtifactPrincipalError extends ArtifactServerError {
+    readonly reason: 'external_requires_service';
+    constructor(reason: 'external_requires_service');
+}
+/**
+ * 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 declare function stepUpError(status: number, body: unknown): ArtifactServerError | null;
+export declare function stepUpErrorFromResponse(response: Response): Promise<ArtifactServerError | null>;
+/**
+ * A refused broker call, keeping what Atlas said: the message carries the route's `detail`
+ * 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 declare function platformRequestError({ status, body, operation }: {
+    status: number;
+    body: unknown;
+    operation: string;
+}): ArtifactServerError;
+/**
+ * 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 declare function refusalFromResponse({ response, operation }: {
+    response: Response;
+    operation: string;
+}): Promise<ArtifactServerError>;
+/**
+ * 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 declare function stepUpResponse(error: ArtifactServerError): Response;

package/dist/server/errors.js

@@ -0,0 +1,89 @@
+/** 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, details = {}) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'ArtifactServerError';
+        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() });
+/**
+ * A refused broker call, keeping what Atlas said: the message carries the route's `detail`
+ * 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 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 (${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/managed-server-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Exact origin-relative path a Lattice `managed_server` node may POST.
+ * No wildcards, query strings, or traversal. Keep this identical to
+ * `atlas/lattice/src/define/managed-server-path.ts`.
+ */
+export declare function isManagedServerInvokePath(path: string): boolean;

package/dist/server/managed-server-path.js

@@ -0,0 +1,14 @@
+/**
+ * Exact origin-relative path a Lattice `managed_server` node may POST.
+ * No wildcards, query strings, or traversal. Keep this identical to
+ * `atlas/lattice/src/define/managed-server-path.ts`.
+ */
+export function isManagedServerInvokePath(path) {
+    if (path.length < 2 || path.length > 512 || !path.startsWith('/') || path.includes('//')) {
+        return false;
+    }
+    if (/[?#\\]/.test(path))
+        return false;
+    const segments = path.slice(1).split('/');
+    return segments.every((segment) => segment !== '.' && segment !== '..' && /^[A-Za-z0-9._~-]+$/.test(segment));
+}

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,
+    };
+}