@nervur-org/dock 0.3.0

package/dock/grants.ts

@@ -0,0 +1,111 @@
+// 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: 'quo' };
+
+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: 'quo' };
+  }
+
+  // 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/http2.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+// Apple, from a Node box. The APNs provider API is HTTP/2 only and refuses
+// HTTP/1.1, and Node's `fetch` speaks HTTP/1.1 alone, so a droplet cannot
+// ring Apple through `apns.ts` at all. This is the same ring over
+// `node:http2`: the same provider token, the same path, the same headers
+// and the same body, which all live in `apns.ts` and are written once,
+// because a phone that is rung two ways must be rung the same way twice.
+//
+// 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`.
+//
+// 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 { 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
+// which app is being rung. A box holding none is a box that rings no
+// iPhones, which is every box but a bell's.
+export function apnsOf(env: Record<string, string | undefined>): Apns | null {
+  const { QUO_APNS_KEY: key, QUO_APNS_KEY_ID: keyId, QUO_APNS_TEAM: teamId, QUO_APNS_TOPIC: topic } = env;
+  return key && keyId && teamId && topic ? { key, keyId, teamId, topic } : null;
+}
+
+// How long a ring waits on Apple before it is a ring that did not leave. A
+// ring that hangs is worse than one that failed: the world behind it is
+// holding an ask open, and a push that is late is a push that is wrong.
+const WITHIN = 10_000;
+
+export function apnsHttp2(a: Apns, at: typeof HOSTS = HOSTS, within = WITHIN): Ring {
+  let made: { at: number; jwt: string } | null = null;
+  const held = new Map<string, ClientHttp2Session>();
+  const session = (host: string): ClientHttp2Session => {
+    const live = held.get(host);
+    if (live && !live.closed && !live.destroyed) return live;
+    const s = connect(host);
+    const gone = () => {
+      if (held.get(host) === s) held.delete(host);
+    };
+    s.on('error', gone);
+    s.on('close', gone);
+    s.unref();
+    held.set(host, s);
+    return s;
+  };
+  return {
+    async ring(token: Token, sealed?: string) {
+      made = await provider(a, made);
+      const req = request(a, made.jwt, token, sealed);
+      const stream = session(token.sandbox === true ? at.sandbox : at.production).request({ ':method': 'POST', ':path': req.path, ...req.headers });
+      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));
+        stream.on('error', no);
+        stream.on('end', () => ok({ status, text }));
+        stream.end(req.body);
+      });
+      answered(status, text);
+    },
+  };
+}

package/dock/index.ts

@@ -0,0 +1,133 @@
+// 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-org/nervur/harbor';
+import type { JsonObject } from '@nervur-org/nervur';
+import { isInvitation } from '@nervur-org/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

@@ -0,0 +1,48 @@
+// 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-org/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/location.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+// Where the box is. One blueprint, and as many bodies as there are terrains:
+// a phone's plugin, a laptop's platform call, a suite's stub. This is the
+// blueprint and the answer a box that cannot gives, and a terrain that can
+// subclasses it. A box with no way at all boots her not at all, and a being
+// who asks for the name is lent nothing.
+import type { JsonObject } from '@nervur-org/nervur';
+import { Faculty } from './faculty.ts';
+
+export type Where = { lat: number; lng: number; accuracy?: number; at: number };
+
+export class Location extends Faculty {
+  static override 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(): Promise<JsonObject> {
+    return Promise.resolve({ error: 'this box cannot say where it is' });
+  }
+}

package/dock/notifications.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's notification center: show the human a line. One blueprint, and a
+// body per terrain. The platform's own permission prompt is the first ask's,
+// and a refusal is the error object every ask after it answers.
+//
+// She also keeps the banner key, which is the one key a world seals a
+// notification to. It is the device's, one pair, minted here the first time
+// it is asked for and kept in her cells; the public half is what a device
+// hands a world it admits, and the secret half never leaves the box.
+//
+// It sits here and not in a being of the library's for one reason. On a
+// phone the process that draws a banner is not the app: an extension runs
+// between the platform and the screen, and it must be able to open the seal
+// before anything is shown. So the secret has to reach wherever that
+// terrain's notification process can read it, and putting a key somewhere a
+// platform can find it is the terrain's business, which is what a faculty
+// is. A terrain overrides `plant` and does it its own way; a terrain that
+// has no second process does nothing and the key never leaves these cells.
+//
+// It is not the ward's seed. That one opens everything the person sees and
+// is kept so that it never leaves the device at all. This one opens
+// banners, and if the process that draws them were ever turned against her
+// it would cost her a line of text rather than her world.
+import { arithmetic } from '@nervur-org/nervur/ward';
+import type { JsonObject } from '@nervur-org/nervur';
+import { Faculty } from './faculty.ts';
+
+// A key is thirty two bytes of the platform's own randomness, as every seed
+// in this kit is.
+const seed = (): Uint8Array => globalThis.crypto.getRandomValues(new Uint8Array(32));
+
+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' } },
+  };
+
+  notify(_args: JsonObject): Promise<JsonObject> {
+    return Promise.resolve({ error: 'this box shows no notifications' });
+  }
+
+  // The pair, minted once and kept. Every call after the first is the same
+  // key, because a device that minted a new one on every ask would be a
+  // device whose worlds all seal to a key it has forgotten.
+  async key(): Promise<{ secret: Uint8Array; pk: Uint8Array }> {
+    if (typeof this.cells.banner !== 'string') {
+      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));
+  }
+
+  async banner(_args: JsonObject): Promise<JsonObject> {
+    return { banner: arithmetic.hex((await this.key()).pk) };
+  }
+
+  // Where this terrain's notification process reads the secret half. The
+  // base plants nothing, which is right for a terrain that draws its own
+  // banners in the same process; a phone overrides it and writes into the
+  // keychain group its extension shares with the app.
+  protected plant(_pair: { secret: Uint8Array; pk: Uint8Array }): Promise<void> {
+    return Promise.resolve();
+  }
+}

package/dock/push.ts

@@ -0,0 +1,161 @@
+// 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-org/nervur';
+import { arithmetic } from '@nervur-org/nervur/ward';
+import type { Asker, JsonObject, OccupantRecord } from '@nervur-org/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) || 'quo';
+  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' };
+    }
+  }
+}