@nervur-org/dock 0.4.1 → 0.6.0

package/{dock → box}/http2.ts

@@ -9,14 +9,14 @@
 // It is its own file for one reason, and the reason is the import. A worker
 // bundle that pulled `node:http2` in would not build, so nothing terrain
 // neutral may name this file: it is imported by the Node terrain and by
-// nothing else, and it is not exported from `dock/index.ts`.
+// nothing else, and it is not exported from `box/index.ts`.
 //
 // A session is one TCP connection carrying every ring to one of Apple's two
 // hosts, which is what HTTP/2 is for and what Apple asks of a provider that
 // rings more than once. It is kept while it lives, made again when it dies,
 // and unref'd, so an idle bell is not a process that will not exit.
 import { connect, type ClientHttp2Session } from 'node:http2';
-import type { Ring, Token } from './push.ts';
+import type { Ring, Token } from './ring.ts';
 import { HOSTS, answered, provider, request, type Apns } from './apns.ts';
 
 // What a Node box holds if it is a bell: the team's key from the portal and
@@ -56,12 +56,12 @@ export function apnsHttp2(a: Apns, at: typeof HOSTS = HOSTS, within = WITHIN): R
       stream.setEncoding('utf8');
       stream.setTimeout(within, () => stream.destroy(new Error('apns did not answer')));
       const { status, text } = await new Promise<{ status: number; text: string }>((ok, no) => {
-        let status = 0;
-        let text = '';
-        stream.on('response', (h) => (status = Number(h[':status'] ?? 0)));
-        stream.on('data', (chunk: string) => (text += chunk));
+        let code = 0;
+        let body = '';
+        stream.on('response', (h) => (code = h[':status'] ?? 0));
+        stream.on('data', (chunk: string) => (body += chunk));
         stream.on('error', no);
-        stream.on('end', () => ok({ status, text }));
+        stream.on('end', () => ok({ status: code, text: body }));
         stream.end(req.body);
       });
       answered(status, text);

