@sequenceholdings/artifact-studio 0.5.0 → 0.6.2

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();
+    // verifyAnyArtifactContext canonicalises `path` (canonicalizeIngressPath) before comparing it.
+    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/ingress-control-contract.d.ts

@@ -0,0 +1,272 @@
+import { z } from 'zod';
+/** Snapshot bodies above this size are refused by the gateway. */
+export declare const INGRESS_SNAPSHOT_MAX_BYTES: number;
+export declare const INGRESS_AUDIT_BATCH_MAX_EVENTS = 500;
+/** The pass lifetime cap a catalog entry may set (`maxPassSeconds`). */
+export declare const INGRESS_MAX_PASS_SECONDS = 900;
+export declare const INGRESS_IDP_ALGORITHMS: readonly ["RS256", "ES256", "PS256"];
+/** A canonical ingress host: lowercase `ingress-<24 hex>.<runtime domain>`, no port, no trailing dot. */
+export declare const ingressHostSchema: z.ZodString;
+/** Kid of a key that signs external (v2) contexts; Atlas's context key id grammar, with the prefix. */
+export declare const ingressExternalKidSchema: z.ZodString;
+/** `"<METHOD> <template>"`, as `matchIngressRoute` names a route. */
+export declare const ingressRouteIdSchema: z.ZodString;
+/** Where an ingress host proxies. `development` is honoured only by a gateway with APP_ENV=development. */
+export declare const ingressSnapshotTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"published">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"development">;
+    sessionId: z.ZodString;
+}, z.core.$strict>], "kind">;
+export declare const ingressSnapshotIngressSchema: z.ZodObject<{
+    id: z.ZodString;
+    provider: z.ZodString;
+    allowedOrigins: z.ZodArray<z.ZodString>;
+    headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    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>>;
+    epoch: z.ZodNumber;
+}, z.core.$strict>;
+export declare const ingressSnapshotHostSchema: z.ZodObject<{
+    host: z.ZodString;
+    projectId: z.ZodString;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"published">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"development">;
+        sessionId: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    ingresses: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        provider: z.ZodString;
+        allowedOrigins: z.ZodArray<z.ZodString>;
+        headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        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>>;
+        epoch: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** The non-secret per-provider summary the gateway's exchange precheck needs. */
+export declare const ingressSnapshotProviderSchema: z.ZodObject<{
+    issuer: z.ZodString;
+    algorithms: z.ZodArray<z.ZodEnum<{
+        RS256: "RS256";
+        ES256: "ES256";
+        PS256: "PS256";
+    }>>;
+}, z.core.$strict>;
+export declare const ingressSnapshotSchema: z.ZodObject<{
+    policyEpoch: z.ZodNumber;
+    hosts: z.ZodArray<z.ZodObject<{
+        host: z.ZodString;
+        projectId: z.ZodString;
+        target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"published">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"development">;
+            sessionId: z.ZodString;
+        }, z.core.$strict>], "kind">;
+        ingresses: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            provider: z.ZodString;
+            allowedOrigins: z.ZodArray<z.ZodString>;
+            headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            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>>;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    providers: z.ZodRecord<z.ZodString, z.ZodObject<{
+        issuer: z.ZodString;
+        algorithms: z.ZodArray<z.ZodEnum<{
+            RS256: "RS256";
+            ES256: "ES256";
+            PS256: "PS256";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type IngressSnapshot = z.infer<typeof ingressSnapshotSchema>;
+export type IngressSnapshotHost = z.infer<typeof ingressSnapshotHostSchema>;
+export declare const ingressExchangeRequestSchema: z.ZodObject<{
+    host: z.ZodString;
+    ingress: z.ZodString;
+    origin: z.ZodNullable<z.ZodString>;
+    token: z.ZodString;
+    clientIp: z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>;
+    userAgent: z.ZodString;
+    requestId: z.ZodUUID;
+}, z.core.$strict>;
+export type IngressExchangeRequest = z.infer<typeof ingressExchangeRequestSchema>;
+export declare const ingressExchangeResponseSchema: z.ZodObject<{
+    principal: z.ZodObject<{
+        email: z.ZodString;
+        subject: z.ZodString;
+        authTime: z.ZodNullable<z.ZodNumber>;
+        amr: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        issuer: z.ZodString;
+        clientId: z.ZodString;
+        emailVerified: z.ZodLiteral<true>;
+        tokenIssuedAt: z.ZodNumber;
+    }, z.core.$strict>;
+    bindingEpoch: z.ZodNumber;
+    passTtlSeconds: z.ZodNumber;
+}, z.core.$strict>;
+export type IngressExchangeResponse = z.infer<typeof ingressExchangeResponseSchema>;
+export declare const ingressGrantRequestSchema: z.ZodObject<{
+    host: z.ZodString;
+    ingress: z.ZodString;
+    provider: z.ZodString;
+    subjectHash: z.ZodString;
+    tokenIssuedAt: z.ZodNumber;
+    passJti: z.ZodUUID;
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+    }>;
+    routeId: z.ZodString;
+}, z.core.$strict>;
+export type IngressGrantRequest = z.infer<typeof ingressGrantRequestSchema>;
+export declare const ingressGrantResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"published">;
+    deploymentId: z.ZodString;
+    frameworkBuildId: z.ZodString;
+    upstreamUrl: z.ZodString;
+    upstreamAudience: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    serviceAccountId: z.ZodString;
+    resources: z.ZodObject<{
+        concurrency: z.ZodNumber;
+        max_instances: z.ZodNumber;
+        timeout_seconds: z.ZodNumber;
+    }, z.core.$strict>;
+    trustedExternalKids: z.ZodArray<z.ZodString>;
+    externalCapable: z.ZodLiteral<true>;
+    policyEpoch: z.ZodNumber;
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"development">;
+    devSessionId: z.ZodString;
+    deploymentId: z.ZodNull;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    serviceAccountId: z.ZodString;
+    resources: z.ZodObject<{
+        concurrency: z.ZodNumber;
+        max_instances: z.ZodNumber;
+        timeout_seconds: z.ZodNumber;
+    }, z.core.$strict>;
+    trustedExternalKids: z.ZodArray<z.ZodString>;
+    externalCapable: z.ZodLiteral<true>;
+    policyEpoch: z.ZodNumber;
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>], "mode">;
+export type IngressGrantResponse = z.infer<typeof ingressGrantResponseSchema>;
+/**
+ * Logout through a pass the gateway verified (design T22, R2). There is deliberately no `at`:
+ * Atlas takes the revocation time from its own clock (`T = now`, "every IdP token issued at or
+ * before now") and applies `revoked_before = greatest(revoked_before, T)`, so a control-token
+ * holder can never date a revocation into the future and lock a subject out past their next
+ * sign-in. It is monotonic and never unblocks. `host`, `ingress` and `passJti` attest the pass the
+ * gateway verified, so Atlas can audit the revoke and refuse one for a provider the host's ingress
+ * does not use; `tokenIssuedAt` is that pass's IdP `iat`.
+ */
+export declare const ingressRevokeRequestSchema: z.ZodObject<{
+    host: z.ZodString;
+    ingress: z.ZodString;
+    provider: z.ZodString;
+    subject: z.ZodString;
+    passJti: z.ZodUUID;
+    tokenIssuedAt: z.ZodNumber;
+}, z.core.$strict>;
+export type IngressRevokeRequest = z.infer<typeof ingressRevokeRequestSchema>;
+export declare const ingressAuditEventSchema: z.ZodObject<{
+    ts: z.ZodNumber;
+    host: z.ZodString;
+    ingress: z.ZodNullable<z.ZodString>;
+    reason: z.ZodString;
+    status: z.ZodNumber;
+    subjectHash: z.ZodOptional<z.ZodString>;
+    clientIp: z.ZodNullable<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>>;
+    passId: z.ZodOptional<z.ZodUUID>;
+}, z.core.$strict>;
+export declare const ingressAuditBatchSchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodObject<{
+        ts: z.ZodNumber;
+        host: z.ZodString;
+        ingress: z.ZodNullable<z.ZodString>;
+        reason: z.ZodString;
+        status: z.ZodNumber;
+        subjectHash: z.ZodOptional<z.ZodString>;
+        clientIp: z.ZodNullable<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>>;
+        passId: z.ZodOptional<z.ZodUUID>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type IngressAuditEvent = z.infer<typeof ingressAuditEventSchema>;
+export type IngressAuditBatch = z.infer<typeof ingressAuditBatchSchema>;

package/dist/server/ingress-control-contract.js

@@ -0,0 +1,196 @@
+import { z } from 'zod';
+import { artifactNextExternalIngressSchema, artifactNextIngressIdSchema, artifactNextIngressProviderRefSchema, } from '../manifest-next-ingress.js';
+import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX, artifactExternalPrincipalSchema, artifactIpAddressSchema, artifactOriginSchema, } from './request-context.js';
+import { INGRESS_ROUTE_METHODS, parseRouteTemplate } from './ingress-routes.js';
+/**
+ * Bodies of the gateway↔Atlas control routes for the external ingress (design "First call",
+ * "Steady state", §(e), §(g) "Gateway denials"). Schemas only: Atlas's `control/ingress-*` routes,
+ * the gateway and the development-mode tooling all import these, and nothing redefines them.
+ */
+const id = z.string().min(1).max(255);
+const epochSeconds = z.number().int().nonnegative();
+const counter = z.number().int().nonnegative();
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, 'Expected a lowercase SHA-256 digest');
+/** Snapshot bodies above this size are refused by the gateway. */
+export const INGRESS_SNAPSHOT_MAX_BYTES = 1024 * 1024;
+export const INGRESS_AUDIT_BATCH_MAX_EVENTS = 500;
+/** The pass lifetime cap a catalog entry may set (`maxPassSeconds`). */
+export const INGRESS_MAX_PASS_SECONDS = 900;
+export const INGRESS_IDP_ALGORITHMS = ['RS256', 'ES256', 'PS256'];
+/** A canonical ingress host: lowercase `ingress-<24 hex>.<runtime domain>`, no port, no trailing dot. */
+export const ingressHostSchema = z.string().max(253).regex(/^ingress-[a-f0-9]{24}(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/, 'Expected a canonical ingress host');
+/** Kid of a key that signs external (v2) contexts; Atlas's context key id grammar, with the prefix. */
+export const ingressExternalKidSchema = z.string().max(64).regex(/^[A-Za-z0-9._-]+$/)
+    .refine((kid) => kid.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX) && kid.length > ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX.length, 'External context kids carry the external- prefix');
+/** `"<METHOD> <template>"`, as `matchIngressRoute` names a route. */
+export const ingressRouteIdSchema = z.string().max(520).refine((routeId) => {
+    const separator = routeId.indexOf(' ');
+    return INGRESS_ROUTE_METHODS.includes(routeId.slice(0, separator)) &&
+        parseRouteTemplate(routeId.slice(separator + 1)) !== null;
+}, 'Expected "<METHOD> <route template>"');
+// GET control/ingress-snapshot -----------------------------------------------------------------
+/** Where an ingress host proxies. `development` is honoured only by a gateway with APP_ENV=development. */
+export const ingressSnapshotTargetSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('published') }),
+    z.strictObject({ kind: z.literal('development'), sessionId: id }),
+]);
+export const ingressSnapshotIngressSchema = z.strictObject({
+    id: artifactNextIngressIdSchema,
+    provider: artifactNextIngressProviderRefSchema,
+    /** The live binding's origins, already narrowed to the catalog's. */
+    allowedOrigins: z.array(artifactOriginSchema).max(64),
+    headers: artifactNextExternalIngressSchema.shape.headers,
+    /** As declared in the manifest the target serves. */
+    routes: artifactNextExternalIngressSchema.shape.routes,
+    /** The binding's write counter; a cache-buster only. */
+    epoch: counter,
+});
+export const ingressSnapshotHostSchema = z.strictObject({
+    host: ingressHostSchema,
+    projectId: id,
+    target: ingressSnapshotTargetSchema,
+    ingresses: z.array(ingressSnapshotIngressSchema).min(1).max(4),
+}).superRefine((entry, ctx) => {
+    if (new Set(entry.ingresses.map((ingress) => ingress.id)).size !== entry.ingresses.length) {
+        ctx.addIssue({ code: 'custom', path: ['ingresses'], message: 'Ingress ids must be unique per host' });
+    }
+    // Loopback http origins exist only for development catalog entries (design C-8); a published
+    // host never carries one, whatever the catalog loader let through.
+    if (entry.target.kind !== 'published')
+        return;
+    for (const [index, ingress] of entry.ingresses.entries()) {
+        for (const [originIndex, origin] of ingress.allowedOrigins.entries()) {
+            if (!origin.startsWith('https://')) {
+                ctx.addIssue({ code: 'custom', path: ['ingresses', index, 'allowedOrigins', originIndex], message: 'A published ingress host allows https origins only' });
+            }
+        }
+    }
+});
+/** The non-secret per-provider summary the gateway's exchange precheck needs. */
+export const ingressSnapshotProviderSchema = z.strictObject({
+    issuer: z.string().min(1).max(2048),
+    algorithms: z.array(z.enum(INGRESS_IDP_ALGORITHMS)).min(1).max(INGRESS_IDP_ALGORITHMS.length),
+});
+export const ingressSnapshotSchema = z.strictObject({
+    policyEpoch: counter,
+    hosts: z.array(ingressSnapshotHostSchema).max(10_000),
+    providers: z.record(artifactNextIngressProviderRefSchema, ingressSnapshotProviderSchema),
+}).superRefine((snapshot, ctx) => {
+    const hosts = new Set();
+    for (const [index, entry] of snapshot.hosts.entries()) {
+        if (hosts.has(entry.host))
+            ctx.addIssue({ code: 'custom', path: ['hosts', index, 'host'], message: 'Snapshot hosts must be unique' });
+        hosts.add(entry.host);
+        for (const [ingressIndex, ingress] of entry.ingresses.entries()) {
+            if (!Object.hasOwn(snapshot.providers, ingress.provider)) {
+                ctx.addIssue({ code: 'custom', path: ['hosts', index, 'ingresses', ingressIndex, 'provider'], message: 'Every ingress provider needs a snapshot provider summary' });
+            }
+        }
+    }
+});
+// POST control/ingress-exchange ----------------------------------------------------------------
+export const ingressExchangeRequestSchema = z.strictObject({
+    host: ingressHostSchema,
+    ingress: artifactNextIngressIdSchema,
+    /** The request's `Origin`; null for a non-browser caller. Atlas requires it within the binding's origins. */
+    origin: artifactOriginSchema.nullable(),
+    /** The identity provider's access token, without the `Bearer ` scheme. */
+    token: z.string().min(1).max(8192),
+    /** The single edge-verified `CF-Connecting-IP`. */
+    clientIp: artifactIpAddressSchema,
+    userAgent: artifactExternalPrincipalSchema.shape.client.shape.userAgent,
+    /** Gateway-generated; never client-supplied. */
+    requestId: z.uuid(),
+});
+export const ingressExchangeResponseSchema = z.strictObject({
+    /** As Atlas verified it. `tokenIssuedAt` is the IdP `iat`, which revocation compares. */
+    principal: artifactExternalPrincipalSchema.pick({
+        issuer: true, subject: true, clientId: true, email: true, emailVerified: true, authTime: true, amr: true, tokenIssuedAt: true,
+    }).strict(),
+    bindingEpoch: counter,
+    passTtlSeconds: z.number().int().min(1).max(INGRESS_MAX_PASS_SECONDS),
+});
+// POST control/ingress-grant -------------------------------------------------------------------
+export const ingressGrantRequestSchema = z.strictObject({
+    host: ingressHostSchema,
+    ingress: artifactNextIngressIdSchema,
+    provider: artifactNextIngressProviderRefSchema,
+    /** `sha256(subject)`, lowercase hex. */
+    subjectHash: sha256Hex,
+    tokenIssuedAt: epochSeconds,
+    passJti: z.uuid(),
+    method: z.enum(INGRESS_ROUTE_METHODS),
+    routeId: ingressRouteIdSchema,
+}).superRefine((request, ctx) => {
+    if (!request.routeId.startsWith(`${request.method} `))
+        ctx.addIssue({ code: 'custom', path: ['routeId'], message: 'routeId must name the request method' });
+});
+const grantCommon = {
+    projectId: id,
+    environment: id,
+    /** The ingress's own service account: `ingressServiceAccounts[ingress]`, never the app's. */
+    serviceAccountId: id,
+    resources: z.strictObject({
+        concurrency: z.number().int().min(1).max(80),
+        max_instances: z.number().int().min(1).max(100),
+        timeout_seconds: z.number().int().min(1).max(300),
+    }),
+    /** External kids the target trusts; the gateway refuses to sign (503) unless its current kid is listed. */
+    trustedExternalKids: z.array(ingressExternalKidSchema).min(1).max(4),
+    externalCapable: z.literal(true),
+    policyEpoch: counter,
+    expiresAt: z.number().int().positive(),
+};
+export const ingressGrantResponseSchema = z.discriminatedUnion('mode', [
+    z.strictObject({
+        ...grantCommon,
+        mode: z.literal('published'),
+        deploymentId: id,
+        frameworkBuildId: artifactNextFrameworkBuildIdSchema,
+        upstreamUrl: z.string().url(),
+        upstreamAudience: z.string().url().optional(),
+    }),
+    /** Local development only: the gateway proxies over the session's tunnel instead of an upstream URL. */
+    z.strictObject({
+        ...grantCommon,
+        mode: z.literal('development'),
+        devSessionId: id,
+        deploymentId: z.null(),
+    }),
+]);
+// POST control/ingress-revoke ------------------------------------------------------------------
+/**
+ * Logout through a pass the gateway verified (design T22, R2). There is deliberately no `at`:
+ * Atlas takes the revocation time from its own clock (`T = now`, "every IdP token issued at or
+ * before now") and applies `revoked_before = greatest(revoked_before, T)`, so a control-token
+ * holder can never date a revocation into the future and lock a subject out past their next
+ * sign-in. It is monotonic and never unblocks. `host`, `ingress` and `passJti` attest the pass the
+ * gateway verified, so Atlas can audit the revoke and refuse one for a provider the host's ingress
+ * does not use; `tokenIssuedAt` is that pass's IdP `iat`.
+ */
+export const ingressRevokeRequestSchema = z.strictObject({
+    host: ingressHostSchema,
+    ingress: artifactNextIngressIdSchema,
+    provider: artifactNextIngressProviderRefSchema,
+    subject: id,
+    passJti: z.uuid(),
+    tokenIssuedAt: epochSeconds,
+});
+// POST control/ingress-audit -------------------------------------------------------------------
+export const ingressAuditEventSchema = z.strictObject({
+    /** Epoch milliseconds when the gateway refused the request. */
+    ts: z.number().int().nonnegative(),
+    host: ingressHostSchema,
+    /** Null when the refusal came before an ingress was known (edge header, unknown route). */
+    ingress: artifactNextIngressIdSchema.nullable(),
+    reason: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/, 'Expected a snake_case reason'),
+    status: z.number().int().min(400).max(599),
+    subjectHash: sha256Hex.optional(),
+    /** Null when the request carried no single valid `CF-Connecting-IP`. */
+    clientIp: artifactIpAddressSchema.nullable(),
+    passId: z.uuid().optional(),
+});
+export const ingressAuditBatchSchema = z.strictObject({
+    events: z.array(ingressAuditEventSchema).min(1).max(INGRESS_AUDIT_BATCH_MAX_EVENTS),
+});

