@nervur-org/dock 0.3.0

package/dist/beings/desk.d.ts

@@ -0,0 +1,53 @@
+import { Being } from '@nervur-org/nervur';
+import type { Asker, Blueprint, JsonObject, Reply, Stance } from '@nervur-org/nervur';
+export declare class Desk extends Being {
+    static asks: {
+        hello: {
+            description: string;
+            input: {
+                type: string;
+            };
+        };
+        send: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    kind: {
+                        type: string;
+                    };
+                    to: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        device: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    proof: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+    };
+    constructor(stance: Stance);
+    get ways(): {
+        id: string;
+        kind: string;
+    }[];
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+    describe(asker: Asker): Blueprint;
+    hello(_args: JsonObject, asker: Asker): {
+        desk: boolean;
+        asker: string | null;
+        kinds: string[];
+    };
+    send(args: JsonObject): Promise<JsonObject>;
+    device(args: JsonObject): Promise<import("@nervur-org/nervur").Json>;
+}

package/dist/beings/desk.js

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: Apache-2.0
+// The front desk. The one public being of a world, and public for the first
+// hello only: everything after is behind an invitation. It holds a standing
+// to every user being, placed by the root, and trades a proof for a device
+// invitation that the user being mints herself. The desk never mints one.
+//
+// A proof is what a route produced after authenticating by its own means. A
+// way in turns a proof of one kind into who it is for: which user, which
+// client identity. The ways in are beings, and the desk reaches each of
+// them as she reaches anything, at a standing under `way:<kind>`: the
+// world's own, placed by the root, and the box's, lent by the dock ward and
+// taken at her birth, so a box with no local side offers no such kind.
+//
+// A kind whose proof the world has to hand out first answers `send` beside
+// `verify`, and a stranger asks for one with `send({ kind, to })`. The desk
+// judges nothing here: she does not know what an address is, whether one was
+// sent to before, or what a link says. She keeps the ways in named in one
+// place, so a side that renders her renders every way into this world.
+import { Being, isSilence, isWord, wordOf } from '@nervur-org/nervur';
+import { join } from '../dock/faculty.js';
+import { LOCAL } from '../dock/local.js';
+import { WAY, kindOf, verified } from './way.js';
+export class Desk extends Being {
+    static asks = {
+        hello: { description: 'how to get in', input: { type: 'object' } },
+        send: { description: 'send a way in to an address of yours', input: { type: 'object', properties: { kind: { type: 'string' }, to: { type: 'string' } }, required: ['kind', 'to'] } },
+        device: { description: 'trade a proof for a device invitation', input: { type: 'object', properties: { proof: { type: 'object' } }, required: ['proof'] } },
+    };
+    // The box's way in, taken at every birth as any being takes what her box
+    // lends. A box that lends none, a tab or the edge, leaves her holding
+    // nothing under that id and the kind is not offered.
+    constructor(stance) {
+        super(stance);
+        void join(this, LOCAL, undefined, WAY(LOCAL));
+    }
+    // The ids of the ways in she holds, in the order they were placed.
+    get ways() {
+        const out = [];
+        for (const id of Object.keys(this.cells.standings)) {
+            const kind = kindOf(id);
+            if (kind !== null && this.standings[id])
+                out.push({ id, kind });
+        }
+        return out;
+    }
+    // Before she is described, she learns what her ways in can be asked. A
+    // standing's blueprint is filled by an empty ask and by nothing else, and
+    // a way in placed on her a moment ago has none yet; each is asked once,
+    // and a way in that will not describe stays a kind she can only verify.
+    async answer(asker, method, args = {}) {
+        if (method === undefined)
+            for (const w of this.ways)
+                if (this.cells.standings[w.id]?.blueprint === null)
+                    await this.standings[w.id]?.ask();
+        return await super.answer(asker, method, args);
+    }
+    // The kinds are the ways in she holds and change with them, so the form a
+    // stranger sees is shaped now rather than declared once: `send` is there
+    // only where a way in says it can be asked to send, and it names the kinds
+    // that can. A world with none shows no such form, and a link is the only
+    // way in, as it always was.
+    describe(asker) {
+        const bp = super.describe(asker);
+        const kinds = this.ways.filter((w) => this.cells.standings[w.id]?.blueprint?.asks.some((a) => a.name === 'send')).map((w) => w.kind);
+        const asks = bp.asks.flatMap((a) => {
+            if (a.name !== 'send')
+                return [a];
+            if (kinds.length === 0)
+                return [];
+            return [{ ...a, input: { type: 'object', properties: { kind: { type: 'string', enum: kinds, default: kinds[0] }, to: { type: 'string' } }, required: ['kind', 'to'] } }];
+        });
+        return { ...bp, asks };
+    }
+    // A stranger learns the proof kinds and nothing else. Who lives on this
+    // world is not the caller's to know: the way in names the user, so
+    // nobody at the door ever has to, and a world with a thousand of them
+    // would otherwise hand the whole list to anyone who knocked.
+    hello(_args, asker) {
+        return { desk: true, asker: asker.id ?? null, kinds: this.ways.map((w) => w.kind) };
+    }
+    // A stranger asks for a way in to an address that is hers. Nothing of this
+    // world changes here and nothing is minted: the way in sends, and the
+    // proof that comes back is what admits her.
+    async send(args) {
+        const { kind, to } = args;
+        if (typeof kind !== 'string' || typeof to !== 'string')
+            return { error: 'kind and to are words' };
+        const way = this.standings[WAY(kind)];
+        if (!way)
+            return { error: 'no such way in' };
+        const out = await way.ask('send', { to });
+        if (isSilence(out) || isWord(out))
+            return { error: 'no such way in' };
+        return out;
+    }
+    async device(args) {
+        const proof = args.proof;
+        if (!proof || typeof proof !== 'object' || Array.isArray(proof) || typeof proof.kind !== 'string')
+            return { error: 'proof has a kind' };
+        // A kind this world holds no way in for and a way in that says no are
+        // one refusal, because the difference between them is a list a stranger
+        // could walk. Only a way in that sends for itself is named at this door,
+        // in its own form's kinds; a way in that only verifies, as a device's
+        // local nonce does, is named nowhere, and two errors here would name it
+        // to anyone who guessed the word.
+        const way = this.standings[WAY(proof.kind)];
+        const said = way ? await way.ask('verify', { proof }) : null;
+        const who = said === null || isSilence(said) || isWord(said) ? null : verified(said);
+        if (!who)
+            return { error: 'refused' };
+        const id = `user:${who.user}`;
+        // A way in that brings its own people: the first proof for a user nobody
+        // has booted makes her, and the desk holds her standing because she is
+        // the desk's to make. She learns her name the way the root's setup names
+        // her, by the desk's first hello, since a being does not know her own
+        // key. A way in that does not say `make` reaches an existing household
+        // and nothing else, which is what the local kind on a device does.
+        if (!this.standings[id] && (who.make === true || typeof who.make === 'string')) {
+            if (!/^[\w.-]{1,80}$/.test(who.user) || who.user === 'desk')
+                return { error: 'a user is a word, and not desk' };
+            if ((await this.boot(typeof who.make === 'string' ? who.make : 'User', who.user, id)) === null)
+                return { error: 'no such user' };
+            await this.standings[id].ask('hello', { name: who.user });
+        }
+        const user = this.standings[id];
+        if (!user)
+            return { error: 'no such user' };
+        const inv = await user.ask('device', { client: who.client, ...(who.wake === true ? { wake: true } : {}), ...(who.reach === true ? { reach: true } : {}), ...(who.mint === true ? { mint: true } : {}), ...(who.revoke === true ? { revoke: true } : {}) });
+        if (isSilence(inv))
+            return { error: 'silence' };
+        if (isWord(inv))
+            return { error: wordOf(inv) };
+        return inv;
+    }
+}

