@sequenceholdings/artifact-studio 0.6.1 → 0.6.3

package/README.md

@@ -79,6 +79,49 @@ because a reset can come after Atlas acted on them, and reject with fetch's
 resend under the same event id.) A response with any status is Atlas's answer
 and is never resent.
 
+## Calling agents from a Next.js server
+
+An application that declares `/api/agents/` in `server.capabilities.api.read`
+and `write` can reach a fixed set of agents API routes as the signed-in user:
+
+| Area | Routes |
+| --- | --- |
+| Chat | `POST chat`, `POST chat/abort`, `GET chat/resume` |
+| Agents | `GET agents`, `GET agents/:id` |
+| Threads | `GET threads`, `POST threads`, `GET threads/:id`, `GET threads/:id/messages`, `PATCH threads/:id/messages/:messageId` |
+| Jobs | `POST jobs`, `GET jobs/:id`, `DELETE jobs/:id` |
+| Files | `POST files`, `GET files/:id`, `DELETE files/:id`, `GET files/:id/url` |
+
+Atlas answers them with the agents API's own handlers, so agent `can_invoke`,
+thread, job and file access stay enforced there. Any other agents path is
+refused, as are service-mode calls and platform service accounts.
+
+A file upload can't travel through the broker's JSON body. Store the file in a
+Workspaces V2 workspace the application declares, then post a reference to it;
+Atlas reads it as the user (up to 25 MB) and uploads it to the agents file
+service:
+
+```ts
+const uploaded = await client.api.post('/api/agents/files?agentId=' + agentId, {
+  storage: { workspaceId, nodeId },
+})
+```
+
+Use `client.api.stream` for a chat turn. Atlas has 60 seconds to start the
+response, as for every broker call, but a stream may then run for as long as
+the turn does; other calls must finish inside the 60 seconds. Calls from the
+browser are buffered by the host, so stream a chat through an application server
+route.
+
+```ts
+const body = await client.api.stream('/api/agents/chat', {
+  method: 'POST',
+  body: { agentId, text },
+  signal: request.signal,
+})
+return new Response(body, { headers: { 'content-type': 'text/event-stream' } })
+```
+
 ## Grouping calls into a trace
 
 The Artifact host supplies tracing context automatically for supported platform

package/VERSION-PIN.md

