@nervur-org/dock 0.4.1 → 0.6.0

package/dist/dock/faculty.js

@@ -1,142 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// A faculty: one being of the dock ward, standing for one thing the box can
-// do. She is a being and nothing else, so what is here is not a second kind
-// of object but the two moves every faculty shares.
-//
-// Out: whoever holds a standing at her asks her methods, and the occupant's
-// notes say what that caller is, a prefix on a store, an account at a
-// vendor. Her own cells say what the thing is.
-//
-// Back: `watch` is the one subscribe verb every faculty has. A being who
-// wants waking mints an invitation and hands it over, this takes it as a
-// standing, and from then on she is asked at her own door as the occupant
-// she named. `occupants.remove` on her side is the whole of unsubscribe: the
-// next wake hears `removed` and the row goes.
-//
-// She holds what the box holds and begins holding it at birth: the
-// connection, the interval, the worker, the route are opened in her
-// constructor, and she is born whether or not the thing is reachable,
-// answering an error object while it is not.
-import { Being, isInvitation, isSilence, isWord, wordOf } from 'nervur';
-export class Faculty extends Being {
-    static cells = { watched: {}, minted: 0 };
-    // Someone wants waking. She hands the invitation she minted and says what
-    // to ask her; this knocks it, takes it under an id of this being's own,
-    // and files it. The id never crosses: it is this side's name for the
-    // relation, and the caller's name for the same relation is her own.
-    //
-    // The empty ask is the knock, because every being answers one and asking
-    // for a named ask would make every subscriber owe a method she does not
-    // otherwise need.
-    async watch(args, asker) {
-        const inv = args.invitation;
-        if (!isInvitation(inv) || typeof args.method !== 'string')
-            return { error: 'an invitation and a method' };
-        const extra = args.args;
-        if (extra !== undefined && (extra === null || typeof extra !== 'object' || Array.isArray(extra)))
-            return { error: 'args is one object' };
-        const out = await this.knock(inv);
-        if (isSilence(out) || isWord(out))
-            return { error: 'no way back' };
-        const cells = this.cells;
-        const id = await this.take(`wake:${(cells.minted += 1)}`, inv);
-        if (id === null)
-            return { error: 'not taken' };
-        cells.watched[id] = { by: asker.id ?? '', method: args.method, args: extra ?? {} };
-        await this.welcomed(id);
-        return { watching: id };
-    }
-    // Somebody new is filed, and the answer to her `watch` waits for this. A
-    // faculty that owes a new subscriber something at once says it here: the
-    // timer wakes her, learns when she is next due and arms the box for it, so
-    // a being born long after the box was up is not waiting for a round nobody
-    // scheduled. Most faculties owe nothing, and this is why they say nothing.
-    async welcomed(_id) { }
-    // One round of waking. Each subscriber is asked what she asked to be
-    // asked, with whatever this round adds. A subscriber who removed the
-    // occupant says `removed` once, and her row goes with the standing; there
-    // is nothing to retry and nothing to remember.
-    //
-    // `only` is one subscriber of the round's own choosing, named by this
-    // being's own id for the relation, and it is the same round down to one
-    // row: a faculty that wakes somebody just filed learns exactly what a full
-    // round would have learned about her.
-    //
-    // `dropped` is this being herself: her ward took her out, so the standings
-    // she holds reach nobody. Null says so, and whoever holds the interval puts
-    // it down rather than waking an empty room for as long as the box is up.
-    async woke(round = (w) => w.args, only) {
-        const cells = this.cells;
-        const out = [];
-        for (const [id, w] of Object.entries(cells.watched)) {
-            if (only !== undefined && id !== only)
-                continue;
-            const said = await this.standings[id]?.ask(w.method, round(w));
-            if (said === undefined || (isWord(said) && wordOf(said) === 'dropped'))
-                return null;
-            if (isWord(said) && wordOf(said) === 'removed') {
-                this.standings.remove(id);
-                delete cells.watched[id];
-                continue;
-            }
-            out.push({ id, by: w.by, out: said });
-        }
-        return out;
-    }
-    // Who is waiting, by this being's own id for the relation. For a device's
-    // own code and for a suite; it crosses no door.
-    get watching() {
-        return this.cells.watched;
-    }
-}
-// The three moves a being makes at every birth to hold what her box lends.
-// A standing points at a being and not at a box, so one she wakes up holding
-// names a being on the box she was on when it was made; a restart and a
-// migration are the same silent event to her, so she does these again every
-// time she is constructed and is always pointed at the box she is on.
-//
-// `watch` says she wants waking too: her ward mints the occupant, the
-// faculty takes the standing it makes, and from then on the wake arrives at
-// her door under the id she chose.
-// Every join in flight on this box. A being takes what her box lends at her
-// birth, and birth is synchronous while taking a standing is not, so a
-// harbor that answered "up" before they landed would be a box whose first
-// tick woke nobody and whose first ring reached no platform. The terrain
-// waits on this once, after its wards are hosted; nothing else reads it, and
-// a join that fails leaves nothing behind but a being who asks again.
-const flight = new Set();
-export const settled = async () => {
-    while (flight.size) {
-        const now = [...flight];
-        await Promise.allSettled(now);
-        for (const p of now)
-            flight.delete(p);
-    }
-};
-export function join(b, name, watch, id = name) {
-    const p = joining(b, name, watch, id);
-    flight.add(p);
-    void p.catch(() => { });
-    return p;
-}
-async function joining(b, name, watch, id) {
-    // One turn, before anything is asked. A being is called at her door and
-    // holds her stance from her first line, but her ward sets that door after
-    // her constructor returns, so a stance call made inside it reaches a being
-    // her ward does not hold yet and is answered as one taken out. Every
-    // faculty relation is made at birth, so the wait belongs here rather than
-    // in each of them.
-    await Promise.resolve();
-    b.standings.remove(id);
-    b.occupants.remove(`${id}:wake`);
-    const got = await b.lend(name, id);
-    if (got === null)
-        return null;
-    if (!watch)
-        return got;
-    const back = await b.invite(`${id}:wake`);
-    if (!back)
-        return got;
-    await b.standings[id]?.ask('watch', { invitation: back, method: watch.method, ...(watch.args ? { args: watch.args } : {}) });
-    return got;
-}