package/dist/beings/doorbell.d.ts

@@ -0,0 +1,78 @@
+import { Being } from '@nervur-org/nervur';
+import type { Asker, JsonObject, OccupantRecord } from '@nervur-org/nervur';
+declare const isDevice: (occ: OccupantRecord | undefined) => boolean;
+declare const isWorld: (occ: OccupantRecord | undefined) => boolean;
+declare const isMaker: (occ: OccupantRecord | undefined) => occ is OccupantRecord;
+export declare class Doorbell extends Being {
+    static cells: JsonObject;
+    static asks: {
+        claim: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: typeof isMaker;
+        };
+        keep: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    token: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof isDevice;
+        };
+        admit: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: typeof isDevice;
+        };
+        drop: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    world: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof isDevice;
+        };
+        allowed: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: typeof isDevice;
+        };
+        ring: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    sealed: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof isWorld;
+        };
+    };
+    describe(asker: Parameters<Being['describe']>[0]): import("@nervur-org/nervur").Blueprint;
+    claim(_args: JsonObject, asker: Asker): Promise<JsonObject>;
+    keep(args: JsonObject): JsonObject;
+    admit(_args: JsonObject): Promise<JsonObject>;
+    drop(args: JsonObject): JsonObject;
+    allowed(_args: JsonObject): JsonObject;
+    ring(args: JsonObject): Promise<JsonObject>;
+}
+export {};

