@nervur-org/dock 0.3.0

package/cli/quo.ts

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// `quo`: the one command of the estate. Thin on purpose: each subcommand
+// picks a folder, reaches the daemon or the disk, and hands off. Logic that
+// appears here was missing from a being or a side, and moves there.
+//
+//   quo init   [--dir D] [--ward W] [--user U] [--class C] [--default] [--show] [--domain DOM]  mint a seed, boot a ward over a disk store, write both; C is the class of the ward's home being, User unless said; --default marks it the default ward; --show shows it at the web route; --domain writes the four routes under DOM
+//   quo default [--dir D] <ward>             mark one ward the default, the one a caller means when naming none; the one ward hosted is the default unmarked
+//   quo show|hide [--dir D] <ward>           show a ward at the web route, listed at its root and its public being's page painted for a stranger; hidden at init, and a hidden ward's page is the plain door
+//   quo domain [--dir D] <domain>            write routes.json by the convention: mcp., web., quo. and api. under the domain, over https
+//   quo serve  [--dir D] [--http PORT]      the daemon: harbor from disk, the two sockets, the HTTP door on loopback, a socket held to every route the dialers faculty keeps
+//   quo census [--dir D] [--ward W] [--via S]        the empty ask: pk and every being
+//   quo boot   [--dir D] [--ward W] [--via S] <json> { key, class, public? }
+//   quo invite [--dir D] [--ward W] [--via S] <json> { being, id }; with routes.json naming web., the answer carries the link
+//   quo knock  [--dir D] [--ward W] [--via S] <json> { being | { boot, key }, id, invitation, method?, args?, wanted? }
+//   quo remove [--dir D] [--ward W] [--via S] <json> { being, id }: a relation out of a being; on the ward pk, an owner
+//   quo unboot [--dir D] [--ward W] [--via S] <json> { being }: a being out of the ward, with every relation she holds
+//   quo ask    [--dir D] [--ward W] <being> [method] [json]  the root asking a being of its own ward, as the device
+//   quo side   [--dir D] [--ward W] --as NAME  an avatar over stdio for a local MCP client; NAME is the client identity
+//   quo run    [--dir D] [--ward W] --as NAME --url URL --model NAME [--turns N]  a human at a terminal talking to a model through an avatar: a line in, the model's final text out
+//   quo pilot  [--dir D] [--ward W] [--via S]        the owner pilot over stdio: census, boot, invite, knock, remove
+//   quo reach  [--dir D] <pk> <url>          a hint for the harbor's directory: that ward pk lives at that quo. route
+//   quo estate <dir> --domain D              an estate folder of the shape every estate has: a droplet's quo directory, unit and Caddyfile, a Mac's launchd agent, on this dock
+//
+// D defaults to $QUO_DIR, then ~/.quo. W defaults to the default ward, and
+// init names a new ward main when none is given. init takes
+// --user NAME for the user being, defaulting to the device's user. run
+// takes the model's base URL as --url or $QUO_MODEL_URL, its name as
+// --model or $QUO_MODEL, a bearer from $QUO_MODEL_KEY, read here and never
+// kept, and --turns as the ceiling of model calls in one turn. S is a
+// standing the user being holds at another ward, one the root there invited
+// as an owner: with --via, the owner asks go to that ward's door, sealed,
+// and the answers are its. Without it they are the root's, on the pointer.
+import { homedir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { isInvitation } from '@nervur-org/nervur';
+import { DiskHarbor } from '../harbor/disk.ts';
+import { serve, readRoutes, writeRoutes } from './daemon.ts';
+import { ask, askBeing, side, reach, type Run } from './client.ts';
+import { link } from '../beings/link.ts';
+import { pilotSide } from './pilot.ts';
+import { estate } from './estate.ts';
+
+const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove', 'unboot']);
+
+function parse(argv: string[]) {
+  const flags: Record<string, string> = {};
+  const rest: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] ?? '';
+    // a flag takes the word after it, unless that word is a flag or there is
+    // none: --default stands alone
+    if (a.startsWith('--')) flags[a.slice(2)] = argv[i + 1] === undefined || argv[i + 1]!.startsWith('--') ? '' : argv[++i]!;
+    else rest.push(a);
+  }
+  const [cmd, json, more, third] = rest;
+  return { cmd, json, more, third, flags, dir: flags.dir ?? process.env.QUO_DIR ?? join(homedir(), '.quo'), ward: flags.ward, via: flags.via };
+}
+
+const print = (v: unknown) => console.log(JSON.stringify(v, null, 2));
+
+async function main(argv: string[]): Promise<number> {
+  const { cmd, json, more, third, flags, dir, via } = parse(argv);
+  if (cmd === 'init') {
+    const made = await DiskHarbor.init(dir, flags.ward, flags.user ?? userInfo().username, flags.class, 'default' in flags, 'show' in flags);
+    print(flags.domain ? { ...made, routes: await writeRoutes(dir, flags.domain) } : made);
+    return 0;
+  }
+  if (cmd === 'default') {
+    if (!json) {
+      console.error('quo default <ward>');
+      return 2;
+    }
+    await DiskHarbor.setDefault(dir, json);
+    print({ default: json });
+    return 0;
+  }
+  if (cmd === 'show' || cmd === 'hide') {
+    if (!json) {
+      console.error(`quo ${cmd} <ward>`);
+      return 2;
+    }
+    await DiskHarbor.setShown(dir, json, cmd === 'show');
+    print({ [cmd === 'show' ? 'shown' : 'hidden']: json });
+    return 0;
+  }
+  if (cmd === 'domain') {
+    if (!json) {
+      console.error('quo domain <domain>');
+      return 2;
+    }
+    print({ routes: await writeRoutes(dir, json) });
+    return 0;
+  }
+  // Every command that reaches a ward is on one: the one named, or the
+  // default, read from the folder the way the daemon reads it, and only once
+  // the command is held right.
+  const wardOf = async () => flags.ward ?? (await DiskHarbor.defaultOf(dir));
+  if (cmd === 'side' || cmd === 'run') {
+    if (!flags.as) {
+      console.error(`quo ${cmd} needs --as NAME`);
+      return 2;
+    }
+    let run: Run | undefined;
+    if (cmd === 'run') {
+      const url = flags.url ?? process.env.QUO_MODEL_URL;
+      const model = flags.model ?? process.env.QUO_MODEL;
+      if (!url || !model) {
+        console.error('quo run needs --url URL and --model NAME, or QUO_MODEL_URL and QUO_MODEL');
+        return 2;
+      }
+      const key = process.env.QUO_MODEL_KEY;
+      const turns = flags.turns !== undefined ? Number(flags.turns) : undefined;
+      if (turns !== undefined && !(Number.isInteger(turns) && turns > 0)) {
+        console.error('--turns is a positive integer');
+        return 2;
+      }
+      run = { url, model, ...(key ? { key } : {}), ...(turns !== undefined ? { turns } : {}) };
+    }
+    await side(dir, flags.as, await wardOf(), run); // stdio to the daemon, until one end closes
+    return -1;
+  }
+  if (cmd === 'pilot') {
+    const ward = await wardOf();
+    await ask(dir, undefined, {}, ward); // no daemon is a clear word now, not at the first tool call
+    const serving = await pilotSide(dir, ward, new StdioServerTransport(), via);
+    process.stdin.once('end', () => void serving.close().then(() => process.exit(0)));
+    return -1;
+  }
+  if (cmd === 'serve') {
+    const port = flags.http ?? process.env.QUO_HTTP;
+    const s = await serve(dir, port !== undefined ? { http: { port: Number(port) } } : {});
+    print({ dir: s.harbor.dir, sock: s.sock, side: s.side, http: s.http ? `http://${s.http.host}:${s.http.port}` : null, dial: s.quo.dialers.map((d) => d.url), wards: Object.fromEntries([...s.harbor.wards].map(([n, h]) => [n, h.pk])) });
+    const stop = () => void s.close().then(() => process.exit(0));
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    return -1; // stays up
+  }
+  if (cmd === 'estate') {
+    if (!json || !flags.domain) {
+      console.error('quo estate needs <dir> --domain D');
+      return 2;
+    }
+    print(await estate(json, flags.domain));
+    return 0;
+  }
+  // The root reaching into a being of its own ward. Two positionals and the
+  // args as JSON, because a human writes this one by hand: `quo ask clock keep
+  // '{"id":"nightly","ask":"desk.hello","cron":"0 3 * * *"}'`. With no
+  // method it is that being's describe, as the device sees her.
+  if (cmd === 'ask') {
+    if (!json) {
+      console.error('quo ask needs <being> [method] [json]');
+      return 2;
+    }
+    const out = await askBeing(dir, json, more, third ? (JSON.parse(third) as Record<string, unknown>) : {}, await wardOf());
+    print('error' in out ? { error: out.error } : out.result);
+    const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
+    return failed ? 1 : 0;
+  }
+  if (cmd === 'reach') {
+    if (!json || !more) {
+      console.error('quo reach needs <pk> <url>');
+      return 2;
+    }
+    const out = await reach(dir, json, more);
+    print('error' in out ? { error: out.error } : out.result);
+    return 'error' in out ? 1 : 0;
+  }
+  if (cmd === 'census' || (cmd !== undefined && OWNER_ASKS.has(cmd))) {
+    const args = json ? (JSON.parse(json) as Record<string, unknown>) : {};
+    const ward = await wardOf();
+    let out = await ask(dir, cmd === 'census' ? undefined : cmd, args, ward, via);
+    // an invitation minted here is handed on as a link when the harbor's
+    // routes name a web. origin: the world's page with the invitation in
+    // the fragment, one string to send to the person it is for
+    const minted = cmd === 'invite' && !via && 'result' in out && isInvitation(out.result) ? out.result : null;
+    const routes = minted ? await readRoutes(dir) : null;
+    // the ward answers null to an invite on an id already held, standing or
+    // occupant, and null on a terminal is nothing to read: it is a refusal
+    // here, in words, and an exit code a script can tell apart
+    if (cmd === 'invite' && 'result' in out && out.result === null) out = { result: { error: 'id taken' } };
+    if (minted && routes) print({ ...minted, link: link(`${routes.web}/${encodeURIComponent(ward)}`, minted) });
+    else print('error' in out ? { error: out.error } : out.result);
+    // an error object the ward answered is an ordinary answer, and still a
+    // non-zero exit, so a script can tell a boot that happened from one that did not.
+    const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
+    return failed ? 1 : 0;
+  }
+  console.error('usage: quo init|default|show|hide|domain|serve|census|boot|public|invite|knock|remove|unboot|ask|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [json]');
+  return 2;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    if (code >= 0) process.exit(code);
+  },
+  (e: unknown) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  },
+);