package/dist/dock/grants.js

@@ -1,99 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The box's grants: `grants`, one faculty of the dock ward. A bearer to an
-// identity in a world, honoured on every route alike. A route says the
-// grammar a caller speaks, forms, tools or JSON, and a grant says who the
-// caller is; no route holds a table of its own. She spans every world the
-// box hosts, and a grant maps a token to an identity and nothing else: the
-// credential is the invitation the avatar knocked with, spent once, and a
-// grant only remembers which avatar a client speaks through. No secret of
-// Quo's is ever here.
-//
-// Her tokens are her cells, kept by the dock ward's partition like every
-// faculty's and by no file of her own, so a box has one place its state is
-// and the harbor's one secret wraps them. Issuing, refreshing and revoking
-// are the routes' to call on her in this process, as the daemon mints a
-// nonce on `local`: none is an ask, none crosses a door, and she answers
-// nothing at hers.
-//
-// A grant is issued by whoever finished a way in: the OAuth exchange on the
-// model side, or the api route trading an invitation straight for tokens.
-// An access token lives an hour and a refresh token thirty days, and
-// refresh rotates. Revocation is the user being removing the occupant,
-// and the route that hears `removed` asks for the grants to go with it.
-import { Faculty } from './faculty.js';
-// The name the dock ward holds her under.
-export const GRANTS = 'grants';
-export const ACCESS_TTL = 60 * 60 * 1000; // an access token, one hour
-export const REFRESH_TTL = 30 * 24 * 60 * 60 * 1000; // a refresh token, thirty days
-// A token is a string the far side offers, and a bare lookup would find
-// `__proto__` and hand back an object with no identity. Own keys only.
-const own = (rec, key) => (Object.hasOwn(rec, key) ? rec[key] : undefined);
-// Thirty-two random bytes as base64url, from the web crypto and the base64
-// every runtime has, so nothing of node stands in a file a tab bundles or a
-// worker imports. `Buffer` is not among those: a worker has one only when a
-// deploy asks for node's shims, and the box's grants are the same code on
-// every terrain.
-const token = () => {
-    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(32));
-    let binary = '';
-    for (const b of bytes)
-        binary += String.fromCharCode(b);
-    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
-};
-export class Grants extends Faculty {
-    static cells = { ...Faculty.cells, access: {}, refresh: {} };
-    static asks = {};
-    // The ward's save, set by whoever holds her ward: a token issued is a
-    // cell written, and the routes answer with a token the partition keeps.
-    persist = async () => { };
-    // The clock, a suite's to move.
-    now = () => Date.now();
-    get kept() {
-        return this.cells;
-    }
-    async issue(identity, ward, client) {
-        const access_token = token(), refresh_token = token();
-        this.kept.access[access_token] = { identity, ward, client, exp: this.now() + ACCESS_TTL };
-        this.kept.refresh[refresh_token] = { identity, ward, client, exp: this.now() + REFRESH_TTL };
-        this.sweep();
-        await this.persist();
-        return { access_token, token_type: 'Bearer', expires_in: ACCESS_TTL / 1000, refresh_token, scope: 'nervur' };
-    }
-    // Rotated: the old one is gone with the new one's birth. Null is a token
-    // nobody issued, or one that died.
-    async refresh(refresh_token) {
-        const r = own(this.kept.refresh, refresh_token);
-        if (!r || r.exp < this.now())
-            return null;
-        delete this.kept.refresh[refresh_token];
-        return this.issue(r.identity, r.ward, r.client);
-    }
-    // The bearer on a request, to an identity in a world. Null is a stranger,
-    // or a token that died; a route tells the two apart by whether the
-    // request offered one at all.
-    bearer(req) {
-        const g = own(this.kept.access, offered(req));
-        return g && g.exp >= this.now() && typeof g.identity === 'string' ? { identity: g.identity, ward: g.ward } : null;
-    }
-    // Every grant an identity holds in a world, gone: the box's half of
-    // revocation. The other half is the user being removing the occupant.
-    async revoke(identity, ward) {
-        for (const k of ['access', 'refresh'])
-            for (const [t, g] of Object.entries(this.kept[k]))
-                if (g.identity === identity && g.ward === ward)
-                    delete this.kept[k][t];
-        await this.persist();
-    }
-    sweep() {
-        const now = this.now();
-        for (const k of ['access', 'refresh'])
-            for (const [t, g] of Object.entries(this.kept[k]))
-                if (!(g.exp >= now))
-                    delete this.kept[k][t];
-    }
-}
-// What a request offered as its bearer, or nothing.
-export const offered = (req) => {
-    const h = req.headers.get('authorization') ?? '';
-    return h.startsWith('Bearer ') ? h.slice(7) : '';
-};