package/dist/beings/doorbell.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: Apache-2.0
+// One device's doorbell. The platform token lives in her cells and leaves
+// for nowhere: no world ever sees it, so no world can copy it, hand it on,
+// or keep ringing after it is told to stop.
+//
+// Her occupants are the worlds that device allowed. `device` is the phone
+// itself, and every other id is one world, invited by the phone and by
+// nobody else. The pair, this device and that world, is a row here, held by
+// neither the world that rings nor the publisher who holds the platform
+// key. That row is the whole of the permission.
+//
+// She is made by the porter, who holds a standing to her and asks once for
+// the device's way in. After a device has claimed it there is nothing the
+// porter can do here at all, which is why `claim` closes itself.
+//
+// A ring carries a banner sealed to the device's banner key. She checks
+// that it fits what the platform will carry and hands it on, and could not
+// read it if she tried.
+//
+// She never learns that key, and there is nothing here for it to be kept
+// in. The device hands its banner key to a world itself, beside the
+// invitation to this doorbell, so a bell that held both halves of the
+// relation is a bell that could read a banner, and this one cannot.
+import { Being, isSilence, isWord, wordOf } from '@nervur-org/nervur';
+const DEVICE = 'device';
+// Her standing at the box's push faculty, under an id of her own. The ward
+// knocks and takes it for her, and the invitation never reaches her.
+const MINE = 'push';
+// What a platform will carry. It is the faculty's number, because the
+// faculty is the one that hands a ring to a platform.
+import { SEAL } from '../dock/push.js';
+const isDevice = (occ) => occ?.id === DEVICE;
+const isWorld = (occ) => occ !== undefined && occ.id !== DEVICE;
+const isMaker = (occ) => occ !== undefined;
+export class Doorbell extends Being {
+    static cells = { token: null, admitted: 0, claimed: false };
+    static asks = {
+        claim: { description: 'the one way in for this doorbell, handed out once', input: { type: 'object' }, for: isMaker },
+        keep: { description: 'the device hands its platform token, for nobody else', input: { type: 'object', properties: { token: { type: 'object' } }, required: ['token'] }, for: isDevice },
+        admit: { description: 'the device allows one world to wake it', input: { type: 'object' }, for: isDevice },
+        drop: { description: 'the device disallows one world, and only that one', input: { type: 'object', properties: { world: { type: 'string' } }, required: ['world'] }, for: isDevice },
+        allowed: { description: 'which worlds this device allows', input: { type: 'object' }, for: isDevice },
+        ring: { description: 'wake this device: a sealed payload and nothing else', input: { type: 'object', properties: { sealed: { type: 'string' } }, required: ['sealed'] }, for: isWorld },
+    };
+    // Once a device holds this doorbell there is no way in left to hand out,
+    // so the ask goes from every blueprint rather than sitting there dead.
+    describe(asker) {
+        const out = super.describe(asker);
+        if (this.cells.claimed !== true)
+            return out;
+        return { ...out, asks: out.asks.filter((a) => a.name !== 'claim') };
+    }
+    // The way in, handed out once and then gone. Whoever made her asks for it
+    // and gives it to the phone; a second ask is refused, so there is no
+    // second key to this device anywhere.
+    async claim(_args, asker) {
+        if (this.cells.claimed === true)
+            return { error: 'this doorbell has a device' };
+        const inv = await this.invite(DEVICE);
+        if (inv === null)
+            return { error: 'no way in' };
+        this.cells.claimed = true;
+        // And she leaves. Whoever made this doorbell has nothing here once the
+        // way in is handed out, so she is not left standing in the list of who
+        // may wake this phone.
+        const maker = this.occupant(asker);
+        if (maker)
+            this.occupants.remove(maker.id);
+        return { invitation: inv };
+    }
+    // Written once and rewritten whenever the platform hands the phone a new
+    // one. No world is told anything, because no world was ever given it.
+    keep(args) {
+        const token = args.token;
+        if (token === null || typeof token !== 'object' || Array.isArray(token) || typeof token.kind !== 'string')
+            return { error: 'a token names its kind' };
+        this.cells.token = token;
+        return { kept: token.kind };
+    }
+    // The device allows a world by asking for a way in and handing it over.
+    // So a world can only ring a phone that chose it.
+    async admit(_args) {
+        const admitted = typeof this.cells.admitted === 'number' ? this.cells.admitted : 0;
+        const world = `world:${admitted + 1}`;
+        const inv = await this.invite(world);
+        if (inv === null)
+            return { error: 'no way in' };
+        this.cells.admitted = admitted + 1;
+        return { world, invitation: inv };
+    }
+    // Disallowing is removing one occupant. The heir is forgotten, that world
+    // hears `removed` once at the door, and her other worlds are untouched.
+    drop(args) {
+        const world = args.world;
+        if (typeof world !== 'string' || world === DEVICE)
+            return { error: 'a world is named, and the device is not one' };
+        if (!Object.hasOwn(this.cells.occupants, world))
+            return { error: 'no such world' };
+        this.occupants.remove(world);
+        return { dropped: world };
+    }
+    allowed(_args) {
+        return { worlds: Object.keys(this.cells.occupants).filter((id) => id !== DEVICE) };
+    }
+    // Who is ringing is the standing it arrived on, so the ask carries no
+    // world, no pk and no token, and there is nothing in it to forge.
+    async ring(args) {
+        const sealed = args.sealed;
+        if (typeof sealed !== 'string' || sealed.length === 0)
+            return { error: 'a ring carries one sealed payload' };
+        if (sealed.length > SEAL)
+            return { error: `a sealed payload is at most ${SEAL} bytes` };
+        const token = this.cells.token;
+        if (token === null)
+            return { error: 'this device has handed no token' };
+        const at = this.standings[MINE] ?? (await this.lend(MINE, MINE).then(() => this.standings[MINE]));
+        if (!at)
+            return { error: 'this box rings nothing' };
+        const out = await at.ask('ring', { token, sealed });
+        if (out === undefined || isSilence(out))
+            return { error: 'this box rings nothing' };
+        if (isWord(out))
+            return { error: wordOf(out) };
+        // What the faculty says is the answer, and a refusal is one of the things
+        // it says: a box holding no key for this kind, or a service that would
+        // not take the ring. Passing that on is the whole of the promise a bell
+        // makes, because a ring reported as rung and never sent is worse than one
+        // that plainly failed: the world stops trying and the human is never told.
+        if (out !== null && typeof out === 'object' && !Array.isArray(out) && typeof out.error === 'string')
+            return { error: out.error };
+        return { rang: true };
+    }
+}

