@nervur-org/dock 0.4.1 → 0.6.0

package/box/dialers.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's lines: a socket held to another box's quo. route, one per row,
+// announcing this harbor's wards on open and reconnecting when a line drops.
+// The rows are her cells, placed by the root with `keep`. The harbor she
+// dials for is the terrain's, handed at birth in the class body it brings;
+// this body dials nothing and stands nowhere. Every row is dialed once the
+// box is up, and a row kept after that is dialed at once.
+import { OWNER } from 'nervur';
+import type { Asker, JsonObject, OccupantRecord, Stance } from 'nervur';
+import { dial, type Dialer, type Harbor } from 'nervur/harbor';
+import type { Harborage } from './box.ts';
+import { contract } from './contract.ts';
+import { Faculty } from './faculty.ts';
+
+export type Row = { url: string };
+
+const root = (_occ: OccupantRecord | undefined, asker: Asker) => asker.id === OWNER;
+
+const URL_ = { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] };
+
+const ASKS = {
+  keep: { description: 'hold a socket to that quo. route, from now and from every boot, until it is dropped', input: URL_, for: root },
+  drop: { description: 'close the socket to that route and forget it', input: URL_, for: root },
+  list: { description: 'every route she dials, and whether the line is open now', input: { type: 'object' }, for: root },
+};
+
+// What the box's own code needs from the faculty that holds its lines.
+export const DIALERS = contract('dialers', ASKS);
+
+export class Dialers extends Faculty {
+  static override cells: JsonObject = { watched: {}, minted: 0, dialers: {} };
+  static override asks = ASKS;
+  static override fulfils = [DIALERS];
+  static override stands(): boolean {
+    return false;
+  }
+
+  readonly harbor: Harbor | undefined;
+  readonly open = new Map<string, Dialer>();
+  #up = false;
+
+  constructor(stance: Stance, box?: Harborage, harbor?: Harbor) {
+    super(stance, box);
+    this.harbor = harbor;
+    this.box.up(() => {
+      this.#up = true;
+      for (const row of Object.values(this.rows)) this.#dial(row.url);
+      return Promise.resolve();
+    });
+  }
+
+  private get rows(): Record<string, Row> {
+    return this.cells.dialers as unknown as Record<string, Row>;
+  }
+
+  #dial(url: string): void {
+    if (!this.harbor || !this.#up || this.open.has(url)) return;
+    this.open.set(url, dial(this.harbor, url));
+  }
+
+  keep(args: JsonObject): JsonObject {
+    const url = args.url;
+    if (typeof url !== 'string' || !/^https?:\/\/\S+$/.test(url)) return { error: 'url is the quo. route of the harbor dialed, over http or https' };
+    const clean = url.replace(/\/$/, '');
+    this.rows[clean] = { url: clean };
+    this.#dial(clean);
+    return { kept: clean };
+  }
+
+  drop(args: JsonObject): JsonObject {
+    const url = typeof args.url === 'string' ? args.url.replace(/\/$/, '') : '';
+    if (!this.rows[url]) return { error: 'no such route' };
+    this.open.get(url)?.close();
+    this.open.delete(url);
+    delete this.rows[url];
+    return { dropped: url };
+  }
+
+  list(): JsonObject {
+    return { dialers: Object.keys(this.rows).map((url) => ({ url, open: this.open.get(url)?.socket !== null && this.open.has(url) })) };
+  }
+
+  // The device puts the box down: every line closes, the rows stay.
+  close(): void {
+    for (const d of this.open.values()) d.close();
+    this.open.clear();
+  }
+}

