nervur 0.20.1 → 0.20.2

package/src/line/web.ts

@@ -0,0 +1,227 @@
+// SPDX-License-Identifier: Apache-2.0
+// Quo over the web, `quo/CARRIER-WEB.md`, on what every engine has: fetch
+// and the WebSocket client.
+//
+//   WebDialer     bytes to a ward pk at an address: `http` and `https` as
+//                 one post each, `ws` and `wss` on one held line per
+//                 address, which many asks share
+//   webFaculty    the web carrier as a faculty of one harbor: it dials
+//                 every web address the harbor routes, and listens where
+//                 its cells say, through a listener the ground hands it
+//
+// A post that comes back with status 200 and a body is a reply, and every
+// other status is nothing. A post the network refused, or a held line
+// that did not open, was not dialed. A line that carried a box and closed
+// answers nothing.
+import type { AskSpec, JsonObject } from '../being/index.ts';
+import { concat, hex, isHex, unhex } from '../crypto/index.ts';
+import { CarrierFaculty, UNDIALED, type Dialed, type Ground, type GroundFaculty } from '../harbor/index.ts';
+import { webAddress, type WebAddress } from '../quo/index.ts';
+import { ownerAsk } from '../ward/index.ts';
+import { askBody, readBody } from './frame.ts';
+
+export const MIN_POST = 65;
+export const MAX_POST = 64 + 1_048_576;
+const MAX_ID = 0xffff_ffff;
+
+// Bytes on a buffer of their own, as a body and a message take them.
+const own = (bytes: Uint8Array): Uint8Array<ArrayBuffer> => new Uint8Array(bytes);
+
+// One held line to one address.
+class HeldLine {
+  readonly #socket: WebSocket;
+  readonly #waiting = new Map<number, (box: Uint8Array | null) => void>();
+  #next = 1;
+
+  private constructor(socket: WebSocket) {
+    this.#socket = socket;
+    socket.binaryType = 'arraybuffer';
+    socket.addEventListener('message', (e: MessageEvent) => {
+      const frame = typeof e.data === 'string' ? null : readBody(new Uint8Array(e.data as ArrayBuffer));
+      if (frame === null) return this.close();
+      if (frame.kind === 'ask') return;
+      const done = this.#waiting.get(frame.id);
+      this.#waiting.delete(frame.id);
+      done?.(frame.kind === 'reply' ? frame.box : null);
+    });
+    socket.addEventListener('close', () => {
+      for (const done of this.#waiting.values()) done(null);
+      this.#waiting.clear();
+    });
+  }
+
+  // A line that opened with the subprotocol `quo`, or null.
+  static open(href: string, onClose: () => void): Promise<HeldLine | null> {
+    return new Promise((resolve) => {
+      let socket: WebSocket;
+      try {
+        socket = new WebSocket(href, 'quo');
+      } catch {
+        resolve(null);
+        return;
+      }
+      const line = new HeldLine(socket);
+      socket.addEventListener('open', () => (socket.protocol === 'quo' ? resolve(line) : (socket.close(), resolve(null))));
+      socket.addEventListener('close', () => {
+        onClose();
+        resolve(null);
+      });
+      socket.addEventListener('error', () => resolve(null));
+    });
+  }
+
+  ask(pk: Uint8Array, box: Uint8Array): Promise<Uint8Array | null> {
+    if (this.#socket.readyState !== WebSocket.OPEN) return Promise.resolve(null);
+    const id = this.#next;
+    this.#next = this.#next === MAX_ID ? 1 : this.#next + 1;
+    return new Promise((resolve) => {
+      this.#waiting.set(id, resolve);
+      this.#socket.send(own(askBody(id, pk, box)));
+    });
+  }
+
+  close(): void {
+    this.#socket.close();
+  }
+}
+
+export class WebDialer {
+  readonly #lines = new Map<string, Promise<HeldLine | null>>();
+
+  dial(at: string, pk: string, bytes: Uint8Array): Promise<Dialed> {
+    const address = webAddress(at);
+    if (address === null || !isHex(pk, 64)) return Promise.resolve(UNDIALED);
+    return address.held ? this.#held(address, pk, bytes) : this.#post(address, pk, bytes);
+  }
+
+  async #post(address: WebAddress, pk: string, bytes: Uint8Array): Promise<Dialed> {
+    let response: Response;
+    try {
+      response = await fetch(address.href, { method: 'POST', body: own(concat(unhex(pk), bytes)) });
+    } catch {
+      return UNDIALED;
+    }
+    const body = new Uint8Array(await response.arrayBuffer().catch(() => new ArrayBuffer(0)));
+    return response.status === 200 && body.length > 0 ? body : null;
+  }
+
+  async #held(address: WebAddress, pk: string, bytes: Uint8Array): Promise<Dialed> {
+    let line = this.#lines.get(address.href);
+    if (!line) {
+      line = HeldLine.open(address.href, () => this.#lines.delete(address.href));
+      this.#lines.set(address.href, line);
+      void line.then((held) => held ?? this.#lines.delete(address.href));
+    }
+    const held = await line;
+    return held ? held.ask(unhex(pk), bytes) : UNDIALED;
+  }
+
+  async close(): Promise<void> {
+    const lines = [...this.#lines.values()];
+    this.#lines.clear();
+    for (const line of await Promise.all(lines)) line?.close();
+  }
+}
+
+// Where the web carrier listens, as its cells keep it: a host, the port it
+// bound, the path it answers on, and the origins whose pages it answers.
+export type WebListen = { host: string; port: number; path: string; origins: string[] };
+
+// A listener a ground runs for the web carrier: it hands every ask it
+// hears to the ground, and says the addresses it answers at, a post's and
+// a held line's.
+export interface WebListener {
+  readonly at: string[];
+  readonly port: number;
+  close(): Promise<void>;
+}
+export type WebServe = (ground: Ground, listen: WebListen) => Promise<WebListener>;
+
+export const WEB = 'org.nervur.web';
+export const WEB_OPENING = { key: 'web', kind: WEB } as const;
+
+const listenOf = (value: unknown): WebListen | null => {
+  if (typeof value !== 'object' || value === null) return null;
+  const { host, port, path, origins } = value as Record<string, unknown>;
+  const fine =
+    typeof host === 'string' &&
+    Number.isInteger(port) &&
+    (port as number) >= 0 &&
+    (port as number) <= 65_535 &&
+    typeof path === 'string' &&
+    path.startsWith('/') &&
+    Array.isArray(origins) &&
+    origins.every((o) => typeof o === 'string');
+  return fine ? { host, port: port as number, path, origins: origins as string[] } : null;
+};
+
+// Quo over the web as a carrier faculty of one harbor, listening through
+// `serve` where the ground has one:
+//
+//   listen  { host?, port?, path?, origins? }
+//                  listen there from now on, 127.0.0.1, a free port, `/`
+//                  and every origin unless named, and on every wake at the
+//                  port it bound
+//   deaf           listen nowhere from now on
+export const webFaculty =
+  (serve?: WebServe): GroundFaculty =>
+  (ground: Ground) =>
+    class WebFaculty extends CarrierFaculty {
+      static override readonly kind: string = WEB;
+      static override asks: Record<string, AskSpec> = {
+        listen: ownerAsk('listen for Quo over the web, and on every wake'),
+        deaf: ownerAsk('listen nowhere'),
+      };
+
+      readonly #dialer = new WebDialer();
+      #listener: WebListener | undefined;
+
+      accepts(address: string): boolean {
+        return webAddress(address) !== null;
+      }
+
+      dial(address: string, pk: string, bytes: Uint8Array): Promise<Dialed> {
+        return this.#dialer.dial(address, pk, bytes);
+      }
+
+      override listening(): string[] {
+        return this.#listener ? [...this.#listener.at] : [];
+      }
+
+      override async awake(): Promise<void> {
+        const at = listenOf(this.cells.listen);
+        if (at && serve && !this.#listener) this.#listener = await serve(ground, at);
+      }
+
+      override async sleep(): Promise<void> {
+        await this.#dialer.close();
+        await this.#listener?.close();
+        this.#listener = undefined;
+      }
+
+      async listen(args: JsonObject): Promise<JsonObject> {
+        if (!serve) return { error: 'this ground listens nowhere on the web' };
+        const at = listenOf({ host: args.host ?? '127.0.0.1', port: args.port ?? 0, path: args.path ?? '/', origins: args.origins ?? ['*'] });
+        if (at === null) return { error: 'host is text, port a port, path a path and origins a list' };
+        await this.#listener?.close();
+        this.#listener = undefined;
+        try {
+          this.#listener = await serve(ground, at);
+        } catch (e) {
+          return { error: (e as Error).message };
+        }
+        this.cells.listen = { ...at, port: this.#listener.port };
+        return { at: [...this.#listener.at] };
+      }
+
+      async deaf(): Promise<JsonObject> {
+        await this.#listener?.close();
+        this.#listener = undefined;
+        delete this.cells.listen;
+        return { deaf: true };
+      }
+    };
+
+// The ward pk and box a post carries, or null for a body that is no ask.
+export const readPost = (body: Uint8Array): { pk: string; box: Uint8Array } | null =>
+  body.length < MIN_POST || body.length > MAX_POST ? null : { pk: hex(body.subarray(0, 64)), box: body.slice(64) };

package/src/node/index.ts

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur/node`: the Node ground. A harbor keeps its seed and sealed
+// memory in a folder, finds its code among the modules it is handed and
+// then in files, speaks TCP from genesis and the web and Web Push where
+// the root opens them, and serves the root line on a local socket, so the
+// `nervur` command reaches it while it stands.
+//
+//   <dir>/seed        the harbor's seed
+//   <dir>/<place>/    its sealed memory
+//   <dir>/root.sock   the root line while the harbor is served, open to
+//                     this user alone, or in the temporary folder for a
+//                     folder too deep for a socket path
+//
+// One run holds a folder: a terrain refuses a folder another run serves.
+import { createHash } from 'node:crypto';
+import { chmod, rm } from 'node:fs/promises';
+import { connect, createServer, type Server } from 'node:net';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { JsonObject } from '../being/index.ts';
+import { Loader, type Loaded, type Module } from '../contract/index.ts';
+import { FolderCustody, FolderMemory } from '../folder/index.ts';
+import { rootLine, type GroundProbe, type Harbor, type RootRequest } from '../harbor/index.ts';
+import { webGround } from '../http/index.ts';
+import { webPush } from '../line/index.ts';
+import { CryptoEntropy, HeldLoader, PointerTerrain } from '../pointer/index.ts';
+import { TCP_OPENING, tcpFaculty } from '../tcp/index.ts';
+
+export const NODE = 'node';
+
+// Where a harbor of this user lives unless named: $NERVUR_DIR, then
+// ~/.nervur.
+export const harborDir = (env: Record<string, string | undefined> = process.env): string => env.NERVUR_DIR ?? join(homedir(), '.nervur');
+
+// A socket path has a hundred bytes or so on every system, so a folder too
+// deep for one puts its socket in this user's temporary folder, under a
+// name drawn from the folder's own path.
+const SOCKET_PATH = 100;
+export const socketOf = (dir: string): string => {
+  const beside = join(resolve(dir), 'root.sock');
+  if (Buffer.byteLength(beside) <= SOCKET_PATH) return beside;
+  return join(tmpdir(), `nervur-${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 32)}.sock`);
+};
+
+// Code from a file: a module that exports `module`, `version` and
+// `classes`, found again by its absolute path. A file that cannot be
+// imported, or exports no module, is none.
+export class ImportLoader extends Loader {
+  async load(from: string): Promise<Loaded | null> {
+    const path = resolve(from);
+    let exported: { module?: unknown; version?: unknown; classes?: unknown };
+    try {
+      exported = (await import(pathToFileURL(path).href)) as typeof exported;
+    } catch {
+      return null;
+    }
+    const { module, version, classes } = exported;
+    if (typeof module !== 'string' || typeof version !== 'string' || !Array.isArray(classes)) return null;
+    return { module, version, classes, from: path };
+  }
+}
+
+// The modules a harbor is handed, by name, and then files.
+export class NodeLoader extends ImportLoader {
+  readonly #held: HeldLoader;
+  constructor(modules: readonly Module[] = []) {
+    super();
+    this.#held = new HeldLoader(modules);
+  }
+  override async load(from: string): Promise<Loaded | null> {
+    return (await this.#held.load(from)) ?? super.load(from);
+  }
+}
+
+// One root request over a served harbor's socket, or undefined where none
+// is served.
+export const askServed = (dir: string, request: RootRequest): Promise<JsonObject | undefined> =>
+  new Promise((done, fail) => {
+    const socket = connect(socketOf(dir));
+    let text = '';
+    socket.once('connect', () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on('data', (chunk: Buffer) => {
+      text += chunk.toString('utf8');
+      const end = text.indexOf('\n');
+      if (end < 0) return;
+      socket.end();
+      done(JSON.parse(text.slice(0, end)) as JsonObject);
+    });
+    socket.once('error', (e: NodeJS.ErrnoException) => (e.code === 'ENOENT' || e.code === 'ECONNREFUSED' ? done(undefined) : fail(e)));
+  });
+
+export type NodeParts = {
+  readonly dir: string;
+  readonly modules?: readonly Module[];
+  // Whether its carriers wake, and whether it serves the root line.
+  readonly wakes?: boolean;
+  readonly serves?: boolean;
+};
+
+export class NodeTerrain extends PointerTerrain {
+  readonly dir: string;
+  readonly serves: boolean;
+  #server: Server | undefined;
+
+  constructor(parts: NodeParts) {
+    const entropy = new CryptoEntropy();
+    super({
+      entropy,
+      loader: new NodeLoader(parts.modules),
+      custody: new FolderCustody(parts.dir, entropy),
+      memory: new FolderMemory(parts.dir),
+      faculties: [tcpFaculty, webGround, webPush],
+      opens: [TCP_OPENING],
+      wakes: parts.wakes ?? true,
+    });
+    this.dir = parts.dir;
+    this.serves = parts.serves ?? true;
+  }
+
+  override async claim(): Promise<void> {
+    if ((await askServed(this.dir, {})) !== undefined) throw new Error(`a harbor is already served from ${this.dir}`);
+  }
+
+  // The root line on the socket. A socket file nobody answers on is a
+  // stale one, and is replaced.
+  override async stand(harbor: Harbor): Promise<void> {
+    if (!this.serves) return;
+    const root = socketOf(this.dir);
+    await rm(root, { force: true });
+    const server = createServer((socket) => {
+      let text = '';
+      socket.on('data', (chunk: Buffer) => {
+        text += chunk.toString('utf8');
+        for (let end = text.indexOf('\n'); end >= 0; end = text.indexOf('\n')) {
+          const line = text.slice(0, end);
+          text = text.slice(end + 1);
+          let value: unknown;
+          try {
+            value = JSON.parse(line);
+          } catch {
+            value = undefined;
+          }
+          void rootLine(harbor, value)
+            .catch(() => ({ error: 'the harbor threw' }))
+            .then((answer) => socket.write(`${JSON.stringify(answer)}\n`));
+        }
+      });
+      socket.on('error', () => socket.destroy());
+    });
+    await new Promise<void>((done) => server.listen(root, done));
+    await chmod(root, 0o600);
+    this.#server = server;
+  }
+
+  override async release(): Promise<void> {
+    const server = this.#server;
+    if (!server) return;
+    this.#server = undefined;
+    await new Promise((done) => server.close(done));
+    await rm(socketOf(this.dir), { force: true });
+  }
+}
+
+// Node, and the engines that answer as Node does.
+export const nodeGround: GroundProbe = {
+  name: NODE,
+  fits: () => typeof process !== 'undefined' && typeof process.versions?.node === 'string',
+  terrain: ({ modules, where }) => new NodeTerrain({ dir: where ?? harborDir(), ...(modules ? { modules } : {}) }),
+};

package/src/node.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur` as Node reads it: the main entry, with the Node ground added, so
+// `Harbor.open()` keeps a harbor in a folder and serves its root line.
+import { addGround } from './harbor/index.ts';
+import { nodeGround } from './node/index.ts';
+
+export * from './index.ts';
+
+addGround(nodeGround);

package/src/pointer/bodies.ts

@@ -53,6 +53,7 @@ export class VolatileMemory extends Memory {
     const entries = this.#places.get(place) ?? new Map<string, Uint8Array>();
     return Promise.resolve(new Map([...entries].map(([name, bytes]) => [name, bytes.slice()])));
   }
+  // One object holds it, so a keep is whole by the run of one turn.
   write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void> {
     let kept = this.#places.get(place);
     if (!kept) this.#places.set(place, (kept = new Map()));
@@ -60,6 +61,16 @@ export class VolatileMemory extends Memory {
       if (bytes === null) kept.delete(name);
       else kept.set(name, bytes.slice());
     }
+    if (kept.size === 0) this.#places.delete(place);
+    return Promise.resolve();
+  }
+
+  places(): Promise<string[]> {
+    return Promise.resolve([...this.#places.keys()]);
+  }
+
+  forget(place: string): Promise<void> {
+    this.#places.delete(place);
     return Promise.resolve();
   }
 }

package/src/pointer/world.ts

@@ -4,7 +4,7 @@
 // restart drops a harbor and opens a new one on the terrain the world
 // keeps for it, so only what its memory kept comes back.
 import { Carrier, type Clock, type Custody, type Entropy, type Loader, type Memory, type Module } from '../contract/index.ts';
-import { Harbor, Terrain } from '../harbor/index.ts';
+import { Harbor, Terrain, type GroundFaculty, type Opening } from '../harbor/index.ts';
 import { CryptoEntropy, HeldCustody, HeldLoader, SystemClock, VolatileMemory } from './bodies.ts';
 
 // A carrier that reaches no one: a harbor alone.
@@ -26,7 +26,17 @@ export class PointerCarrier extends Carrier {
   }
 }
 
-export type PointerParts = { entropy?: Entropy; clock?: Clock; custody?: Custody; memory?: Memory; carrier?: Carrier; loader?: Loader };
+export type PointerParts = {
+  entropy?: Entropy;
+  clock?: Clock;
+  custody?: Custody;
+  memory?: Memory;
+  carrier?: Carrier;
+  loader?: Loader;
+  faculties?: readonly GroundFaculty[];
+  opens?: readonly Opening[];
+  wakes?: boolean;
+};
 
 export class PointerTerrain extends Terrain {
   readonly entropy: Entropy;
@@ -35,6 +45,9 @@ export class PointerTerrain extends Terrain {
   readonly memory: Memory;
   readonly carrier: Carrier;
   readonly loader: Loader;
+  override readonly faculties: readonly GroundFaculty[];
+  override readonly opens: readonly Opening[];
+  override readonly wakes: boolean;
 
   constructor(parts: PointerParts = {}) {
     super();
@@ -44,6 +57,9 @@ export class PointerTerrain extends Terrain {
     this.memory = parts.memory ?? new VolatileMemory();
     this.carrier = parts.carrier ?? new NoCarrier();
     this.loader = parts.loader ?? new HeldLoader();
+    this.faculties = parts.faculties ?? [];
+    this.opens = parts.opens ?? [];
+    this.wakes = parts.wakes ?? true;
   }
 }
 

package/src/quo/address.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+// Addresses, as `SPEC.md` names them in an invitation's `at`: a URI of
+// RFC 3986 whose scheme, read in any case, names a carrier.
+// `CARRIER-TCP.md` writes `tcp://host:port`, and `CARRIER-WEB.md` writes
+// `http` and `https` for the post and `ws` and `wss` for the held line.
+
+// RFC 3986 appendix B, with the characters a URI may hold checked apart.
+const SPLIT = /^(?:([^:/?#]+):)?(?:\/\/([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?$/;
+const URI_CHARS = /^(?:[A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=]|%[0-9A-Fa-f]{2})*$/;
+const SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*$/;
+const REG_NAME = /^(?:[A-Za-z0-9\-._~!$&'()*+,;=]|%[0-9A-Fa-f]{2})*$/;
+const IP_LITERAL = /^\[(?:[0-9A-Fa-f:.]+|v[0-9A-Fa-f]+\.[A-Za-z0-9\-._~!$&'()*+,;=:]+)\]$/;
+
+type Parts = { scheme: string; authority: string | null; userinfo: string | null; host: string | null; port: string | null; path: string; query: string | null; fragment: string | null };
+
+// A URI with a scheme, taken apart, or null. `host` is as written,
+// brackets included, and `port` the digits as written.
+const parse = (s: unknown): Parts | null => {
+  if (typeof s !== 'string' || !URI_CHARS.test(s)) return null;
+  const m = SPLIT.exec(s);
+  if (!m || m[1] === undefined || !SCHEME.test(m[1])) return null;
+  const out: Parts = { scheme: m[1].toLowerCase(), authority: m[2] ?? null, userinfo: null, host: null, port: null, path: m[3] ?? '', query: m[4] ?? null, fragment: m[5] ?? null };
+  if (out.authority === null) return out;
+  let rest = out.authority;
+  const at = rest.lastIndexOf('@');
+  if (at >= 0) {
+    out.userinfo = rest.slice(0, at);
+    rest = rest.slice(at + 1);
+  }
+  const hp = /^(\[[^\]]*\]|[^:[\]]*)(?::([0-9]*))?$/.exec(rest);
+  if (!hp) return null;
+  const host = hp[1]!;
+  if (host.startsWith('[') ? !IP_LITERAL.test(host) : !REG_NAME.test(host)) return null;
+  out.host = host;
+  out.port = hp[2] ?? null;
+  return out;
+};
+
+// The host as a socket takes it: an IPv6 literal without its brackets.
+const bare = (host: string): string => (host.startsWith('[') ? host.slice(1, -1) : host);
+
+// The scheme an address names, lowercase, or null for what is no URI.
+export const schemeOf = (s: unknown): string | null => parse(s)?.scheme ?? null;
+
+export type TcpAddress = { host: string; port: number };
+
+// A `tcp` address as `CARRIER-TCP.md` writes one, or null.
+export const tcpAddress = (s: unknown): TcpAddress | null => {
+  const a = parse(s);
+  if (!a || a.scheme !== 'tcp' || a.authority === null) return null;
+  if (a.userinfo !== null || a.path !== '' || a.query !== null || a.fragment !== null) return null;
+  if (!a.host || a.port === null || !/^[0-9]+$/.test(a.port)) return null;
+  const port = Number(a.port);
+  if (port < 1 || port > 65_535) return null;
+  return { host: bare(a.host), port };
+};
+
+// The `tcp` address of a host and port.
+export const tcpAt = (host: string, port: number): string => `tcp://${host.includes(':') ? `[${host}]` : host}:${port}`;
+
+export type WebAddress = { scheme: 'http' | 'https' | 'ws' | 'wss'; secure: boolean; held: boolean; host: string; port: number; path: string; href: string };
+const WEB = new Set(['http', 'https', 'ws', 'wss']);
+
+// An address of `CARRIER-WEB.md`, or null. `path` is the path and query
+// a request names, `/` when both are empty.
+export const webAddress = (s: unknown): WebAddress | null => {
+  const a = parse(s);
+  if (!a || !WEB.has(a.scheme) || a.authority === null) return null;
+  if (a.userinfo !== null || a.fragment !== null || !a.host) return null;
+  if (a.port !== null && a.port !== '' && (!/^[0-9]+$/.test(a.port) || Number(a.port) > 65_535)) return null;
+  const scheme = a.scheme as WebAddress['scheme'];
+  const secure = scheme === 'https' || scheme === 'wss';
+  const port = a.port ? Number(a.port) : secure ? 443 : 80;
+  const path = `${a.path || '/'}${a.query !== null ? `?${a.query}` : ''}`;
+  return { scheme, secure, held: scheme === 'ws' || scheme === 'wss', host: bare(a.host), port, path, href: s as string };
+};
+
+// Whether a tcp or web address names the unspecified host, where a
+// listener binds every interface and no caller can dial.
+export const unspecified = (s: unknown): boolean => {
+  const host = (tcpAddress(s) ?? webAddress(s))?.host;
+  return host === '0.0.0.0' || host === '::';
+};
+
+// An invitation's `at` as `SPEC.md` reads it: the strings that are URIs
+// with a scheme, in their order. A value that is no array is absent.
+export const readAt = (value: unknown): string[] => (Array.isArray(value) ? value.filter((s): s is string => parse(s) !== null) : []);

package/src/quo/door.ts

@@ -43,12 +43,14 @@ export class Door {
 
   // A new heir, held fresh, and its invitation. The lock is drawn at the
   // first invitation that names an heir, before the heir's secret.
-  async invite(): Promise<{ heir: string; invitation: Invitation }> {
+  // A new heir, and its invitation, naming in `at` the addresses given.
+  async invite(at: readonly string[] = []): Promise<{ heir: string; invitation: Invitation }> {
     let lock = this.relations.lock();
     if (!lock) this.relations.setLock((lock = drawLock(this.draw)));
     const heir = await SigningKey.draw(this.draw);
     this.relations.set(heir.id, { state: 'fresh' });
-    return { heir: heir.id, invitation: { ward: this.key.pk, heir: heir.id, secret: hex(heir.secret), lock: hex(lock.ek) } };
+    const invitation = { ward: this.key.pk, heir: heir.id, secret: hex(heir.secret), lock: hex(lock.ek), ...(at.length > 0 ? { at: [...at] } : {}) };
+    return { heir: heir.id, invitation };
   }
 
   // The door stops holding an heir. A fresh one leaves nothing, a spent one

package/src/quo/index.ts

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Quo's wire: keys, the invitation, the payload, the reply, the boxes, the
 // door and the standing. It knows no being, no ward and no terrain.
+export { readAt, schemeOf, tcpAddress, tcpAt, unspecified, webAddress, type TcpAddress, type WebAddress } from './address.ts';
 export { Door, SPAN, type Behind, type Choice, type Judged } from './door.ts';
 export { readInvitation, type Invitation } from './invitation.ts';
 export { Ephemeral, SigningKey, WardKey, type Draw } from './keys.ts';

package/src/quo/invitation.ts

@@ -1,15 +1,19 @@
 // SPDX-License-Identifier: Apache-2.0
-// The invitation: `{ ward, heir, secret, lock }`, a value with no route.
+// The invitation: `{ ward, heir, secret, lock, at? }`. A door reads no
+// route from it; `at`, when present, names where the ward is reached.
 import { EK, encapsulate, isHex, unhex } from '../crypto/index.ts';
+import { readAt } from './address.ts';
 
-export type Invitation = { readonly ward: string; readonly heir: string; readonly secret: string; readonly lock: string };
+export type Invitation = { readonly ward: string; readonly heir: string; readonly secret: string; readonly lock: string; readonly at?: string[] };
 
-// An invitation, or null for any other shape. A field beside the four is
-// ignored, and the lock is held to the modulus check.
+// An invitation, or null for any other shape. A field beside the five is
+// ignored, the lock is held to the modulus check, and `at` keeps the
+// addresses it holds, an `at` with none or of another shape being absent.
 export const readInvitation = (value: unknown): Invitation | null => {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
-  const { ward, heir, secret, lock } = value as Record<string, unknown>;
+  const { ward, heir, secret, lock, at } = value as Record<string, unknown>;
   if (!isHex(ward, 64) || !isHex(heir, 32) || !isHex(secret, 32) || !isHex(lock, EK)) return null;
   if (encapsulate(unhex(lock), new Uint8Array(32)) === null) return null;
-  return { ward, heir, secret, lock };
+  const addresses = readAt(at);
+  return { ward, heir, secret, lock, ...(addresses.length > 0 ? { at: addresses } : {}) };
 };