package/dist/beings/envoy.d.ts

@@ -0,0 +1,54 @@
+import { Being } from '@nervur-org/nervur';
+import type { Asker, AskSpec, JsonObject, OccupantRecord } from '@nervur-org/nervur';
+export declare const owner: (_rec: OccupantRecord | undefined, asker: Asker) => boolean;
+export declare const occupant: (rec: OccupantRecord | undefined) => boolean;
+export declare const places: (rec: OccupantRecord | undefined, asker: Asker) => boolean;
+export declare const CREDENTIAL: (properties: Record<string, JsonObject>, required: string[]) => AskSpec;
+export type Delivery = {
+    id: string;
+    kind: string;
+    about: string | null;
+    data: JsonObject;
+};
+export type Wake = {
+    method: string;
+    args: JsonObject;
+};
+export type Heard = {
+    ok: boolean;
+    status: number;
+    body: JsonObject;
+};
+export declare class Envoy extends Being {
+    #private;
+    static cells: JsonObject;
+    static asks: Record<string, AskSpec>;
+    static IN: Record<string, AskSpec>;
+    protected check(c: JsonObject): string | null;
+    static at: string | null;
+    credential(args: JsonObject, asker: Asker): JsonObject;
+    forget(): JsonObject;
+    protected get held(): JsonObject | null;
+    protected out(path: string, init?: {
+        method?: string;
+        body?: JsonObject;
+        headers?: Record<string, string>;
+    }): Promise<Heard>;
+    protected refused(h: Heard): JsonObject;
+    protected remember(vendorId: string, by: string, more?: JsonObject): void;
+    protected recall(vendorId: string): (JsonObject & {
+        by: string;
+    }) | undefined;
+    deliver(args: JsonObject): Promise<JsonObject>;
+    protected verify(_body: string, _headers: Record<string, string>): Promise<boolean> | boolean;
+    protected decode(_body: string, _headers: Record<string, string>): Delivery | {
+        error: string;
+    };
+    protected landed(_query: string, _headers: Record<string, string>): JsonObject | Promise<JsonObject>;
+    protected hmac(secret: string, text: string): Promise<string>;
+    protected fresh(ts: string | number): boolean;
+    protected wake(_d: Delivery, _about: (JsonObject & {
+        by: string;
+    }) | undefined): Wake | null;
+    get unwoken(): JsonObject[];
+}