package/cli/stand.ts

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: Apache-2.0
+// Standing a harbor up: the beings an estate boots for its own working and
+// the relations between them, placed by the root once, from the estate's
+// own `stand.ts`, on real invitations. The desk and the user being, the
+// bell, an estate's front, the clock with her keep and her voice: each is
+// furniture the estate owns rather than a world anyone keeps on it, and each
+// is placed the way every relation is placed, an invite on the far ward's
+// owner pointer and a knock on the near one. Nothing here is read at boot:
+// the wards are the whole truth about what stands, and a script is a
+// recipe run once, never a second record kept in step.
+//
+// Five rules, and the first is the one the rest exist to protect.
+//
+// **It places ordinary relations.** Real keys, rotating, written into both
+// beings' cells, removable by hand afterwards like any other. Never a channel
+// the harbor grants itself. The moment a standing exists because the harbor
+// said so rather than because an invitation was minted and taken, a being's
+// occupants stop being the whole truth about who can reach her, and every
+// gate in this tree rests on that being true.
+//
+// **It is idempotent.** A being already booted is left alone and a standing
+// already held is left alone, so a script run twice stands the estate once.
+//
+// **Same harbor only.** Both ends name a ward this device hosts. Across
+// harbors an invitation is not bookkeeping, it is consent, and there is no
+// shared root to automate it with: those relations stay a human's to make.
+//
+// **It adds and never removes.** A line taken out of a script leaves its
+// relation standing, because silently unplacing a relation is a wake that
+// stops with nobody told. Removal is a deliberate `quo remove`.
+//
+// **It fails loudly.** A line that will not place stops the script where it
+// is, and a harbor half stood is said, never served.
+import type { Invitation, JsonObject } from '@nervur-org/nervur';
+import type { Harbor } from '@nervur-org/nervur/harbor';
+import { DiskHarbor } from '../harbor/disk.ts';
+
+// A being the estate boots, and where; `public` marks her as the one being
+// of her ward that answers strangers, an estate's front in place of the desk.
+export type Boot = { ward: string; key: string; class: string; public?: boolean };
+
+// One arrow. `from` ends up holding the standing, `to` ends up holding the
+// occupant, which is what a relation in Quo is: one direction, and the answer
+// rides the ask back. `as` names the standing on the near side and defaults to
+// the far being's key, because that is the name a schedule or a caller will
+// write. `known` names the occupant on the far side and defaults to the near
+// being's key. `notes` are the terms the occupant is minted under, hers to
+// read on her gate and nobody else's to write, which is how a watcher is
+// declared here rather than in code.
+export type Wire = { from: string; to: string; as?: string; known?: string; notes?: JsonObject };
+
+export type Stand = { boot?: Boot[]; wire?: Wire[] };
+
+const KEY = /^[\w.:-]+$/;
+const RESERVED = new Set(['knock', 'take', 'remove']);
+
+const fail = (why: string): never => {
+  throw new Error(`stand: ${why}`);
+};
+
+// `<ward>.<key>`, split at the first dot: a ward's name is a plain word and a
+// being's key is not, so the ambiguity only ever falls one way.
+function at(v: string, what: string): { ward: string; key: string } {
+  const dot = v.indexOf('.');
+  if (dot < 1) return fail(`${what}: "${v}" is not "<ward>.<being>"`);
+  return { ward: v.slice(0, dot), key: v.slice(dot + 1) };
+}
+
+type Wards = { wards: Map<string, { being(key: string): unknown; ask(method: string, args: JsonObject): Promise<unknown> }>; partitionOf(name: string): Record<string, unknown> | undefined };
+
+// A name a wire would use, read off the partition the harbor already holds:
+// whether a being holds it as a standing and whether she holds it as an
+// occupant. Standings and occupants are one namespace, so a name held under
+// the other kind is a collision and never this wire.
+function holds(h: Wards, ward: string, key: string, id: string): { standing: boolean; occupant: boolean } {
+  const p = h.partitionOf(ward) as { bind?: Record<string, { standings?: Record<string, unknown> }>; beings?: Record<string, { occupants?: Record<string, unknown> }> } | undefined;
+  return { standing: Object.hasOwn(p?.bind?.[key]?.standings ?? {}, id), occupant: Object.hasOwn(p?.beings?.[key]?.occupants ?? {}, id) };
+}
+
+const ward = (h: Wards, name: string, why: string) => h.wards.get(name) ?? fail(`${why}: this device hosts no ward ${name}`);
+
+// Stand a booted harbor up. Everything declared and absent is placed;
+// everything declared and present is left exactly as it is.
+//
+// Idempotency is read off the mint and not off anybody's cells. A being is
+// whatever answers, `Being` or a bare object with one method, so there is no
+// shape here to reach into: what says a wire already stands is that the far
+// being refuses to mint that occupant a second time. `invite` answers null
+// for exactly one reason once the reader has held the id to a word the ward
+// does not reserve, which is that the id is taken, and an id taken is this
+// wire, placed the last time the script ran.
+export async function standUp(harbor: Harbor | Wards, decl: Stand): Promise<{ booted: string[]; wired: string[]; already: string[] }> {
+  const h = harbor as Wards;
+  const booted: string[] = [];
+  for (const b of decl.boot ?? []) {
+    const w = ward(h, b.ward, `boot ${b.ward}.${b.key}`);
+    if (!w.being(b.key)) {
+      const out = (await w.ask('boot', { key: b.key, class: b.class })) as { error?: string };
+      if (out.error) fail(`boot ${b.ward}.${b.key} as ${b.class}: ${out.error}`);
+      booted.push(`${b.ward}.${b.key}`);
+    }
+    // the mark is one per ward and the script is what says who holds it:
+    // taken off whoever holds it, the desk init put there, and put on her,
+    // which is the same two asks whether or not she held it already
+    if (b.public) {
+      const off = (await w.ask('public', { key: null })) as { error?: string };
+      if (off.error) fail(`public ${b.ward}.${b.key}: ${off.error}`);
+      const out = (await w.ask('public', { key: b.key })) as { error?: string };
+      if (out.error) fail(`public ${b.ward}.${b.key}: ${out.error}`);
+    }
+  }
+  const wired: string[] = [];
+  const already: string[] = [];
+  for (const one of decl.wire ?? []) {
+    const from = at(one.from, 'from'),
+      to = at(one.to, 'to');
+    const as = one.as ?? to.key,
+      known = one.known ?? from.key;
+    if (!KEY.test(as) || !KEY.test(known)) fail(`a name is a word: ${one.from} -> ${one.to}`);
+    // The three the stance keeps for itself. A ward refuses them at invite
+    // and at take, and refusing them here is what leaves `invite` answering
+    // null for one reason only, which is the whole of how this stays
+    // idempotent without reading anybody's cells.
+    if (RESERVED.has(as) || RESERVED.has(known)) fail(`knock, take and remove are the ward's own words: ${one.from} -> ${one.to}`);
+    const near = ward(h, from.ward, `wire ${one.from}`),
+      far = ward(h, to.ward, `wire ${one.to}`);
+    if (!near.being(from.key)) fail(`wire ${one.from}: no such being`);
+    if (!far.being(to.key)) fail(`wire ${one.to}: no such being`);
+    // A name held under the other kind is not this wire and never will be:
+    // said now, before a heir is spent on it, rather than read as a wire
+    // already placed or refused at the knock with the far side already bound.
+    const atFar = holds(h, to.ward, to.key, known);
+    const atNear = holds(h, from.ward, from.key, as);
+    if (atFar.standing) fail(`wire ${one.from} -> ${one.to}: ${to.key} already holds a standing named ${known}, and a name is one of the two`);
+    if (atNear.occupant) fail(`wire ${one.from} -> ${one.to}: ${from.key} already holds an occupant named ${as}, and a name is one of the two`);
+    const inv = (await far.ask('invite', { being: to.key, id: known, ...(one.notes ? { notes: one.notes } : {}) })) as Invitation | { error?: string } | null;
+    if (inv === null) {
+      already.push(`${one.from} -> ${one.to}`);
+      continue;
+    }
+    if ('error' in inv) fail(`wire ${one.from} -> ${one.to}: ${inv.error}`);
+    const took = (await near.ask('knock', { being: from.key, id: as, invitation: inv })) as { taken?: string; error?: string };
+    if (took.taken !== as) fail(`wire ${one.from} -> ${one.to}: ${took.error ?? `${from.key} would not take ${as}`}`);
+    wired.push(`${one.from} -> ${one.to}`);
+  }
+  return { booted, wired, already };
+}
+
+// What an estate's `stand.ts` calls: the harbor folder booted here, with no
+// daemon over it, stood up and written back. The lease refuses a folder a
+// daemon holds, so the recipe is stop, stand, start, like an init.
+export async function stand(dir: string, decl: Stand): Promise<{ booted: string[]; wired: string[]; already: string[] }> {
+  const h = new DiskHarbor(dir);
+  await h.boot();
+  try {
+    return await standUp(h, decl);
+  } finally {
+    await h.close();
+  }
+}