package/box/dock.ts

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box ward's own being, and so the harbor's. She is the kit's Box, the
+// box as one standing that every hosted ward holds, and two things more.
+//
+// She lends by contract: a being asks her for a contract's digest, and she
+// holds each faculty under its key, so her cells keep the index from digest
+// to key, written whole by the root at every boot from what this run's
+// classes say. A name she is asked to offer is a digest first and a key
+// second, and then it is the kit's offer.
+//
+// And she carries: she holds a standing at every faculty her harbor stood
+// and shows their asks as her own to whoever the root let in, so the one
+// screen a device has with no world joined draws her the way it draws any
+// being.
+import { OWNER } from 'nervur';
+import { Box, BOX_SEED } from 'nervur/harbor';
+import type { Asker, JsonObject, OccupantRecord, Reply } from 'nervur';
+import { carry } from '../beings/carry.ts';
+
+export { BOX } from 'nervur/harbor';
+
+const root = (_occ: OccupantRecord | undefined, asker: Asker) => asker.id === OWNER;
+
+// The public origins a proxy serves for this box, `mcp.`, `web.`, `quo.`
+// and `api.`, by the one convention: under one domain, over https. A domain
+// is said once and the names follow.
+export type Routes = { mcp: string; web: string; quo?: string; api?: string };
+export const DOMAIN = /^[a-z0-9.-]+\.[a-z]{2,}$/i;
+export function routesFor(domain: string): Required<Routes> {
+  if (!DOMAIN.test(domain)) throw new Error(`${domain} is not a domain`);
+  return { mcp: `https://mcp.${domain}`, web: `https://web.${domain}`, quo: `https://quo.${domain}`, api: `https://api.${domain}` };
+}
+
+// The apps this box's links open, as the two platforms want them named. A
+// box that names none serves no association file, and its links open the
+// tab.
+export type Apps = { apple: string[]; android: { package: string; fingerprints: string[] }[] };
+
+// What the box is, as the root placed it through her asks and as the
+// harbor reads it at boot: its routes, its apps and the ward a caller means
+// when naming none. Null is unsaid.
+export type BoxCells = { routes: Routes | null; apps: Apps | null; default: string | null };
+
+const APPS = { type: 'object', properties: { apple: { type: 'array', items: { type: 'string' } }, android: { type: 'array', items: { type: 'object', properties: { package: { type: 'string' }, fingerprints: { type: 'array', items: { type: 'string' } } }, required: ['package', 'fingerprints'] } } } };
+
+export class Dock extends Box {
+  static carries(occupant: OccupantRecord | undefined): boolean {
+    return occupant !== undefined;
+  }
+  // She holds every faculty twice: under its key, which is the lend seam
+  // and plumbing, and under the word the first contract it is lent under
+  // calls itself, which is the section a screen shows. A key is a path
+  // through the class tree and always carries a slash; a title never does.
+  // Both are this run's: `stood` writes the index whole and puts down any
+  // title standing this run does not say.
+  static skips(id: string): boolean {
+    return id.includes('/');
+  }
+
+  static override cells: JsonObject = { lends: {}, titles: {}, clashes: {}, hosted: [], routes: null, apps: null, default: null };
+  static override asks = {
+    ...Box.asks,
+    box: { description: 'what this box is: its routes, its apps and its default ward, each null until said', input: { type: 'object' }, for: root },
+    domain: { description: 'the four routes by the convention, mcp., web., quo. and api. under this domain over https, kept until said again', input: { type: 'object', properties: { domain: { type: 'string' } }, required: ['domain'] }, for: root },
+    apps: { description: 'the apps this box’s links open, apple app ids and android packages with their fingerprints; neither named forgets them', input: APPS, for: root },
+    default: { description: 'the ward a caller means when naming none; the harbor holds it to the wards it hosts at boot', input: { type: 'object', properties: { ward: { type: 'string' } }, required: ['ward'] }, for: root },
+    lends: { description: 'which faculty is lent under each contract, by digest to key, and which contracts are lent to nobody because two classes clashed under them', input: { type: 'object' }, for: root },
+    stood: {
+      description: 'what this boot stood: each contract, by digest, to the faculty that fulfils it, each title to the faculty shown under it, and each clash to the keys that clashed; a title held that this does not say goes',
+      input: { type: 'object', properties: { lends: { type: 'object' }, titles: { type: 'object' }, clashes: { type: 'object' } }, required: ['lends', 'titles', 'clashes'] },
+      for: root,
+    },
+  };
+
+  override answer(asker: Asker, method?: string, args: JsonObject = {}): Promise<Reply> {
+    return carry(this, asker, method, args, (a, m, g) => super.answer(a, m, g));
+  }
+
+  #key(name: string): string {
+    const index = this.cells.lends as Record<string, string>;
+    return Object.hasOwn(index, name) ? index[name] : name;
+  }
+
+  override offer(args: JsonObject): Promise<JsonObject> {
+    return super.offer({ name: this.#key(args.name as string) });
+  }
+  override retract(args: JsonObject): Promise<JsonObject> {
+    return super.retract({ ...args, name: this.#key(args.name as string) });
+  }
+
+  lends(): JsonObject {
+    return { lends: this.cells.lends, clashes: this.cells.clashes ?? {} };
+  }
+
+  // What the box is, placed by the root and read by the harbor: nothing here
+  // comes from a file.
+  box(): JsonObject {
+    return { routes: this.cells.routes ?? null, apps: this.cells.apps ?? null, default: this.cells.default ?? null };
+  }
+  domain(args: JsonObject): JsonObject {
+    if (typeof args.domain !== 'string' || !DOMAIN.test(args.domain)) return { error: `${JSON.stringify(args.domain)} is not a domain` };
+    this.cells.routes = routesFor(args.domain);
+    return { routes: this.cells.routes };
+  }
+  apps(args: JsonObject): JsonObject {
+    const apple = Array.isArray(args.apple) ? args.apple.filter((x): x is string => typeof x === 'string') : [];
+    const android = Array.isArray(args.android)
+      ? (args.android as { package?: unknown; fingerprints?: unknown }[])
+          .filter((a): a is { package: string; fingerprints: unknown[] } => typeof a?.package === 'string' && Array.isArray(a.fingerprints))
+          .map((a) => ({ package: a.package, fingerprints: a.fingerprints.filter((f): f is string => typeof f === 'string') }))
+      : [];
+    this.cells.apps = apple.length === 0 && android.length === 0 ? null : { apple, android };
+    return { apps: this.cells.apps };
+  }
+  default(args: JsonObject): JsonObject {
+    if (typeof args.ward !== 'string' || args.ward === '' || args.ward === BOX_SEED) return { error: 'a ward is a name, and the box ward is never the default' };
+    this.cells.default = args.ward;
+    return { default: args.ward };
+  }
+
+  // The index, written whole at every boot: what stands is what this run's
+  // classes say, and nothing an earlier run said, the clashes with it, by
+  // the word the contract calls itself to the keys that clashed. Her title
+  // standings are held to it: one under a title this run shows nobody
+  // under, or that now names another faculty, goes here, and the root
+  // removes the far end. She answers what she holds and what went, so the
+  // root places only what is not there.
+  stood(args: JsonObject): JsonObject {
+    const { lends, titles, clashes } = args;
+    if (!isIndex(lends)) return { error: 'lends is a digest to a key' };
+    if (!isIndex(titles)) return { error: 'titles is a title to a key' };
+    if (clashes === null || typeof clashes !== 'object' || Array.isArray(clashes) || !Object.values(clashes).every((ks) => Array.isArray(ks) && ks.every((k) => typeof k === 'string'))) return { error: 'clashes is a word to keys' };
+    this.cells.clashes = clashes;
+    const was = (this.cells.titles ?? {}) as Record<string, string>;
+    const pruned: string[] = [];
+    for (const id of Object.keys(this.cells.standings)) {
+      if (id.includes('/')) continue;
+      if (Object.hasOwn(titles, id) && was[id] === titles[id]) continue;
+      this.standings.remove(id);
+      pruned.push(id);
+    }
+    this.cells.lends = lends;
+    this.cells.titles = titles;
+    return { lends, held: Object.keys(this.cells.standings), pruned };
+  }
+}
+
+const isIndex = (v: unknown): v is Record<string, string> => v !== null && typeof v === 'object' && !Array.isArray(v) && Object.values(v).every((k) => typeof k === 'string');

package/box/envoy.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// The rung for a faculty that stands for an account elsewhere: a bank, a
+// booking service, any vendor. A leaf is one class per vendor, its asks out,
+// and three hooks for what the vendor sends back.
+//
+// Out, the account is the being's: the credential crosses on her ask, is
+// used once, and is kept nowhere here, so one faculty serves every account
+// on the box and an account moves with the being who owns it.
+//
+// In, bytes arrive for an account. A being who wants them watches with her
+// account id and the signing secret the vendor gave her; both are kept on
+// her watch and go with it. `inbound` reads which account the bytes are for,
+// verifies them with that watcher's secret before anything else is trusted,
+// decodes them into one ask, answers `{ ok }`, and then wakes her with it as
+// the occupant she named. A delivery seen before is `{ ok }` and wakes
+// nobody twice. The being woken cannot tell it from a timer's tick.
+import type { Asker, JsonObject } from 'nervur';
+import { Faculty, WATCH, type Watched } from './faculty.ts';
+
+// A watch for an account: the invitation back, the ask to wake her with,
+// her account at the vendor and the secret the vendor signs with.
+export const WATCH_ACCOUNT = {
+  description: 'wake me for my account: an invitation back, the ask to wake me with, the account id and its signing secret',
+  input: { type: 'object', properties: { ...WATCH.input.properties, account: { type: 'string' }, secret: { type: 'string' } }, required: ['invitation', 'method', 'account', 'secret'] },
+};
+
+// One delivery as a leaf decodes it: the vendor's id for it, and the ask
+// that wakes the watcher.
+export type Delivery = { id: string; method: string; args: JsonObject };
+
+type Account = Watched & { account: string; secret: string };
+
+const SEEN = 200;
+
+export class EnvoyFaculty extends Faculty {
+  static override cells: JsonObject = { watched: {}, minted: 0, seen: [] };
+
+  override async watch(args: JsonObject, asker: Asker): Promise<JsonObject> {
+    if (typeof args.account !== 'string' || !args.account || typeof args.secret !== 'string' || !args.secret) return { error: 'an account and its secret' };
+    const out = await super.watch(args, asker);
+    const id = out.watching;
+    if (typeof id === 'string') Object.assign((this.cells.watched as Record<string, Account>)[id], { account: args.account, secret: args.secret });
+    return out;
+  }
+
+  #waking: Promise<void> = Promise.resolve();
+  // The wake that went out after the last `{ ok }`, for the device's own
+  // code and a suite.
+  get waking(): Promise<void> {
+    return this.#waking;
+  }
+
+  // The vendor's bytes, as they arrived on a path she claims, handed by the
+  // http faculty; nothing in them is trusted before `verify`.
+  override async inbound(args: JsonObject): Promise<JsonObject> {
+    const body = typeof args.body === 'string' ? args.body : '';
+    const headers = (args.headers !== null && typeof args.headers === 'object' && !Array.isArray(args.headers) ? args.headers : {}) as Record<string, string>;
+    const account = this.account(body, headers);
+    const watched = this.cells.watched as Record<string, Account>;
+    const mine = account === null ? [] : Object.entries(watched).filter(([, w]) => w.account === account);
+    if (mine.length === 0) return { error: 'nobody watches that account' };
+    // every watcher of the account whose secret the bytes were signed with
+    const at: string[] = [];
+    for (const [id, w] of mine) if (await this.verify(body, headers, w.secret)) at.push(id);
+    if (at.length === 0) return { error: 'bad signature' };
+    const d = this.decode(body, headers);
+    if ('error' in d) return d;
+    const seen = this.cells.seen as string[];
+    if (seen.includes(d.id)) return { ok: true };
+    seen.push(d.id);
+    while (seen.length > SEEN) seen.shift();
+    this.#waking = (async () => {
+      for (const id of at) await this.standings[id]?.ask(d.method, d.args);
+    })();
+    return { ok: true };
+  }
+
+  // Which account the bytes are for: the one thing read before they are
+  // verified, since it names whose secret verifies them.
+  protected account(_body: string, _headers: Record<string, string>): string | null {
+    return null;
+  }
+  protected verify(_body: string, _headers: Record<string, string>, _secret: string): Promise<boolean> | boolean {
+    return false;
+  }
+  protected decode(_body: string, _headers: Record<string, string>): Delivery | { error: string } {
+    return { error: 'this faculty is not called in' };
+  }
+
+  // A signature over text with a shared secret, hex: the shape most vendors
+  // sign in, here once so a leaf writes only the vendor's framing.
+  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('');
+  }
+}

