@quo-systems/dock 0.2.0 → 0.2.2

package/human/tab.ts

@@ -1,23 +1,68 @@
 // SPDX-License-Identifier: Apache-2.0
-// The tab: a page in a tab that is a world. The tab boots a browser harbor
-// on a seed minted into IndexedDB the first time, a ward with one avatar in
-// it, and dials the world's quo. route. The exchange, once: the owner
-// password goes to the web route, which mints a nonce the desk honours
-// under the `tab` proof kind; the avatar in the tab knocks the desk over the
-// socket with it, joins the user being, and from then on there is no cookie
-// and no token anywhere. The second time the page opens, she already holds
-// `user` and nothing is asked.
+// The tab: a page on a world's web. that is a device of its own. The tab
+// boots a browser harbor on a seed minted into IndexedDB the first time,
+// and is a browser of worlds and of the relations in them, `worlds.ts`: one
+// local ward per far world, one avatar per relation, a switcher over both.
+// A switch is a switch of avatar and nothing more.
 //
-// The screen itself is the human side in `screen.ts` over the DOM surface
-// in `dom.ts`: her describe as forms, an answer as a view, a push on the
-// page. This file is the harbor and the exchange, and hands her over.
-import type { Invitation } from '@quo-systems/quo';
+// Two ways in, the same act, a knock that ends in a standing, and each one
+// a fresh avatar:
+//
+//   a link      the page with the invitation in its fragment, `#quo=...`,
+//               read and stripped before anything else runs, then joined.
+//               The invitation names its ward, so it is joined in that
+//               world's local ward whatever page it was opened on, and a
+//               link opened while already in is one more relation.
+//   a guest     the world's public being, whatever class she is, rendered
+//               as a page by the same screen; a form on it whose answer is
+//               an invitation is the way in.
+//
+// Nothing is typed to get in, ever: no password, no account. A ward with
+// nobody at its door shows the door page, `door.ts`, and a link is the only
+// way. From then on there is no cookie and no token anywhere; the seed and
+// the standings are in the tab's store, and a reload asks nothing. The screen
+// is the human side in `screen.ts` over the DOM surface in `dom.ts`. This
+// file is the shell: the harbor, the config, the switcher and the ways in,
+// and it hands one avatar at a time to the side.
+import type { Invitation, JsonObject } from '@quo-systems/quo';
 import { BrowserHarbor } from '../harbor/browser.ts';
-import { Avatar, USER } from '../beings/avatar.ts';
+import { USER } from '../beings/avatar.ts';
+import { parse, strip } from '../beings/link.ts';
 import { screenSide } from './screen.ts';
 import { domSurface } from './dom.ts';
+import { guest } from './guest.ts';
+import { door } from './door.ts';
+import { world, relations, fresh, type Relation } from './worlds.ts';
+
+// What the page is told by the daemon that served it: the world's routes,
+// every ward on that harbor by name, its pk and whether a public being is
+// at its door, and which of them this page is, if it is one's.
+export type Config = { quo: string; web: string; wards: Record<string, { pk: string; public: boolean }>; ward?: string };
 