package/dist/api/route.d.ts

@@ -0,0 +1,21 @@
+import type { Handler } from '../harbor/http.ts';
+import type { Hosted } from '@nervur-org/nervur/harbor';
+import type { Avatar } from '../beings/avatar.ts';
+import type { Grants } from '../dock/grants.ts';
+import { type Invitation } from '@nervur-org/nervur';
+export type Held = {
+    wards: ReadonlyMap<string, Hosted>;
+    here(): string;
+};
+export type Options = {
+    grants: Grants;
+    resolve: (identity: string, ward: string) => Promise<{
+        avatar?: Avatar;
+        error?: string;
+    }>;
+    join: (identity: string, invitation: Invitation, ward: string) => Promise<{
+        error?: string;
+    }>;
+    web?: string;
+};
+export declare function apiRoute(harbor: Held, o: Options): Handler;

package/dist/api/route.js

@@ -0,0 +1,193 @@
+import { readText } from '../harbor/http.js';
+import { invitationOf } from '../beings/link.js';
+import { landed, POLICY } from '../human/door.js';
+import { CSS } from '../human/style.js';
+import { isInvitation, isSilence, isWord, wordOf } from '@nervur-org/nervur';
+const open = { 'access-control-allow-origin': '*', 'access-control-allow-methods': 'GET, POST, OPTIONS', 'access-control-allow-headers': 'content-type, authorization' };
+const word = (s) => (typeof s === 'string' && /^[\w.-]{1,40}$/.test(s) ? s : null);
+export function apiRoute(harbor, o) {
+    return async (req, rest) => {
+        const json = (status, body) => Response.json(body, { status, headers: open });
+        // The one page this road serves, and it wears the one stylesheet every
+        // screen wears. No cross-origin header on it: a page is for the browser
+        // that was sent here and never for a script somewhere else. Its policy
+        // is the allow page's, and for the same reason: a page that runs no
+        // script of its own should be allowed none.
+        const page = (status, body) => new Response(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</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' },
+        });
+        // Where this world lives, as the daemon was told and not as the request
+        // said: a Host header is the caller's to write, and a page that printed
+        // one would print whatever a caller wanted a human to read. Falling back
+        // to it is for a box configured with no web address at all, where the
+        // request is the only thing that knows.
+        const hostOf = (r) => {
+            try {
+                return o.web === undefined ? (r.headers.get('host') ?? '') : new URL(o.web).host;
+            }
+            catch {
+                return r.headers.get('host') ?? '';
+            }
+        };
+        if (req.method === 'OPTIONS')
+            return new Response(null, { status: 204, headers: open });
+        if (req.method !== 'GET' && req.method !== 'POST')
+            return json(405, { error: 'GET or POST' });
+        const body = async () => {
+            const raw = await readText(req);
+            if (raw === undefined)
+                return null;
+            let parsed = {};
+            try {
+                parsed = raw.length === 0 ? {} : JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+            return parsed === null || typeof parsed !== 'object' || Array.isArray(parsed) ? null : parsed;
+        };
+        // The trade: an invitation for a grant, or a refresh token for the next.
+        if ((rest === '' || rest === '/') && req.method === 'POST') {
+            const b = await body();
+            if (b === null)
+                return json(400, { error: 'the body is a JSON object' });
+            if (typeof b.refresh === 'string') {
+                const t = await o.grants.refresh(b.refresh);
+                return t ? json(200, t) : json(400, { error: 'invalid_grant' });
+            }
+            const inv = typeof b.invitation === 'string' ? invitationOf(b.invitation) : isInvitation(b.invitation) ? b.invitation : null;
+            if (!inv)
+                return json(400, { error: 'that is not an invitation' });
+            const world = [...harbor.wards].find(([, h]) => h.pk === inv.ward);
+            if (!world)
+                return json(400, { error: 'that invitation is for a world that does not live here' });
+            const [ward, hosted] = world;
+            const identity = word(b.identity);
+            if (identity === null || identity === hosted.record.user || identity === 'desk')
+                return json(400, { error: 'an identity is one word, and not the user or the desk' });
+            // Nobody at a page vouches for a program, so a trade is a knock that
+            // spends: an identity already in refreshes, or is removed at the user
+            // being and invited again, and never re-enters on a spent invitation.
+            if ((await o.resolve(identity, ward)).avatar)
+                return json(400, { error: 'already in' });
+            const joined = await o.join(identity, inv, ward);
+            if (joined.error)
+                return json(400, { error: joined.error });
+            return json(200, await o.grants.issue(identity, ward, 'api'));
+        }
+        // No ward named is the device's own ward, and never a default the route
+        // picks: the harbor points at one of its wards and says that one is the
+        // device's, and its door answers for it.
+        const [, named = '', ask = '', ...more] = rest.split('/');
+        const ward = named === '' ? harbor.here() : named;
+        // The delivery: a vendor's webhook to an envoy, `/api/<ward>/<being>/deliver`.
+        // Not a stranger's ask and not an occupant's: the owner asking her
+        // `deliver` with the raw bytes and the headers, and nothing else. The
+        // body is read as a string and never parsed here, since the vendor
+        // signed the bytes and a reparsed body fails her check; no bearer is
+        // read, since the rung is not the caller's to prove. She answers `{ ok }`
+        // or her error object, and the route carries it.
+        // A GET on the same path is the same ask with an empty body: where an
+        // OAuth redirect lands, the code in the query. The query crosses inside
+        // the headers under `:query`, a name no header on the wire can have, so
+        // her one ask in stays one.
+        if (more.length === 1 && more[0] === 'deliver') {
+            if (req.method !== 'POST' && req.method !== 'GET')
+                return json(405, { error: 'POST, or GET for a redirect' });
+            const hosted = harbor.wards.get(ward);
+            if (!hosted || !/^[\w-]+$/.test(ask))
+                return json(404, { error: 'no such world' });
+            const raw = req.method === 'GET' ? '' : await readText(req);
+            if (raw === undefined)
+                return json(413, { error: 'too big' });
+            const headers = {};
+            req.headers.forEach((v, k) => (headers[k] = v));
+            const query = new URL(req.url).search.slice(1);
+            if (query)
+                headers[':query'] = query;
+            const out = await hosted.ask('ask', { being: ask, method: 'deliver', args: { body: raw, headers } });
+            await hosted.save();
+            // A GET here is a browser and a browser is a human: a vendor a world
+            // sent her to has opened this URL in her tab, so what she is looking
+            // at is whatever the envoy answered a machine. She gets a page
+            // instead, and only she does; a vendor asking for JSON is answered in
+            // JSON as it always was, and so is a GET that says nothing about what
+            // it wants.
+            const wants = req.method === 'GET' && (req.headers.get('accept') ?? '').includes('text/html');
+            if (wants) {
+                const ok = out !== null && typeof out === 'object' && !Array.isArray(out) && typeof out.error !== 'string';
+                return page(ok ? 200 : 400, landed({ world: ward, host: hostOf(req), ...(o.web ? { at: `${o.web.replace(/\/$/, '')}/${encodeURIComponent(ward)}` } : {}), ok }));
+            }
+            if (isSilence(out) || out === null || typeof out !== 'object' || Array.isArray(out))
+                return json(503, { error: 'silence' });
+            const said = out.error;
+            if (said === 'no such being' || said === 'unknown ask')
+                return json(404, { error: 'no such envoy' });
+            if (said === 'silence' || said === 'threw' || said === 'late')
+                return json(503, { error: 'silence' });
+            if (typeof said === 'string')
+                return json(400, out);
+            return json(200, out);
+        }
+        if (!/^[\w.-]+$/.test(ward) || more.length > 0 || (ask !== '' && !/^[\w-]+$/.test(ask)))
+            return json(404, { error: 'GET /api for the device’s ward, GET /api/<ward> for the describe, GET or POST /api/<ward>/<ask> for one ask, POST /api/<ward>/<being>/deliver for a delivery' });
+        const hosted = harbor.wards.get(ward);
+        if (!hosted)
+            return json(404, { error: 'no such world' });
+        let args;
+        if (req.method === 'POST') {
+            const b = await body();
+            if (b === null)
+                return json(400, { error: 'the body is a JSON object' });
+            args = b;
+        }
+        else {
+            const url = new URL(req.url);
+            args = Object.fromEntries(url.searchParams.entries());
+        }
+        const carried = (req.headers.get('authorization') ?? '') !== '';
+        const grant = o.grants.bearer(req);
+        if (carried && grant === null)
+            return json(401, { error: 'unauthorized' });
+        if (grant === null) {
+            // The owner's `ask` with no being named: the public being, asked as
+            // nobody, bounded and judged by the ward, which is the in-process twin
+            // of the bytes a stranger would send. The route holds none of that. A
+            // world with nobody at the door and a being who said nothing are one
+            // answer here, as they are one answer on the wire.
+            const out = await hosted.ask('ask', ask === '' ? {} : { method: ask, args });
+            if (isSilence(out) || out === null || typeof out !== 'object' || Array.isArray(out))
+                return json(503, { error: 'silence' });
+            const said = out.error;
+            if (said === 'silence' || said === 'threw' || said === 'late' || said === 'no such being')
+                return json(503, { error: 'silence' });
+            if (typeof said === 'string')
+                return json(400, out);
+            return json(200, out);
+        }
+        // An occupant: the grant names a world, and the path must name the same
+        // one, since an avatar is one relation in one world.
+        if (grant.ward !== ward)
+            return json(403, { error: 'not your world' });
+        const found = await o.resolve(grant.identity, ward);
+        if (found.error === 'removed') {
+            await o.grants.revoke(grant.identity, ward);
+            return json(401, { error: 'removed' });
+        }
+        if (!found.avatar)
+            return json(401, { error: found.error ?? 'not joined' });
+        const out = ask === '' ? await found.avatar.tools() : await found.avatar.call(ask, args);
+        await hosted.save();
+        if (isSilence(out))
+            return json(503, { error: 'silence' });
+        if (isWord(out))
+            return json(503, { error: wordOf(out) });
+        if (out === null || typeof out !== 'object' || Array.isArray(out))
+            return json(200, out);
+        const said = out.error;
+        if (typeof said === 'string' && !('asks' in out))
+            return json(400, out);
+        return json(200, out);
+    };
+}

package/dist/beings/avatar.d.ts

@@ -0,0 +1,32 @@
+import type { Answer, Blueprint, Invitation, JsonObject, OccupantRecord, Wanted } from '@nervur-org/nervur';
+import { Carrier } from './carry.ts';
+export declare const USER = "user";
+export declare const PUSHER = "user:push";
+export declare class Avatar extends Carrier {
+    static cells: {
+        inbox: JsonObject[];
+    };
+    static asks: {
+        notify: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: (occ: OccupantRecord | undefined) => boolean;
+        };
+    };
+    readonly ears: Set<(object: JsonObject) => void>;
+    notify(args: JsonObject): {
+        notified: boolean;
+    };
+    enter(desk: Invitation, proof: JsonObject): Promise<Blueprint | {
+        error: string;
+    }>;
+    join(invitation: Invitation): Promise<Blueprint | {
+        error: string;
+    }>;
+    tools(): Promise<Blueprint | {
+        error: string;
+    }>;
+    call(name: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+}