package/dist/dock/index.d.ts

@@ -1,41 +0,0 @@
-import type { Harbor, Lend } from 'nervur/harbor';
-import { Faculty } from './faculty.ts';
-import { Console } from './console.ts';
-import { Local } from './local.ts';
-import { Location } from './location.ts';
-import { Notifications } from './notifications.ts';
-import { Push } from './push.ts';
-import { Timer } from './timer.ts';
-export { Console, CONSOLE } from './console.ts';
-export { Faculty, join, settled, type Watched, type Woke } from './faculty.ts';
-export { Local, LOCAL } from './local.ts';
-export { Location, type Where } from './location.ts';
-export { Notifications } from './notifications.ts';
-export { Push, isToken, bellOf, banner, sealBanner, SEAL, type Token, type Ring, type Line } from './push.ts';
-export { Timer } from './timer.ts';
-export { webPush, mintVapid, publicOf, type Vapid } from './webpush.ts';
-export { apnsPush, pkcs8, HOSTS, type Apns } from './apns.ts';
-export { fcmPush, isAccount, DOORS, type Account, type Doors } from './fcm.ts';
-export { handedTo, ringing, routed } from './service.ts';
-export declare const LOCATION = "location";
-export declare const NOTIFICATIONS = "notifications";
-export declare const PUSH = "push";
-export declare const TIMER = "timer";
-export declare const FACULTIES: Record<string, string>;
-export declare const FACULTY_CLASSES: {
-    Console: typeof Console;
-    Local: typeof Local;
-    Location: typeof Location;
-    Notifications: typeof Notifications;
-    Push: typeof Push;
-    Timer: typeof Timer;
-};
-export declare const DOCK = "dock";
-export declare function stand(harbor: Harbor, lent?: Record<string, string>): Promise<Lend>;
-export type Rooted = {
-    ask(method?: string, args?: Record<string, unknown>): Promise<unknown>;
-    save?(): Promise<void>;
-};
-export declare function standOn(ward: Rooted, lent?: Record<string, string>): Promise<Lend>;
-export declare function lending(ward: Rooted): Lend;
-export declare function facultyOf<F extends Faculty>(harbor: Harbor, name: string): F | undefined;

