slopkit 0.3.0 → 0.4.0-rc.0

package/DEPS.md

@@ -28,9 +28,11 @@ seeded network's PRNG and scheduler.
 
 ## Budgets
 
-- **Kit client core**, gated by `pack:check` on the packed package: `schema`, `contract`, `sync`, `client`, `machine`,
-  `money`, `digest`, `states` and `web/replica`, minified and gzipped together, ≤ 13,951 bytes (13,951 measured; the
-  paged first copy added 1,470, refused pushes and the bounded outbox 1,755).
+- **Kit client core**, gated by `pack:check` on the packed package: `schema`, `contract`, `api`, `sync`, `client`,
+  `machine`, `money`, `digest`, `states`, `web/replica` and `web/runtime`, minified and gzipped together, ≤ 17,286
+  bytes (17,286 measured; the paged first copy added 1,470, refused pushes and the bounded outbox 1,755, the sync
+  contract and the page's runtime 2,428, in place of each app's own, a working state's owed work 107, and an upgrade
+  keeping the offline copy 800).
   `cron` is browser-safe but outside the core; an app that ships it counts it in its own budget. The budget grows only
   with a new entry or guarantee, by its measured size.
 - **Hello app** (preact, signals, and `sync`, `client`, `web/replica`, `schema`, `contract`, `states`): ≤ 17 KB gzip

package/README.md

