@nervur-org/dock 0.4.1 → 0.6.0

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' };
-    }
-  }
-}

package/dock/timer.ts

@@ -1,174 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The box's clock, and the one being on a device that reads one. A being who
-// could read a clock could not be moved, since the moment she read would be
-// her box's and no other, so the moment reaches every other being the one way
-// anything reaches a being: as an ask at her door, from this faculty, as the
-// occupant she named when she asked to be woken.
-//
-// She arms for the next due moment and for nothing else. Every watcher
-// answers a round with when she is next due, this arms for the earliest of
-// them, and a box whose watchers all say null arms nothing and sleeps until
-// somebody keeps something. So a box with no schedules never ticks, and a
-// home on the edge with a sweep at three in the morning wakes once a night.
-//
-// A round is armed for one moment at a time and never overlaps the one
-// before, and the moment is floored to the minute with half a second after
-// it, since a watcher floors the moment she is handed and a round that fired
-// a hair early would floor to the minute before.
-//
-// One method knows a terrain, `arm`, and a subclass replaces it: a
-// `setTimeout` here, the object's storage alarm on a worker. Nothing else in
-// her reads a platform.
-import type { JsonObject } from 'nervur';
-import { Faculty, type Woke } from './faculty.ts';
-
-const MINUTE = 60_000;
-// A timeout further out than this is not trusted, so the arming is capped and
-// made again when it goes off. It is the base class's own bound and no rule
-// of the faculty: a terrain whose alarm holds a month arms for the month.
-const DAY = 86_400_000;
-
-export class Timer extends Faculty {
-  static override asks = {
-    watch: { description: 'wake me when I say I am next due', input: { type: 'object', properties: { invitation: { type: 'object' }, method: { type: 'string' }, args: { type: 'object' } }, required: ['invitation', 'method'] } },
-    due: { description: 'bring my next round forward to this moment', input: { type: 'object', properties: { at: { type: 'number' } }, required: ['at'] } },
-    now: { description: 'this box’s moment', input: { type: 'object' } },
-  };
-
-  #timeout: ReturnType<typeof setTimeout> | undefined;
-  #stopped = false;
-  #armed: number | null = null;
-  #round: Promise<Woke[]> | null = null;
-
-  // The moment she is armed for, or null while she is asleep. For the
-  // device's own code and for a suite; it crosses no door.
-  get armed(): number | null {
-    return this.#armed;
-  }
-
-  // A watcher says she is due sooner than the box knew. It only ever brings
-  // the round forward: what fires is decided at the tick, in the watcher's
-  // own cells, so an arming that moved later on somebody's word would be a
-  // schedule somebody else held silenced. The door is the whole gate here:
-  // a standing at a faculty comes from `lend` alone, and this adds no second
-  // one.
-  due(args: JsonObject): JsonObject {
-    const at = args.at;
-    if (typeof at !== 'number' || !Number.isFinite(at)) return { error: 'a due carries the moment: { at }' };
-    const when = moment(at);
-    if (this.#armed === null || when < this.#armed) this.#arm(when);
-    return { armed: this.#armed };
-  }
-
-  // Whoever was just filed is ticked at once, and what she answers is what
-  // the box arms for. One move covers a box booting, a home moving in and a
-  // watcher born long after the box was up: she is never waiting for a round
-  // nobody scheduled.
-  protected override async welcomed(id: string): Promise<void> {
-    await this.round(Date.now(), id);
-  }
-
-  // The arming went off. A moment still well ahead is the day's cap this
-  // class put on its own timeout, so it is armed again rather than fired: a
-  // terrain calls this and never has to know how far out the arming was.
-  async rang(): Promise<Woke[]> {
-    if (this.#stopped) return [];
-    if (this.#armed !== null && this.#armed - Date.now() > 1_000) {
-      this.arm(this.#armed);
-      return [];
-    }
-    return this.fire(Date.now());
-  }
-
-  // The moment, read here and handed on. A device's own code may call it at a
-  // moment it names, which is how a suite proves a wake without waiting for
-  // one and how an operator makes a round happen now.
-  fire(now: number): Promise<Woke[]> {
-    return this.round(now);
-  }
-
-  // One round, and never two: a second while one is in flight is handed the
-  // one already running. What every watcher answered decides the next
-  // arming, and a `due` that landed while the round ran is not lost.
-  protected round(now: number, only?: string): Promise<Woke[]> {
-    if (this.#round) return this.#round;
-    const mine = this.#run(now, only);
-    this.#round = mine;
-    return mine.finally(() => {
-      if (this.#round === mine) this.#round = null;
-    });
-  }
-
-  async #run(now: number, only?: string): Promise<Woke[]> {
-    if (only === undefined) this.#arm(null); // the arming is spent, whether it went off or the device called this by hand
-    const woke = await this.woke((w) => ({ ...w.args, now }), only);
-    if (woke === null) {
-      this.stop(); // her ward took her out; there is nobody left to wake
-      return [];
-    }
-    // A moment already gone is no arming. Every watcher works out when she is
-    // next due from the moment she was handed, so a round fired by hand at a
-    // moment that is not this box's answers one that is not this box's
-    // either, and a box that armed for it would run a round for a minute long
-    // past. A round at the box's own moment always names one still ahead.
-    const named = soonest(woke);
-    const said = named !== null && named > Date.now() ? named : null;
-    const held = this.#armed;
-    const at = said === null ? held : held === null ? moment(said) : Math.min(held, moment(said));
-    if (at !== null && at !== this.#armed) this.#arm(at);
-    else if (at === null && this.#armed !== null) this.#arm(null);
-    return woke;
-  }
-
-  #arm(when: number | null): void {
-    if (this.#stopped) return;
-    this.#armed = when;
-    this.arm(when);
-  }
-
-  // The one thing a terrain says about itself: be woken at this moment, or at
-  // no moment at all. A subclass replaces this and nothing else of her.
-  //
-  // Here it is a timeout, capped at a day and armed again when the cap goes
-  // off. The box stays up for its work and never for this, so the handle is
-  // unreferenced.
-  protected arm(when: number | null): void {
-    clearTimeout(this.#timeout);
-    this.#timeout = undefined;
-    if (when === null) return;
-    this.#timeout = setTimeout(() => void this.rang(), Math.min(Math.max(when - Date.now(), 0), DAY));
-    this.#timeout.unref?.();
-  }
-
-  // A being her ward took out reaches nobody, so nothing is left to wake. The
-  // device calls this when it puts the box down.
-  stop(): void {
-    this.#stopped = true;
-    this.#armed = null;
-    this.arm(null);
-  }
-
-  now(): JsonObject {
-    return { now: Date.now() };
-  }
-}
-
-// Half a second past the minute a moment falls in, and never before the
-// moment itself: a watcher floors what she is handed, so a round that fired a
-// hair early would floor to the minute before and fire nothing.
-const moment = (at: number): number => Math.max(at, Math.floor(at / MINUTE) * MINUTE + 500);
-
-// What one round learned. Every watcher says when she is next due, and the
-// box arms for the earliest of them. A watcher who named no moment has
-// nothing to be woken for, and so has one who answered something that is no
-// tally at all.
-function soonest(woke: Woke[]): number | null {
-  let at: number | null = null;
-  for (const w of woke) {
-    if (w.out === null || typeof w.out !== 'object') continue;
-    const next = (w.out as { next?: unknown }).next;
-    if (typeof next !== 'number' || !Number.isFinite(next)) continue;
-    if (at === null || next < at) at = next;
-  }
-  return at;
-}

package/quo-api.md

@@ -1,196 +0,0 @@
-# The api route
-
-This is the fourth rendering of one describe. The screen speaks a being's
-describe as forms, the model side speaks it as tools, the CLI speaks it as
-lines, and this route speaks it as plain HTTP and JSON. It is one route of
-the daemon described in `papers/quo-dock.md`, which owns the routes, the
-grants, the avatar and the shared invariants; this document assumes all of
-that and adds only what the route does. `papers/WORLDS.md` decides what
-every route is held to: a route says the grammar a caller speaks and never
-who the caller is, and the same credential is honoured on every route.
-
-## What it is for
-
-A route hears every rung. A request carrying nothing is the stranger every
-route knows: an ask at the named ward's public being as `{}`, which is what
-every stranger is at every door, and what a browser fetch, a page
-rendering server side, a crawler and a tab on another origin are. A
-request carrying a bearer the box granted is an occupant: the identity's
-avatar in the world the grant names, asked through her one standing at the
-world's being. What a script sees with a bearer is what a model sees with
-the same bearer as tools and a tab sees as forms, because all three are
-one avatar's describe for one identity, and the gate is one decision for
-describe and for dispatch. The route judges nothing and names nobody: the
-public being answers a stranger by her own gate, the world's being answers
-an occupant by hers, and the route carries the answer.
-
-A grant is the box's and may die at any moment: a box wiped, an occupant
-removed at the world's being, thirty days without a refresh. Nothing of
-the world dies with it, since the avatar and her standing are the ward's;
-only the box's memory of which token names her is gone, and the holder
-trades again on a fresh invitation and lands on the same avatar. So a
-bearer is held by something with a human near it: a model client whose
-human clicks the allow page again, a script whose root mints again, a
-SaaS whose operator signs up again as at any vendor. A program of the
-org's that must run without a human is not a caller of this route. It is
-a harbor of the org with a ward and a standing, or an agent the daemon
-boots on the box, and either speaks Quo on keys that do not expire.
-
-A world is a ward, so the route names one. Every ward `init` made holds a
-desk, who is public for the first hello and answers a stranger nothing
-else, so a world's public reads live in a ward of their own, and the route is what
-makes a second ward reachable by name from outside: the corpus of a court
-watcher, a catalogue, a board. An occupant's world is the one her
-invitation named, and a bearer on any other world is refused.
-
-## The mapping
-
-`packages/dock/api/route.ts` is the route, `Request` in and `Response` out
-and naming no terrain: the daemon mounts it under `/api` and the proxy maps
-it from the api. hostname, and the worker at the edge mounts the same file
-under its harbor's prefix. It asks its harbor for the wards it holds and for
-which of them a caller who names none is at, and for nothing else.
-
-| request                              | Quo                                                                  |
-| ------------------------------------ | -------------------------------------------------------------------- |
-| `POST /api` `{identity, invitation}` | the trade: her avatar knocks with it, and a grant is issued          |
-| `POST /api` `{refresh}`              | the next grant; the old refresh token dies                           |
-| `GET /api`                           | the describe of the default ward, as `GET /api/<that ward>`          |
-| `GET /api/<ward>`                    | the describe: the public being for nobody, the avatar under a bearer |
-| `GET /api/<ward>/<ask>?k=v`          | that ask, the query as args, every value a string                    |
-| `POST /api/<ward>/<ask>` JSON body   | that ask, the object as args                                         |
-| `POST /api/<ward>/<being>/deliver`   | a vendor's delivery, the raw body and the headers to that envoy      |
-| `GET /api/<ward>/<being>/deliver`    | the same with an empty body: a redirect lands here, query in headers |
-| `OPTIONS`                            | the preflight, any origin, `authorization` allowed                   |
-
-What a caller leaves unsaid follows `papers/WORLDS.md`, and none of it is
-a default the route picks. A credential names an identity in a world, so an
-occupant's ward is her grant's and a bearer on any other ward is refused.
-A stranger carries nothing that names a world, so a stranger who names no
-ward is at the ward the terrain says it is at, the one the box hosts or the
-one it marks, and `GET /api` is what a tab at the web
-route's root sees and a model's first tool list. A being is never named,
-because a caller
-does not choose who answers: naming a ward is naming a door, and behind it
-the ward decides, the public being as nobody for a stranger and the
-identity's avatar for an occupant. The one path that names a being is the
-delivery, and there it is not a choice either: the envoy claimed that path
-at her birth, and a delivery with no envoy named has nowhere to land and
-is 404, never the public being.
-
-The trade is the allow page of the model side without the page. Nobody at
-a page vouches for a program, so a trade is a knock that spends: the
-invitation is the one the root minted for that identity on the world's
-being with `nervur invite`, sent as a line, and the avatar knocks with it
-inside the trade. An identity already in is refused with `already in` and
-refreshes instead, or is removed at the world's being and invited again,
-and never re-enters on a spent invitation. What comes back is the box's
-grant, `dock/grants.ts`: an access token for an hour, a refresh token for
-thirty days, the same grant the OAuth dance issues, honoured on the model
-route too.
-
-What she says crosses as the model side crosses it:
-
-| she answered                   | the client gets                                        |
-| ------------------------------ | ------------------------------------------------------ |
-| an object                      | 200 with that JSON                                     |
-| `{ error }`                    | 400 with that JSON                                     |
-| silence, a throw, a wait spent | 503 `{ error: 'silence' }`: the work may have happened |
-| an ask not hers for this asker | 400 `{ error: 'unknown ask' }`, her own answer         |
-
-For a stranger, a ward with nobody at the door is 503 beside them, and
-not a 404 of its own: on the wire a stranger who asks a ward that has no
-public being hears one silence, and a device speaking for strangers says
-what the door would. A stranger learns which world exists here and nothing
-else about it. For an occupant the ward's words cross by name, `unreached`
-as 503 `{ error: 'unreached' }`, and `removed` is 401 `{ error: 'removed'
-}` with the grant forgotten at the box, so a script the world's being
-removed starts over with a fresh invitation, exactly as a model client
-does.
-
-And what the route says on its own: 404 for a ward not here and for a path
-that is not one of the shapes, 400 for a body that is not a JSON object,
-400 `{ error: 'already in' }` for a trade on an identity that holds a live
-standing, 401 `{ error: 'unauthorized' }` for a bearer nobody issued or one
-that died, 403 `{ error: 'not your world' }` for a bearer on a world the
-grant does not name, 413 for a body past a megabyte, 405 for any other
-method. Every answer is JSON and open to any origin: the route carries
-nothing a stranger can use that she did not choose to say, and a bearer is
-the caller's to keep.
-
-The route holds none of the judgement. For a stranger it asks the ward the
-owner's `ask` with no being named, which is the public being asked as
-nobody, and the ward bounds the wait, names the three choices and saves
-before the pointer returns: a public being may write while answering, a
-tally, a board, and what she wrote is hers to keep. For an occupant it
-asks her avatar, `tools` for the describe and `call` for an ask, the two
-things every side asks of her, and saves the ward after.
-
-## The delivery
-
-A vendor's webhook is not a stranger's ask and does not land as `{}`, and
-it is not an occupant's ask either: it is the owner asking the envoy
-`deliver`, as `papers/quo-dock.md` says of envoys, and the route carries
-the bytes and nothing of the judgement. `POST /api/<ward>/<being>/deliver`
-is its own row and not an ask: the body is read as a string and never
-parsed here, since the vendor signed the bytes and a reparsed body fails
-her check, and the rule that a body is a JSON object does not apply. The
-route asks the ward's owner pointer for that being's `deliver` with `{
-body, headers }`, and answers what she answers: `{ ok }` as 200, her error
-object as 400, silence as 503. No bearer is read on this path, because the
-rung is not the caller's to prove: the signature is hers to check, and
-what fails it is refused by her and never by the route.
-
-A `GET` on the same path is the same ask with an empty body, and is where
-an OAuth redirect lands when an envoy begins an account, the code in the
-query. The query crosses inside the headers object under the name
-`:query`, which no header on the wire can carry, so her one ask in stays
-one and an author writes no second door for redirects. What she answers
-crosses as JSON like any delivery.
-
-**And a browser gets a page.** This is a road for programs with exactly one
-human arrival, and it is somebody who has just paid for something: a vendor
-returns her by opening this URL in her tab, so without a page she ends a
-payment reading what an envoy says to a machine. A `GET` whose `accept`
-names HTML is answered with the human side's landing page, saying which of
-the two happened and offering the world's own page, since a tab a vendor
-opened has no history to go back through. What the envoy answered is never
-on it. Everything else is unchanged: a vendor asking for JSON is answered
-in JSON, a `GET` that says nothing about what it wants is answered in JSON,
-and the page carries no cross-origin header, since a page is for the
-browser that was sent here and never for a script somewhere else.
-
-On its own the route says 404 for a ward not here, for a being not hers
-and for a third segment that is not `deliver`, 413 past a megabyte and 405
-for any method but `POST` and `GET`. A vendor that retries on anything but a quick
-200 lands once, because she keeps the delivery id and answers `{ ok }` for
-one she has seen before she wakes anyone.
-
-## What is not here
-
-A ward's delivery reaching more than one envoy, and a vendor that cannot
-sign what it sends. Both stand when a first user does.
-
-## The proof
-
-`packages/dock/test/api.test.ts`, over a real daemon on loopback. A
-stranger: a world with a public board described and asked by anyone, args
-by query and by body, what she wrote kept across a reboot, no ward named
-being the device's own, and every refusal. An occupant: an invitation
-traded for a grant, the describe under the bearer being the avatar's own
-with no ward named and with hers, an ask through her, another world
-refused, refresh rotating, removal at the world's being ending the grant,
-and the identity let in again on a fresh invitation. One identity, two
-grammars: a bearer the OAuth dance issued honoured here and its refresh
-rotating at the trade, a bearer the trade issued opening an MCP session,
-and the tool list being this route's describe with her look and page
-left out. The delivery: signed bytes landing on an envoy's `deliver` as
-the owner, a good signature kept and woken once, a retry landing once, a
-bad one her refusal as 400, no bearer read, what she kept outliving the
-daemon, and the route's own 404, 405 and 413.
-
-The same route on a second terrain is
-`packages/dock/test/terrain/edge.test.ts`, behind `npm run deep:dock`: the
-trade at a worker's `/api`, the ask through her avatar, and the answer
-compared against a Node daemon doing the same thing, because a rendering of
-one describe must not differ by terrain.