package/dist/server/ingress-routes.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Inbound route grammar for an Artifact Next external ingress (design §(a) "Paths").
+ *
+ * One module owns the three steps every component must agree on: the gateway canonicalises the
+ * raw request target and matches it, Atlas re-matches the signed path on the active manifest, and
+ * the SDK binds the context to the route it serves. The static wildcard matcher
+ * (`manifest-static.ts`) is deliberately not used: it prefix-matches, and a route must not.
+ */
+export declare const INGRESS_ROUTE_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
+export type IngressRouteMethod = typeof INGRESS_ROUTE_METHODS[number];
+/** Longest raw request target the canonicaliser looks at, the signed context path's own cap. */
+export declare const MAX_INGRESS_PATH_LENGTH = 8192;
+export interface CanonicalIngressPath {
+    /** The canonical pathname, the only part routes match. */
+    path: string;
+    /** The raw query string without its `?`, kept verbatim; `''` when there is none. */
+    query: string;
+}
+/**
+ * Canonicalises a raw origin-form request target (`/path?query`). Returns `null`, so the caller
+ * answers 404, when the pathname is not already canonical: it differs from what the URL parser
+ * makes of it, contains an empty, `.` or `..` segment (a trailing slash is an empty segment), or
+ * contains `%`; or when the query is not already in the form the URL parser serializes it to.
+ * The query string is never used for matching and is returned verbatim.
+ */
+export declare function canonicalizeIngressPath(raw: string): CanonicalIngressPath | null;
+/** The single string the gateway signs, Atlas re-matches and the SDK binds: path plus raw query. */
+export declare function signedIngressPath({ path, query }: CanonicalIngressPath): string;
+export type IngressRouteSegment = {
+    kind: 'literal';
+    value: string;
+} | {
+    kind: 'placeholder';
+    name: string;
+};
+export interface ParsedIngressRouteTemplate {
+    template: string;
+    segments: readonly IngressRouteSegment[];
+}
+/**
+ * Parses a declared route template such as `/api/borrower/documents/{documentId}/notes`.
+ * Literal segments use the Lattice `managed_server` path grammar; a `{name}` placeholder is a
+ * whole segment. Returns `null` for anything else: no `/api/` prefix, a wildcard, `%`, a query,
+ * a trailing slash, an empty, `.` or `..` segment, or a repeated placeholder name.
+ */
+export declare function parseRouteTemplate(template: string): ParsedIngressRouteTemplate | null;
+export interface IngressRouteDeclaration {
+    path: string;
+    methods: readonly string[];
+}
+export interface IngressRouteMatch<Route extends IngressRouteDeclaration = IngressRouteDeclaration> {
+    /** `"<METHOD> <template>"`, stable across releases while the declaration is unchanged. */
+    routeId: string;
+    params: Readonly<Record<string, string>>;
+    route: Route;
+}
+export declare function ingressRouteId({ method, template }: {
+    method: string;
+    template: string;
+}): string;
+/**
+ * Exact-matches a method and a canonical pathname (from `canonicalizeIngressPath(...).path`, never
+ * the query) against declared routes. Methods compare exactly. An unparseable declaration never
+ * matches, and a path that two declarations both match returns `null`: the manifest refuses
+ * overlapping routes, so ambiguity here means the declarations did not come from a valid manifest.
+ */
+export declare function matchIngressRoute<Route extends IngressRouteDeclaration>(routes: readonly Route[], method: string, canonicalPath: string): IngressRouteMatch<Route> | null;
+/**
+ * Whether one request path could match both templates: same segment count, and at every position
+ * either equal literals or at least one placeholder. Conservative: a placeholder is treated as
+ * matching any literal opposite it.
+ */
+export declare function ingressRouteTemplatesOverlap({ left, right }: {
+    left: ParsedIngressRouteTemplate;
+    right: ParsedIngressRouteTemplate;
+}): boolean;