@@ -59,7 +59,8 @@ const update: Update<Note, Msg, Effect> = (note, msg) => {
 const ui = states<"check">({ order: MEANINGS });
 const view = ui.subject<Note>("note", {
   draft: { meaning: "none", where: "main", claim: false, why: "unsent", text: () => "draft", action: null },
-  saving: { meaning: "working", where: "main", claim: false, why: "sent", text: () => "saving", action: null },
+  saving: { meaning: "working", where: "main", claim: false, why: "sent", text: () => "saving", action: null,
+    owes: () => ({ sync: true }) }, // a working state names its work, checked to be under way
   saved: { meaning: "ok", where: "main", claim: false, why: "kept", text: () => "saved", action: null },
   unsure: { meaning: "you", where: "main", claim: true, why: "may have saved", text: () => "saved?", action: "check" },
 });
@@ -72,6 +73,14 @@ const { model, effects } = replay(update, { kind: "draft" }, [
 view.line(model).text; // "saved?", drawn ⚠ with a check action
 effects; // [{ kind: "send", text: "hi" }], one send
 
+// the page's own state (route, filters, applied forms) lives in the model too, so every view a replay reaches is checked
+const { problems } = replayProblems(update, { kind: "draft" }, messages, { view: (note) => view.line(note), order: MEANINGS });
+
+// the app's real page, headless, over its own server in this process, signed in by the test login
+const page = await openPage({ server, page: () => import("../src/web/main.tsx"), at: "2026-01-01T12:00:00Z", path: "/?note=a" });
+await page.press(/save/); // by accessible name; settles, then checks the view
+await page.reload(); // same device: IndexedDB, localStorage, sessionStorage and the address kept
+
 // the page calls it, and the server answers after checking the login, the request and the reply
 const sent = await call(save, { text: "hi" }); // { ok: true, value: { id } } or a typed failure
 await serveWeb({
@@ -94,6 +103,20 @@ export default defineConfig({
 });
 ```
 
+agents call your app with a key (`addKey(home, name)` from `slopkit/server/keys`, allowed as `key:<name>` in
+`web.allow`), never as the person. prove it in your own tests against your real server:
+
+```ts
+import { agentAccess, reads, refused } from "slopkit/test/agents";
+
+await agentAccess({
+  url: server.url,
+  token: await addKey(home, "agent"),
+  reads: [reads(list, {})],
+  refused: [refused(push, request, { refusal: (reply) => reply.results.every(forbidden) })],
+});
+```
+
 push handlers return per-command outcomes as ledger receipts. once any command in a request has acted, never throw
 an `invalid`, `forbidden` or `conflict` refusal for the whole request: a refusal proves only that attempt did not act,
 not that an earlier delivery did not. request schemas are checked before the handler runs.
@@ -145,6 +168,75 @@ import { pullConformance } from "slopkit/conformance/pull";
 pullConformance({ name: "my app", create: async (limits) => fixtureOverMyRealStore(limits) });
 ```
 
+### the app shell
+
+the page's runtime, the server's sync, the store and the command line are the same in every app, so they live here.
+an app declares its rows, commands and outcomes once:
+
+```ts
+import { syncApi } from "slopkit/api";
+
+// pull, push, telemetry and the socket's poke, plus the outbox record. rows need an `id`
+export const api = syncApi({ rows: { notes: note, tags: tag }, server, command, outcome });
+```
+
+the store is the kit's core (meta, revisions, the command ledger, jobs) plus your tables:
+
+```ts
+import { schemaVersion, SyncStore } from "slopkit/server/store";
+
+const SCHEMA = { base: "create table notes(...) strict; ...", replicated: ["notes", "tags"], baseVersion: 1,
+  migrations: [], indexes: "create index if not exists notes_order on notes(at, id, deleted);" };
+
+class Store extends SyncStore {
+  readonly ledger = this.createLedger<Kept>({ encode: JSON.stringify, decode: readKept });
+  constructor(path: string) { super(path, { name: "notes", schema: SCHEMA }); }
+}
+```
+
+the server answers pull and push over it, and serves them with the poke socket and telemetry:
+
+```ts
+import { serveSync, syncHandlers } from "slopkit/server/sync";
+
+const sync = syncHandlers({ api, store, ledger: store.ledger, log, server: (caller) => facts(caller),
+  history: { row: "notes", table: "notes", order: ["at", "id"], version: 1, live: "deleted = 0", read: toNote,
+    through: ([at]) => String(at) },
+  unpaged: (since) => ({ tags: store.tags(since) }), everything: () => store.everything(),
+  names: (kept) => [kept.note], limits, act: (command) => ({ local: () => store.apply(command) }),
+  outcome: (kept) => kept });
+
+await serveSync({ name: "notes", api, sync, home, config, env, log, page, assets: "dist/web" });
+```
+
+your outcome union must admit the kit's own answers (`failed` with `conflict` or `forbidden`, and `retired`): if it
+can't, `serveSync` doesn't compile. the page runs the same engine headless or in a browser:
+
+```ts
+import { createRuntime } from "slopkit/web/runtime";
+
+const runtime = createRuntime({ name: "notes", sync, api, replica: { version: 1, tables, empty } });
+runtime.subscribe((model) => draw(model));
+runtime.start();
+```
+
+and `main.ts` is the command line: `serve | update | rollback | probe | version`, one server per home, releases that
+boot on a copy of the store before they replace the running one, automatic rollback of a crashing update, and `probe`,
+the live server checked from its host with no identity (it serves, the version that passed, no test login, requests
+without identity refused, the public door matching `web.json`):
+
+```ts
+import { runCli } from "slopkit/server/cli";
+
+process.exitCode = await runCli(process.argv.slice(2), {
+  name: "notes", root: new URL("../", import.meta.url), schema: schemaVersion(SCHEMA), serves: "your notes.",
+  serve: async ({ home, version, log, web, env }) => {
+    /* open the store, serveSync when web isn't off */
+    return { url, close };
+  },
+});
+```
+
 the shared lint rules go on top of ultracite's presets (`oxlint.config.ts`):
 
 ```ts

package/RULES.md

@@ -1,6 +1,6 @@
 # Rules for apps on slopkit
 
-Rules version: 1
+Rules version: 2
 
 The standard every app built on `slopkit` meets, and the kit itself. The aim is speed and correctness,
 solved once in the kit so every app built on it starts with these problems solved. Each rule is a property of the
@@ -56,9 +56,21 @@ What the screen can say is decided for every state, as a pure function of the ap
   with composition rules, not one giant enum. Prevents a concurrent fact being lost to another.
 - **Every state's display is decided, with its reason.** A typed table `satisfies Record<State["kind"], Display>` maps
   each state to where it is drawn (`main`: it changes what the person should believe about the numbers or needs them
-  to act; `badge`; `panel`; `log`), why, tone, glyph, text and action. A new state doesn't compile until it is placed.
+  to act; `badge`; `panel`; `log`), why, tone, glyph, text and action, and for a working state what it owes. A new
+  state doesn't compile until it is placed.
   Two states share a display only when the statement is true for both and implies the same safe action. A hidden state
   has a reason, and hiding it changes no claim or action.
+- **Working names what it waits on.** A working state's table entry names the work it waits on (a job, a command,
+  the page's own sync), and the state is drawn only while that work is under way. One whose work is the world's (a
+  parcel in transit) says so in its entry, with why. Prevents "checking…" on a check nobody runs.
+- **The page's own state is model state.** What changes what the screen says or what a tap does (the route and open
+  item, modes, open panels, filters and searches, selections, forms with drafts and applied values held apart, and
+  persisted view settings) is part of the model. It changes only through the model's pure `update` (a message in; the
+  model and effects out), so a replay of messages reaches it like the rest of the model. The address and storage are
+  read once at load and written as effects, so a deep link opens the screen navigating there does, back returns, and
+  a reload keeps what was set on that device. The numbers never read a form's draft. Focus, hover, scroll and
+  animation stay in the browser unless the view changes with them. Prevents a selection that moves the numbers with
+  no state of its own.
 - **Never claim more than is true.** Order by placement, then severity, with each app setting its own severity order
   by consequence. Facts that change what the numbers mean (incomplete, possibly wrong, not saved, stale) sit next to
   the numbers and are never folded into a count behind another headline; a headline may lead with an action (sign in
@@ -78,8 +90,10 @@ What the screen can say is decided for every state, as a pure function of the ap
   and accessibility violations fail the build. No new colours, boxes or spinners.
 - **Verified over the whole catalog.** Tests enumerate every state and bounded combinations through the real engine
   and `view`: placement holds, states needing different actions never render the same text, and no number is shown
-  without its claim-critical facts. Every state can also be drawn on its own at phone size (a gallery of the catalog),
-  so each display can be seen as rendered.
+  without its claim-critical facts. Every view an app's tests reach (replayed messages, the app's real page driven
+  headless) passes the kit's `viewProblems`: no broken value, "ok" only when every part is, claims kept whole, and
+  every working line's owed work under way. Every state can also be drawn on its own at phone size (a gallery of the
+  catalog), so each display can be seen as rendered.
 
 ## 4. Outside services
 
@@ -154,7 +168,9 @@ work up.
   overlap, interrupted commits, shared storage, identity changes, reconnects. More happy paths or seeds can't cover a missing failure dimension.
 - Headless correctness doesn't prove the UI binding: a renderer can drop a recovery button or swap actions while
   `view()` passes. Thin rendering and binding checks prove each action in `view` reaches the right command and each
-  warning is drawn, in each target browser (Safari and iOS PWA storage differ). A packed-consumer check proves the app
+  warning is drawn, on the app's real page driven headless, and in each target browser for what a DOM shim can't
+  show: layout and overflow, and platform bindings (a popup inside the tap, storage persistence, the service worker;
+  Safari and iOS PWA storage differ). A packed-consumer check proves the app
   runs the kit as shipped.
 - Tiers: pure model tests in milliseconds; a seeded headless end-to-end gate in seconds; adapter and binding checks; a
   read-only check of the deployed app on synthetic data.
@@ -202,7 +218,11 @@ Performance is a requirement, aimed at the limits of every service and system in
 - **Dependencies.** Few, from `DEPS.md`, so apps stay small. Few never means hand-rolled crypto, JWT, protocol parsers
   or weaker storage semantics: those use a vetted library (for example `jose`).
 - **Defaults:** IndexedDB in the browser (SQLite in the browser only where demonstrably better); SQLite on the server;
-  OIDC login, or Cloudflare Access's signed header where deployed; logins added in the UI.
+  logins to outside accounts added in the UI.
+- **Its own login.** An app signs people in itself, with OpenID Connect, and serves on a local binding. An
+  identity-aware proxy in front (Cloudflare Access's signed header) is an optional outer door, never the app's login.
+  A test identity (the kit's OIDC stand-in) signs in on a test home, so the app is proven end to end without a real
+  login.
 - **Look.** Brutalist, mobile-first PWAs: dense, monospace, black and white, no shadows or rounded corners.
 - Shipped source is generic: no hostnames, accounts or private data in code or docs; private data lives in the app's
   data directory and configuration.

package/dist/api.d.ts

@@ -0,0 +1,93 @@
+import type { Endpoint } from "./contract.ts";
+import type { Schema } from "./schema.ts";
+import type { Page, Pending, Receipt } from "./sync.ts";
+/** The answers the kit's server gives a command itself (`slopkit/server/sync`): an app's outcomes must admit them. */
+export type KitOutcome = {
+    kind: "failed";
+    reason: "conflict" | "forbidden";
+    message: string;
+} | {
+    kind: "retired";
+};
+/** Each row key's list, as a pull reply carries them. */
+export type Rows<R> = {
+    [K in keyof R]: R[K][];
+};
+export type PullRequest = {
+    client: string;
+    dataset: string | null;
+    since: number;
+    verify?: boolean;
+    page?: string | null;
+    commands?: {
+        client: string;
+        id: number;
+    }[];
+};
+export type PullReply<R, S, O> = Rows<R> & {
+    dataset: string;
+    revision: number;
+    reset: boolean;
+    commands: Receipt<O>[];
+    server: S;
+    checksum?: string;
+    page?: Page;
+};
+export type PushRequest<C> = {
+    client: string;
+    dataset: string | null;
+    since: number;
+    commands: {
+        id: number;
+        command: C;
+    }[];
+};
+export type PushReply<O> = {
+    results: Receipt<O>[];
+    revision: number;
+};
+export type TelemetryEvent = {
+    name: string;
+    at: string;
+    attributes?: Record<string, string | number | boolean | null>;
+};
+export type TelemetryRequest = {
+    client: string;
+    events: TelemetryEvent[];
+};
+/** What the socket sends: the server's revision, when it moves and as a heartbeat. */
+export type Poke = {
+    type: "poke";
+    revision: number;
+};
+export type SyncApi<R, S, C, O> = {
+    /** The row keys, in the order the fingerprint and the checksum digest them. */
+    rows: readonly (keyof R & string)[];
+    /** What the server says of itself, read with every pull. */
+    server: Schema<S>;
+    pull: Endpoint<PullRequest, PullReply<R, S, O>>;
+    push: Endpoint<PushRequest<C>, PushReply<O>>;
+    telemetry: Endpoint<TelemetryRequest, {
+        ok: true;
+    }>;
+    socket: {
+        path: string;
+        message: Schema<Poke>;
+    };
+    /** A command as a device's outbox keeps it, checked when read back. */
+    pending: Schema<Pending<C, O>>;
+};
+export declare function syncApi<R extends Record<string, {
+    id: string | number;
+}>, S, C, O>(definition: {
+    rows: {
+        [K in keyof R]: Schema<R[K]>;
+    };
+    server: Schema<S>;
+    command: Schema<C>;
+    outcome: Schema<O>;
+    /** A store's dataset id; default text of 1 to 200 characters. */
+    dataset?: Schema<string>;
+    /** A page's `through`, as the app formats an order group; default text of at most 64 characters. */
+    through?: Schema<string>;
+}): SyncApi<R, S, C, O>;

package/dist/api.js

@@ -0,0 +1,111 @@
+/**
+ * The sync contract's endpoints, built from an app's own schemas: pull (what changed since a revision, paged), push
+ * (commands, each acting once), telemetry (the page's counts and timings, for the server's log) and the socket's poke.
+ * The page, the server and the engine share these shapes, so an app declares only its rows, what its server says of
+ * itself, its commands and their outcomes.
+ */
+import { endpoint } from "./contract.js";
+import { array, boolean, literal, nullable, number, object, optional, record, scalar, string, variant, } from "./schema.js";
+import { PUSH_MAX } from "./sync.js";
+/** A reply's own fields: no row list may take one of their names. */
+const RESERVED = new Set([
+    "dataset",
+    "revision",
+    "reset",
+    "commands",
+    "server",
+    "checksum",
+    "page",
+]);
+const revision = number({ integer: true, min: 0 });
+const client = string({ pattern: /^[A-Za-z0-9_-]{8,64}$/ });
+const commandId = number({ integer: true, min: 1 });
+const cursor = string({ min: 1, max: 1000 });
+const iso = string({
+    pattern: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/,
+});
+export function syncApi(definition) {
+    const keys = Object.keys(definition.rows);
+    const taken = keys.find((key) => RESERVED.has(key));
+    if (taken !== undefined) {
+        throw new Error(`syncApi: a row key can't be a reply's own field: ${taken}`);
+    }
+    const dataset = definition.dataset ?? string({ min: 1, max: 200 });
+    const receipt = object({ id: commandId, outcome: definition.outcome, revision, client: optional(client) }, { strict: true });
+    const page = object({
+        from: nullable(cursor),
+        next: nullable(cursor),
+        through: nullable(definition.through ?? string({ max: 64 })),
+        held: number({ integer: true, min: 0 }),
+        total: number({ integer: true, min: 0 }),
+    }, { strict: true });
+    const lists = Object.fromEntries(Object.entries(definition.rows).map(([key, row]) => [key, array(row)]));
+    const reply = object({
+        dataset,
+        revision,
+        reset: boolean(),
+        ...lists,
+        commands: array(receipt),
+        server: definition.server,
+        checksum: optional(string({ pattern: /^[0-9a-f]{64}$/ })),
+        page: optional(page),
+    }, { strict: true });
+    const pull = endpoint("GET", "/api/pull", object({
+        client,
+        dataset: nullable(dataset),
+        since: revision,
+        verify: optional(boolean()),
+        page: optional(nullable(cursor)),
+        commands: optional(array(object({ client, id: commandId }, { strict: true }), { max: PUSH_MAX })),
+    }, { strict: true }), {
+        expected: reply.expected,
+        shape: reply.shape,
+        // SAFETY: `reply` is the strict object of exactly PullReply's fields: the fixed ones above and one array of
+        // each row schema under its key; the spread of `lists` is what TypeScript can't follow.
+        // oxlint-disable-next-line typescript/consistent-type-assertions, typescript/no-unsafe-type-assertion
+        parse: (value, path) => reply.parse(value, path),
+    });
+    const push = endpoint("POST", "/api/push", object({
+        client,
+        dataset: nullable(dataset),
+        since: revision,
+        commands: array(object({ id: commandId, command: definition.command }, { strict: true }), {
+            max: PUSH_MAX,
+        }),
+    }, { strict: true }), object({ results: array(receipt), revision }, { strict: true }));
+    const telemetry = endpoint("POST", "/api/telemetry", object({
+        client,
+        events: array(object({
+            name: string({ pattern: /^[a-z][a-z0-9.-]{0,63}$/ }),
+            at: iso,
+            attributes: optional(record(scalar())),
+        }, { strict: true }), { max: 100 }),
+    }, { strict: true }), object({ ok: literal(true) }, { strict: true }));
+    const message = variant("type", {
+        poke: object({ type: literal("poke"), revision }, { strict: true }),
+    });
+    const pending = object({
+        client,
+        id: commandId,
+        dataset: nullable(dataset),
+        since: optional(revision),
+        command: definition.command,
+        at: number(),
+        state: variant("kind", {
+            saving: object({ kind: literal("saving") }, { strict: true }),
+            queued: object({ kind: literal("queued") }, { strict: true }),
+            sending: object({ kind: literal("sending") }, { strict: true }),
+            unknown: object({ kind: literal("unknown"), failure: string(), parked: optional(literal(true)) }, { strict: true }),
+            done: object({ kind: literal("done"), outcome: definition.outcome, revision }, { strict: true }),
+        }),
+    }, { strict: true });
+    return {
+        rows: keys,
+        server: definition.server,
+        pull,
+        push,
+        telemetry,
+        socket: { path: "/api/socket", message },
+        pending,
+    };
+}

package/dist/client.d.ts

@@ -13,11 +13,15 @@ export declare class Replaced extends Error {
     constructor();
 }
 export type StoragePort<T, S, C, O> = {
-    /** The replica and the outbox; `unreadable` counts kept commands this version can't read (left on disk). */
+    /**
+     * The replica and the outbox; `unreadable` counts kept commands this version can't read (left on disk); `restart`
+     * when the copy owes a real reset before it is trusted (one lifted from an earlier release's row shapes).
+     */
     load: () => Promise<{
         replica: Replica<T, S>;
         commands: Pending<C, O>[];
         unreadable: number;
+        restart?: "paged";
     }>;
     /**
      * Commit a patch, decided against the disk inside its transaction; returns what the disk now holds, and `whole:

package/dist/conformance/agent-access.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/conformance/agent-access.test.js

@@ -0,0 +1,74 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test } from "vitest";
+import { endpoint } from "../contract.js";
+import { array, literal, object, string } from "../schema.js";
+import { parseWebConfig } from "../server/config.js";
+import { addKey } from "../server/keys.js";
+import { Log, scoped } from "../server/log.js";
+import { route, serveWeb } from "../server/web.js";
+import { agentAccess, reads, refused } from "../test/agents.js";
+import { identityProvider } from "../test/oidc.js";
+const cleanups = [];
+afterEach(async () => {
+    for (const close of cleanups.splice(0).toReversed()) {
+        await close();
+    }
+});
+const list = endpoint("GET", "/api/list", object({}), object({ items: array(string()) }));
+const grade = endpoint("POST", "/api/grade", object({ item: string() }), object({ ok: literal(true) }));
+const push = endpoint("POST", "/api/push", object({ item: string() }), object({ outcome: literal("done", "forbidden") }));
+/** An app on loopback with one key: `person` says which of its routes only a person's login may call. */
+async function app(person) {
+    const home = await mkdtemp(join(tmpdir(), "agent-access-"));
+    const provider = await identityProvider("owner");
+    const token = await addKey(home, "agent");
+    const server = await serveWeb({
+        home,
+        config: parseWebConfig({
+            port: 0,
+            oidc: { issuer: provider.issuer, clientId: "test" },
+            allow: ["sub:owner", "key:agent"],
+        }, []),
+        env: {},
+        log: scoped(new Log(home, "test", { echo: false }), "web"),
+        assets: home,
+        manifest: {},
+        cookie: "app_session",
+        routes: [
+            route({ ...list, person: person.list }, () => ({ items: ["a"] })),
+            route({ ...grade, person: person.grade }, () => ({ ok: true })),
+            route(push, (_request, caller) => ({ outcome: caller.person ? "done" : "forbidden" })),
+        ],
+    });
+    cleanups.push(async () => {
+        await server.close();
+        await provider.close();
+        await rm(home, { recursive: true, force: true });
+    });
+    return { url: server.url, token };
+}
+const cases = {
+    reads: [reads(list, {})],
+    refused: [
+        refused(grade, { item: "a" }),
+        refused(push, { item: "a" }, { refusal: (reply) => reply.outcome === "forbidden" }),
+    ],
+};
+test("an app whose key reads its agents' calls and is refused the person's passes", async () => {
+    const running = await app({ list: false, grade: true });
+    await expect(agentAccess({ ...running, ...cases })).resolves.toBeUndefined();
+});
+test("a person's call a key can make fails, naming it", async () => {
+    const running = await app({ list: false, grade: false });
+    await expect(agentAccess({ ...running, ...cases })).rejects.toThrow("POST /api/grade: a key should be refused, got an answer");
+});
+test("an agent's read a key can't make fails, naming it", async () => {
+    const running = await app({ list: true, grade: true });
+    await expect(agentAccess({ ...running, ...cases })).rejects.toThrow("GET /api/list: a key should read it, got forbidden");
+});
+test("a check with nothing to read or nothing refused proves nothing and fails", async () => {
+    const running = await app({ list: false, grade: true });
+    await expect(agentAccess({ ...running, reads: [], refused: cases.refused })).rejects.toThrow("proves nothing");
+});

package/dist/conformance/paging-state.test.js

@@ -11,6 +11,7 @@ const working = {
     why: "the copy is loading",
     text: () => "loading copy",
     action: null,
+    owes: () => ({ sync: true }),
 };
 const warning = {
     meaning: "ours",

package/dist/conformance/states.test.js

@@ -45,6 +45,7 @@ const table = {
         why: "Tap waits, numbers unchanged",
         text: () => "keeping the tap",
         action: null,
+        owes: null,
     },
 };
 const kit = () => states({ order });
@@ -288,14 +289,24 @@ describe("states: independent conformance", () => {
                         text: () => meaning,
                         action: null,
                     }
-                    : {
-                        meaning,
-                        where: "main",
-                        claim: false,
-                        why: "An obligation",
-                        text: () => meaning,
-                        action: null,
-                    },
+                    : meaning === "working"
+                        ? {
+                            meaning,
+                            where: "main",
+                            claim: false,
+                            why: "An obligation",
+                            text: () => meaning,
+                            action: null,
+                            owes: null,
+                        }
+                        : {
+                            meaning,
+                            where: "main",
+                            claim: false,
+                            why: "An obligation",
+                            text: () => meaning,
+                            action: null,
+                        },
         })
             .line({ kind: "x" }));
         for (let i = 0; i < subjects.length; i++) {

package/dist/server/auth.d.ts

@@ -12,15 +12,16 @@ export declare class WebAuth {
     private writing;
     private readonly pending;
     private readonly env;
+    private readonly keys;
     constructor(config: WebConfig, home: string, env: Readonly<Record<string, string | undefined>>);
     get oidc(): boolean;
     private allowed;
     /**
-     * The allowed identities of a request: from the proxy's JWT when it sends one (a bad one is refused, never ignored),
-     * else from the session token (the session cookie's value). `undefined` means not signed in; `false`, signed in but
+     * The allowed identities of a request: from an agent's bearer key when it sends one, else the proxy's JWT when it
+     * sends one (a bad one of either is refused, never ignored), else from the session token (the session cookie's value). `undefined` means not signed in; `false`, signed in but
      * not allowed.
      */
-    identify(proxyJwt: string | undefined, token: string | undefined): Promise<Identities | false | undefined>;
+    identify(proxyJwt: string | undefined, token: string | undefined, bearer?: string): Promise<Identities | false | undefined>;
     private discover;
     /** Where to send a browser to sign in, with PKCE; `redirect` is this server's own callback URL. */
     loginUrl(redirect: string): Promise<string>;

package/dist/server/auth.js

@@ -1,12 +1,13 @@
 /**
- * Who a web request is: Cloudflare Access's signed JWT (`Cf-Access-Jwt-Assertion`), or a session from this server's
- * own OpenID Connect login (authorization code with PKCE). The issuer, audience and claims come from `web.json`.
- * Either way the identity must be on `web.allow`.
+ * Who a web request is: an agent's key (`Authorization: Bearer`, see `keys.ts`), Cloudflare Access's signed JWT
+ * (`Cf-Access-Jwt-Assertion`), or a session from this server's own OpenID Connect login (authorization code with
+ * PKCE). The issuer, audience and claims come from `web.json`. Either way the identity must be on `web.allow`.
  */
 import { createHash, randomBytes } from "node:crypto";
 import { readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createRemoteJWKSet, jwtVerify } from "jose";
+import { Keys } from "./keys.js";
 const SESSION_DAYS = 7;
 const PENDING_MS = 10 * 60_000;
 /** A claim by dotted path, as a string, or `undefined`. */
@@ -42,6 +43,7 @@ export class WebAuth {
     writing = Promise.resolve();
     pending = new Map();
     env;
+    keys;
     constructor(config, home, env) {
         if (config.access === undefined && config.oidc === undefined) {
             throw new Error("web needs a login: set web.access (an identity-aware proxy) or web.oidc in web.json");
@@ -52,6 +54,7 @@ export class WebAuth {
         this.config = config;
         this.env = env;
         this.sessionsPath = join(home, "web-sessions.json");
+        this.keys = new Keys(home);
         this.accessKeys =
             config.access === undefined
                 ? undefined
@@ -66,11 +69,16 @@ export class WebAuth {
             : undefined;
     }
     /**
-     * The allowed identities of a request: from the proxy's JWT when it sends one (a bad one is refused, never ignored),
-     * else from the session token (the session cookie's value). `undefined` means not signed in; `false`, signed in but
+     * The allowed identities of a request: from an agent's bearer key when it sends one, else the proxy's JWT when it
+     * sends one (a bad one of either is refused, never ignored), else from the session token (the session cookie's value). `undefined` means not signed in; `false`, signed in but
      * not allowed.
      */
-    async identify(proxyJwt, token) {
+    async identify(proxyJwt, token, bearer) {
+        // A bearer decides alone: one that doesn't verify is refused, never passed over for a cookie or a proxy's header.
+        if (bearer !== undefined) {
+            const name = await this.keys.verify(bearer);
+            return name === undefined ? false : (this.allowed([`key:${name}`]) ?? false);
+        }
         if (proxyJwt !== undefined) {
             const access = this.config.access;
             if (access === undefined || this.accessKeys === undefined) {