package/box/faculty.ts

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: Apache-2.0
+// A faculty: a being of the box ward standing for one thing outside every
+// being. She says everything about herself on her class: the contracts she
+// fulfils, whether she can work on this runtime, and the paths she claims on
+// the box's wire. She is born holding her harbor's box. What every faculty
+// shares is here: `watch`, the one way a being asks to be woken, and
+// `woke`, one round of waking whoever asked.
+import { Lent, isInvitation, isSilence, isWord, wordOf } from 'nervur';
+import type { Asker, JsonObject, OccupantRecord, Stance } from 'nervur';
+import type { Contract } from './contract.ts';
+import { ALONE, type Harborage } from './box.ts';
+
+// One subscription, as she files it: who asked for it, and what to ask them.
+export type Watched = { by: string; method: string; args: JsonObject };
+
+// What one round of waking did, per subscription.
+export type Woke = { id: string; by: string; out: unknown };
+
+// The ask the http faculty makes of a faculty that claims a path, and only
+// the http faculty: the root places her one occupant per claimed path,
+// `http:<path>`.
+export const HTTP = 'http:';
+export const INBOUND = {
+  description: 'bytes that arrived on a path this faculty claims',
+  input: { type: 'object', properties: { body: { type: 'string' }, headers: { type: 'object' }, query: { type: 'string' }, method: { type: 'string' } }, required: ['body', 'headers'] },
+  for: (occ: OccupantRecord | undefined) => occ?.id.startsWith(HTTP) === true,
+};
+
+export const WATCH = {
+  description: 'wake me: an invitation back, the ask to wake me with, and what to add to it',
+  input: { type: 'object', properties: { invitation: { type: 'object' }, method: { type: 'string' }, args: { type: 'object' } }, required: ['invitation', 'method'] },
+};
+
+export class Faculty extends Lent {
+  static override cells: JsonObject = { watched: {}, minted: 0 };
+
+  // The contracts she fulfils; the box lends her under each one's digest.
+  static fulfils: Contract[] = [];
+
+  // Whether she can work on the runtime reading this, answered honestly.
+  // One that cannot is never booted and never lent.
+  static stands(): boolean {
+    return true;
+  }
+
+  // The paths on the box's wire she answers. The http faculty hands her the
+  // bytes that arrive on one as `inbound`, and nobody else may ask it.
+  static claims: string[] = [];
+
+  // What her harbor is to her, handed at birth.
+  readonly box: Harborage;
+  constructor(stance: Stance, box: Harborage = ALONE) {
+    super(stance);
+    this.box = box;
+  }
+
+  // Bytes on a path she claims: the body as text, the headers, the query and
+  // the method. This body is called in by nobody; a faculty that claims a
+  // path says what the bytes mean.
+  inbound(_args: JsonObject): Promise<JsonObject> | JsonObject {
+    return { error: 'this faculty is not called in' };
+  }
+
+  // Someone wants waking. She hands an invitation back and says what to ask
+  // her; this knocks it, takes it under an id of this being's own, and files
+  // it. The empty ask is the knock, because every being answers one.
+  async watch(args: JsonObject, asker: Asker): Promise<JsonObject> {
+    const inv = args.invitation;
+    if (!isInvitation(inv) || typeof args.method !== 'string') return { error: 'an invitation and a method' };
+    const extra = args.args;
+    if (extra !== undefined && (extra === null || typeof extra !== 'object' || Array.isArray(extra))) return { error: 'args is one object' };
+    const out = await this.knock(inv);
+    if (isSilence(out) || isWord(out)) return { error: 'no way back' };
+    const cells = this.cells as unknown as { watched: Record<string, Watched>; minted: number };
+    const id = await this.take(`wake:${(cells.minted += 1)}`, inv);
+    if (id === null) return { error: 'not taken' };
+    cells.watched[id] = { by: asker.id ?? '', method: args.method, args: extra ?? {} };
+    await this.welcomed(id);
+    return { watching: id };
+  }
+
+  // Somebody new is filed, and the answer to her `watch` waits for this. A
+  // faculty that owes a new subscriber something at once says it here.
+  protected async welcomed(_id: string): Promise<void> {}
+
+  // One round. Each subscriber is asked what she asked to be asked, with
+  // whatever this round adds; `only` is one of them. A subscriber who removed
+  // the occupant says `removed` once and her row goes. Null is this being
+  // herself taken out of her ward, so whoever holds an interval puts it down.
+  protected async woke(round: (w: Watched) => JsonObject = (w) => w.args, only?: string): Promise<Woke[] | null> {
+    const watched = this.cells.watched as unknown as Record<string, Watched>;
+    const out: Woke[] = [];
+    for (const [id, w] of Object.entries(watched)) {
+      if (only !== undefined && id !== only) continue;
+      const said = await this.standings[id]?.ask(w.method, round(w));
+      if (said === undefined || (isWord(said) && wordOf(said) === 'dropped')) return null;
+      if (isWord(said) && wordOf(said) === 'removed') {
+        this.standings.remove(id);
+        delete watched[id];
+        continue;
+      }
+      out.push({ id, by: w.by, out: said });
+    }
+    return out;
+  }
+
+  // Who is waiting, by this being's own id for the relation.
+  get watching(): Record<string, Watched> {
+    return this.cells.watched as unknown as Record<string, Watched>;
+  }
+}

