@nervur-org/dock 0.5.0 → 0.6.0

package/dock/faculty.ts

@@ -1,148 +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';
-import type { Asker, JsonObject } from 'nervur';
-
-// One subscription, as she files it: her own id for the relation, who asked
-// for it, and what to ask them.
-export type Watched = { by: string; method: string; args: JsonObject };
-
-// What one round of waking did, per subscription.
-export type Woke = { id: string; by: string; out: unknown };
-
-export class Faculty extends Being {
-  static override cells: JsonObject = { 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: JsonObject, asker: Asker): Promise<JsonObject> {
-    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 as unknown as { watched: Record<string, Watched>; minted: number };
-    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.
-  protected async welcomed(_id: string): Promise<void> {}
-
-  // 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.
-  protected async woke(round: (w: Watched) => JsonObject = (w) => w.args, only?: string): Promise<Woke[] | null> {
-    const cells = this.cells as unknown as { watched: Record<string, Watched> };
-    const out: Woke[] = [];
-    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(): Record<string, Watched> {
-    return this.cells.watched as unknown as Record<string, 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<Promise<unknown>>();
-export const settled = async (): Promise<void> => {
-  while (flight.size) {
-    const now = [...flight];
-    await Promise.allSettled(now);
-    for (const p of now) flight.delete(p);
-  }
-};
-
-export function join(b: Being, name: string, watch?: { method: string; args?: JsonObject }, id = name): Promise<string | null> {
-  const p = joining(b, name, watch, id);
-  flight.add(p);
-  void p.catch(() => {});
-  return p;
-}
-
-async function joining(b: Being, name: string, watch: { method: string; args?: JsonObject } | undefined, id: string): Promise<string | null> {
-  // 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/dock/grants.ts

@@ -1,111 +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.ts';
-
-// 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 = <T>(rec: Record<string, T>, key: string): T | undefined => (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('=', '');
-};
-
-// A grant names the world the identity was let into, since one harbor holds
-// many, and the client it was issued to: an OAuth client id, or the route
-// that traded for it.
-export type Grant = { identity: string; ward: string; client: string; exp: number };
-type Kept = { access: Record<string, Grant>; refresh: Record<string, Grant> };
-export type Tokens = { access_token: string; token_type: 'Bearer'; expires_in: number; refresh_token: string; scope: 'nervur' };
-
-export class Grants extends Faculty {
-  static override cells = { ...Faculty.cells, access: {}, refresh: {} };
-  static override 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: () => Promise<void> = async () => {};
-  // The clock, a suite's to move.
-  now: () => number = () => Date.now();
-
-  get kept(): Kept {
-    return this.cells as unknown as Kept;
-  }
-
-  async issue(identity: string, ward: string, client: string): Promise<Tokens> {
-    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: string): Promise<Tokens | null> {
-    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: Request): { identity: string; ward: string } | null {
-    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: string, ward: string): Promise<void> {
-    for (const k of ['access', 'refresh'] as const) 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(): void {
-    const now = this.now();
-    for (const k of ['access', 'refresh'] as const) 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: Request): string => {
-  const h = req.headers.get('authorization') ?? '';
-  return h.startsWith('Bearer ') ? h.slice(7) : '';
-};

package/dock/index.ts

@@ -1,133 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The dock ward: the ward a harbor boots and roots for itself, holding what
-// the box can do. `stand` puts it up and answers the `lend` a harbor hands
-// its other wards, which is the whole of what a terrain says about itself.
-//
-// Which names a box lends is the terrain's word; which ward may ask for one
-// is the harbor's, decided in `lendFor`, and a ward whose code came from a
-// stranger is lent nothing.
-import type { Harbor, Lend } from 'nervur/harbor';
-import type { JsonObject } from 'nervur';
-import { isInvitation } from 'nervur';
-import { Faculty } from './faculty.ts';
-import { Console, 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';
-// 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, 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 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: Record<string, string> = { [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: Harbor, lent: Record<string, string> = FACULTIES): Promise<Lend> {
-  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);
-}
-
-// A ward as its root holds it: the ask pointer, and a save where the terrain
-// keeps one. Every harbor here has both; a memory harbor has the first.
-export type Rooted = { ask(method?: string, args?: Record<string, unknown>): Promise<unknown>; save?(): Promise<void> };
-
-// 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: Rooted, lent: Record<string, string> = FACULTIES): Promise<Lend> {
-  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 as unknown as JsonObject });
-  }
-  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: Rooted): Lend {
-  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 = (): string =>
-  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<F extends Faculty>(harbor: Harbor, name: string): F | undefined {
-  return harbor.wards.get(DOCK)?.being(name) as F | undefined;
-}

package/dock/local.ts

@@ -1,48 +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.ts';
-import type { JsonObject } from 'nervur';
-import { VERIFY, type Verified } from '../beings/way.ts';
-
-// 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 override asks = { verify: VERIFY };
-
-  readonly #nonces = new Map<string, Verified>();
-
-  // 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: 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 as JsonObject).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/push.ts

@@ -1,161 +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 type { Asker, JsonObject, OccupantRecord } from 'nervur';
-import { Faculty } from './faculty.ts';
-import { mintVapid } from './webpush.ts';
-
-// 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;
-  }
-}
-
-// The root and nobody else: where a box hands a phone's ring is the box's own.
-const root = (_occ: OccupantRecord | undefined, asker: 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 override cells: JsonObject = { watched: {}, minted: 0, key: null, service: null };
-  static override 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(): Promise<JsonWebKey> {
-    if (this.cells.key === null) this.cells.key = (await mintVapid()).key as unknown as JsonObject;
-    return 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. A terrain overrides it and builds its rings from
-  // its environment and this being's cells; 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' };
-    }
-  }
-}