package/dist/dock/index.js

@@ -1,113 +0,0 @@
-import { isInvitation } from 'nervur';
-import { Faculty } from './faculty.js';
-import { Console, CONSOLE } from './console.js';
-import { Local } from './local.js';
-import { Location } from './location.js';
-import { Notifications } from './notifications.js';
-import { Push } from './push.js';
-import { Timer } from './timer.js';
-export { Console, CONSOLE } from './console.js';
-export { Faculty, join, settled } from './faculty.js';
-export { Local, LOCAL } from './local.js';
-export { Location } from './location.js';
-export { Notifications } from './notifications.js';
-export { Push, isToken, bellOf, banner, sealBanner, SEAL } from './push.js';
-export { Timer } from './timer.js';
-// The three grounds the push faculty rings through, and the bell service
-// that holds a publisher's keys: what the box can do, beside the faculty.
-export { webPush, mintVapid, publicOf } from './webpush.js';
-export { apnsPush, pkcs8, HOSTS } from './apns.js';
-export { fcmPush, isAccount, DOORS } from './fcm.js';
-export { handedTo, ringing, routed } from './service.js';
-// The names this package lends under. They are conventions of the dock and
-// nothing of Quo's: a name is the harbor's namespace, and a being holds each
-// one under an id of her own choosing.
-export const LOCATION = 'location';
-export const NOTIFICATIONS = 'notifications';
-export const PUSH = 'push';
-export const TIMER = 'timer';
-// The classes every dock ward may hold, by class name. A terrain hands its
-// own subclasses under the same names and the harbor holds those instead.
-// `local` and `grants` are not among them: the box's way in and the box's
-// grants stand only where a terrain serves routes, and that terrain adds
-// them to what it lends. `Grants` is not in this file at all, so that a tab
-// bundling this index carries no route's notion: the terrain that serves
-// routes hands her class to its harbor, as the daemon hands its own push.
-export const FACULTIES = { [LOCATION]: 'Location', [NOTIFICATIONS]: 'Notifications', [PUSH]: 'Push', [TIMER]: 'Timer' };
-export const FACULTY_CLASSES = { Console, Local, Location, Notifications, Push, Timer };
-// The name a harbor keeps its own ward under. It is a ward in every other
-// respect, and this one is never adopted or dropped as a migration: its
-// beings are the box's and die with it.
-export const DOCK = 'dock';
-// Put the dock ward up and answer the `lend` this harbor hands its wards.
-// `lent` says which names this box offers and which class stands for each;
-// a name it does not hold is null, and so is every other kind of no.
-//
-// The harbor keeps this ward's ask pointer rather than handing it out, so it
-// is the root here, and the root may invite on any being of its ward. That
-// is the whole of what `lend` does: it never mints, it asks its own root to.
-export async function stand(harbor, lent = FACULTIES) {
-    const kept = await harbor.store.load(DOCK);
-    const ward = harbor.wards.get(DOCK) ?? (kept ? await harbor.host(DOCK, kept) : await harbor.create(DOCK, CONSOLE));
-    return standOn(ward, lent);
-}
-// The faculties up in a ward already made, and the `lend` that reaches them.
-// Apart from `stand` so a suite can put its own stubs in its own ward and
-// get the same thing a box gets. It is run again at every boot and says the
-// same thing twice without harm: a key already booted is refused, and an
-// invitation on an id already held is null.
-export async function standOn(ward, lent = FACULTIES) {
-    for (const [name, className] of Object.entries(lent))
-        await ward.ask('boot', { key: name, class: className });
-    // The box as one being, carrying what it stood. She is the page a device
-    // that has joined no world shows, and she is placed by the root because
-    // the root is the box: a standing at every faculty, minted and knocked in
-    // one move, as an owner places any relation into a being of its ward.
-    await ward.ask('boot', { key: CONSOLE, class: 'Console' });
-    for (const name of Object.keys(lent)) {
-        const inv = await ward.ask('invite', { being: name, id: `${CONSOLE}:${name}` });
-        if (!isInvitation(inv))
-            continue;
-        await ward.ask('knock', { being: CONSOLE, id: name, invitation: inv });
-    }
-    await ward.save?.();
-    return lending(ward);
-}
-// The root's half alone: a name and a taker in, whether the ward took it out.
-// It never mints; it asks the root of the ward it holds to, which is what a
-// root may do on any being of its ward. And it unmints: a taker that would
-// not take leaves an occupant on that faculty which nobody holds, so the root
-// removes it before answering, and a refused lend costs the box nothing.
-//
-// Any being of the dock ward is lent by her key, not only the ones a terrain
-// stood: the faculties the dock ships are examples, and an estate boots its
-// own into the dock ward, of a class in its own `classes/`, and lends it the
-// same way. A name nobody there answers to is refused at the invite.
-//
-// The id is drawn and never counted. A faculty's occupants are in her cells
-// and outlive the process, so a count that started again at every boot would
-// name, on the first lend after a restart, an id she already holds, and the
-// invite would be refused for the rest of the box's life.
-export function lending(ward) {
-    return async (name, take) => {
-        const id = `lent:${fresh()}`;
-        const out = await ward.ask('invite', { being: name, id });
-        if (!isInvitation(out))
-            return false;
-        const took = await take(out);
-        if (!took)
-            await ward.ask('remove', { being: name, id });
-        await ward.save?.();
-        return took;
-    };
-}
-const fresh = () => Array.from(globalThis.crypto.getRandomValues(new Uint8Array(8)))
-    .map((b) => b.toString(16).padStart(2, '0'))
-    .join('');
-// One faculty of this box, as the device's own code holds it: the object the
-// harbor made, in this process. Not a path around a door, and nothing of it
-// crosses an edge; it is how a device fires its own timer at a moment it
-// names and how a suite reads what a stub recorded.
-export function facultyOf(harbor, name) {
-    return harbor.wards.get(DOCK)?.being(name);
-}