package/{dock → box}/fcm.ts

@@ -16,7 +16,7 @@
 // which dials, drains what it missed over Quo, sealed, and composes what
 // the human reads. High priority is what wakes a dozing device; it is the
 // same promise Apple's background push makes, which is best effort.
-import type { Ring, Token } from './push.ts';
+import type { Ring, Token } from './ring.ts';
 
 const subtle = () => globalThis.crypto.subtle;
 const RS256 = { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' } as const;

package/box/grants.ts

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's grants: a bearer to an identity in a world, honoured on every
+// route alike. A route says the grammar a caller speaks and a grant says who
+// the caller is. A grant maps a token to an identity and nothing else; no
+// secret of Quo's is ever here.
+//
+// Her tokens are her cells. Issuing, refreshing and revoking are the routes'
+// to call on her in this process, and a token issued is a cell written
+// outside any ask, so she keeps her ward through her box. Her clock is the
+// box's. An access token lives an hour and a refresh token thirty days, and
+// refresh rotates.
+import { contract } from './contract.ts';
+import { Faculty } from './faculty.ts';
+
+// What a route needs from the box's grants. She lends nothing to beings, so
+// the contract has no ask; its title is what the box's own code finds her by.
+export const GRANTS = contract('grants', {});
+
+export const ACCESS_TTL = 60 * 60 * 1000;
+export const REFRESH_TTL = 30 * 24 * 60 * 60 * 1000;
+
+// Own keys only: a token is a string the far side offers.
+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 what every runtime has.
+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('=', '');
+};
+
+export type Grant = { identity: string; ward: string; client: string; exp: number };
+type Kept = { access: Record<string, Grant>; refresh: Record<string, Grant> };
+export type Tokens = { access_token: string; token_type: 'Bearer'; expires_in: number; refresh_token: string; scope: 'nervur' };
+
+export class Grants extends Faculty {
+  static override cells = { ...Faculty.cells, access: {}, refresh: {} };
+  static override asks = {};
+  static override fulfils = [GRANTS];
+
+  get kept(): Kept {
+    return this.cells as unknown as Kept;
+  }
+
+  // The box's moment, which is hers.
+  now(): number {
+    return this.box.now();
+  }
+
+  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.box.save();
+    return { access_token, token_type: 'Bearer', expires_in: ACCESS_TTL / 1000, refresh_token, scope: 'nervur' };
+  }
+
+  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);
+  }
+
+  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;
+  }
+
+  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.box.save();
+  }
+
+  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 route calls on the box's grants, in this process.
+export type Bearers = Pick<Grants, 'issue' | 'refresh' | 'bearer' | 'revoke' | 'now'>;
+
+// 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/box/http.ts

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// The http faculty: the box's wire. A terrain that owns a wire hands her every
+// request no route of its own took, and she hands the bytes on a claimed
+// path to the faculty that claims it, through a standing the root placed at
+// unpacking, as the occupant `http:<path>`. Nobody asks with owner rights:
+// the faculty called in is asked by her, and answers in her own words.
+//
+// What crosses back is what every route here speaks: an object is 200, an
+// error object 400, and no object at all 503. A path nobody claims is 404, a
+// method but GET and POST is 405, and a body past a megabyte is 413. A GET
+// is where a redirect lands, the code in the query, and a GET from a browser
+// is a human sent back from somewhere: she is shown a page saying whether it
+// finished, and never what the faculty answered a machine.
+import { isSilence, isWord, OWNER } from 'nervur';
+import type { Asker, JsonObject, OccupantRecord } from 'nervur';
+import { landed, POLICY } from '../human/door.ts';
+import { CSS } from '../human/style.ts';
+import { contract } from './contract.ts';
+import { Faculty } from './faculty.ts';
+
+// The box's wire. She lends nothing to beings, so her contract has no ask;
+// its title is what unpacking finds her by.
+export const WIRE = contract('http', {});
+
+const LIMIT = 1 << 20;
+
+const json = (status: number, body: unknown) => Response.json(body, { status });
+
+// The one page this wire serves, wearing the one stylesheet every screen
+// wears, and allowed no script, since it runs none.
+const page = (status: number, body: string) =>
+  new Response(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>nervur</title>\n<style>${CSS}</style>\n</head><body>${body}</body></html>`, {
+    status,
+    headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': POLICY, 'referrer-policy': 'no-referrer' },
+  });
+
+const root = (_occ: OccupantRecord | undefined, asker: Asker) => asker.id === OWNER;
+
+export class Http extends Faculty {
+  static override fulfils = [WIRE];
+  static override cells: JsonObject = { watched: {}, minted: 0, claimed: {} };
+  static override asks = {
+    wired: {
+      description: 'what this boot claims: each path to the faculty that claims it; a path held that this does not say goes',
+      input: { type: 'object', properties: { claimed: { type: 'object' } }, required: ['claimed'] },
+      for: root,
+    },
+  };
+
+  // The paths this run placed, held to: a standing under a path nobody
+  // claims now, or that another faculty claims now, goes here, and the
+  // root removes the far end. She answers what she holds and what went.
+  wired(args: JsonObject): JsonObject {
+    const claimed = args.claimed;
+    if (claimed === null || typeof claimed !== 'object' || Array.isArray(claimed) || !Object.values(claimed).every((k) => typeof k === 'string')) return { error: 'claimed is a path to a key' };
+    const was = (this.cells.claimed ?? {}) as Record<string, string>;
+    const pruned: string[] = [];
+    for (const p of Object.keys(this.cells.standings)) {
+      if (Object.hasOwn(claimed, p) && was[p] === claimed[p]) continue;
+      this.standings.remove(p);
+      pruned.push(p);
+    }
+    this.cells.claimed = claimed;
+    return { held: Object.keys(this.cells.standings), pruned };
+  }
+
+  // The terrain's own call, crossing no door: one request, one response.
+  // The longest claimed path the request's path begins with, at a segment
+  // boundary, is the faculty it goes to.
+  async handle(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    const claimed = Object.keys(this.cells.standings)
+      .filter((p) => url.pathname === p || url.pathname.startsWith(`${p}/`))
+      .sort((a, b) => b.length - a.length)[0];
+    const at = claimed === undefined ? undefined : this.standings[claimed];
+    if (!at) return json(404, { error: 'nobody claims this path' });
+    if (req.method !== 'GET' && req.method !== 'POST') return json(405, { error: 'POST, or GET for a redirect' });
+    const bytes = req.method === 'GET' ? new ArrayBuffer(0) : await req.arrayBuffer();
+    if (bytes.byteLength > LIMIT) return json(413, { error: 'too big' });
+    const headers: Record<string, string> = {};
+    req.headers.forEach((v, k) => (headers[k] = v));
+    const out = await at.ask('inbound', { body: new TextDecoder().decode(bytes), headers, query: url.search.slice(1), method: req.method });
+    const object = out !== undefined && !isSilence(out) && !isWord(out) && out !== null && typeof out === 'object' && !Array.isArray(out) ? out : null;
+    if (req.method === 'GET' && (req.headers.get('accept') ?? '').includes('text/html')) {
+      const ok = object !== null && typeof object.error !== 'string';
+      // No host is printed: a Host header is the caller's to write, and a
+      // page that printed one would print whatever a caller wanted read.
+      return page(ok ? 200 : 400, landed({ host: '', ok }));
+    }
+    if (object === null) return json(503, { error: 'silence' });
+    return json(typeof object.error === 'string' ? 400 : 200, object);
+  }
+}