@nervur-org/dock 0.3.0

package/beings/desk.ts

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

package/beings/doorbell.ts

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

package/beings/envoy.ts

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

package/beings/index.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Apache-2.0
+// The beings every side shares. See quo-dock.md, the trunk.
+export { User, DESK, HOME, BELL } from './user.ts';
+export { Desk } from './desk.ts';
+export { WAY, kindOf, verified, VERIFY, SEND, type Proof, type Verified } from './way.ts';
+export { Avatar, USER, PUSHER } from './avatar.ts';
+export { Carrier } from './carry.ts';
+export { Presence } from './presence.ts';
+export { Courier, MOVER, isMoving, type Moving } from './courier.ts';
+export { Porter } from './porter.ts';
+export { Doorbell } from './doorbell.ts';
+export { Envoy, owner, occupant, type Delivery, type Wake, type Heard } from './envoy.ts';
+export { DOCK, CONSOLE, LOCAL, LOCATION, NOTIFICATIONS, PUSH, TIMER, FACULTIES, FACULTY_CLASSES, Console, Faculty, Local, Location, Notifications, Push, Timer, isToken, join, settled, stand, standOn, lending, facultyOf, type Ring, type Token, type Where, type Watched, type Woke, type Rooted } from '../dock/index.ts';
+export { webPush, mintVapid, publicOf, apnsPush, pkcs8, HOSTS, fcmPush, isAccount, DOORS, handedTo, ringing, routed, type Vapid, type Apns, type Account, type Doors } from '../dock/index.ts';
+export { Clock, CLOCK, setupClock, placeClock, readSchedule, parseCron, nextFire, civil, fromCivil, type Schedule, type Fire, type Cron, type Civil } from './clock.ts';
+export { sanitise, hint, hintFor, groups, type Look, type Hint } from './look.ts';

package/beings/join.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// An identity in a world, as a route needs her: her avatar found or booted,
+// her way in with an invitation, and her avatar as she already stands. It is
+// three asks at a ward's own door and nothing of any terrain, so the daemon
+// and the worker at the edge hand the same functions to the same routes.
+//
+// A way in that is the box's own, a nonce on the `local` faculty, is not
+// here: it is a process the device saw on its own socket, which only a
+// terrain with processes has, and the daemon keeps it.
+import type { Hosted } from '@nervur-org/nervur/harbor';
+import type { Invitation } from '@nervur-org/nervur';
+import type { Avatar } from './avatar.ts';
+
+// Her avatar in a ward, found or booted under the identity's key. An
+// identity is a word, and never a being of the ward.
+export async function avatarOf(hosted: Hosted, identity: string): Promise<{ avatar?: Avatar; error?: string }> {
+  if (!/^[\w.-]+$/.test(identity) || identity === hosted.record.user || identity === 'desk') return { error: 'an identity is a word, and not a being of the ward' };
+  const key = `avatar:${identity}`;
+  let avatar = hosted.being(key) as Avatar | undefined;
+  if (!avatar) {
+    const out = (await hosted.ask('boot', { key, class: 'Avatar' })) as { error?: string };
+    if (out.error) return { error: out.error };
+    avatar = hosted.being(key) as Avatar;
+  }
+  return { avatar };
+}
+
+// Join a client identity to a ward with an invitation the root minted for
+// it: find or boot her avatar, and she knocks. The one path for an identity
+// from elsewhere, the exchange page. Nothing is typed to get in but the
+// invitation, and the knock spends it.
+export async function letIn(hosted: Hosted, identity: string, invitation: Invitation): Promise<{ avatar?: Avatar; error?: string }> {
+  const found = await avatarOf(hosted, identity);
+  if (!found.avatar) return found;
+  const joined = await found.avatar.join(invitation);
+  await hosted.save();
+  if ('error' in joined && !('asks' in joined)) return { error: joined.error };
+  return { avatar: found.avatar };
+}
+
+// Her avatar as she stands, for a session opening under a grant: she is in
+// or she is not, and nothing is minted here. An identity the user being
+// removed hears `removed` on her describe, which the endpoint speaks as 401.
+export async function find(hosted: Hosted, identity: string): Promise<{ avatar?: Avatar; error?: string }> {
+  const avatar = hosted.being(`avatar:${identity}`) as Avatar | undefined;
+  if (!avatar) return { error: 'not joined' };
+  const bp = await avatar.tools();
+  await hosted.save();
+  if ('error' in bp && !('asks' in bp)) return { error: bp.error };
+  return { avatar };
+}