-export type Config = { quo: string; web: string };
+// What the tab remembers between pages, beside the harbor: the worlds it
+// has joined, by pk, where each lives and what it is called; which relation
+// is on screen in each; and what each relation is called. A tab with no
+// storage still works, and forgets.
+type Worlds = Record<string, { url: string; name: string }>;
+const kept = <T>(key: string, fallback: T): T => {
+  try {
+    return (JSON.parse(localStorage.getItem(key) ?? 'null') as T | null) ?? fallback;
+  } catch {
+    return fallback;
+  }
+};
+const keep = (key: string, value: unknown) => {
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+    /* forgets */
+  }
+};
+const WORLDS = 'quo-worlds';
+const worlds = (): Worlds => kept(WORLDS, {});
+const remember = (pk: string, url: string, name: string) => keep(WORLDS, { ...worlds(), [pk]: { url, name } });
+const AT = (pk: string) => `quo-at:${pk}`;
+const NAMES = (pk: string) => `quo-names:${pk}`;
 
 const el = <K extends keyof HTMLElementTagNameMap>(tag: K, text = '', attrs: Record<string, string> = {}): HTMLElementTagNameMap[K] => {
   const e = document.createElement(tag);
@@ -27,58 +72,153 @@ const el = <K extends keyof HTMLElementTagNameMap>(tag: K, text = '', attrs: Rec
 };
 
 export async function start(cfg: Config, root: HTMLElement = document.body): Promise<void> {
+  // The link, first and once: the invitation leaves the address bar before
+  // any other code sees it.
+  const linked = parse(location.hash);
+  if (linked) history.replaceState(null, '', location.pathname + location.search + strip(location.hash));
+
+  const nav = el('nav', '', { class: 'worlds' });
+  const who = el('nav', '', { class: 'relations' });
   const status = el('p', 'booting');
   const screen = el('div');
-  root.append(status, screen);
+  root.append(nav, who, status, screen);
   const say = (s: string) => (status.textContent = s);
 
-  // The harbor in the tab: one database, one ward, one avatar, for good.
+  // The harbor in the tab: one database per origin, one ward per world.
   const harbor = new BrowserHarbor('quo');
   await harbor.boot();
-  const main = harbor.wards.get('main') ?? (await harbor.create('main', 'me'));
-  if (!main.being('me')) await main.ask('boot', { key: 'me', class: 'Avatar' });
-  const me = main.being('me') as Avatar;
   harbor.dial(cfg.quo);
 
-  // The screen: every call rotates her keys and a same-ward ask never
-  // crosses the harbor, so the side saves after each one.
-  const show = async (notice: string) => {
-    status.remove();
-    await screenSide(me, domSurface(screen), () => main.save(), notice);
+  // The world this page is about: the link's, since an invitation names
+  // its ward, or the page's own. A link for a world not on this harbor is
+  // a link to the wrong page, and says so.
+  const nameOf = (pk: string) => Object.keys(cfg.wards).find((n) => cfg.wards[n]!.pk === pk);
+  const pk = linked?.ward ?? (cfg.ward ? cfg.wards[cfg.ward]?.pk : undefined);
+  const wardName = pk ? nameOf(pk) : undefined;
+  const pageOf = (name: string) => `${new URL(cfg.web).pathname.replace(/\/$/, '')}/${encodeURIComponent(name)}`;
+
+  const switcher = () => {
+    nav.replaceChildren();
+    const known = worlds();
+    for (const [k, w] of Object.entries(known)) {
+      const a = el('a', w.name || k.slice(0, 8), { href: w.url });
+      if (k === pk) a.setAttribute('aria-current', 'page');
+      nav.append(a);
+    }
+    if (pk && !known[pk] && wardName) nav.append(el('span', `${wardName} at ${new URL(cfg.web).host}`));
   };
+  switcher();
 
-  // Already in: reconnect, nothing minted.
-  const had = await me.tools();
-  if ('asks' in had) return show('in, as before');
-
-  // The exchange, once: the owner password for a nonce, the nonce for an
-  // invitation the user being mints, the invitation for a standing.
-  const form = el('form');
-  const identity = el('input', '', { name: 'identity', value: 'tab', placeholder: 'identity' });
-  const password = el('input', '', { name: 'password', type: 'password', placeholder: 'owner password' });
-  const go = el('button', 'enter');
-  form.append(identity, password, go);
-  root.insertBefore(form, screen);
-  say(`not in (${had.error}): the owner password opens the world`);
-  form.onsubmit = async (ev) => {
-    ev.preventDefault();
-    say('asking the world');
-    let res: Response;
-    try {
-      res = await fetch(`${cfg.web}/tab/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ password: password.value, identity: identity.value }) });
-    } catch (e) {
-      return say(`the world did not answer: ${(e as Error).message}`);
+  if (!pk || !wardName) {
+    say(linked ? 'this link is for a world that does not live here' : 'choose a world');
+    return;
+  }
+  if (linked && location.pathname !== pageOf(wardName)) history.replaceState(null, '', pageOf(wardName) + location.search + location.hash);
+  const ward = await world(harbor, pk);
+  const at = { name: wardName, pk, public: cfg.wards[wardName]!.public };
+
+  // The relations in this world, and which one is on screen.
+  let side: { close(): Promise<void> } | null = null;
+  let current: Relation | null = null;
+  const names = () => kept<Record<string, string>>(NAMES(pk), {});
+  const people = () => {
+    who.replaceChildren();
+    const rels = relations(ward);
+    const called = names();
+    for (const r of rels) {
+      const b = el('button', called[r.key] ?? r.key, { type: 'button' });
+      if (r.key === current?.key) b.setAttribute('aria-current', 'true');
+      b.onclick = () => void inside(r, `in, as ${called[r.key] ?? r.key}`, called[r.key] ?? r.key);
+      who.append(b);
+    }
+    if (rels.length) {
+      const more = el('button', 'another way in', { type: 'button', class: 'another' });
+      more.onclick = () => void atDoor();
+      who.append(more);
     }
-    if (!res.ok) return say(`refused: ${(await res.json().catch(() => ({ error: res.status })) as { error?: string }).error ?? res.status}`);
-    const { nonce, ward } = (await res.json()) as { nonce: string; ward: string };
-    password.value = '';
+  };
+
+  // In, as one relation: her page. Every call rotates her keys and a
+  // same-ward ask never crosses the harbor, so the side saves after each.
+  const inside = async (rel: Relation, notice: string, called: string) => {
+    await side?.close();
+    status.remove();
+    root.querySelector('form.password')?.remove();
+    screen.replaceChildren();
+    current = rel;
+    keep(AT(pk), rel.key);
+    const s = await screenSide(rel.avatar, domSurface(screen), { after: () => ward.save(), notice });
+    side = s;
+    const bp = s.model.blueprint;
+    const notesName = typeof (bp?.notes as JsonObject | null)?.name === 'string' ? ((bp!.notes as JsonObject).name as string) : '';
+    remember(pk, location.origin + pageOf(at.name), s.model.look.name || notesName || at.name);
+    if (!names()[rel.key]) keep(NAMES(pk), { ...names(), [rel.key]: called });
+    switcher();
+    people();
+  };
+
+  // The way in, from any of the three: a fresh avatar joins, the ward is
+  // saved, and she is the one on screen.
+  const admit = async (inv: Invitation, notice: string, called: string) => {
     say('knocking');
-    const got = await me.enter({ ward } as Invitation, { kind: 'tab', nonce });
-    await main.save(); // the knock went through her own door, which the harbor never sees
-    if (!('asks' in got)) return say(`not in: ${got.error}`);
-    form.remove();
-    await show(`in, as ${identity.value}`);
+    const rel = await fresh(ward);
+    const got = await rel.avatar.join(inv);
+    await ward.save(); // the knock went through her own door, which the harbor never sees
+    if (!('asks' in got)) {
+      say(`not in: ${got.error}`);
+      return false;
+    }
+    await inside(rel, notice, called);
+    return true;
   };
+
+  // At the door. With a public being there, her describe as a page, and a
+  // form whose answer is an invitation lets the guest in. With nobody
+  // there, the door page: a link is the only way in, and nothing to type.
+  const atDoor = async () => {
+    await side?.close();
+    side = null;
+    current = null;
+    screen.replaceChildren();
+    if (!status.isConnected) root.insertBefore(status, screen);
+    people();
+    if (!at.public) {
+      status.remove();
+      screen.innerHTML = door({ world: at.name, host: new URL(cfg.web).host });
+      return;
+    }
+    say(`at the door of ${at.name}`);
+    const rel = await fresh(ward);
+    const gate = guest(rel.avatar, pk);
+    const s = await screenSide(gate, domSurface(screen), {
+      after: () => ward.save(),
+      notice: `a guest at ${at.name}: what she shows strangers`,
+      admit: async (inv) => {
+        await s.close();
+        await admit(inv, `in, as a guest of ${at.name}`, 'guest');
+      },
+    });
+    side = s;
+  };
+
+  // A link: one more relation, whoever else is in. Then whoever was on
+  // screen last, or the door.
+  if (linked && (await admit(linked, 'in, by the link', 'link'))) return;
+  const rels = relations(ward);
+  const last = kept<string | null>(AT(pk), null);
+  const back = rels.find((r) => r.key === last) ?? rels[rels.length - 1];
+  if (back) {
+    const had = await back.avatar.tools();
+    await ward.save(); // her keys rotated on that ask, whatever it answered
+    if ('asks' in had) return inside(back, linked ? `not in by the link; in, as before` : 'in, as before', names()[back.key] ?? back.key);
+    say(`not in (${had.error})`);
+  }
+  await atDoor();
 }
 
+// The page hands the config in a JSON script, which a content security
+// policy allows where an inline script is not.
+const config = document.getElementById('quo');
+if (config?.textContent) void start(JSON.parse(config.textContent) as Config);
+
 export { USER };

package/human/web.ts

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+// The web route: the worlds' pages, served by the daemon under `/web` and
+// mapped by the proxy from the web. hostname. A world is a ward with a
+// public being, and its address is `/web/<ward>`: the tab page, `tab.ts`,
+// told which ward this is, and every ward on the harbor by name, pk and
+// whether a public being is at its door, so that its guest is that ward's
+// public being rendered by the screen, whatever class she is. Every ward
+// has a page, since a link may point into one with nobody at the door;
+// `/web/` lists the worlds and carries the tab too, so a link at the root
+// lands in the ward its invitation names, and with no world to list it is
+// the door page, `door.ts`. The bundle is built once from the source
+// beside this file, `.ts` in the tree, `.js` once emitted into the
+// package's dist. Nothing here authenticates and nothing is admitted on
+// this side: the way into a world is an invitation, carried by a link, and
+// the knock is the tab's. Paths this route does not take fall through to
+// the exchange pages, which share the prefix.
+//
+// The page carries a content security policy: scripts from this origin
+// only and never inline, connections to this origin and the quo. route the
+// tab dials, images from data URIs and this origin, and nothing else. So
+// even a bug in a renderer cannot become a script, and no look can reach a
+// server. The config crosses in a JSON script, which the policy allows.
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+import type { DiskHarbor, Hosted } from '../harbor/disk.ts';
+import { door } from './door.ts';
+
+export type WebOptions = {
+  // where the routes are, as a tab sees them: what it dials and where it is
+  at: { quo: string; web: string };
+};
+
+// The paths under `/web` that are the exchange's, never a ward's name.
+const RESERVED_PATHS = new Set(['login', 'allow', 'tab.js']);
+
+export function webRoute(harbor: DiskHarbor, o: WebOptions): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean> {
+  const tabEntry = () => {
+    const js = fileURLToPath(new URL('./tab.js', import.meta.url));
+    return existsSync(js) ? js : fileURLToPath(new URL('./tab.ts', import.meta.url));
+  };
+  let bundle: Promise<string> | undefined;
+  const built = () =>
+    (bundle ??= build({ entryPoints: [tabEntry()], bundle: true, format: 'esm', platform: 'browser', target: 'es2023', write: false }).then((out) => out.outputFiles[0]!.text));
+  const quoOrigin = (() => {
+    try {
+      const u = new URL(o.at.quo);
+      return `${u.origin} ${u.origin.replace(/^http/, 'ws')}`;
+    } catch {
+      return '';
+    }
+  })();
+  const host = (() => {
+    try {
+      return new URL(o.at.web).host;
+    } catch {
+      return o.at.web;
+    }
+  })();
+  const policy = `default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ${quoOrigin}; form-action 'self'; base-uri 'none'; frame-ancestors 'none'`;
+  const shell = (body: string) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
+<style>${CSS}</style>
+</head><body>${body}</body></html>`;
+  const esc = (v: string) => v.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+  const publicOf = (h: Hosted) => (h.partition as { public?: string | null }).public ?? null;
+  const html = (status: number, res: ServerResponse, body: string) => {
+    res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': policy, 'referrer-policy': 'no-referrer' });
+    res.end(shell(body));
+    return true;
+  };
+  const wards = () => Object.fromEntries([...harbor.wards].map(([n, h]) => [n, { pk: h.pk, public: publicOf(h) !== null }]));
+  const tab = (ward?: string) => {
+    const cfg = { quo: o.at.quo, web: o.at.web, wards: wards(), ...(ward ? { ward } : {}) };
+    return `<script id="quo" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script type="module" src="${o.at.web}/tab.js"></script>`;
+  };
+  return async (req, res, rest) => {
+    const parts = rest.split('/').filter(Boolean);
+    if (req.method === 'GET' && (rest === '' || rest === '/')) {
+      const list = [...harbor.wards]
+        .filter(([, h]) => publicOf(h) !== null)
+        .map(([n, h]) => `<li><a href="${o.at.web}/${encodeURIComponent(n)}">${esc(n)}</a> <small>${esc(publicOf(h) ?? '')} at the door, <code>${h.pk.slice(0, 16)}…</code></small></li>`)
+        .join('');
+      return html(200, res, `${list ? `<h1>worlds</h1><ul>${list}</ul>` : door({ host })}${tab()}`);
+    }
+    if (rest === '/tab.js' && req.method === 'GET') {
+      res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });
+      res.end(await built());
+      return true;
+    }
+    const wardName = parts[0] ?? '';
+    if (!wardName || RESERVED_PATHS.has(wardName)) return false;
+    const hosted = harbor.wards.get(wardName);
+    if (!hosted) return html(404, res, `<h1>no such world</h1><p>no ward named ${esc(wardName)} on this harbor.</p>`);
+    if (parts.length === 1 && req.method === 'GET') return html(200, res, tab(wardName));
+    return false;
+  };
+}
+
+// The tab's stylesheet: one, light and dark, honouring the variables a look
+// sets on a section. The page owns layout; a far being paints inside her
+// section and nowhere else. The door page is the one designed thing in it.
+const CSS = [
+  ':root{color-scheme:light dark;--accent:#3b6ef5;--bg:transparent;--fg:inherit;--font:system-ui,sans-serif;--radius:6px;--ink:#1c1b22;--paper:#fbfaf7;--mute:#6b6a73}',
+  '@media(prefers-color-scheme:dark){:root{--ink:#ecebe6;--paper:#141318;--mute:#9a99a2}}',
+  'html{background:var(--paper);color:var(--ink)}',
+  'body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem}',
+  'nav.worlds{display:flex;flex-wrap:wrap;gap:.5rem 1rem;font-size:.9rem;opacity:.8}nav.worlds a[aria-current]{font-weight:600}',
+  'nav.relations{display:flex;flex-wrap:wrap;gap:.25rem;margin:.5rem 0}nav.relations button{background:transparent;color:inherit;border:1px solid color-mix(in srgb,currentColor 30%,transparent)}nav.relations button[aria-current]{border-color:var(--accent);font-weight:600}',
+  'header,main{background:var(--bg);color:var(--fg);font-family:var(--font)}header{display:flex;flex-wrap:wrap;align-items:center;gap:.5rem 1rem}header .notice{width:100%;margin:0}',
+  'input,select,textarea,button{font:inherit;padding:.4rem;margin:.2rem;border-radius:var(--radius)}button{background:var(--accent);color:#fff;border:0;padding:.4rem .9rem}',
+  'fieldset{border:1px solid color-mix(in srgb,currentColor 20%,transparent);border-radius:var(--radius);margin:.5rem 0}',
+  'section.standing{background:var(--bg);color:var(--fg);font-family:var(--font);border-left:4px solid var(--accent);border-radius:var(--radius);padding:.25rem 1rem;margin:1.5rem 0}section.standing h2{display:flex;align-items:center;gap:.5rem;font-size:1.1rem}img.logo{height:1.6rem}',
+  'table{border-collapse:collapse}td,th{padding:.15rem .5rem;text-align:left}.answer{margin:.5rem 0 1rem;padding:.5rem;border-left:3px solid var(--accent)}.answer.error{border-color:#c33}.answer.silence,.answer.word,.answer.unreached{border-color:#c93}pre{padding:.75rem;overflow:auto}',
+  // the door page: one column, generous air, the mark, a word, a sentence
+  'main.door{min-height:70vh;display:flex;flex-direction:column;justify-content:center;align-items:flex-start;max-width:32rem;margin:0 auto;padding:3rem 0;font-family:ui-serif,Georgia,"Times New Roman",serif}',
+  'main.door .mark{width:3.5rem;height:3.5rem;color:var(--ink);opacity:.9;margin-bottom:1.25rem}',
+  'main.door h1{font-size:3rem;font-weight:400;letter-spacing:-.02em;line-height:1;margin:0 0 .5rem}',
+  'main.door .where{font-family:system-ui,sans-serif;font-size:.85rem;letter-spacing:.08em;text-transform:uppercase;color:var(--mute);margin:0 0 2rem}main.door .where span{text-transform:none;letter-spacing:0}',
+  'main.door .lead{font-size:1.5rem;line-height:1.3;margin:0 0 1rem}',
+  'main.door p{font-size:1.05rem;line-height:1.6;margin:0 0 1rem;max-width:30rem}',
+  'main.door .quiet{color:var(--mute);font-size:.95rem;border-top:1px solid color-mix(in srgb,currentColor 15%,transparent);padding-top:1rem;margin-top:1rem}',
+].join('');

package/human/worlds.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// The worlds in a tab, and the relations in each. A tab is a device with a
+// harbor of its own, and it keeps one local ward per far world, named by
+// the far ward's pk; inside it, one avatar per relation, since an avatar is
+// one standing and nothing more. An invitation names its ward by pk, so an
+// invitation is self-addressing: the local ward is chosen by the invitation
+// and never by the page it was opened on, and a fresh invitation is always a
+// fresh avatar, never a join on one that already holds her standing. Two
+// humans on one family tablet are two relations in one world; a shop and a
+// friend in one far ward are two as well. Nothing here touches a document:
+// `tab.ts` is the shell over this, and this is what the memory harbor proves.
+import type { Harbor, Hosted } from '@quo-systems/quo/harbor';
+import { Avatar, USER } from '../beings/avatar.ts';
+
+// The local ward for a far world, by its pk: created on first sight, on
+// the tab's own seed, empty.
+export const localName = (pk: string): string => `w-${pk.slice(0, 16)}`;
+export async function world(harbor: Harbor, pk: string): Promise<Hosted> {
+  const name = localName(pk);
+  return harbor.wards.get(name) ?? (await harbor.create(name, 'me'));
+}
+
+// The relations held in a local ward: every avatar there who holds her
+// standing, by key, in the order they were born.
+export type Relation = { key: string; avatar: Avatar };
+export function relations(ward: Hosted): Relation[] {
+  const beings = (ward.partition as { beings?: Record<string, { class?: string }> }).beings ?? {};
+  const out: Relation[] = [];
+  for (const key of Object.keys(beings)) {
+    const a = ward.being(key) as Avatar | undefined;
+    if (a instanceof Avatar && a.standings[USER]) out.push({ key, avatar: a });
+  }
+  return out;
+}
+
+// An avatar for a relation not yet made: one who holds no standing, whether
+// left by a guest who never came in or booted now under the next free key.
+// She is the one who knocks, as a guest or with an invitation, and she
+// becomes a relation the moment she takes her standing.
+export async function fresh(ward: Hosted): Promise<Relation> {
+  const beings = (ward.partition as { beings?: Record<string, { class?: string }> }).beings ?? {};
+  for (const key of Object.keys(beings)) {
+    const a = ward.being(key) as Avatar | undefined;
+    if (a instanceof Avatar && !a.standings[USER]) return { key, avatar: a };
+  }
+  let n = 1;
+  while (beings[`r${n}`]) n++;
+  const key = `r${n}`;
+  const out = (await ward.ask('boot', { key, class: 'Avatar' })) as { error?: string };
+  if (out.error) throw new Error(`the tab could not boot an avatar: ${out.error}`);
+  return { key, avatar: ward.being(key) as Avatar };
+}

package/mcp/http.ts

@@ -15,9 +15,10 @@ import type { Avatar } from '../beings/avatar.ts';
 import type { Serving } from '../beings/side.ts';
 import { mcpSide } from './server.ts';
 
-export type Session = { identity: string; transport: StreamableHTTPServerTransport; serving: Serving; touched: number };
+export type Session = { identity: string; ward: string; transport: StreamableHTTPServerTransport; serving: Serving; touched: number };
 export const SESSION_IDLE = 60 * 60 * 1000;
-export type Resolve = (identity: string) => Promise<{ avatar?: Avatar; error?: string }>;
+// An identity in a world: one harbor holds many, and the grant names which.
+export type Resolve = (identity: string, ward: string) => Promise<{ avatar?: Avatar; error?: string }>;
 
 export class McpHttp {
   readonly sessions = new Map<string, Session>();
@@ -27,7 +28,7 @@ export class McpHttp {
   // What to do with an identity the user being has removed: the route's
   // revoke, so the client's tokens go with the occupant. Set by whoever
   // mounts the route beside the credential exchange.
-  gone: (identity: string) => Promise<void> = async () => {};
+  gone: (identity: string, ward: string) => Promise<void> = async () => {};
   constructor(resolve: Resolve, after: () => Promise<void> = async () => {}) {
     this.resolve = resolve;
     this.after = after;
@@ -36,7 +37,7 @@ export class McpHttp {
   // `identity` is what the bearer named; the caller has already turned a
   // stranger away. A request on a known session goes to it. A request with
   // no session opens one, if it is an initialize; anything else is 400.
-  async handle(req: IncomingMessage, res: ServerResponse, identity: string): Promise<void> {
+  async handle(req: IncomingMessage, res: ServerResponse, identity: string, ward = 'main'): Promise<void> {
     const id = req.headers['mcp-session-id'];
     const sid = Array.isArray(id) ? id[0] : id;
     const json = (status: number, body: unknown) => {
@@ -47,22 +48,22 @@ export class McpHttp {
     if (sid !== undefined) {
       const s = this.sessions.get(sid);
       if (!s) return json(404, { jsonrpc: '2.0', error: { code: -32001, message: 'no such session' }, id: null });
-      if (s.identity !== identity) return json(403, { jsonrpc: '2.0', error: { code: -32003, message: 'not your session' }, id: null });
+      if (s.identity !== identity || s.ward !== ward) return json(403, { jsonrpc: '2.0', error: { code: -32003, message: 'not your session' }, id: null });
       s.touched = this.now();
       await s.transport.handleRequest(req, res);
       if (req.method === 'DELETE') this.drop(sid);
       return;
     }
     if (req.method !== 'POST') return json(400, { jsonrpc: '2.0', error: { code: -32000, message: 'no session' }, id: null });
-    const found = await this.resolve(identity);
+    const found = await this.resolve(identity, ward);
     // A session opens on her describe, and admit already asked it. The one
     // word the door says for an identity the user being removed is
     // `removed`, under the key it bound for her avatar: in MCP's vocabulary
     // that is 401, the client drops its token and starts the exchange again,
     // and the route forgets the grant.
     if (found.error === 'removed') {
-      await this.gone(identity);
-      for (const [sid, s] of this.sessions) if (s.identity === identity) this.drop(sid);
+      await this.gone(identity, ward);
+      for (const [sid, s] of this.sessions) if (s.identity === identity && s.ward === ward) this.drop(sid);
       res.writeHead(401, { 'content-type': 'application/json' });
       return void res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32001, message: 'removed: the user being removed this identity' }, id: null }));
     }
@@ -70,7 +71,7 @@ export class McpHttp {
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: () => randomUUID(),
       onsessioninitialized: (s) => {
-        this.sessions.set(s, { identity, transport, serving, touched: this.now() });
+        this.sessions.set(s, { identity, ward, transport, serving, touched: this.now() });
       },
       onsessionclosed: (s) => this.drop(s),
     });

package/mcp/oauth.ts

@@ -33,11 +33,13 @@ export const REFRESH_TTL = 30 * 24 * 60 * 60 * 1000; // a refresh token, thirty
 // is open to anyone, and what nobody allowed must not stay on disk.
 export type Client = { client_id: string; client_name: string; redirect_uris: string[]; exp: number };
 export type Pending = { client_id: string; redirect_uri: string; challenge: string; state: string | null; resource: string | null; exp: number };
-export type Grant = { identity: string; client_id: string; exp: number };
+// A grant names the world the human allowed the client into, since one
+// harbor holds many; a record from before there were worlds is `main`'s.
+export type Grant = { identity: string; ward: string; client_id: string; exp: number };
 export type Store = {
   clients: Record<string, Client>;
   pending: Record<string, Pending>;
-  codes: Record<string, Pending & { identity: string }>;
+  codes: Record<string, Pending & { identity: string; ward: string }>;
   access: Record<string, Grant>;
   refresh: Record<string, Grant>;
 };
@@ -129,13 +131,14 @@ export class OAuth {
     return client ? { ...p, client } : null;
   }
 
-  // The web route's last step: the human allowed this client as this identity.
-  async complete(id: string, identity: string): Promise<{ redirect: string } | { error: string }> {
+  // The web route's last step: the human allowed this client as this
+  // identity, into this world.
+  async complete(id: string, identity: string, ward = 'main'): Promise<{ redirect: string } | { error: string }> {
     const p = this.pending(id);
     if (!p) return { error: 'expired' };
     delete this.store.pending[id];
     const code = token();
-    this.store.codes[code] = { ...p, identity, exp: this.now() + CODE_TTL };
+    this.store.codes[code] = { ...p, identity, ward, exp: this.now() + CODE_TTL };
     await this.o.persist(this.store);
     return { redirect: withQuery(p.redirect_uri, { code, state: p.state }) };
   }
@@ -160,23 +163,23 @@ export class OAuth {
         await this.o.persist(this.store);
         return { error: 'invalid_grant' };
       }
-      return this.issue(c.identity, c.client_id);
+      return this.issue(c.identity, c.ward ?? 'main', c.client_id);
     }
     if (grant === 'refresh_token') {
       const rt = body.get('refresh_token') ?? '';
       const r = own(this.store.refresh, rt);
       if (!r || r.exp < this.now()) return { error: 'invalid_grant' };
       delete this.store.refresh[rt]; // rotated: the old one is gone with the new one's birth
-      return this.issue(r.identity, r.client_id);
+      return this.issue(r.identity, r.ward ?? 'main', r.client_id);
     }
     return { error: 'unsupported_grant_type' };
   }
 
-  async issue(identity: string, client_id: string) {
+  async issue(identity: string, ward: string, client_id: string) {
     const access_token = token(),
       refresh_token = token();
-    this.store.access[access_token] = { identity, client_id, exp: this.now() + ACCESS_TTL };
-    this.store.refresh[refresh_token] = { identity, client_id, exp: this.now() + REFRESH_TTL };
+    this.store.access[access_token] = { identity, ward, client_id, exp: this.now() + ACCESS_TTL };
+    this.store.refresh[refresh_token] = { identity, ward, client_id, exp: this.now() + REFRESH_TTL };
     const c = own(this.store.clients, client_id);
     if (c) c.exp = this.now() + REFRESH_TTL; // allowed: the client lives as long as what it was granted
     this.sweep();
@@ -184,18 +187,18 @@ export class OAuth {
     return { access_token, token_type: 'Bearer', expires_in: ACCESS_TTL / 1000, refresh_token, scope: 'quo' };
   }
 
-  // The bearer on an MCP request, to a client identity. Null is 401.
-  bearer(req: IncomingMessage): string | null {
+  // The bearer on an MCP request, to a client identity in a world. Null is 401.
+  bearer(req: IncomingMessage): { identity: string; ward: string } | null {
     const h = req.headers.authorization ?? '';
     const t = h.startsWith('Bearer ') ? h.slice(7) : '';
     const g = own(this.store.access, t);
-    return g && g.exp >= this.now() && typeof g.identity === 'string' ? g.identity : null;
+    return g && g.exp >= this.now() && typeof g.identity === 'string' ? { identity: g.identity, ward: g.ward ?? 'main' } : null;
   }
 
-  // Every grant an identity holds, gone: the route's half of revocation.
-  // The other half is the user being removing the occupant.
-  async revoke(identity: string): Promise<void> {
-    for (const k of ['access', 'refresh'] as const) for (const [t, g] of Object.entries(this.store[k])) if (g.identity === identity) delete this.store[k][t];
+  // Every grant an identity holds in a world, gone: the route's half of
+  // revocation. The other half is the user being removing the occupant.
+  async revoke(identity: string, ward = 'main'): Promise<void> {
+    for (const k of ['access', 'refresh'] as const) for (const [t, g] of Object.entries(this.store[k])) if (g.identity === identity && (g.ward ?? 'main') === ward) delete this.store[k][t];
     await this.o.persist(this.store);
   }
 

package/mcp/pilot.ts

@@ -26,7 +26,7 @@ export function owner(dir: string, ward: string, via?: string): Subject {
     if (isRecord(r) && typeof r.word === 'string') return { error: r.word };
     return r as Answer;
   };
-  return { tools: () => one(undefined, {}) as Promise<Blueprint | { error: string }>, call: (name, args) => one(name, args), ears: new Set() };
+  return { tools: () => one(undefined, {}) as Promise<Blueprint | { error: string }>, call: (name, args) => one(name, args ?? {}), ears: new Set() };
 }
 
 export function pilotSide(dir: string, ward: string, transport: Transport, via?: string): Promise<Serving> {