package/dist/beings/envoy.js

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: Apache-2.0
+// The envoy base: what every envoy is and no envoy has alone. An envoy is
+// a being of the org's standing in for a ward she does not run, an account
+// at a thing that speaks no Quo, and the trunk's envoy chapter says the
+// seven things she is. This is those seven as one class an author extends,
+// so that a vendor's envoy is her asks out, her signature and her decoding,
+// and nothing else.
+//
+// Two gates, one credential, one way out, one way in, one memory, one way
+// back. `credential` and `forget` are the owner's; `deliver`, for an envoy
+// that is called in, is the owner's too, and the daemon asks it with the
+// vendor's raw bytes and headers. What an occupant may ask is the class's
+// asks out, gated by `occupant` or by her own reading of the notes.
+//
+// Nothing here knows a vendor's name. The signature is `verify`, the
+// vocabulary is `decode`, and what a delivery wakes is `wake`, each a
+// method the class fills; the base keeps the discipline around them: the
+// bytes checked before anything is parsed, the id kept bounded so a retry
+// lands once, `{ ok }` answered before the wake goes out, a wake that meets
+// silence written down and never retried.
+import { Being, isSilence, isWord, wordOf } from '@nervur-org/nervur';
+// The two gates. The owner is the ward's ask pointer, `{ id: 'OWNER' }`,
+// which is how the daemon asks `deliver` and how the root places a
+// credential; an occupant is anyone holding a standing at her.
+export const owner = (_rec, asker) => asker.id === 'OWNER';
+export const occupant = (rec) => rec !== undefined;
+// The third gate: who may place what the vendor gave this account. WORLDS
+// has placing an envoy as an ask on home, shown by the gate to the org's
+// presences and to its model, with the box never logged into for it, so
+// this cannot be the owner alone. It is the owner or an occupant whose
+// note says she may, placed with her standing the way every other note is,
+// and it is never a default: an org that marked nobody has the root's
+// shell and nothing else, which is where this began.
+export const places = (rec, asker) => asker.id === 'OWNER' || rec?.notes.credential === true;
+// A credential as a form, for a class that wants one. `at` is never among
+// the fields and cannot be: it is where this box sends the org's key, so a
+// form that set it would be a form that points the box at anywhere and
+// makes it fetch there with the account's own secret. Where a vendor
+// answers is the class's, since the class is the thing that speaks that
+// vendor, and only the owner may name another.
+export const CREDENTIAL = (properties, required) => ({
+    description: 'what the vendor gave this account: kept in her cells, and never shown again',
+    input: { type: 'object', properties, required },
+    for: places,
+});
+const SEEN = 200;
+const FRESH = 5 * 60_000;
+export class Envoy extends Being {
+    static cells = { credential: null, about: {}, seen: [], unwoken: [] };
+    static asks = {
+        credential: { description: 'what the vendor gave the account: kept in her cells, never shown', input: { type: 'object' }, for: places },
+        forget: { description: 'forget the credential', input: { type: 'object' }, for: places },
+    };
+    // The one ask in, for an envoy the vendor calls: a class that is called
+    // in spreads it into her asks, `{ ...Envoy.asks, ...Envoy.IN, ...hers }`,
+    // and a one-way envoy shows no deliver at all.
+    static IN = {
+        deliver: { description: 'the vendor delivers: its raw bytes and headers, from the daemon as the owner', input: { type: 'object', properties: { body: { type: 'string' }, headers: { type: 'object' } }, required: ['body', 'headers'] }, for: owner },
+    };
+    // 1. Her credential is in her cells, and she gets it herself. The owner
+    // places what the vendor gave, values only; `check` is the class's word
+    // on what it must hold, a reason or null.
+    check(c) {
+        for (const [k, v] of Object.entries(c))
+            if (typeof v !== 'string' || v === '')
+                return `${k} is a non-empty string`;
+        return Object.keys(c).length ? null : 'a credential has at least one field';
+    }
+    // Where the vendor answers, as the class that speaks that vendor knows
+    // it. A class that leaves it null has an owner who must name one once.
+    static at = null;
+    credential(args, asker) {
+        // `at` is the one field a form may not carry. From anyone but the
+        // owner it is dropped rather than refused, since a human pasting a key
+        // has said nothing about it either way, and what stands is the one
+        // already placed or the class's own.
+        const { at: named, ...rest } = args;
+        const at = asker.id === 'OWNER' && typeof named === 'string' ? named : (this.held?.at ?? this.constructor.at);
+        const c = { ...rest, ...(typeof at === 'string' ? { at } : {}) };
+        const why = this.check(c);
+        if (why)
+            return { error: why };
+        this.cells.credential = c;
+        return { kept: true };
+    }
+    forget() {
+        this.cells.credential = null;
+        return { kept: false };
+    }
+    get held() {
+        return this.cells.credential ?? null;
+    }
+    // 2. Her asks out are the vendor's surface, narrowed: one fetch, from
+    // `at` in her credential with `key` as the bearer, the answer as values.
+    // The class reshapes what it heard and passes nothing through raw.
+    async out(path, init = {}) {
+        const c = this.held;
+        if (!c || typeof c.at !== 'string')
+            return { ok: false, status: 0, body: { error: 'no credential: the owner has not placed one' } };
+        let r;
+        try {
+            r = await fetch(`${c.at}${path}`, {
+                method: init.method ?? (init.body ? 'POST' : 'GET'),
+                headers: { ...(typeof c.key === 'string' ? { authorization: `Bearer ${c.key}` } : {}), ...(init.body ? { 'content-type': 'application/json' } : {}), ...(init.headers ?? {}) },
+                ...(init.body ? { body: JSON.stringify(init.body) } : {}),
+            });
+        }
+        catch {
+            return { ok: false, status: 0, body: { error: 'the vendor is unreachable' } };
+        }
+        const v = (await r.json().catch(() => ({})));
+        const body = v !== null && typeof v === 'object' && !Array.isArray(v) ? v : {};
+        return { ok: r.ok, status: r.status, body };
+    }
+    // The vendor's no, as an error object in her own words.
+    refused(h) {
+        return h.status === 0 ? h.body : { error: `the vendor refused: ${h.status}${typeof h.body.message === 'string' ? ` ${h.body.message}` : ''}` };
+    }
+    // 4. Her cells are what the vendor told her: the map from the vendor's id
+    // to whom it is about, written when she asked out, read when called in.
+    remember(vendorId, by, more = {}) {
+        this.cells.about[vendorId] = { by, ...more };
+    }
+    recall(vendorId) {
+        const m = this.cells.about;
+        return Object.hasOwn(m, vendorId) ? m[vendorId] : undefined;
+    }
+    // 3. `deliver` is her one ask in. The daemon asks it as the owner with
+    // the raw body and the headers; an empty body is a redirect landing,
+    // the query in the headers under `:query`. The signature is checked
+    // before anything is parsed; a delivery she has seen is `{ ok }` at once
+    // and wakes nobody twice; and 6, `{ ok }` goes back before the wake.
+    async deliver(args) {
+        const body = typeof args.body === 'string' ? args.body : '';
+        const headers = (args.headers && typeof args.headers === 'object' && !Array.isArray(args.headers) ? args.headers : {});
+        if (body === '')
+            return this.landed(headers[':query'] ?? '', headers);
+        if (!(await this.verify(body, headers)))
+            return { error: 'bad signature' };
+        const d = this.decode(body, headers);
+        if ('error' in d)
+            return d;
+        const seen = this.cells.seen;
+        const mark = `${d.kind}:${d.id}`;
+        if (seen.includes(mark))
+            return { ok: true };
+        seen.push(mark);
+        while (seen.length > SEEN)
+            seen.shift();
+        void this.#wake(d);
+        return { ok: true };
+    }
+    // The class's word on the vendor's signature, over the bytes as sent.
+    verify(_body, _headers) {
+        return false;
+    }
+    // The class's reading of the vendor's vocabulary.
+    decode(_body, _headers) {
+        return { error: 'not called in' };
+    }
+    // Where a redirect lands: an OAuth code in the query, for a class that
+    // begins its account that way. The base takes nothing from it.
+    landed(_query, _headers) {
+        return { ok: true };
+    }
+    // A signature over text with a shared secret, hex, the shape most
+    // vendors sign in: here once so a class writes the vendor's framing only.
+    async hmac(secret, text) {
+        const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+        return [...new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(text)))].map((x) => x.toString(16).padStart(2, '0')).join('');
+    }
+    // Whether a vendor's timestamp is within five minutes of now, in seconds
+    // or in milliseconds, since vendors sign in either and a class should
+    // not have to know which.
+    fresh(ts) {
+        const t = Number(ts);
+        if (!Number.isFinite(t))
+            return false;
+        const ms = t < 1e11 ? t * 1000 : t;
+        return Math.abs(Date.now() - ms) <= FRESH;
+    }
+    // 5. Her way back is a standing placed like any other, `to:<id>` for the
+    // occupant a vendor id was remembered for, handed to her at the knock.
+    // A delivery is one ask on it, in her own words, said by `wake`; the
+    // being woken cannot tell it from a clock.
+    wake(_d, _about) {
+        return null;
+    }
+    async #wake(d) {
+        const about = d.about === null ? undefined : this.recall(d.about);
+        const w = this.wake(d, about);
+        if (!w)
+            return;
+        const unwoken = this.cells.unwoken;
+        // a wake the class shaped wrong is written down, never dropped on the floor
+        if (typeof w.method !== 'string' || !w.method || w.args === null || typeof w.args !== 'object')
+            return void unwoken.push({ id: d.id, kind: d.kind, why: 'a wake is { method, args }' });
+        const back = about ? this.standings[`to:${about.by}`] : undefined;
+        if (!back)
+            return void unwoken.push({ id: d.id, kind: d.kind, why: about ? `no way back to ${about.by}` : 'about nobody she remembers' });
+        const out = await back.ask(w.method, w.args);
+        if (isSilence(out) || out === undefined)
+            unwoken.push({ id: d.id, kind: d.kind, why: 'silence' });
+        else if (isWord(out))
+            unwoken.push({ id: d.id, kind: d.kind, why: wordOf(out) });
+    }
+    // What she could not wake, for the device's own code and a suite.
+    get unwoken() {
+        return this.cells.unwoken;
+    }
+}