package/dist/dock/local.js

@@ -1,44 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The box's way in: `local`, one faculty of the dock ward. The daemon saw a
-// process reach a socket only the device's user can open, and that is the
-// whole of the vouch; file permissions are the device's rules, which is what
-// `quo/SPEC.md` allows a harbor to hand the root by.
-//
-// She holds the nonces this box minted, in this process and never in cells:
-// a vouch that outlived a restart would be a vouch for a process that is
-// gone. Each is honoured once, and a `local` proof arriving any other way
-// names no nonce and is refused.
-//
-// The device's own code mints on her directly, as a device fires its own
-// timer: `mint` is not an ask, it crosses no door, and nothing at a door
-// can reach it. The desk asks `verify` at her standing, as she asks any way
-// in.
-import { Faculty } from './faculty.js';
-import { VERIFY } from '../beings/way.js';
-// The name the dock ward lends her under. A box with no local side lends no
-// such name, and the desk there holds no such standing.
-export const LOCAL = 'local';
-export class Local extends Faculty {
-    static asks = { verify: VERIFY };
-    #nonces = new Map();
-    // A nonce for one client this box saw itself, spent by the first proof
-    // that names it. The caller drops it when the admit is over: a nonce that
-    // was never spent is not a way in that stays open.
-    mint(nonce, who) {
-        this.#nonces.set(nonce, who);
-    }
-    drop(nonce) {
-        this.#nonces.delete(nonce);
-    }
-    verify(args) {
-        const proof = args.proof;
-        if (!proof || typeof proof !== 'object' || Array.isArray(proof))
-            return null;
-        const nonce = proof.nonce;
-        const who = typeof nonce === 'string' ? this.#nonces.get(nonce) : undefined;
-        if (!who)
-            return null;
-        this.#nonces.delete(nonce);
-        return who;
-    }
-}