package/beings/link.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+// A link: a world's page with an invitation in the fragment. The page is the
+// hint, where the world lives; the fragment is the invitation, which never
+// leaves the browser: a query string reaches the server, its logs and every
+// referer, and an invitation is a capability. One reserved key, `quo`, the
+// one word no page uses for anything else, and the value is the invitation
+// compact: `ward.heir.secret`, three hex strings, or `ward` alone for a
+// world's public being. The dock's human module reads it, strips it before
+// any page code runs, and joins. One other key is reserved, `proof`, for the
+// way in a world sent out itself, and it is read the same way.
+import type { Invitation } from '@nervur-org/nervur';
+
+export const KEY = 'quo';
+// The other reserved key: a proof, for a way in the world sent out itself.
+// A proof is not a capability into a ward, it is a word one door will trade
+// once for an invitation, and it rides in the fragment for the same reason:
+// a query string is in every log and every referer, and one read of it is
+// one way in taken. `<kind>.<token>`, the kind the desk knows it by and the
+// token that door minted.
+export const PROOF = 'proof';
+const HEX = (n: number) => `[0-9a-f]{${n}}`;
+const FULL = new RegExp(`^(${HEX(128)})\\.(${HEX(64)})\\.(${HEX(64)})$`);
+const PUBLIC = new RegExp(`^${HEX(128)}$`);
+
+export function format(inv: Invitation): string {
+  return inv.heir && inv.secret ? `${inv.ward}.${inv.heir}.${inv.secret}` : inv.ward;
+}
+
+// The invitation in a fragment, or null. Anything else in the fragment is
+// the page's own and is left alone.
+export function parse(hash: string): Invitation | null {
+  const m = /(?:^#|&)quo=([^&]+)/.exec(hash.startsWith('#') ? hash : `#${hash}`);
+  if (!m) return null;
+  const v = decodeURIComponent(m[1]);
+  const full = FULL.exec(v);
+  if (full) return { ward: full[1], heir: full[2], secret: full[3] };
+  return PUBLIC.test(v) ? { ward: v } : null;
+}
+
+// The proof in a fragment, or null. The kind is a word and the token is
+// whatever the door that minted it wrote, opaque here and never read.
+export function parseProof(hash: string): { kind: string; token: string } | null {
+  const m = new RegExp(`(?:^#|&)${PROOF}=([^&]+)`).exec(hash.startsWith('#') ? hash : `#${hash}`);
+  if (!m) return null;
+  const v = decodeURIComponent(m[1]);
+  const at = v.indexOf('.');
+  if (at < 1 || at === v.length - 1) return null;
+  const kind = v.slice(0, at);
+  return /^[\w-]{1,40}$/.test(kind) ? { kind, token: v.slice(at + 1) } : null;
+}
+
+// The fragment without what the dock reserves, so the page keeps whatever
+// else it put there and neither capability is left in the address bar.
+export function strip(hash: string): string {
+  const rest = (hash.startsWith('#') ? hash.slice(1) : hash)
+    .split('&')
+    .filter((p) => !p.startsWith(`${KEY}=`) && !p.startsWith(`${PROOF}=`))
+    .join('&');
+  return rest ? `#${rest}` : '';
+}
+
+export function link(page: string, inv: Invitation): string {
+  return `${page}#${KEY}=${format(inv)}`;
+}
+
+// A world's own way in, as it goes out in a mail or a message: the page of
+// the world it is for, with the proof in the fragment.
+export function proofLink(page: string, kind: string, token: string): string {
+  return `${page}#${PROOF}=${encodeURIComponent(`${kind}.${token}`)}`;
+}
+
+// The invitation as a human hands it over: the compact form, the whole link
+// it came in, or the JSON value `quo invite` printed. Wherever a person
+// types or pastes an invitation, this is what reads it, so the three forms
+// are one form everywhere.
+export function invitationOf(text: string): Invitation | null {
+  const t = text.trim();
+  const hash = t.indexOf('#');
+  const linked = parse(hash === -1 ? `#${KEY}=${t}` : t.slice(hash));
+  if (linked?.heir) return linked;
+  try {
+    const v = JSON.parse(t) as Record<string, unknown>;
+    if (v && typeof v === 'object' && typeof v.ward === 'string' && typeof v.heir === 'string' && typeof v.secret === 'string') return { ward: v.ward, heir: v.heir, secret: v.secret };
+  } catch {
+    /* not JSON either */
+  }
+  return null;
+}
+
+// The reach note in front of an invitation: the URL a link was written on,
+// which for a link between two devices is the rendezvous to dial to reach
+// the one that wrote it. A hint is not a capability, so it travels beside
+// the invitation in the open. Nothing that is not a URL is one.
+export function reachOf(text: string): string | null {
+  const t = text.trim();
+  const hash = t.indexOf('#');
+  const before = hash === -1 ? '' : t.slice(0, hash);
+  try {
+    return /^https?:$/.test(new URL(before).protocol) ? before : null;
+  } catch {
+    return null;
+  }
+}
+