package/box/index.ts

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: Apache-2.0
+// The dock: what a harbor stands for itself, in acts. A harbor is handed
+// classes, a partition and a seed. Act one stands its own ward, the box
+// ward: the Dock, then every faculty of the tree whose class stands, each
+// born holding this box and held by the Dock under its key, then the index
+// of which faculty fulfils which contract written into her cells, then
+// every claimed path placed on the wire. Act two is the kit's: every other
+// ward is handed one invitation on the Dock and takes it at boot, and a
+// lend is an ask on her. Nothing here names a class a terrain or an estate
+// brings: each faculty says on her class the contracts she fulfils, whether
+// she stands on this runtime and the paths she claims.
+import type { Harbor, WardPointers } from 'nervur/harbor';
+import { BOX, hold, offerTo, BOX_SEED } from 'nervur/harbor';
+import type { BeingClass, Stance } from 'nervur';
+import { isInvitation } from 'nervur';
+import { Dock, type BoxCells } from './dock.ts';
+import { nameOf, titleOf, type Contract } from './contract.ts';
+import { HTTP, type Faculty } from './faculty.ts';
+import { WIRE } from './http.ts';
+import type { Harborage } from './box.ts';
+import { keyed, type Tree } from './tree.ts';
+
+export { ALONE, harborageOver, type Harborage } from './box.ts';
+export { Dock, BOX, DOMAIN, routesFor, type Routes, type Apps, type BoxCells } from './dock.ts';
+export { BOX_SEED } from 'nervur/harbor';
+export { Faculty, WATCH, INBOUND, HTTP, type Watched } from './faculty.ts';
+export { Http, WIRE } from './http.ts';
+export { Timer, TIMER } from './timer.ts';
+export { Local, LOCAL } from './local.ts';
+export { Grants, GRANTS, offered, ACCESS_TTL, REFRESH_TTL, type Grant, type Tokens, type Bearers } from './grants.ts';
+export { Push, PUSH } from './push.ts';
+export { Agents, AGENTS, isProcess, type Row as AgentRow, type Runner, type Side } from './agents.ts';
+export { Dialers, DIALERS } from './dialers.ts';
+export { EnvoyFaculty, WATCH_ACCOUNT, type Delivery } from './envoy.ts';
+export { contract, covers, nameOf, titleOf, type Contract } from './contract.ts';
+export { join, settled } from './join.ts';
+export { Location, LOCATION, type Where } from './location.ts';
+export { Notifications, NOTIFICATIONS } from './notifications.ts';
+export { keyed, type Tree } from './tree.ts';
+// What waking a device rings through: the push parts every terrain shares,
+// the three grounds, and the bell service that holds a publisher's keys.
+export { isToken, bellOf, banner, sealBanner, SEAL, type Token, type Ring, type Line } from './ring.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';
+
+// The classes this folder brings to every box ward, as a tree.
+export const OWN: Tree = { box: { Dock } };
+
+// A faculty as standing reads one: by the shape of its class, never by
+// `instanceof`, so a class from a second copy of this package reads the same.
+type FacultyClass = BeingClass & { fulfils: Contract[]; stands(): boolean; claims: string[] };
+const isFaculty = (v: unknown): v is FacultyClass => typeof v === 'function' && Array.isArray((v as { fulfils?: unknown }).fulfils) && typeof (v as { stands?: unknown }).stands === 'function';
+
+// The classes a box ward is handed, keyed where they live, every faculty
+// among them born holding this box. The kit makes a being with her stance
+// alone, so the class found under a faculty's key is her own class with the
+// harborage handed on.
+export function classes(tree: Tree, box: Harborage): Record<string, BeingClass> {
+  const out: Record<string, BeingClass> = keyed(OWN);
+  for (const [key, C] of Object.entries(keyed(tree))) {
+    if (!isFaculty(C)) continue;
+    const F = C as unknown as new (stance: Stance, box: Harborage) => Faculty;
+    out[key] = class extends F {
+      constructor(stance: Stance) {
+        super(stance, box);
+      }
+    };
+  }
+  return out;
+}
+
+// One faculty of this box, as the device's own code holds it: found the way
+// a being finds one, by contract. The Dock is asked which key she lends the
+// contract under, and the object under that key is taken, in this process
+// and across no door. Nothing here names a class, so a terrain's subclass
+// and an estate's leaf are found the same way the dock's own are.
+type Boxed = { wards: ReadonlyMap<string, { ask: WardPointers['ask']; being(key: string): unknown }> };
+export async function keyLent(harbor: Boxed, needs: Contract): Promise<string | undefined> {
+  const ward = harbor.wards.get(BOX_SEED);
+  if (!ward) return undefined;
+  const out = (await ward.ask('ask', { being: BOX, method: 'lends' })) as { lends?: Record<string, string> };
+  return out.lends?.[await nameOf(needs)];
+}
+export async function lent<F extends Faculty>(harbor: Boxed, needs: Contract): Promise<F | undefined> {
+  const key = await keyLent(harbor, needs);
+  return key === undefined ? undefined : (harbor.wards.get(BOX_SEED)?.being(key) as F | undefined);
+}
+
+// What the box is, asked of the Dock: its routes, its apps and its default
+// ward, each null until the root said it. A harbor with no box ward is a
+// box that is nothing yet.
+export async function boxOf(harbor: Boxed): Promise<BoxCells> {
+  const ward = harbor.wards.get(BOX_SEED);
+  const out = ward ? ((await ward.ask('ask', { being: BOX, method: 'box' })) as Partial<BoxCells>) : {};
+  return { routes: out.routes ?? null, apps: out.apps ?? null, default: out.default ?? null };
+}
+
+// Act one on a harbor: its classes handed to it, each faculty born holding
+// this box, the box's ward woken from what the store keeps or made, and
+// stood. From here the harbor hands every other ward one invitation on the
+// Dock, which is act two, the kit's.
+export async function standHarbor(harbor: Harbor, tree: Tree, box: Harborage): Promise<void> {
+  Object.assign(harbor.classes, classes(tree, box));
+  const kept = await harbor.store.load(BOX_SEED);
+  const ward = harbor.wards.get(BOX_SEED) ?? (kept ? await harbor.host(BOX_SEED, kept) : await harbor.create(BOX_SEED, BOX));
+  await stand(ward, tree);
+  harbor.offering = (name) => offerTo(ward, name);
+}
+
+// A ward as its root holds it: the ask pointer, and a save where the terrain
+// keeps one.
+export type Rooted = { ask(method?: string, args?: Record<string, unknown>): Promise<unknown>; save?(): Promise<void> };
+
+// Stand a box ward already made, in the order a harbor stands: her own
+// being first, then every faculty of the tree whose class stands, each held
+// by her under its key, then the index of which faculty fulfils which
+// contract written into her cells, then every claimed path placed on the
+// wire. A key already booted is refused and costs nothing, so standing a
+// ward that woke from its partition finds every being as it was; and a run
+// says only itself, so a title or a path an earlier run placed that this
+// one does not is removed at both ends before anything is placed.
+export async function stand(ward: Rooted, tree: Tree = {}): Promise<void> {
+  const own = keyed(OWN);
+  await ward.ask('boot', { key: BOX, class: Object.keys(own).find((k) => own[k] === Dock) });
+  const standing = Object.entries(keyed(tree)).filter((e): e is [string, FacultyClass] => isFaculty(e[1]) && e[1].stands());
+
+  // The index. Under each contract, the classes that fulfil it, and of
+  // those the ones no other extends, so a subclass wins over its base when
+  // both stand. One left is lent under it. Two left, with neither extending
+  // the other, are a clash: the contract is lent to neither, the Dock keeps
+  // the clash by name in her cells for the root to read and a terrain to
+  // print, and the box stays up, so one bad contract costs that contract
+  // and nothing else.
+  const under = new Map<string, { title: string; keys: [string, FacultyClass][] }>();
+  const names = new Map<string, string[]>();
+  for (const [key, C] of standing) {
+    for (const c of C.fulfils) {
+      const name = await nameOf(c);
+      names.set(key, [...(names.get(key) ?? []), name]);
+      const u = under.get(name) ?? { title: titleOf(c), keys: [] };
+      u.keys.push([key, C]);
+      under.set(name, u);
+    }
+  }
+  const lends: Record<string, string> = {};
+  const clashes: Record<string, string[]> = {};
+  for (const [name, u] of under) {
+    const leaves = u.keys.filter(([, C]) => !u.keys.some(([, D]) => D !== C && D.prototype instanceof C));
+    if (leaves.length === 1) lends[name] = leaves[0][0];
+    else clashes[u.title || name] = leaves.map(([k]) => k);
+  }
+  // The word a screen shows a faculty under: what the first contract she is
+  // lent under calls itself. A key carries a slash and a title never does.
+  const titles: Record<string, string> = {};
+  for (const [key] of standing) {
+    const first = (names.get(key) ?? []).find((n) => lends[n] === key);
+    const title = first === undefined ? '' : (under.get(first)?.title ?? '');
+    if (title && title !== key) titles[title] = key;
+  }
+
+  const claims = new Map<string, string[]>();
+  for (const [key, C] of standing) {
+    const made = (await ward.ask('boot', { key, class: key })) as { booted?: string };
+    if (made.booted === key) await hold(ward, key);
+    for (const p of C.claims ?? []) claims.set(p, [...(claims.get(p) ?? []), key]);
+  }
+
+  // The index written whole, and the Dock's title standings held to this
+  // run: she removes her end of one this run does not place, and the root
+  // removes the far end from every faculty she holds, before placing what
+  // she does not hold yet.
+  const stood = (await ward.ask('ask', { being: BOX, method: 'stood', args: { lends, titles, clashes } })) as { held?: string[]; pruned?: string[] };
+  const keys = (stood.held ?? []).filter((id) => id.includes('/'));
+  for (const t of stood.pruned ?? []) for (const key of keys) await ward.ask('remove', { being: key, id: `${BOX}:${t}` });
+  for (const [title, key] of Object.entries(titles)) {
+    if (stood.held?.includes(title)) continue;
+    const inv = await ward.ask('invite', { being: key, id: `${BOX}:${title}` });
+    if (isInvitation(inv)) await ward.ask('knock', { being: BOX, id: title, invitation: inv });
+  }
+
+  // Every claimed path, placed on the box's wire: the root invites on the
+  // faculty that claims it for the http faculty, who holds it under the
+  // path. A path two faculties claim is neither's, and the box stays up. A
+  // path she holds that this run does not claim, or that another faculty
+  // claims now, goes at both ends the same way a title does.
+  const wire = lends[await nameOf(WIRE)];
+  if (wire) {
+    const claimed: Record<string, string> = {};
+    for (const [p, ks] of claims) if (ks.length === 1) claimed[p] = ks[0];
+    const wired = (await ward.ask('ask', { being: wire, method: 'wired', args: { claimed } })) as { held?: string[]; pruned?: string[] };
+    for (const p of wired.pruned ?? []) for (const key of keys) await ward.ask('remove', { being: key, id: `${HTTP}${p}` });
+    for (const [p, key] of Object.entries(claimed)) {
+      if (wired.held?.includes(p)) continue;
+      const inv = await ward.ask('invite', { being: key, id: `${HTTP}${p}` });
+      if (isInvitation(inv)) await ward.ask('knock', { being: wire, id: p, invitation: inv });
+    }
+  }
+  await ward.save?.();
+}