package/dist/dock/location.js

@@ -1,11 +0,0 @@
-import { Faculty } from './faculty.js';
-export class Location extends Faculty {
-    static asks = {
-        where: { description: 'where this box is', input: { type: 'object' } },
-    };
-    // The platform's own permission prompt is the first ask's, and a refusal is
-    // the error object every ask after it answers.
-    where() {
-        return Promise.resolve({ error: 'this box cannot say where it is' });
-    }
-}

package/dist/dock/push.js

@@ -1,132 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Waking a device that is not reachable, the one way its platform allows: a
-// push that carries the device's token and the banner sealed to that
-// device's own key, which nothing between the world and the phone can
-// read. A token names its
-// kind, and a kind is one ring: `web` is Web Push under a keypair a world
-// mints itself, `apns` and `fcm` are the two stores' own, handed on to the
-// publisher's bell service by a world that holds no platform key. A box that
-// was given no ring for a kind says so, which is what a world that rings no
-// iPhones says to one.
-//
-// The rings are live objects and not values, so they are not cells: a
-// terrain subclasses and builds its own in `rings`, out of what its
-// environment and this being's cells give it.
-import { OWNER } from 'nervur';
-import { arithmetic } from 'nervur/ward';
-import { Faculty } from './faculty.js';
-import { mintVapid } from './webpush.js';
-export const isToken = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && typeof v.kind === 'string';
-// The bell a token names, when it names one a ring can reach.
-export function bellOf(token) {
-    if (typeof token.bell !== 'string')
-        return undefined;
-    try {
-        const u = new URL(token.bell);
-        return u.protocol === 'https:' || u.protocol === 'http:' ? token.bell : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-// What a platform will carry, so a seal too big is refused where a human
-// can still read why rather than two hops later by a service nobody reads.
-export const SEAL = 4096;
-// The line a device shows when it was woken while nobody was looking,
-// composed from one object. A pushed object is whatever the far being sent,
-// so the two names a notification has are taken when they are there and the
-// object is shown as it is when they are not.
-export function banner(o) {
-    const text = (v) => (typeof v === 'string' && v.trim() ? v.trim() : '');
-    const title = text(o.title) || text(o.from) || 'Nervur';
-    const body = text(o.body) ||
-        text(o.said) ||
-        Object.entries(o)
-            .filter(([k]) => k !== 'title' && k !== 'from')
-            .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
-            .join(', ');
-    return { title, body };
-}
-// A banner sealed to a device's banner key, as hex, or null when it will
-// not seal or will not fit. The world seals and the process that draws the
-// banner opens it; no doorbell, no bell service and no platform between
-// them holds either half, which is why a ring may carry a line at all.
-export async function sealBanner(line, key) {
-    if (!/^[0-9a-f]{64}$/.test(key))
-        return null;
-    try {
-        const boxed = await arithmetic.box(new TextEncoder().encode(JSON.stringify(line)), arithmetic.unhex(key), globalThis.crypto.getRandomValues(new Uint8Array(32)));
-        const wire = arithmetic.hex(boxed.bytes);
-        return wire.length > SEAL ? null : wire;
-    }
-    catch {
-        return null;
-    }
-}
-// The root and nobody else: where a box hands a phone's ring is the box's own.
-const root = (_occ, asker) => asker.id === OWNER;
-export class Push extends Faculty {
-    // What she keeps, beside every faculty's: the world's doorbell key, a P-256
-    // JWK she mints herself the first time a terrain asks for one, so a Web
-    // Push is signed under a key that lives with the wards and in no file; and
-    // the bell service a phone's ring is handed to when its token names none,
-    // a row the root keeps, since whose service it is belongs to an estate.
-    static cells = { watched: {}, minted: 0, key: null, service: null };
-    static asks = {
-        ring: { description: 'wake a device: its token, the banner sealed to it, or the line itself where the ground encrypts it', input: { type: 'object', properties: { token: { type: 'object' }, sealed: { type: 'string' }, line: { type: 'object', properties: { title: { type: 'string' }, body: { type: 'string' } }, required: ['title', 'body'] } }, required: ['token'] } },
-        kinds: { description: 'which kinds this box can ring', input: { type: 'object' } },
-        keep: { description: 'the bell service a phone is rung through when its token names none; null forgets it', input: { type: 'object', properties: { service: { type: ['string', 'null'] } }, required: ['service'] }, for: root },
-    };
-    // The doorbell key, minted once and kept. A terrain asks for it when it
-    // serves a web route; a box that never does holds none and rings no tabs.
-    async mint() {
-        if (this.cells.key === null)
-            this.cells.key = (await mintVapid()).key;
-        return this.cells.key;
-    }
-    get key() {
-        return this.cells.key;
-    }
-    get service() {
-        return typeof this.cells.service === 'string' ? this.cells.service : undefined;
-    }
-    keep(args) {
-        const service = args.service;
-        if (service !== null && (typeof service !== 'string' || !/^https?:\/\/\S+$/.test(service)))
-            return { error: 'a bell service is a URL over http or https, or null' };
-        this.cells.service = service === null ? null : service.replace(/\/$/, '');
-        return { service: this.cells.service };
-    }
-    // What this box can ring. A terrain overrides it and builds its rings from
-    // its environment and this being's cells; the base rings nothing.
-    get rings() {
-        return {};
-    }
-    kinds() {
-        return { kinds: Object.keys(this.rings) };
-    }
-    async ring(args) {
-        const token = args.token;
-        if (!isToken(token))
-            return { error: 'a token names its kind' };
-        const sealed = args.sealed;
-        if (sealed !== undefined && typeof sealed !== 'string')
-            return { error: 'a seal is text' };
-        if (typeof sealed === 'string' && sealed.length > SEAL)
-            return { error: `a seal is at most ${SEAL} bytes` };
-        const said = args.line;
-        if (said !== undefined && (said === null || typeof said !== 'object' || Array.isArray(said) || typeof said.title !== 'string' || typeof said.body !== 'string'))
-            return { error: 'a line is a title and a body' };
-        const line = said;
-        const r = Object.hasOwn(this.rings, token.kind) ? this.rings[token.kind] : undefined;
-        if (!r)
-            return { error: `this box cannot ring a ${token.kind}` };
-        try {
-            await r.ring(token, sealed, line);
-            return { rang: token.kind };
-        }
-        catch (e) {
-            return { error: e instanceof Error ? e.message : 'the ring threw' };
-        }
-    }
-}