@@ -36,6 +36,13 @@ and an external principal reaches platform services only through `asService()`.
 0.6.0 also carries `error.atlas` (`{ code, detail }`) on a refused broker call
 (#13398); a step-up 401 still surfaces as `insufficient_user_authentication`.
 
+0.6.0 also accepts the `server.ingress` manifest block. Earlier CLIs and Atlas
+versions parse the server block strictly and reject the key, so an app that
+declares an ingress needs 0.6.0 on both sides; that failure is closed. An
+external context binds the canonical route path (`server/ingress-routes`): a
+handler's `path` is canonicalised the same way before it is compared, and a
+signed path that is not canonical is refused.
+
 Context version policy: a context verifier rejects any unknown top-level or
 `principal` key unless it sits under `ext` or is named in `crit` (and `crit`
 names only extensions the verifier understands; today none, so it is empty).

package/dist/manifest-next-ingress.d.ts

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+/**
+ * `server.ingress`: opt-in front doors for callers that are not Atlas users (design §(a)). Each
+ * external ingress names an identity provider from the environment's catalog, the service account
+ * its callers act as, the real routes they call, and capabilities that must sit inside the
+ * server's own. Nothing environment-specific (issuer, audience, origins) belongs here.
+ */
+export declare const ARTIFACT_NEXT_MAX_INGRESSES = 4;
+export declare const ARTIFACT_NEXT_MAX_INGRESS_ROUTES = 64;
+export declare const ARTIFACT_NEXT_INGRESS_DEFAULT_MAX_BODY_BYTES: number;
+export declare const ARTIFACT_NEXT_INGRESS_MAX_BODY_BYTES: number;
+/** The content types an ingress route may return. No HTML, JavaScript or SVG, ever. */
+export declare const ARTIFACT_NEXT_INGRESS_RESPONSE_TYPES: readonly ["application/json", "application/problem+json", "application/pdf", "application/zip", "image/png", "image/jpeg", "image/webp", "text/csv", "application/octet-stream"];
+/** Verified principal fields the broker may bind into an evidence operation's variables. */
+export declare const ARTIFACT_NEXT_INGRESS_EVIDENCE_SOURCES: readonly ["subject", "email", "authTime", "amr", "client.ip", "client.userAgent", "issuer"];
+declare const STORAGE_ROLE_RANK: {
+    readonly viewer: 0;
+    readonly editor: 1;
+    readonly admin: 2;
+};
+export declare const artifactNextIngressIdSchema: z.ZodString;
+export declare const artifactNextIngressProviderRefSchema: z.ZodString;
+export declare const artifactNextIngressRouteSchema: z.ZodObject<{
+    path: z.ZodString;
+    methods: z.ZodArray<z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+    }>>;
+    fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+    max_body_bytes: z.ZodDefault<z.ZodNumber>;
+    responses: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "application/json": "application/json";
+        "application/problem+json": "application/problem+json";
+        "application/pdf": "application/pdf";
+        "application/zip": "application/zip";
+        "image/png": "image/png";
+        "image/jpeg": "image/jpeg";
+        "image/webp": "image/webp";
+        "text/csv": "text/csv";
+        "application/octet-stream": "application/octet-stream";
+    }>>>;
+}, z.core.$strict>;
+export type ArtifactNextIngressRoute = z.infer<typeof artifactNextIngressRouteSchema>;
+export declare const artifactNextExternalIngressSchema: z.ZodObject<{
+    id: z.ZodString;
+    provider: z.ZodString;
+    service_account: z.ZodString;
+    headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    capabilities: z.ZodPrefault<z.ZodObject<{
+        storage: z.ZodOptional<z.ZodRecord<z.ZodUUID, z.ZodEnum<{
+            viewer: "viewer";
+            editor: "editor";
+            admin: "admin";
+        }>>>;
+        data: z.ZodPrefault<z.ZodObject<{
+            read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        api: z.ZodPrefault<z.ZodObject<{
+            read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        functions: z.ZodPrefault<z.ZodObject<{
+            invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        audit: z.ZodOptional<z.ZodObject<{
+            service: z.ZodString;
+        }, z.core.$strict>>;
+        processes: z.ZodOptional<z.ZodNever>;
+    }, z.core.$strict>>;
+    evidence: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        bind: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            email: "email";
+            subject: "subject";
+            authTime: "authTime";
+            amr: "amr";
+            "client.ip": "client.ip";
+            "client.userAgent": "client.userAgent";
+            issuer: "issuer";
+        }>>>;
+        fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    routes: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        methods: z.ZodArray<z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+        }>>;
+        fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+        max_body_bytes: z.ZodDefault<z.ZodNumber>;
+        responses: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            "application/json": "application/json";
+            "application/problem+json": "application/problem+json";
+            "application/pdf": "application/pdf";
+            "application/zip": "application/zip";
+            "image/png": "image/png";
+            "image/jpeg": "image/jpeg";
+            "image/webp": "image/webp";
+            "text/csv": "text/csv";
+            "application/octet-stream": "application/octet-stream";
+        }>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ArtifactNextExternalIngress = z.infer<typeof artifactNextExternalIngressSchema>;
+export declare const artifactNextIngressSchema: z.ZodObject<{
+    external: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        provider: z.ZodString;
+        service_account: z.ZodString;
+        headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        capabilities: z.ZodPrefault<z.ZodObject<{
+            storage: z.ZodOptional<z.ZodRecord<z.ZodUUID, z.ZodEnum<{
+                viewer: "viewer";
+                editor: "editor";
+                admin: "admin";
+            }>>>;
+            data: z.ZodPrefault<z.ZodObject<{
+                read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+            api: z.ZodPrefault<z.ZodObject<{
+                read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+            functions: z.ZodPrefault<z.ZodObject<{
+                invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+            audit: z.ZodOptional<z.ZodObject<{
+                service: z.ZodString;
+            }, z.core.$strict>>;
+            processes: z.ZodOptional<z.ZodNever>;
+        }, z.core.$strict>>;
+        evidence: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            bind: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                email: "email";
+                subject: "subject";
+                authTime: "authTime";
+                amr: "amr";
+                "client.ip": "client.ip";
+                "client.userAgent": "client.userAgent";
+                issuer: "issuer";
+            }>>>;
+            fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        routes: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            methods: z.ZodArray<z.ZodEnum<{
+                GET: "GET";
+                POST: "POST";
+                PUT: "PUT";
+                PATCH: "PATCH";
+                DELETE: "DELETE";
+            }>>;
+            fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+            max_body_bytes: z.ZodDefault<z.ZodNumber>;
+            responses: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                "application/json": "application/json";
+                "application/problem+json": "application/problem+json";
+                "application/pdf": "application/pdf";
+                "application/zip": "application/zip";
+                "image/png": "image/png";
+                "image/jpeg": "image/jpeg";
+                "image/webp": "image/webp";
+                "text/csv": "text/csv";
+                "application/octet-stream": "application/octet-stream";
+            }>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ArtifactNextIngress = z.infer<typeof artifactNextIngressSchema>;
+/** The server fields an ingress is checked against, as the server schema parses them. */
+interface ServerForIngress {
+    capabilities: {
+        data: {
+            read: readonly string[];
+            write: readonly string[];
+        };
+        api: {
+            read: readonly string[];
+            write: readonly string[];
+        };
+        functions: {
+            invoke: readonly string[];
+        };
+        storage?: Readonly<Record<string, keyof typeof STORAGE_ROLE_RANK>>;
+        audit?: {
+            service: string;
+        };
+    };
+    service_account?: string;
+    resources: {
+        concurrency: number;
+        max_instances: number;
+    };
+    ingress?: ArtifactNextIngress;
+}
+/**
+ * Cross-field rules between `server.ingress` and the rest of `server`: one ingress per provider,
+ * a service account distinct from the app's, capabilities inside the server's own (verbatim list
+ * membership; for storage, the same workspace at a role no higher than the server's), and room for
+ * the ingress share of concurrency. Called from the server schema's refinement.
+ */
+export declare function validateIngressAgainstServer({ server, ctx }: {
+    server: ServerForIngress;
+    ctx: z.RefinementCtx;
+}): void;
+export {};

package/dist/manifest-next-ingress.js

@@ -0,0 +1,187 @@
+import { storageScopesSchema } from '@sequenceholdings/storage';
+import { z } from 'zod';
+import { isPrefixApiCapabilityEntry } from './manifest-static.js';
+import { artifactNextAuditCapabilitySchema, boundedRef, dataReadRef, ormOperationRef, reachShape, serviceAccountRef, } from './manifest-next-reach.js';
+import { INGRESS_ROUTE_METHODS, ingressRouteTemplatesOverlap, parseRouteTemplate, } from './server/ingress-routes.js';
+import { INGRESS_CLIENT_ADDRESS_HEADERS, isPrivateRequestHeader } from './tunnel/reserved-headers.js';
+/**
+ * `server.ingress`: opt-in front doors for callers that are not Atlas users (design §(a)). Each
+ * external ingress names an identity provider from the environment's catalog, the service account
+ * its callers act as, the real routes they call, and capabilities that must sit inside the
+ * server's own. Nothing environment-specific (issuer, audience, origins) belongs here.
+ */
+export const ARTIFACT_NEXT_MAX_INGRESSES = 4;
+export const ARTIFACT_NEXT_MAX_INGRESS_ROUTES = 64;
+export const ARTIFACT_NEXT_INGRESS_DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+export const ARTIFACT_NEXT_INGRESS_MAX_BODY_BYTES = 32 * 1024 * 1024;
+/** The content types an ingress route may return. No HTML, JavaScript or SVG, ever. */
+export const ARTIFACT_NEXT_INGRESS_RESPONSE_TYPES = [
+    'application/json', 'application/problem+json', 'application/pdf', 'application/zip',
+    'image/png', 'image/jpeg', 'image/webp', 'text/csv', 'application/octet-stream',
+];
+/** Verified principal fields the broker may bind into an evidence operation's variables. */
+export const ARTIFACT_NEXT_INGRESS_EVIDENCE_SOURCES = [
+    'subject', 'email', 'authTime', 'amr', 'client.ip', 'client.userAgent', 'issuer',
+];
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const STORAGE_ROLE_RANK = { viewer: 0, editor: 1, admin: 2 };
+export const artifactNextIngressIdSchema = z.string().regex(/^[a-z][a-z0-9-]{0,31}$/, 'Ingress ids are lowercase, start with a letter, and are at most 32 characters');
+export const artifactNextIngressProviderRefSchema = z.string().regex(/^[a-z][a-z0-9-]{0,63}$/, 'Identity provider references are lowercase catalog keys');
+/** Seconds since the caller's interactive sign-in a step requires; 0 means no requirement. */
+const freshAuthSeconds = z.number().int().refine((value) => value === 0 || (value >= 60 && value <= 86_400), 'fresh_auth_seconds is 0 (none) or between 60 and 86400');
+// Framework-internal and routing-override headers: declaring one would make it a CORS-allowed
+// request header that can steer Next.js (middleware subrequests, data requests), override the
+// method or URL, or forge the request id the platform generates.
+const INGRESS_FRAMEWORK_HEADER_PREFIX = /^x-(?:middleware-|nextjs-|invoke-|vercel-|now-)/;
+const INGRESS_ROUTING_OVERRIDE_HEADERS = new Set([
+    'x-http-method-override', 'x-method-override', 'x-original-url', 'x-rewrite-url', 'x-original-method',
+    'x-request-id', 'x-forwarded', 'x-real-ip',
+]);
+const ingressHeaderName = z.string().regex(/^x-[a-z0-9-]{1,48}$/, 'Ingress headers are lowercase x- names of at most 50 characters').refine((name) => !isPrivateRequestHeader(name) && !INGRESS_CLIENT_ADDRESS_HEADERS.includes(name), 'Ingress headers cannot use a name the platform proxy strips or owns').refine((name) => !INGRESS_FRAMEWORK_HEADER_PREFIX.test(name) && !INGRESS_ROUTING_OVERRIDE_HEADERS.has(name), 'Ingress headers cannot use a framework-internal or routing-override name');
+function unique(values) {
+    return new Set(values).size === values.length;
+}
+export const artifactNextIngressRouteSchema = z.strictObject({
+    path: z.string().refine((template) => parseRouteTemplate(template) !== null, 'Ingress routes are exact /api/ paths: literal segments or whole-segment {name} placeholders, no wildcards, %, queries or trailing slash'),
+    methods: z.array(z.enum(INGRESS_ROUTE_METHODS)).min(1).max(INGRESS_ROUTE_METHODS.length).refine(unique, 'Route methods must be unique'),
+    fresh_auth_seconds: freshAuthSeconds.optional(),
+    max_body_bytes: z.number().int().min(1).max(ARTIFACT_NEXT_INGRESS_MAX_BODY_BYTES).default(ARTIFACT_NEXT_INGRESS_DEFAULT_MAX_BODY_BYTES),
+    responses: z.array(z.enum(ARTIFACT_NEXT_INGRESS_RESPONSE_TYPES)).min(1).max(ARTIFACT_NEXT_INGRESS_RESPONSE_TYPES.length)
+        .refine(unique, 'Route response types must be unique').default(['application/json']),
+}).superRefine((route, ctx) => {
+    if ((route.fresh_auth_seconds ?? 0) > 0 && route.methods.some((method) => !MUTATING_METHODS.has(method))) {
+        ctx.addIssue({ code: 'custom', path: ['fresh_auth_seconds'], message: 'fresh_auth_seconds applies only to mutating methods; declare the read twin as its own route' });
+    }
+});
+const evidenceEntrySchema = z.strictObject({
+    bind: z.record(z.string().regex(/^[_A-Za-z][_0-9A-Za-z]{0,63}$/, 'Evidence binds GraphQL variable names'), z.enum(ARTIFACT_NEXT_INGRESS_EVIDENCE_SOURCES))
+        .refine((bind) => Object.keys(bind).length <= 16, 'At most 16 bound variables per operation').default({}),
+    fresh_auth_seconds: freshAuthSeconds.optional(),
+}).refine((entry) => Object.keys(entry.bind).length > 0 || (entry.fresh_auth_seconds ?? 0) > 0, 'An evidence entry binds at least one variable or requires fresh authentication');
+// Unlike the app-wide grammar, an ingress write names each ORM operation: a table ref would let an
+// external caller run any mutation the ORM role allows over that table, and evidence binding and
+// freshness are keyed per named operation (D28; design C-3, "by name, no globs").
+const ingressDataWriteRef = boundedRef.refine((ref) => ormOperationRef.test(ref), 'Ingress ORM writes name each operation: namespace/ops/Operation');
+const ingressCapabilitiesSchema = z.strictObject({
+    storage: storageScopesSchema.optional(),
+    data: z.strictObject({
+        read: z.array(dataReadRef).max(256).default([]),
+        write: z.array(ingressDataWriteRef).max(256).default([]),
+    }).prefault({}),
+    api: reachShape.api,
+    functions: reachShape.functions,
+    audit: artifactNextAuditCapabilitySchema.optional(),
+    processes: z.never({ error: 'Ingress capabilities cannot start Lattice processes' }).optional(),
+}).prefault({});
+/** Whole-segment `*` only, and never a form `apiCapabilityPathAllowed` would treat as a prefix. */
+function ingressApiEntryProblem(entry) {
+    if (entry.endsWith('/') || isPrefixApiCapabilityEntry(entry)) {
+        return 'Ingress API capabilities cannot end in / or /*: a prefix would admit every future path below it';
+    }
+    if (entry.split('/').some((part) => part.includes('*') && part !== '*'))
+        return 'Ingress API capabilities use whole-segment * only';
+    return null;
+}
+export const artifactNextExternalIngressSchema = z.strictObject({
+    id: artifactNextIngressIdSchema,
+    provider: artifactNextIngressProviderRefSchema,
+    service_account: serviceAccountRef,
+    headers: z.array(ingressHeaderName).max(8).refine(unique, 'Ingress headers must be unique').default([]),
+    capabilities: ingressCapabilitiesSchema,
+    evidence: z.record(z.string().regex(ormOperationRef, 'Evidence keys are ORM operation references (namespace/ops/Operation)'), evidenceEntrySchema)
+        .refine((evidence) => Object.keys(evidence).length <= 256, 'At most 256 evidence operations').default({}),
+    routes: z.array(artifactNextIngressRouteSchema).min(1).max(ARTIFACT_NEXT_MAX_INGRESS_ROUTES),
+}).superRefine((ingress, ctx) => {
+    const seen = new Map();
+    for (const [index, route] of ingress.routes.entries()) {
+        const parsed = parseRouteTemplate(route.path);
+        if (!parsed)
+            continue;
+        for (const method of route.methods) {
+            const declared = seen.get(method) ?? [];
+            if (declared.some((other) => other.template === parsed.template)) {
+                ctx.addIssue({ code: 'custom', path: ['routes', index, 'methods'], message: `${method} ${route.path} is declared twice` });
+            }
+            else if (declared.some((other) => ingressRouteTemplatesOverlap({ left: other, right: parsed }))) {
+                ctx.addIssue({ code: 'custom', path: ['routes', index, 'path'], message: `${method} ${route.path} overlaps another declared route; one request must match one route` });
+            }
+            seen.set(method, [...declared, parsed]);
+        }
+    }
+    for (const access of ['read', 'write']) {
+        for (const [index, entry] of ingress.capabilities.api[access].entries()) {
+            const problem = ingressApiEntryProblem(entry);
+            if (problem)
+                ctx.addIssue({ code: 'custom', path: ['capabilities', 'api', access, index], message: problem });
+        }
+    }
+    for (const operation of Object.keys(ingress.evidence)) {
+        if (!ingress.capabilities.data.write.includes(operation)) {
+            ctx.addIssue({ code: 'custom', path: ['evidence', operation], message: 'Evidence operations must be listed in the ingress capabilities.data.write' });
+        }
+    }
+});
+export const artifactNextIngressSchema = z.strictObject({
+    external: z.array(artifactNextExternalIngressSchema).min(1).max(ARTIFACT_NEXT_MAX_INGRESSES),
+});
+function requireMembers({ ctx, path, entries, allowed, label }) {
+    for (const [index, entry] of entries.entries()) {
+        if (!allowed.includes(entry))
+            ctx.addIssue({ code: 'custom', path: [...path, index], message: `${entry} must also be declared in server.capabilities.${label}` });
+    }
+}
+/**
+ * Cross-field rules between `server.ingress` and the rest of `server`: one ingress per provider,
+ * a service account distinct from the app's, capabilities inside the server's own (verbatim list
+ * membership; for storage, the same workspace at a role no higher than the server's), and room for
+ * the ingress share of concurrency. Called from the server schema's refinement.
+ */
+export function validateIngressAgainstServer({ server, ctx }) {
+    const external = server.ingress?.external;
+    if (!external)
+        return;
+    if (server.resources.concurrency * server.resources.max_instances < 2) {
+        ctx.addIssue({ code: 'custom', path: ['resources'], message: 'An app that declares an ingress needs concurrency × max_instances ≥ 2, so the ingress share never takes the whole app' });
+    }
+    const ids = new Set();
+    const providers = new Set();
+    const serviceAccounts = new Set();
+    for (const [index, ingress] of external.entries()) {
+        const at = ['ingress', 'external', index];
+        if (ids.has(ingress.id))
+            ctx.addIssue({ code: 'custom', path: [...at, 'id'], message: `Ingress id ${ingress.id} is declared twice` });
+        ids.add(ingress.id);
+        if (providers.has(ingress.provider))
+            ctx.addIssue({ code: 'custom', path: [...at, 'provider'], message: `At most one ingress per identity provider; ${ingress.provider} is used twice` });
+        providers.add(ingress.provider);
+        // A shared account would carry the union of both ingresses' platform grants, leaving the
+        // per-ingress split to principal.ingress, which is a routing label and not an authorization attribute.
+        if (serviceAccounts.has(ingress.service_account)) {
+            ctx.addIssue({ code: 'custom', path: [...at, 'service_account'], message: 'Each ingress needs its own service account' });
+        }
+        serviceAccounts.add(ingress.service_account);
+        // These are reference strings, so a UUID here and a slug on the server for the same account pass.
+        // Atlas's deploy preflight resolves both to account ids and refuses an ingress account equal to
+        // the app's or to another ingress's (preflightArtifactAttachments).
+        if (server.service_account !== undefined && ingress.service_account === server.service_account) {
+            ctx.addIssue({ code: 'custom', path: [...at, 'service_account'], message: 'An ingress service account must differ from server.service_account' });
+        }
+        const own = ingress.capabilities;
+        const declared = server.capabilities;
+        const capabilities = [...at, 'capabilities'];
+        requireMembers({ ctx, path: [...capabilities, 'data', 'read'], entries: own.data.read, allowed: declared.data.read, label: 'data.read' });
+        requireMembers({ ctx, path: [...capabilities, 'data', 'write'], entries: own.data.write, allowed: declared.data.write, label: 'data.write' });
+        requireMembers({ ctx, path: [...capabilities, 'api', 'read'], entries: own.api.read, allowed: declared.api.read, label: 'api.read' });
+        requireMembers({ ctx, path: [...capabilities, 'api', 'write'], entries: own.api.write, allowed: declared.api.write, label: 'api.write' });
+        requireMembers({ ctx, path: [...capabilities, 'functions', 'invoke'], entries: own.functions.invoke, allowed: declared.functions.invoke, label: 'functions.invoke' });
+        for (const [workspace, role] of Object.entries(own.storage ?? {})) {
+            const ceiling = declared.storage?.[workspace];
+            if (ceiling === undefined || STORAGE_ROLE_RANK[role] > STORAGE_ROLE_RANK[ceiling]) {
+                ctx.addIssue({ code: 'custom', path: [...capabilities, 'storage', workspace], message: 'Ingress storage must name a server.capabilities.storage workspace at a role no higher than the server\'s' });
+            }
+        }
+        if (own.audit && own.audit.service !== declared.audit?.service) {
+            ctx.addIssue({ code: 'custom', path: [...capabilities, 'audit', 'service'], message: 'Ingress audit service must equal server.capabilities.audit.service' });
+        }
+    }
+}

package/dist/manifest-next-reach.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const boundedRef: z.ZodString;
+export declare const serviceAccountRef: z.ZodString;
+export declare const apiPath: z.ZodString;
+export declare const ormTableRef: RegExp;
+export declare const ormOperationRef: RegExp;
+export declare const dataReadRef: z.ZodString;
+export declare const dataWriteRef: z.ZodString;
+export declare const latticeProcessRef: z.ZodString;
+export declare const reachShape: {
+    storage: z.ZodOptional<z.ZodRecord<z.ZodUUID, z.ZodEnum<{
+        viewer: "viewer";
+        editor: "editor";
+        admin: "admin";
+    }>>>;
+    data: z.ZodPrefault<z.ZodObject<{
+        read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    api: z.ZodPrefault<z.ZodObject<{
+        read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    functions: z.ZodPrefault<z.ZodObject<{
+        invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    processes: z.ZodPrefault<z.ZodObject<{
+        start: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        act: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+};
+/**
+ * Where the server's audit events (`client.audit.record`) go: an Atlas audit service id. Every
+ * application may record under `artifact_studio`; Atlas admits a first-party service, such as
+ * `application_portal`, only for the projects it registers for it. Server-only: browsers can't audit.
+ */
+export declare const artifactNextAuditCapabilitySchema: z.ZodObject<{
+    service: z.ZodString;
+}, z.core.$strict>;

package/dist/manifest-next-reach.js

@@ -0,0 +1,48 @@
+import { storageScopesSchema } from '@sequenceholdings/storage';
+import { z } from 'zod';
+// Reach primitives shared by the app-wide capability blocks and the external ingress block.
+export const boundedRef = z.string().min(1).max(255).regex(/^[a-zA-Z0-9][a-zA-Z0-9_./:-]*$/).refine((value) => value.split('/').every((part) => part !== '' && part !== '.' && part !== '..'), 'Resource references cannot contain empty segments or traversal');
+export const serviceAccountRef = z.string().regex(/^([a-z][a-z0-9-]{1,98}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/);
+export const apiPath = z.string().min(1).max(512).refine((value) => {
+    if (!value.startsWith('/api/') || value === '/api/' || value === '/api/*')
+        return false;
+    if (/[\\%?#\s\x00-\x1f]/.test(value))
+        return false;
+    return value.split('/').slice(1).every((part, index, parts) => part !== '.' && part !== '..' && (part !== '' || index === parts.length - 1));
+}, 'API capability paths must be scoped below /api/ without encoded paths, traversal, queries, or fragments');
+// ORM references are what a delegated data token covers (orm-data-plane checkDataTokenScope):
+// a query needs namespace/table for every table it reads, and a mutation needs its
+// namespace/ops/Operation (or table coverage). Any other shape can never match, so it is
+// a typo to report here rather than a 403 at request time. The patterns mirror the ORM's
+// NAMESPACE_PATTERN, IDENTIFIER_PATTERN and GraphQL operation names; they are kept local so
+// browser code that parses manifests does not load the ORM package. platformUsers is the
+// ORM's built-in platform-user entity (PLATFORM_USER_TABLE), a logical key outside the
+// identifier pattern that queries traversing user relations read.
+export const ormTableRef = /^[a-z][a-z0-9_]{0,40}\/(?:[a-z][a-z0-9_]{0,62}|platformUsers)$/;
+export const ormOperationRef = /^[a-z][a-z0-9_]{0,40}\/ops\/[_A-Za-z][_0-9A-Za-z]*$/;
+export const dataReadRef = boundedRef.refine((ref) => ormTableRef.test(ref), 'ORM read references use namespace/table');
+export const dataWriteRef = boundedRef.refine((ref) => ormTableRef.test(ref) || ormOperationRef.test(ref), 'ORM write references use namespace/ops/Operation or namespace/table');
+export const latticeProcessRef = z.string().min(2).max(128).regex(/^[A-Za-z0-9._-]+$/, 'Process references are Lattice process ids');
+export const reachShape = {
+    storage: storageScopesSchema.optional(),
+    data: z.strictObject({ read: z.array(dataReadRef).max(256).default([]), write: z.array(dataWriteRef).max(256).default([]) }).prefault({}),
+    api: z.strictObject({ read: z.array(apiPath).max(256).default([]), write: z.array(apiPath).max(256).default([]) }).prefault({}),
+    functions: z.strictObject({ invoke: z.array(boundedRef).max(256).default([]) }).prefault({}),
+    // `start`: processes the server may start runs of. `read`: processes whose runs, template and
+    // the user's own steps it may read. `act`: processes whose human steps it may advance and
+    // reassign, and whose runs' viewers it may manage. All name exact process ids; the user's own
+    // Invoker / Viewer / Advancer / Owner grants decide what happens.
+    processes: z.strictObject({
+        start: z.array(latticeProcessRef).max(256).default([]),
+        read: z.array(latticeProcessRef).max(256).default([]),
+        act: z.array(latticeProcessRef).max(256).default([]),
+    }).prefault({}),
+};
+/**
+ * Where the server's audit events (`client.audit.record`) go: an Atlas audit service id. Every
+ * application may record under `artifact_studio`; Atlas admits a first-party service, such as
+ * `application_portal`, only for the projects it registers for it. Server-only: browsers can't audit.
+ */
+export const artifactNextAuditCapabilitySchema = z.strictObject({
+    service: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/, 'Audit services are Atlas audit service ids, such as artifact_studio'),
+});