package/box/join.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// How a being takes what her box lends. She names the contract she needs and
+// the id she holds it under; the box lends under the contract's digest; she
+// reads the describe she was handed and keeps it only if it covers what she
+// asked for. With `watch` she also asks to be woken, as the occupant she
+// names `<id>:wake`, handing whatever the faculty needs to know her by; a
+// watch refused puts the whole relation down.
+//
+// A being takes what her box lends at her birth, again at every birth, since
+// a restart and a move are one event to her. Birth is synchronous and taking
+// a standing is not, so every join in flight is kept on the being who made
+// it, and a terrain waits on `settled` over its own wards once they are
+// hosted: a box is up when its beings have landed, and another box's beings
+// are no business of this one.
+import { isBlueprint } from 'nervur';
+import type { Being, JsonObject } from 'nervur';
+import { covers, nameOf, type Contract } from './contract.ts';
+
+const flight = new WeakMap<object, Set<Promise<unknown>>>();
+
+// A ward as whoever holds it can walk it: the keys of the beings here this
+// run, and the object under each.
+export type Hosting = { keys(): string[]; being(key: string): unknown };
+// The memory harbor's hand for a suite: every partition, and the object
+// under each being's cells. A booted ward there is two pointers and a pk
+// and nothing else, so the walk goes through the harbor.
+type Memory = { partitions: ReadonlyMap<string, Record<string, unknown>>; objects: WeakMap<object, unknown> };
+
+const beingsOf = (of: { wards: ReadonlyMap<string, Hosting> } | Hosting | Memory): unknown[] => {
+  if ('partitions' in of) return [...of.partitions.values()].flatMap((rows) => Object.values((rows.beings ?? {}) as Record<string, object>).map((cells) => of.objects.get(cells)));
+  const wards = 'wards' in of ? [...of.wards.values()] : [of];
+  return wards.flatMap((w) => w.keys().map((k) => w.being(k)));
+};
+
+// Every join in flight on one box's wards, or on one ward, landed. Walked
+// again until nothing is in flight, since a being landing may boot another.
+export async function settled(of: { wards: ReadonlyMap<string, Hosting> } | Hosting | Memory): Promise<void> {
+  for (;;) {
+    const now = beingsOf(of).flatMap((b) => [...(flight.get(b as object) ?? [])]);
+    if (now.length === 0) return;
+    await Promise.allSettled(now);
+  }
+}
+
+export function join(b: Being, needs: Contract, id: string, watch?: { method: string; args?: JsonObject; with?: JsonObject }): Promise<string | null> {
+  const p = joining(b, needs, id, watch);
+  const mine = flight.get(b) ?? new Set<Promise<unknown>>();
+  mine.add(p);
+  flight.set(b, mine);
+  const done = () => void mine.delete(p);
+  void p.then(done, done);
+  return p;
+}
+
+async function joining(b: Being, needs: Contract, id: string, watch: { method: string; args?: JsonObject; with?: JsonObject } | undefined): Promise<string | null> {
+  // One turn first: her ward sets her door after her constructor returns, so
+  // a stance call made inside it would reach a being her ward does not hold
+  // yet.
+  await Promise.resolve();
+  b.standings.remove(id);
+  b.occupants.remove(`${id}:wake`);
+  if ((await b.lend(await nameOf(needs), id)) === null) return null;
+  const held = await b.standings[id]?.ask();
+  if (!isBlueprint(held) || !covers(held, needs)) {
+    b.standings.remove(id);
+    return null;
+  }
+  if (watch) {
+    const back = await b.invite(`${id}:wake`);
+    const said = back ? await b.standings[id]?.ask('watch', { ...watch.with, invitation: back as unknown as JsonObject, method: watch.method, ...(watch.args ? { args: watch.args } : {}) }) : undefined;
+    if (!said || typeof said !== 'object' || 'error' in said) {
+      b.standings.remove(id);
+      b.occupants.remove(`${id}:wake`);
+      return null;
+    }
+  }
+  return id;
+}

