slopkit 0.3.0 → 0.4.0-rc.1

package/dist/server/web.js

@@ -4,8 +4,12 @@
  * (an access proxy's JWT or the server's own OIDC login), the Host must be ours, and every POST and the socket must come
  * from the page's own Origin. Responses carry a strict CSP and no framing.
  *
+ * An agent's key (`Authorization: Bearer`) decides a request alone and needs no Origin: the Origin check guards
+ * credentials a browser sends on its own (cookies), and a bearer isn't one.
+ *
  * Routes are contract endpoints: the request is checked against its schema before the handler runs and the reply
  * after, so neither side can drift from the contract. Failures answer `{ kind, message, path? }` with the kind's status.
+ * Raw routes (`rawRoute`) take and answer bytes behind the same guards, with their own body limit.
  * The socket is a hint channel: the app sends small messages (pokes, pings); nothing correct depends on it.
  * Every API request is logged with an id, status, time and whether a person or a service asked.
  */
@@ -45,11 +49,19 @@ export class Refusal extends Error {
         this.path = path;
     }
 }
-export function route(endpoint, handle) {
+/** A body limit as given: a positive whole number of bytes. */
+function bodyBytes(bytes) {
+    if (!Number.isSafeInteger(bytes) || bytes < 1) {
+        throw new Error(`a body limit must be a positive integer, got ${bytes}`);
+    }
+    return bytes;
+}
+export function route(endpoint, handle, options = {}) {
     return {
         method: endpoint.method,
         path: endpoint.path,
         person: endpoint.person,
+        ...(options.bodyLimit === undefined ? {} : { bodyLimit: bodyBytes(options.bodyLimit) }),
         run: async (input, caller) => {
             let request;
             try {
@@ -66,6 +78,53 @@ export function route(endpoint, handle) {
         },
     };
 }
+export function rawRoute(definition) {
+    if (!/^\/[^*]*(\/\*)?$/.test(definition.path)) {
+        throw new Error(`a raw route's path is exact or ends in /*: ${definition.path}`);
+    }
+    return {
+        raw: true,
+        method: definition.method,
+        path: definition.path,
+        person: definition.person ?? false,
+        bodyLimit: bodyBytes(definition.bodyLimit ?? 65_536),
+        handle: definition.handle,
+    };
+}
+/** Types worth gzipping; images never are, whatever their format. */
+const COMPRESSIBLE = /^(text\/|application\/(json|javascript|xml|manifest\+json))/i;
+/** CSP directives that only take away: a handler may add these to the server's policy. */
+const TIGHTENING = new Set([
+    "sandbox",
+    "upgrade-insecure-requests",
+    "block-all-mixed-content",
+    "require-trusted-types-for",
+    "trusted-types",
+]);
+function directives(policy) {
+    return new Map(policy
+        .split(";")
+        .map((part) => part.trim().replaceAll(/\s+/g, " "))
+        .filter((part) => part !== "")
+        .map((part) => {
+        const space = part.indexOf(" ");
+        return space === -1
+            ? [part.toLowerCase(), ""]
+            : [part.slice(0, space).toLowerCase(), part.slice(space + 1)];
+    }));
+}
+/**
+ * The server's policy with the tightening directives a handler's policy names added (`sandbox` for bytes someone else
+ * made). Everything else in the handler's policy is ignored: the server's directives are never replaced or dropped.
+ */
+function tightened(base, offered) {
+    if (offered === undefined) {
+        return base;
+    }
+    const own = directives(base);
+    const added = [...directives(offered)].flatMap(([name, value]) => TIGHTENING.has(name) && !own.has(name) ? [value === "" ? name : `${name} ${value}`] : []);
+    return [base, ...added].join("; ");
+}
 function header(request, name) {
     const value = request.headers[name];
     return Array.isArray(value) ? value[0] : value;
@@ -77,11 +136,36 @@ function sessionToken(request, cookie) {
         .find((part) => part.startsWith(`${cookie}=`))
         ?.slice(cookie.length + 1);
 }
+/** How long a sign-in keeps the page it interrupted. */
+const BACK_SECONDS = 600;
+function decodeCookie(value) {
+    try {
+        return value === undefined ? undefined : decodeURIComponent(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A path on this server to return to, or nothing: never another origin (`//host`, `/\\host`, a scheme), and only
+ * printable ASCII, which a Location header always takes (the redirect to the login percent-encodes the rest).
+ */
+function onThisServer(path) {
+    return path !== null &&
+        path !== undefined &&
+        path.length <= 2048 &&
+        /^\/(?![/\\])[\u0021-\u005B\u005D-\u007E]*$/.test(path)
+        ? path
+        : undefined;
+}
 /** Send a body, gzipped when the client takes it and it is worth it. */
 function send(request, response, status, body, headers = {}) {
     let bytes = typeof body === "string" ? Buffer.from(body) : body;
     const extra = {};
-    if (bytes.length > 1024 && /\bgzip\b/.test(header(request, "accept-encoding") ?? "")) {
+    const type = headers["content-type"] ?? "text/plain";
+    if (bytes.length > 1024 &&
+        COMPRESSIBLE.test(type) &&
+        /\bgzip\b/.test(header(request, "accept-encoding") ?? "")) {
         bytes = gzipSync(bytes, { level: 6 });
         extra["content-encoding"] = "gzip";
         extra.vary = "accept-encoding";
@@ -98,11 +182,12 @@ function send(request, response, status, body, headers = {}) {
 function failure(request, response, kind, message, path) {
     send(request, response, STATUS[kind], JSON.stringify({ kind, message, ...(path === undefined ? {} : { path }) }), { "content-type": "application/json" });
 }
-/**
- * The body as JSON: its bytes collected and counted against `limit`, then decoded once, so a character split between
- * chunks arrives whole. Bytes that aren't UTF-8 are refused, never replaced.
- */
-async function readBody(request, limit) {
+/** The body's bytes, counted against `limit` as they arrive: past it, refused before anything reads them. */
+async function readBytes(request, limit) {
+    const declared = Number(header(request, "content-length"));
+    if (Number.isFinite(declared) && declared > limit) {
+        throw new Refusal("invalid", "the request is too large");
+    }
     const chunks = [];
     let size = 0;
     for await (const chunk of request) {
@@ -113,9 +198,17 @@ async function readBody(request, limit) {
         }
         chunks.push(bytes);
     }
+    return Buffer.concat(chunks);
+}
+/**
+ * The body as JSON: its bytes collected and counted against `limit`, then decoded once, so a character split between
+ * chunks arrives whole. Bytes that aren't UTF-8 are refused, never replaced.
+ */
+async function readBody(request, limit) {
+    const bytes = await readBytes(request, limit);
     let text;
     try {
-        text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
     }
     catch {
         throw new Refusal("invalid", "the request is not UTF-8");
@@ -133,22 +226,124 @@ export async function serveWeb(options) {
     const hosts = new Set();
     const origins = new Set();
     let plainHost;
-    const routes = new Map(options.routes.map((each) => [`${each.method} ${each.path}`, each]));
+    const contract = options.routes.filter((each) => !("raw" in each));
+    const raws = options.routes.filter((each) => "raw" in each);
+    const routes = new Map(contract.map((each) => [`${each.method} ${each.path}`, each]));
     const manifest = JSON.stringify(options.manifest);
+    // A raw route can't take over the login, the socket or the manifest, or shadow another route.
+    for (const each of raws) {
+        const prefix = each.path.endsWith("/*") ? each.path.slice(0, -1) : undefined;
+        const covers = (path) => prefix === undefined
+            ? path === each.path
+            : path.startsWith(prefix) || path === prefix.slice(0, -1) || prefix === "/";
+        if (each.path.startsWith("/auth/") ||
+            covers("/auth/login") ||
+            covers("/manifest.webmanifest") ||
+            (options.socket !== undefined && covers(options.socket.path)) ||
+            contract.some((other) => covers(other.path))) {
+            throw new Error(`a raw route can't serve ${each.path}`);
+        }
+    }
+    if (new Set(raws.map((each) => `${each.method} ${each.path}`)).size !== raws.length) {
+        throw new Error("two raw routes have the same method and path");
+    }
+    /** The raw routes for a path, most specific first, with what a `/*` matched. */
+    function rawFor(path) {
+        // Matched on the decoded path, so a prefix's remainder is decoded exactly once.
+        return raws
+            .flatMap((each) => {
+            if (each.path === path) {
+                return [{ found: each, params: undefined, rank: Number.MAX_SAFE_INTEGER }];
+            }
+            const prefix = each.path.endsWith("/*") ? each.path.slice(0, -1) : undefined;
+            return prefix !== undefined && path.startsWith(prefix)
+                ? [{ found: each, params: path.slice(prefix.length), rank: prefix.length }]
+                : [];
+        })
+            .toSorted((a, b) => b.rank - a.rank);
+    }
     /** The caller, or undefined when not signed in, or false when signed in but not allowed. */
     async function identify(request) {
+        const authorization = header(request, "authorization");
+        // Any Authorization is a bearer's claim: one that isn't a well-formed bearer is refused, never ignored.
+        const bearer = authorization === undefined ? undefined : (/^Bearer (\S+)$/i.exec(authorization)?.[1] ?? "");
         const jwt = header(request, "cf-access-jwt-assertion");
-        const identities = await auth.identify(jwt, sessionToken(request, cookie));
+        const identities = await auth.identify(jwt, sessionToken(request, cookie), bearer);
         if (identities === undefined || identities === false) {
             return identities;
         }
         return {
             identities,
-            person: !identities.some((identity) => identity.startsWith("service:")),
-            login: jwt === undefined ? "oidc" : "access",
+            person: !identities.some((identity) => identity.startsWith("service:") || identity.startsWith("key:")),
+            login: bearer === undefined ? (jwt === undefined ? "oidc" : "access") : "key",
             request: randomBytes(6).toString("base64url"),
         };
     }
+    /** Whether a request may act: a key always (it isn't sent on its own); a cookie or proxy only from the page. */
+    const fromPage = (request, caller) => caller.login === "key" || origins.has(header(request, "origin") ?? "");
+    /** Log one request's outcome, as every route does. */
+    function logged(caller, method, path, status, started) {
+        log(status < 400 ? "info" : "warn", "request", {
+            request: caller.request,
+            method,
+            path,
+            status,
+            ms: Math.round(performance.now() - started),
+            person: caller.person,
+            ...(caller.login === "key" ? { caller: caller.identities.join(" ") } : {}),
+        });
+    }
+    async function raw(request, response, url, caller, candidates) {
+        const started = performance.now();
+        const method = request.method === "HEAD" ? "GET" : (request.method ?? "GET");
+        const match = candidates.find((each) => each.found.method === method);
+        let status = 200;
+        try {
+            if (match === undefined) {
+                status = 405;
+                send(request, response, 405, "Method not allowed");
+                logged(caller, method, url.pathname, status, started);
+                return;
+            }
+            const { found, params } = match;
+            if (method === "POST" && !fromPage(request, caller)) {
+                throw new Refusal("forbidden", "bad origin");
+            }
+            if (found.person && !caller.person) {
+                throw new Refusal("forbidden", "only a person's login can do this");
+            }
+            const body = method === "POST" ? await readBytes(request, found.bodyLimit) : undefined;
+            const reply = await found.handle({
+                url,
+                params: params === undefined ? {} : { "*": params },
+                body,
+                headers: request.headers,
+            }, caller);
+            status = reply.status;
+            const offered = Object.entries(reply.headers ?? {}).find(([name]) => name.toLowerCase() === "content-security-policy")?.[1];
+            const own = Object.fromEntries(Object.entries(reply.headers ?? {}).filter(([name]) => !(name.toLowerCase() in SECURITY) &&
+                !["content-type", "content-encoding", "cache-control", "vary"].includes(name.toLowerCase())));
+            send(request, response, reply.status, reply.body, {
+                ...own,
+                "content-type": reply.type,
+                "cache-control": reply.cache === "immutable" ? "private, max-age=31536000, immutable" : "no-store",
+                "content-security-policy": tightened(SECURITY["content-security-policy"], offered),
+            });
+        }
+        catch (error) {
+            const kind = error instanceof Refusal ? error.kind : "unavailable";
+            status = STATUS[kind];
+            if (!(error instanceof Refusal)) {
+                log("error", "handler failed", {
+                    request: caller.request,
+                    path: url.pathname,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+            failure(request, response, kind, error instanceof Refusal ? error.message : "the server failed; see its log");
+        }
+        logged(caller, method, url.pathname, status, started);
+    }
     async function asset(request, response, path) {
         const relative = normalize(decodeURIComponent(path)).replace(/^[/\\]+/, "");
         if (relative.split(sep).includes("..")) {
@@ -196,7 +391,7 @@ export async function serveWeb(options) {
                 throw new Refusal("invalid", `no ${method} ${url.pathname}`);
             }
             // A page from anywhere else must never act with this browser's credentials.
-            if (method === "POST" && !origins.has(header(request, "origin") ?? "")) {
+            if (method === "POST" && !fromPage(request, caller)) {
                 throw new Refusal("forbidden", "bad origin");
             }
             if (found.person && !caller.person) {
@@ -204,7 +399,7 @@ export async function serveWeb(options) {
             }
             let input;
             if (method === "POST") {
-                input = await readBody(request, options.bodyLimit ?? 65_536);
+                input = await readBody(request, found.bodyLimit ?? options.bodyLimit ?? 65_536);
             }
             else {
                 const q = url.searchParams.get("q");
@@ -231,14 +426,7 @@ export async function serveWeb(options) {
             }
             failure(request, response, kind, error instanceof Refusal ? message : "the server failed; see its log", error instanceof Refusal ? error.path : undefined);
         }
-        log(status < 400 ? "info" : "warn", "request", {
-            request: caller.request,
-            method,
-            path: url.pathname,
-            status,
-            ms: Math.round(performance.now() - started),
-            person: caller.person,
-        });
+        logged(caller, method, url.pathname, status, started);
     }
     /** The sockets each sign-in session opened, so signing out closes them. */
     const signedIn = new Map();
@@ -255,14 +443,21 @@ export async function serveWeb(options) {
                 if (!auth.oidc) {
                     return send(request, response, 404, "No login here");
                 }
-                return send(request, response, 302, "", { location: await auth.loginUrl(callback) });
+                const back = onThisServer(url.searchParams.get("back"));
+                return send(request, response, 302, "", {
+                    location: await auth.loginUrl(callback),
+                    // Where the sign-in returns, for the callback; only a path on this server is kept.
+                    "set-cookie": `${cookie}_back=${back === undefined ? "" : encodeURIComponent(back)}; Path=/auth; HttpOnly;${secure} SameSite=Lax; Max-Age=${back === undefined ? 0 : BACK_SECONDS}`,
+                });
             }
             if (url.pathname === "/auth/callback" && request.method === "GET") {
                 try {
                     const token = await auth.callback(url.searchParams.get("state") ?? "", url.searchParams.get("code") ?? "");
                     log("info", "signed in");
+                    // Every sign-in starts at /auth/login, which sets or clears this, so it is never an older one's.
+                    const back = onThisServer(decodeCookie(sessionToken(request, `${cookie}_back`)));
                     return send(request, response, 302, "", {
-                        location: "/",
+                        location: back ?? "/",
                         "set-cookie": `${cookie}=${token}; Path=/; HttpOnly;${secure} SameSite=Lax; Max-Age=${7 * 86_400}`,
                     });
                 }
@@ -292,10 +487,23 @@ export async function serveWeb(options) {
                 log("warn", caller === false ? "refused" : "not signed in", { path: url.pathname });
                 const navigation = request.method === "GET" && (header(request, "accept") ?? "").includes("text/html");
                 if (caller === undefined && navigation && auth.oidc) {
-                    return send(request, response, 302, "", { location: "/auth/login" });
+                    return send(request, response, 302, "", {
+                        location: `/auth/login?back=${encodeURIComponent(url.pathname + url.search)}`,
+                    });
                 }
                 return failure(request, response, caller === false ? "forbidden" : "signed-out", caller === false ? "not allowed" : "sign in first");
             }
+            let decoded;
+            try {
+                decoded = decodeURIComponent(url.pathname);
+            }
+            catch {
+                return send(request, response, 400, "Bad path");
+            }
+            const candidates = rawFor(decoded);
+            if (candidates.length > 0) {
+                return await raw(request, response, url, caller, candidates);
+            }
             if (url.pathname.startsWith("/api/")) {
                 return await api(request, response, url, caller);
             }
@@ -328,13 +536,13 @@ export async function serveWeb(options) {
                 new URL(request.url ?? "/", "http://localhost").pathname !== options.socket.path) {
                 return refuse(404);
             }
-            if (!origins.has(header(request, "origin") ?? "")) {
-                return refuse(403);
-            }
             const caller = await identify(request);
             if (caller === undefined || caller === false) {
                 return refuse(caller === false ? 403 : 401);
             }
+            if (!fromPage(request, caller)) {
+                return refuse(403);
+            }
             const open = options.socket.open;
             sockets.handleUpgrade(request, stream, head, (socket) => {
                 socket.on("error", () => {

package/dist/states.d.ts

@@ -77,25 +77,59 @@ export declare const LOOKS: {
  * history. `log`: nothing to act on or misread.
  */
 export type Place = "main" | "badge" | "panel" | "log";
-type Placed = {
+/**
+ * The work a `working` state waits on, so it can be checked to be under way (`slopkit/test/states` `viewProblems`): the
+ * server's job of a kind and key, a command in the page's outbox, or the page's own copy (loading, pulling, pushing,
+ * writing). A working state that owes nothing of the app's (the world is at work: a parcel in transit) says `owes: null`.
+ */
+export type Owed = {
+    readonly job: {
+        readonly kind: string;
+        readonly key: string;
+    };
+} | {
+    readonly command: {
+        readonly client: string;
+        readonly id: number;
+    };
+} | {
+    readonly sync: true;
+};
+type Others = Exclude<Meaning, "ok" | "partial" | "stale" | "working">;
+type Placed<S> = {
     readonly meaning: "ok";
     readonly where: Place;
     readonly claim: false;
+    readonly owes?: never;
 } | {
     readonly meaning: "partial" | "stale";
     readonly where: "main";
     readonly claim: true;
+    readonly owes?: never;
 } | {
-    readonly meaning: Exclude<Meaning, "ok" | "partial" | "stale">;
+    readonly meaning: Others;
     readonly where: "main";
     readonly claim: boolean;
+    readonly owes?: never;
 } | {
-    readonly meaning: Exclude<Meaning, "ok" | "partial" | "stale">;
+    readonly meaning: Others;
     readonly where: "badge";
     readonly claim: false;
+    readonly owes?: never;
+} | {
+    readonly meaning: "working";
+    readonly where: "main";
+    readonly claim: boolean;
+    /** What is at work: checked to be under way whenever this is drawn. Required. */
+    readonly owes: ((state: S) => Owed) | null;
+} | {
+    readonly meaning: "working";
+    readonly where: "badge";
+    readonly claim: false;
+    readonly owes: ((state: S) => Owed) | null;
 };
 /** One state's display: what it means, where and why it is drawn, its words, and what the person can do. */
-export type Display<S, A> = Placed & {
+export type Display<S, A> = Placed<S> & {
     /** Why it is drawn there, or not at all. Required. */
     readonly why: string;
     readonly text: (state: S) => string;
@@ -109,9 +143,20 @@ export type Table<S extends {
         kind: K;
     }>, A>;
 };
+/**
+ * Brands a Line and a Screen carry, so a check holding one copy of this module still knows another copy's (a fresh
+ * module graph for each page load in a test, two installed versions).
+ */
+declare const LINE: unique symbol;
+declare const SCREEN: unique symbol;
+/** Whether a value is a Line, made by any copy of this module. */
+export declare function isLine(value: unknown): value is Line<unknown>;
+/** Whether a value is a Screen, made by any copy of this module. */
+export declare function isScreen(value: unknown): value is Screen<unknown>;
 /** A drawn state: only a subject makes one, from its table. */
 export declare class Line<A> {
     #private;
+    readonly [LINE] = true;
     readonly subject: string;
     readonly kind: string;
     readonly meaning: Meaning;
@@ -121,11 +166,14 @@ export declare class Line<A> {
     readonly tone: Tone;
     readonly text: string;
     readonly action: A | null;
+    /** The work a working state waits on (its table's `owes`), or null. */
+    readonly owed: Owed | null;
     private constructor();
 }
 /** A screen's summary of all its parts: only `compose` makes one. */
 export declare class Screen<A> {
     #private;
+    readonly [SCREEN] = true;
     /** Every part is ok. */
     readonly ok: boolean;
     /** The status line: the first part that isn't ok (by placement, severity, order), or the ok text; `more` counts the rest. */

package/dist/states.js

@@ -45,6 +45,20 @@ export const LOOKS = {
     ours: { glyph: "✕", tone: "warning" },
     gone: { glyph: "⊘", tone: "muted" },
 };
+/**
+ * Brands a Line and a Screen carry, so a check holding one copy of this module still knows another copy's (a fresh
+ * module graph for each page load in a test, two installed versions).
+ */
+const LINE = Symbol.for("slopkit.states.Line");
+const SCREEN = Symbol.for("slopkit.states.Screen");
+/** Whether a value is a Line, made by any copy of this module. */
+export function isLine(value) {
+    return typeof value === "object" && value !== null && LINE in value;
+}
+/** Whether a value is a Screen, made by any copy of this module. */
+export function isScreen(value) {
+    return typeof value === "object" && value !== null && SCREEN in value;
+}
 // Set by the classes' static blocks: nothing outside this module can make a Line or a Screen.
 let makeLine;
 let makeScreen;
@@ -53,6 +67,7 @@ export class Line {
     // A private field makes the type nominal: no object literal or spread of a Line is one.
     // oxlint-disable-next-line no-unused-private-class-members -- its presence is its use
     #made = true;
+    [LINE] = true;
     subject;
     kind;
     meaning;
@@ -62,6 +77,8 @@ export class Line {
     tone;
     text;
     action;
+    /** The work a working state waits on (its table's `owes`), or null. */
+    owed;
     constructor(fields) {
         this.subject = fields.subject;
         this.kind = fields.kind;
@@ -72,6 +89,7 @@ export class Line {
         this.tone = fields.tone;
         this.text = fields.text;
         this.action = fields.action;
+        this.owed = fields.owed;
     }
     static {
         makeLine = (fields) => new Line(fields);
@@ -81,6 +99,7 @@ export class Line {
 export class Screen {
     // oxlint-disable-next-line no-unused-private-class-members -- nominal, as Line's
     #made = true;
+    [SCREEN] = true;
     /** Every part is ok. */
     ok;
     /** The status line: the first part that isn't ok (by placement, severity, order), or the ok text; `more` counts the rest. */
@@ -185,6 +204,7 @@ export function states(options) {
                     tone: look.tone,
                     text,
                     action: display.action,
+                    owed: display.meaning === "working" && display.owes !== null ? display.owes(state) : null,
                 });
             },
         };

package/dist/sync.d.ts

@@ -317,6 +317,8 @@ export type Msg<T, P, S, C, O> = {
     replica: Replica<T, S>;
     commands: Pending<C, O>[];
     unreadable: number;
+    /** The copy owes a real reset before it is trusted (lifted from an earlier release's row shapes). */
+    restart?: "paged";
     now: number;
 } | {
     type: "loadFailed";

package/dist/sync.js

@@ -635,6 +635,7 @@ export function createSync(spec) {
                         replica: msg.replica,
                         saved: { ...at.saved, dataset: msg.replica.dataset, revision: msg.replica.revision },
                         target: Math.max(at.target, msg.replica.revision),
+                        restart: msg.restart ?? at.restart,
                         commands: [...resumed, ...at.commands],
                         unreadable: msg.unreadable,
                     },

package/dist/test/agents.d.ts

@@ -0,0 +1,19 @@
+import type { Endpoint } from "../contract.ts";
+export type AgentCase = {
+    name: string;
+    check: (base: string, token: string) => Promise<string[]>;
+};
+/** A call an agent's key makes and gets answered. */
+export declare function reads<Req, Res>(endpoint: Endpoint<Req, Res>, input: Req, name?: string): AgentCase;
+/** A call only the person may make: the key gets `forbidden`, or an answer `refusal` judges a refusal. */
+export declare function refused<Req, Res>(endpoint: Endpoint<Req, Res>, input: Req, options?: {
+    name?: string;
+    refusal?: (reply: Res) => boolean;
+}): AgentCase;
+/** Run every case against the app at `url` with an allowed key's `token`; throws listing every failure. */
+export declare function agentAccess(options: {
+    url: string;
+    token: string;
+    reads: readonly AgentCase[];
+    refused: readonly AgentCase[];
+}): Promise<void>;

package/dist/test/agents.js

@@ -0,0 +1,62 @@
+/**
+ * Agent access, checked on an app's real server: the app lists what its agents read with a key and what only the
+ * person may do, and `agentAccess` proves over HTTP, as an agent calls it (a bearer key, no Origin, no login), that:
+ *
+ * - the key reads each `reads` case, and the reply is the contract's;
+ * - none of those reads is public: without credentials it's `signed-out`, with an unknown key `forbidden`;
+ * - the key is refused each `refused` case: `forbidden`, or a reply the case judges a refusal (a sync push answers
+ *   each command it refuses with a receipt).
+ *
+ * Every failure is collected and thrown together, so one run shows the whole gap.
+ */
+import { call } from "../contract.js";
+const bearer = (token) => ({ authorization: `Bearer ${token}` });
+const said = (result) => result.ok ? "an answer" : `${result.failure.kind}: ${result.failure.message}`;
+/** A call an agent's key makes and gets answered. */
+export function reads(endpoint, input, name) {
+    const named = name ?? `${endpoint.method} ${endpoint.path}`;
+    return {
+        name: named,
+        check: async (base, token) => {
+            const failures = [];
+            const read = await call(endpoint, input, { base, headers: bearer(token) });
+            if (!read.ok) {
+                failures.push(`${named}: a key should read it, got ${said(read)}`);
+            }
+            const anonymous = await call(endpoint, input, { base });
+            if (anonymous.ok || anonymous.failure.kind !== "signed-out") {
+                failures.push(`${named}: without credentials it should be signed-out, got ${said(anonymous)}`);
+            }
+            const unknown = await call(endpoint, input, { base, headers: bearer("nobody.not-a-key") });
+            if (unknown.ok || unknown.failure.kind !== "forbidden") {
+                failures.push(`${named}: an unknown key should be forbidden, got ${said(unknown)}`);
+            }
+            return failures;
+        },
+    };
+}
+/** A call only the person may make: the key gets `forbidden`, or an answer `refusal` judges a refusal. */
+export function refused(endpoint, input, options = {}) {
+    const named = options.name ?? `${endpoint.method} ${endpoint.path}`;
+    return {
+        name: named,
+        check: async (base, token) => {
+            const result = await call(endpoint, input, { base, headers: bearer(token) });
+            const refusal = result.ok
+                ? options.refusal?.(result.value) === true
+                : result.failure.kind === "forbidden";
+            return refusal ? [] : [`${named}: a key should be refused, got ${said(result)}`];
+        },
+    };
+}
+/** Run every case against the app at `url` with an allowed key's `token`; throws listing every failure. */
+export async function agentAccess(options) {
+    if (options.reads.length === 0 || options.refused.length === 0) {
+        throw new Error("agentAccess: name at least one read and one refused call, or it proves nothing");
+    }
+    const base = options.url.replace(/\/$/, "");
+    const failures = (await Promise.all([...options.reads, ...options.refused].map((each) => each.check(base, options.token)))).flat();
+    if (failures.length > 0) {
+        throw new Error(`agent access:\n${failures.map((line) => `- ${line}`).join("\n")}`);
+    }
+}