package/box/local.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's way in: a process the device saw on a socket only its user can
+// open, which is the whole of the vouch. She holds the nonces this box
+// minted, in this process and never in cells, each honoured once. The
+// device's own code mints on her directly; the desk asks `verify` at the
+// standing she lends.
+import type { JsonObject } from 'nervur';
+import { VERIFY, type Verified } from '../beings/way.ts';
+import { contract } from './contract.ts';
+import { Faculty } from './faculty.ts';
+
+// What a desk needs from a box that saw a process on its own socket.
+export const LOCAL = contract('local', { verify: VERIFY });
+
+export class Local extends Faculty {
+  static override asks = { verify: VERIFY };
+  static override fulfils = [LOCAL];
+
+  readonly #nonces = new Map<string, Verified>();
+
+  mint(nonce: string, who: Verified): void {
+    this.#nonces.set(nonce, who);
+  }
+  drop(nonce: string): void {
+    this.#nonces.delete(nonce);
+  }
+
+  verify(args: JsonObject): Verified | null {
+    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 as string);
+    return who;
+  }
+}

package/{dock → box}/location.ts

@@ -6,13 +6,25 @@
 // who asks for the name is lent nothing.
 import type { JsonObject } from 'nervur';
 import { Faculty } from './faculty.ts';
+import { contract } from './contract.ts';
 
 export type Where = { lat: number; lng: number; accuracy?: number; at: number };
 
+const ASKS = {
+  where: { description: 'where this box is', input: { type: 'object' } },
+};
+
+// What a being needs from a box that can say where it is.
+export const LOCATION = contract('location', ASKS);
+
 export class Location extends Faculty {
-  static override asks = {
-    where: { description: 'where this box is', input: { type: 'object' } },
-  };
+  static override asks = ASKS;
+  static override fulfils = [LOCATION];
+  // This body says where nothing is, so it stands nowhere: a terrain whose
+  // platform can answer subclasses her and says so.
+  static override stands(): boolean {
+    return false;
+  }
 
   // The platform's own permission prompt is the first ask's, and a refusal is
   // the error object every ask after it answers.

package/{dock → box}/notifications.ts

@@ -24,6 +24,15 @@
 import { arithmetic } from 'nervur/ward';
 import type { JsonObject } from 'nervur';
 import { Faculty } from './faculty.ts';
+import { contract } from './contract.ts';
+
+const ASKS = {
+  notify: { description: 'show the human a line', input: { type: 'object', properties: { title: { type: 'string' }, body: { type: 'string' } }, required: ['title'] } },
+  banner: { description: "this device's banner key, the public half, which a world seals a notification to", input: { type: 'object' } },
+};
+
+// What a being needs from a box that can show the human a line.
+export const NOTIFICATIONS = contract('notifications', ASKS);
 
 // A key is thirty two bytes of the platform's own randomness, as every seed
 // in this kit is.
@@ -33,10 +42,13 @@ export class Notifications extends Faculty {
   // The banner key, as hex: the seed it was made from, kept so the pair can
   // be made again, and the public half a device hands out.
   static override cells: JsonObject = { watched: {}, minted: 0, banner: null };
-  static override asks = {
-    notify: { description: 'show the human a line', input: { type: 'object', properties: { title: { type: 'string' }, body: { type: 'string' } }, required: ['title'] } },
-    banner: { description: "this device's banner key, the public half, which a world seals a notification to", input: { type: 'object' } },
-  };
+  static override asks = ASKS;
+  static override fulfils = [NOTIFICATIONS];
+  // This body shows nothing, so it stands nowhere: a terrain with a
+  // notification center subclasses her and says so.
+  static override stands(): boolean {
+    return false;
+  }
 
   notify(_args: JsonObject): Promise<JsonObject> {
     return Promise.resolve({ error: 'this box shows no notifications' });
@@ -50,7 +62,7 @@ export class Notifications extends Faculty {
       this.cells.banner = arithmetic.hex(seed());
       await this.plant(await arithmetic.sealingPair(arithmetic.unhex(this.cells.banner)));
     }
-    return arithmetic.sealingPair(arithmetic.unhex(this.cells.banner as string));
+    return arithmetic.sealingPair(arithmetic.unhex(this.cells.banner));
   }
 
   async banner(_args: JsonObject): Promise<JsonObject> {

package/box/push.ts

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+// Waking a device that is not reachable, the one way its platform allows: a
+// ring carrying the device's token and a banner sealed to its key. A token
+// names its kind and a kind is one ring. The rings are live objects and not
+// values, so a terrain that can ring brings a class that builds its own; this
+// body rings nothing and stands nowhere.
+//
+// What she keeps: the world's doorbell key, a P-256 JWK she mints herself the
+// first time a terrain asks, and the bell service a phone's ring is handed
+// to when its token names none, a row the root keeps.
+import { OWNER } from 'nervur';
+import type { Asker, JsonObject, OccupantRecord } from 'nervur';
+import { SEAL, isToken, type Line, type Ring } from './ring.ts';
+import { mintVapid, publicOf } from './webpush.ts';
+import { contract } from './contract.ts';
+import { Faculty } from './faculty.ts';
+
+const root = (_occ: OccupantRecord | undefined, asker: Asker) => asker.id === OWNER;
+
+// What a holder is owed: a ring, and which kinds this box can ring.
+const OWED = {
+  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' } },
+};
+
+// What a being needs from a box that can wake a device.
+export const PUSH = contract('push', OWED);
+
+export class Push extends Faculty {
+  static override cells: JsonObject = { watched: {}, minted: 0, key: null, service: null };
+  static override asks = { ...OWED, bell: { description: 'the public half of this box’s doorbell key, minted at the first ask and kept in her cells', input: { type: 'object' }, for: root }, 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 } };
+  static override fulfils = [PUSH];
+  static override stands(): boolean {
+    return false;
+  }
+
+  // The doorbell key, minted at the root's first ask and kept; nobody mints
+  // it from outside. What crosses is the public half, which every page's
+  // config carries.
+  async bell(): Promise<JsonObject> {
+    if (this.cells.key === null) this.cells.key = (await mintVapid()).key as unknown as JsonObject;
+    return { bell: publicOf(this.cells.key as unknown as JsonWebKey) };
+  }
+  get key(): JsonWebKey | null {
+    return this.cells.key as unknown as JsonWebKey | null;
+  }
+  get service(): string | undefined {
+    return typeof this.cells.service === 'string' ? this.cells.service : undefined;
+  }
+
+  keep(args: JsonObject): JsonObject {
+    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. The base rings nothing.
+  protected get rings(): Readonly<Record<string, Ring>> {
+    return {};
+  }
+
+  kinds(): JsonObject {
+    return { kinds: Object.keys(this.rings) };
+  }
+
+  async ring(args: JsonObject): Promise<JsonObject> {
+    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 as Line | undefined;
+    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' };
+    }
+  }
+}

package/box/ring.ts

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+// What waking a device is made of, beside the push faculty: the token a
+// device hands a world, the ring a platform rings through, the banner a
+// device shows, and the seal only the device can open. 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.
+import { arithmetic } from 'nervur/ward';
+import type { JsonObject } from 'nervur';
+
+// What a device hands a world so it can be woken, kept in that device's
+// occupant notes and re-sent whenever the device comes to the foreground,
+// since a push service may hand a device a new one at any time. A token of
+// a store's kind names its bell, the address of the service holding the
+// keys of the app that minted it, and that app, so a world rings a phone
+// running an app it never shipped and holds no key; Web Push is the
+// world's own key and names no service.
+export type Token = { kind: string; bell?: string; app?: string } & JsonObject;
+export const isToken = (v: unknown): v is Token => v !== null && typeof v === 'object' && !Array.isArray(v) && typeof (v as { kind?: unknown }).kind === 'string';
+
+// The bell a token names, when it names one a ring can reach.
+export function bellOf(token: Token): string | undefined {
+  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;
+  }
+}
+
+// One platform's way of ringing. It is handed the token whole, because only
+// the platform knows what is in one, and it says nothing back: a ring either
+// left or threw.
+//
+// `sealed` is the banner, sealed to the device's banner key by the world
+// that rang. Nothing between the world and the device can read it: not this
+// box, not the bell service, not the platform that carries it. A ring with
+// neither a seal nor a line wakes the device and says nothing, which is
+// what a world with nothing to show sends.
+//
+// `line` is the same banner, unsealed, and only a ground whose own
+// encryption the world performs may take one: Web Push, where RFC 8291
+// encrypts the body to keys only that browser holds and the world holds the
+// keypair the subscription was made under. A store's ground is handed the
+// seal and never this, because what carries it is a service the world does
+// not own.
+export type Line = { title: string; body: string };
+export type Ring = { ring(token: Token, sealed?: string, line?: Line): Promise<void> };
+
+// 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: JsonObject): Line {
+  const text = (v: unknown) => (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: JsonObject, key: string): Promise<string | null> {
+  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;
+  }
+}

package/{dock → box}/service.ts

@@ -26,7 +26,7 @@
 // own. An account here would be a registry of worlds, which is the one
 // thing the app is built not to have. The day this is abused it wants a
 // rate limit at the edge, which is the terrain's and not a word of Quo.
-import { bellOf, type Ring, type Token } from './push.ts';
+import { bellOf, type Ring, type Token } from './ring.ts';
 
 // The ring a world holds for a store's kind: the token names its bell and
 // the ring goes there, so a phone running an app this world never shipped
@@ -88,7 +88,7 @@ export function ringing(rings: Record<string, Ring>, apps?: readonly string[]):
     const app = (token as { app?: unknown }).app;
     if (apps && (typeof app !== 'string' || !apps.includes(app))) return answer(400, { error: `this service holds no key for ${typeof app === 'string' ? app : 'an app the token does not name'}` });
     try {
-      await g.ring(token as Token, sealed as string | undefined);
+      await g.ring(token as Token, sealed);
       return answer(200, { rang: kind });
     } catch (e) {
       // The platform's own refusal, passed back as it came. A world reads