@onlyne/node-host 0.0.0-stage → 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dbydd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @onlyne/node-host
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The host half that every Onlyne node shares: identity keys on disk, DNS-SD discovery, the
+gateway trust terminal, a bounded log ring, and the English/Simplified Chinese message
+catalogs.
+
+The library owns protocol state. This package owns the filesystem and terminal work that the
+library is not allowed to do.
+
+## Entry points
+
+| Export | Contents |
+|---|---|
+| `@onlyne/node-host` | `startNodeHost`, `GatewayTui`, `createLogger`, `NetworkDiscovery` |
+| `@onlyne/node-host/keys` | `createNodeKey`, `loadOrCreateKey`, `writeKeyMaterial`, `ensureKeyDir` |
+| `@onlyne/node-host/network` | DNS-SD publish and browse over `bonjour-service` |
+| `@onlyne/node-host/i18n` | `Locale`, `resolveLocale`, `getLocale`, `setLocale`, `createTranslator` |
+
+`startNodeHost` publishes the bound endpoint, browses for peers, re-observes the catalog every
+30 seconds, and on a terminal hands the operator the trust screen. Discovery only adds
+candidates: a key exchange still needs both fingerprints confirmed.
+
+`startNodeHost({ status })` accepts an async callback that returns gateway-specific display lines.
+The terminal refreshes these lines with its trust view once per second. Hosts use them for connection
+state, server tool counts, scheduled tasks, and delivery queues. `ONLYNE_NO_TUI=1` keeps JSON logging
+and skips terminal startup.
+
+## Log levels
+
+`createLogger` returns one callable line writer plus the other three levels: calling it, and
+`logger.log`, write `info`, so every existing host line keeps its level. `ONLYNE_LOG_LEVEL` selects
+the threshold, default `info`; a fourth argument overrides it for one process. Every level that
+passes goes to the ring the TUI renders and to the file sink, and each JSON line names its `level`.
+
+| Level | Meaning | Examples |
+|---|---|---|
+| `debug` | Per-pass work and protocol internals, off by default | reconcile pulls, replays, injected-context details |
+| `info` | State transitions and business milestones, one line each | `onlyne.tui.ready`, `connector.state`, a committed send |
+| `warn` | Degraded but running | reconnects, retries, an unconfirmed delivery, a rate-limit hit, a failed reconcile pull |
+| `error` | The operation failed and the caller lost something | a received event that could not be stored |
+
+A sink that is a plain function rather than a `createLogger` result records every line it is
+handed: it has no threshold of its own, so filtering belongs to the host that built it.
+
+## Language
+
+`resolveLocale` reads an explicit value first, then `ONLYNE_LANG`, then `LC_ALL` or `LANG`, and
+falls back to `en`. A module that renders text keeps its own `en` and `zh-CN` catalogs and calls
+`createTranslator`; the returned function reads the process locale on every call.
+
+## Runtime
+
+The package ships TypeScript source for Bun. It performs filesystem access, so it belongs to the
+host, never to `@onlyne/lib`.
+
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@onlyne/node-host",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.1.0",
+  "description": "Shared Onlyne node host pieces: identity keys, DNS-SD discovery, the gateway trust terminal, and message catalogs",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dbydd/onlyne.git",
+    "directory": "packages/node-host"
+  },
+  "homepage": "https://github.com/dbydd/onlyne#readme",
+  "bugs": "https://github.com/dbydd/onlyne/issues",
+  "keywords": ["onlyne", "agent", "discovery", "keys", "i18n"],
+  "publishConfig": { "access": "public" },
+  "engines": { "bun": ">=1.4.3" },
+  "exports": {
+    ".": "./src/index.ts",
+    "./keys": "./src/keys.ts",
+    "./network": "./src/network.ts",
+    "./i18n": "./src/i18n.ts"
+  },
+  "files": ["src", "README.md", "LICENSE"],
+  "scripts": { "check": "tsc --noEmit" },
+  "dependencies": {
+    "@onlyne/lib": "^3.1.0",
+    "bonjour-service": "^1.4.4"
+  },
+  "devDependencies": { "@types/bun": "^1.3.0", "typescript": "^5.9.0" }
+}

package/src/i18n.ts

@@ -0,0 +1,22 @@
+export type Locale = 'en' | 'zh-CN';
+export const LOCALES: readonly Locale[] = ['en', 'zh-CN'];
+
+export function parseLocale(value: string | null | undefined): Locale | undefined {
+  const language = value?.trim().toLowerCase().replace(/_/g, '-');
+  if (language === 'en' || language?.startsWith('en-') || language?.startsWith('en.')) return 'en';
+  if (language === 'zh' || language?.startsWith('zh-') || language?.startsWith('zh.')) return 'zh-CN';
+  return undefined;
+}
+
+export function resolveLocale(explicit?: string | null, env: Record<string, string | undefined> = process.env): Locale {
+  return parseLocale(explicit) ?? parseLocale(env.ONLYNE_LANG) ?? parseLocale(env.LC_ALL || env.LANG) ?? 'en';
+}
+
+let locale: Locale = resolveLocale();
+export function getLocale(): Locale { return locale; }
+export function setLocale(value: Locale): void { locale = value; }
+export type Catalog<K extends string> = Record<Locale, Record<K, string>>;
+
+export function createTranslator<K extends string>(catalog: Catalog<K>): (key: K, vars?: Record<string, string | number>) => string {
+  return (key, vars) => catalog[getLocale()][key].replace(/\{(\w+)\}/g, (match, name: string) => vars?.[name] === undefined ? match : String(vars[name]));
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+import type { OnlyneNode, ServiceDescription } from '@onlyne/lib';
+import { NetworkDiscovery } from './network.ts';
+import type { LogRing } from './log.ts';
+import { GatewayTui } from './tui.ts';
+
+export { createNodeKey } from './keys.ts';
+export { NetworkDiscovery } from './network.ts';
+export { createLogger, leveled, resolveLogLevel } from './log.ts';
+export type { GatewayLogger, LeveledLog, LogLevel, LogLine, LogRing, LogSink } from './log.ts';
+export { GatewayTui } from './tui.ts';
+
+export interface NodeHostOptions {
+  node: OnlyneNode;
+  endpoint: string;
+  bind: string;
+  seeds?: string[];
+  /** The log ring the TUI renders; the host's logger owns it. */
+  ring?: LogRing;
+  /** Defaults to the terminal surface when both ends of the process are a TTY. */
+  interactive?: boolean;
+  /** Gateway-specific state rendered with the trust terminal. */
+  status?: () => Promise<string[]>;
+  log(message: string, fields?: Record<string, unknown>): void;
+}
+
+/**
+ * The host half every gateway shares: publish the bound endpoint over DNS-SD, browse for
+ * peers, re-observe the catalog, and — on a terminal — hand the operator the trust surface.
+ * Discovery only adds candidates; a key exchange still needs both fingerprints confirmed.
+ */
+export async function startNodeHost(options: NodeHostOptions): Promise<{ close(): Promise<void> }> {
+  const { node, log } = options;
+  const controller = new AbortController();
+  const response = await node.fetch(new Request(`${options.endpoint}/description`));
+  const description = await response.json() as ServiceDescription;
+  const network = new NetworkDiscovery({
+    node_id: node.auth.actor, instance_id: description.instance_id, endpoint: options.endpoint, bind: options.bind,
+    onCandidate: async (url, source, expectedNode) => {
+      if (expectedNode === node.auth.actor) return;
+      await node.discovery.observe(url, source, expectedNode, controller.signal);
+    },
+    onError: error => log('onlyne.discovery.failed', { error: String(error) }),
+  });
+  try { await network.start(); }
+  catch (error) { log('onlyne.discovery.unavailable', { error: String(error) }); }
+  for (const seed of options.seeds ?? []) {
+    try { await node.discovery.observe(seed, 'bootstrap', undefined, controller.signal); }
+    catch (error) { log('onlyne.discovery.failed', { seed, error: String(error) }); }
+  }
+  let refreshing = false;
+  const timer = setInterval(() => {
+    if (refreshing) return;
+    refreshing = true;
+    void node.discovery.refresh(controller.signal)
+      .catch(error => { if (!controller.signal.aborted) log('onlyne.discovery.failed', { error: String(error) }); })
+      .finally(() => { refreshing = false; });
+  }, 30_000);
+
+  let tui: GatewayTui | undefined;
+  // `ONLYNE_NO_TUI=1` keeps the plain JSON log on stdout, for a pipe or a screen a TUI would spoil.
+  const interactive = (options.interactive ?? true) && process.env.ONLYNE_NO_TUI !== '1';
+  if (interactive && options.ring !== undefined && process.stdin.isTTY && process.stdout.isTTY) {
+    const surface = new GatewayTui(node, options.ring, options.endpoint, undefined, options.status);
+    try {
+      log('onlyne.tui.starting');
+      await surface.start();
+      tui = surface;
+      log('onlyne.tui.ready');
+    } catch (error) {
+      log('onlyne.tui.unavailable', { error: String(error) });
+    }
+  }
+
+  return {
+    async close(): Promise<void> {
+      clearInterval(timer);
+      await tui?.close();
+      controller.abort();
+      await network.close();
+    },
+  };
+}

package/src/keys.ts

@@ -0,0 +1,158 @@
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import type { KeyHook, KeyMaterial } from "@onlyne/lib";
+import { execFile } from "node:child_process";
+import { generateKeyMaterial } from "@onlyne/lib";
+
+/** RFC 0017 §2: the private key rides in its own file as base64 DER; the public half is derived on load. */
+const PRIVATE_NAME = "priv.pem";
+const PUBLIC_NAME = "pub.key";
+
+function projectKeysRoot(cwd: string): string {
+	return join(cwd, ".onlyne", "keys");
+}
+
+function globalKeysRoot(): string {
+	return join(homedir(), ".config", "onlyne", "keys");
+}
+
+function encodePrivate(material: KeyMaterial): string {
+	return Buffer.from(material.private_key).toString("base64");
+}
+
+function decodePrivate(text: string): Uint8Array {
+	return new Uint8Array(Buffer.from(text, "base64"));
+}
+
+/** Refuses group/world-readable private keys and symlinked or foreign-owned files. */
+function assertPrivatePermissions(path: string): void {
+	const stats = statSync(path, { throwIfNoEntry: false });
+	if (stats === undefined) return;
+	if (stats.isSymbolicLink()) throw new Error(`The node key must not be a symlink: ${path}`);
+	if ((stats.mode & 0o077) !== 0) {
+		throw new Error(`The node key is readable beyond its owner. Fix it with: chmod 600 ${path}`);
+	}
+}
+
+async function assertDirectoryPermissions(path: string): Promise<void> {
+	const stats = await statSync(path, { throwIfNoEntry: false });
+	if (stats === undefined || (stats.mode & 0o077) !== 0) {
+		throw new Error(`The key directory is readable beyond its owner. Fix it with: chmod 700 ${path}`);
+	}
+}
+
+/** The node id names a subdirectory; a traversal-looking id is a configuration error. */
+function keyDirectory(root: string, nodeId: string): string {
+	if (nodeId.includes("/") || nodeId.includes("\\") || nodeId.includes("..")) {
+		throw new Error(`The node id cannot name a key directory: ${nodeId}`);
+	}
+	return join(root, encodeURIComponent(nodeId));
+}
+
+/**
+ * The git check is `git check-ignore --quiet`, the real semantics: an ancestor ignore,
+ * a negation rule, or a .git/info/exclude all read the same way the user's git does.
+ */
+function ignoredByGit(root: string, target: string): Promise<boolean> {
+	return new Promise(resolve => {
+		// `cwd` is the project root: the key directory does not exist yet on a first run.
+		execFile("git", ["check-ignore", "--quiet", "--", target], { cwd: root }, error => {
+			// Exit 0 = ignored, exit 1 = tracked-or-untracked but not ignored, other = outside a work tree.
+			resolve(error === null || (typeof (error as { code?: number }).code === "number" && (error as { code?: number }).code === 0));
+		});
+	});
+}
+
+async function insideGitWorkTree(path: string): Promise<boolean> {
+	return new Promise(resolve => {
+		execFile("git", ["rev-parse", "--is-inside-work-tree"], { cwd: path }, (error, stdout) => {
+			resolve(error === null && stdout.trim() === "true");
+		});
+	});
+}
+
+/**
+ * Resolves the key directory for a node (RFC 0017 §2). A project key inside a git work
+ * tree whose ignore rules do not cover `.onlyne/keys` is refused, with both escapes named.
+ */
+export async function ensureKeyDir(cwd: string, nodeId: string, scope: "project" | "global"): Promise<string> {
+	// The global directory holds the node's identity by default; a project directory is an
+	// override for this working tree, read first when both exist.
+	const root = scope === "project" ? projectKeysRoot(cwd) : globalKeysRoot();
+	const dir = keyDirectory(root, nodeId);
+	if (scope === "global") {
+		await mkdir(dir, { recursive: true });
+		await chmod(dir, 0o700);
+		return dir;
+	}
+	if (await insideGitWorkTree(cwd) && !(await ignoredByGit(cwd, dir)) && !(await ignoredByGit(cwd, projectKeysRoot(cwd)))) {
+		throw new Error(
+			"Refusing to create a node key inside a git work tree: .onlyne/keys is not ignored. "
+			+ "Add '.onlyne/keys' to .gitignore, or set node.key_scope = \"global\" in the config.",
+		);
+	}
+	await mkdir(dir, { recursive: true });
+	await chmod(dir, 0o700);
+	return dir;
+}
+
+/** Loads the node's identity key, generating it on first use. */
+export async function loadOrCreateKey(dir: string, nodeId: string): Promise<KeyMaterial> {
+	await assertDirectoryPermissions(dir);
+	const privatePath = join(dir, PRIVATE_NAME);
+	if (!existsSync(privatePath)) {
+		const material = generateKeyMaterial();
+		await writeKeyMaterial(dir, material);
+		return material;
+	}
+	assertPrivatePermissions(privatePath);
+	const base: { private_key: Uint8Array; public_key: Uint8Array } = {
+		private_key: decodePrivate((await readFile(privatePath, "utf8")).trim()),
+		public_key: new Uint8Array(),
+	};
+	// The public half always comes from the private key: the file is a cache, never a source.
+	const { createPrivateKey, createPublicKey } = await import("node:crypto");
+	const pair = createPrivateKey({ key: Buffer.from(base.private_key), format: "der", type: "pkcs8" });
+	const jwk = createPublicKey(pair).export({ format: "jwk" });
+	return { private_key: base.private_key, public_key: new Uint8Array(Buffer.from(String(jwk.x), "base64url")) };
+}
+
+/**
+ * Writes the key pair atomically. `replace` is the `plugins.keys.replace` path — the only
+ * caller allowed to overwrite an existing private key, because `trust.rotate` has already
+ * committed the rotation window and must complete the swap.
+ */
+export async function writeKeyMaterial(dir: string, material: KeyMaterial, options: { replace?: boolean } = {}): Promise<void> {
+	const privatePath = join(dir, PRIVATE_NAME);
+	if (existsSync(privatePath) && options.replace !== true) throw new Error(`A node key already exists at ${privatePath}; use trust rotation instead of overwriting it.`);
+	const publicPath = join(dir, PUBLIC_NAME);
+	const stagingPrivate = join(dir, `.${basename(PRIVATE_NAME)}.${process.pid}.tmp`);
+	const stagingPublic = join(dir, `.${basename(PUBLIC_NAME)}.${process.pid}.tmp`);
+	// Every fallible step runs before the private key is renamed: a replace that throws must
+	// leave the old key usable, or the rotation proof for peers pinning it is gone for good.
+	await writeFile(stagingPrivate, encodePrivate(material), { mode: 0o600 });
+	await chmod(stagingPrivate, 0o600);
+	await writeFile(stagingPublic, Buffer.from(material.public_key).toString("base64"), { mode: 0o644 });
+	await chmod(stagingPublic, 0o644);
+	// The public file is a cache derived from the private key, so it may be replaced first.
+	await rename(stagingPublic, publicPath);
+	await rename(stagingPrivate, privatePath);
+}
+
+/** Synchronous guard for the startup path: the existing key must already be private. */
+export function assertKeyPermissions(dir: string): void {
+	assertPrivatePermissions(join(dir, PRIVATE_NAME));
+	void chmod;
+	void chmodSync;
+	void mkdirSync;
+	void readFileSync;
+}
+
+export async function createNodeKey(nodeId: string): Promise<KeyHook> {
+	const dir = await ensureKeyDir(process.cwd(), nodeId, "global");
+	return Object.assign(() => loadOrCreateKey(dir, nodeId), {
+		replace: (material: KeyMaterial) => writeKeyMaterial(dir, material, { replace: true }),
+	});
+}

package/src/log.ts

@@ -0,0 +1,103 @@
+import { appendFileSync } from 'node:fs';
+
+/** A bounded tail of the gateway's own log lines, so the TUI can show them. */
+export interface LogRing {
+  push(key: string, line: string): void;
+  tail(count: number): string[];
+}
+
+/** The four levels of the convention: `debug` loops, `info` milestones, `warn` degradation, `error` loss. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/** One JSON line about to be written. */
+export type LogLine = (message: string, fields?: Record<string, unknown>) => void;
+
+/**
+ * A host's log sink. Calling it writes `info`, the level every existing call site uses; a sink
+ * that also carries `debug`/`warn`/`error` records those levels where the host put them.
+ */
+export type LogSink = LogLine & {
+  readonly debug?: LogLine;
+  readonly warn?: LogLine;
+  readonly error?: LogLine;
+};
+
+export type LeveledLog = LogLine & {
+  log: LogLine;
+  debug: LogLine;
+  warn: LogLine;
+  error: LogLine;
+};
+
+export type GatewayLogger = LeveledLog & { readonly level: LogLevel; readonly ring: LogRing };
+
+const ORDER: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+
+/** `ONLYNE_LOG_LEVEL` selects a level; anything unrecognised (and unset) keeps `info`. */
+export function resolveLogLevel(value: string | undefined): LogLevel {
+  return value === 'debug' || value === 'warn' || value === 'error' ? value : 'info';
+}
+
+/**
+ * Normalizes a sink to the four entry points. A sink without level methods records every line
+ * it is handed: it cannot filter, so the host's own store decides what the level means.
+ */
+export function leveled(sink?: LogSink): LeveledLog {
+  const call: LogLine = (message, fields) => { if (typeof sink === 'function') sink(message, fields); };
+  return Object.assign(call, {
+    log: call,
+    debug: sink?.debug ?? call,
+    warn: sink?.warn ?? call,
+    error: sink?.error ?? call,
+  });
+}
+
+/**
+ * The gateway logs JSON lines. Under the TUI those lines would corrupt the alternate
+ * screen, so they go to a ring the TUI renders instead; without a TTY they stay on stdout.
+ * The returned function is the `info` line — `logger.log` is the same entry point — and
+ * `debug`, `warn`, `error` are the other levels of the same convention.
+ */
+export function createLogger(toStdout: boolean, capacity = 200, file?: string, level?: LogLevel): GatewayLogger {
+  const selected = level ?? resolveLogLevel(process.env.ONLYNE_LOG_LEVEL);
+  const threshold = ORDER[selected];
+  // One entry per distinct message: a gateway that retries every five seconds would otherwise
+  // fill the pane with the same line and hide everything else.
+  const lines: Array<{ key: string; line: string; count: number }> = [];
+  const ring: LogRing = {
+    push(key: string, line: string): void {
+      const last = lines.at(-1);
+      if (last !== undefined && last.key === key) {
+        last.line = line;
+        last.count += 1;
+        return;
+      }
+      lines.push({ key, line, count: 1 });
+      if (lines.length > capacity) lines.splice(0, lines.length - capacity);
+    },
+    tail(count: number): string[] {
+      return lines.slice(Math.max(0, lines.length - count))
+        .map(entry => (entry.count === 1 ? entry.line : `${entry.line} ×${entry.count}`));
+    },
+  };
+  const emit = (at: LogLevel, message: string, fields?: Record<string, unknown>): void => {
+    if (ORDER[at] < threshold) return;
+    const line = JSON.stringify({ at: new Date().toISOString(), level: at, message, ...fields });
+    if (toStdout) console.log(line);
+    else ring.push(`${at}|${message}|${JSON.stringify(fields ?? {})}`, line);
+    // The TUI owns the screen, so the durable record is the file; without one the line would
+    // exist only in the ring and vanish with the process.
+    if (file !== undefined) {
+      try { appendFileSync(file, `${line}\n`); } catch { /* a full disk must not stop the gateway */ }
+    }
+  };
+  const info: LogLine = (message, fields) => emit('info', message, fields);
+  return Object.assign(info, {
+    level: selected,
+    log: info,
+    debug: (message: string, fields?: Record<string, unknown>) => emit('debug', message, fields),
+    warn: (message: string, fields?: Record<string, unknown>) => emit('warn', message, fields),
+    error: (message: string, fields?: Record<string, unknown>) => emit('error', message, fields),
+    ring,
+  });
+}

package/src/network.ts

@@ -0,0 +1,382 @@
+import { networkInterfaces } from "node:os";
+
+/** DNS-SD types used by the host adapter. */
+interface BonjourService {
+	fqdn: string;
+	name: string;
+	port: number;
+	host?: string;
+	addresses?: string[];
+	txt: unknown;
+	referer?: { address?: string };
+	records(): Array<{ type: string }>;
+}
+interface BonjourBrowser {
+	on(event: "up" | "srv-update" | "txt-update" | "down", listener: (service: BonjourService) => void): void;
+	stop(): void;
+}
+interface BonjourInstance {
+	find(options: { type: string; protocol: string }): BonjourBrowser;
+	publish(options: { name: string; type: string; protocol: string; port: number; host: string; probe: boolean; txt: Record<string, string> }): BonjourService;
+	unpublishAll(callback: () => void): void;
+	destroy(callback: () => void): void;
+}
+type BonjourConstructor = new (options: object, error: (error: unknown) => void) => BonjourInstance;
+
+/** RFC 0011 §5.1: the one service type every HTTP binding publishes. */
+const SERVICE_TYPE = "onlyne";
+const SERVICE_PROTOCOL = "tcp";
+const WIRE_PROTOCOL = "onlyne/3";
+const SERVICE_PATH_SUFFIX = "/onlyne/v3";
+const SOURCE = "mdns";
+
+export interface NetworkDiscoveryOptions {
+	node_id: string;
+	/** Identifies this process instance in the service name and TXT record. */
+	instance_id: string;
+	/** Absolute URL the node is listening on; its port is the allocated one. */
+	endpoint: string;
+	/** Local listener address; a wildcard binding advertises a concrete interface. */
+	bind: string;
+	/** `expectedNode` is the identity the advertisement claims, not a verified fact. */
+	onCandidate(url: string, source: string, expectedNode?: string): Promise<void>;
+	onError(error: unknown): void;
+	/** A candidate that was delivered earlier is no longer advertised. */
+	onUnavailable?(url: string): void;
+}
+
+/**
+ * Same-link discovery over DNS-SD/mDNS: publishes `_onlyne._tcp.local` and
+ * offers every advertisement to the library, which owns identity resolution
+ * and membership. The browser keeps other regions' candidates; only the
+ * HTTP declaration decides region.
+ */
+export class NetworkDiscovery {
+	readonly #options: NetworkDiscoveryOptions;
+	#bonjour: BonjourInstance | undefined;
+	#browser: BonjourBrowser | undefined;
+	#service: BonjourService | undefined;
+	#started = false;
+	#closed: Promise<void> | undefined;
+	#closing = false;
+	/** Deliveries in flight, keyed by URL, so repeated advertisements run once. */
+	#inflight = new Map<string, Promise<boolean>>();
+	/** Delivered URL per service fqdn; a change or a goodbye withdraws the old one. */
+	#delivered = new Map<string, string>();
+
+	constructor(options: NetworkDiscoveryOptions) {
+		this.#options = options;
+	}
+
+	async start(): Promise<void> {
+		if (this.#started) return;
+		this.#closed = undefined;
+		this.#closing = false;
+		const publication = plan(this.#options);
+		let module: { default?: BonjourConstructor } | BonjourConstructor;
+		try {
+			module = await import("bonjour-service") as unknown as { default?: BonjourConstructor } | BonjourConstructor;
+		} catch {
+			throw new Error("DNS-SD discovery is unavailable. Check the bonjour-service installation.");
+		}
+		const Constructor = typeof module === "function" ? module : module.default;
+		if (Constructor === undefined) throw new Error("bonjour-service does not export a constructor.");
+		const bonjour = new Constructor({}, (error: unknown) => this.#fail(error));
+		try {
+			const browser = bonjour.find({ type: SERVICE_TYPE, protocol: SERVICE_PROTOCOL });
+			browser.on("up", service => this.#consider(service));
+			browser.on("srv-update", service => this.#consider(service));
+			browser.on("txt-update", service => this.#consider(service));
+			browser.on("down", service => this.#withdraw(service));
+			this.#bonjour = bonjour;
+			this.#browser = browser;
+
+			// A probe keeps the first `records()` call asynchronous, which is what lets
+			// the loopback filter below take effect before the announcement is sent.
+			const service = bonjour.publish({
+				name: publication.name,
+				type: SERVICE_TYPE,
+				protocol: SERVICE_PROTOCOL,
+				port: publication.port,
+				host: publication.host,
+				probe: true,
+				txt: publication.txt,
+			});
+			if (isLoopback(publication.host)) {
+				// bonjour-service attaches every interface address to the SRV target. A
+				// loopback binding is reachable only from this host, so publishing those
+				// addresses (none of them loopback) would advertise a dead endpoint.
+				const records = service.records.bind(service);
+				service.records = () => records().filter(record => record.type !== "A" && record.type !== "AAAA");
+			}
+			this.#service = service;
+			this.#started = true;
+		} catch (error) {
+			bonjour.destroy(() => undefined);
+			throw error;
+		}
+	}
+
+	async close(): Promise<void> {
+		if (this.#closed !== undefined) return this.#closed;
+		const bonjour = this.#bonjour;
+		this.#closing = true;
+		this.#started = false;
+		this.#browser?.stop();
+		this.#browser = undefined;
+		this.#service = undefined;
+		this.#bonjour = undefined;
+		this.#inflight.clear();
+		this.#delivered.clear();
+		if (bonjour === undefined) {
+			this.#closed = Promise.resolve();
+			return this.#closed;
+		}
+		this.#closed = new Promise<void>(resolve => {
+			bonjour.unpublishAll(() => bonjour.destroy(() => resolve()));
+		});
+		return this.#closed;
+	}
+
+	#consider(service: BonjourService): void {
+		if (this.#closing) return;
+		if (service.fqdn === this.#service?.fqdn) return;
+		const txt = text(service);
+		const node = txt["node_id"];
+		const instance = txt["instance_id"];
+		if (node === this.#options.node_id && instance === this.#options.instance_id) return;
+
+		const protocol = txt["protocol"];
+		if (protocol !== WIRE_PROTOCOL) {
+			this.#fail(new Error(`Service ${service.name} does not speak ${WIRE_PROTOCOL}.`));
+			return;
+		}
+		if (node === undefined || instance === undefined) {
+			this.#fail(new Error(`Service ${service.name} is missing its node_id or instance_id.`));
+			return;
+		}
+		const scheme = txt["scheme"];
+		if (scheme !== "http" && scheme !== "https") {
+			this.#fail(new Error(`Service ${service.name} advertises scheme ${scheme ?? "(missing)"}.`));
+			return;
+		}
+		const path = txt["path"];
+		if (path === undefined || !normalizePath(path).endsWith(SERVICE_PATH_SUFFIX)) {
+			this.#fail(new Error(`Service ${service.name} does not advertise a ${SERVICE_PATH_SUFFIX} path.`));
+			return;
+		}
+		if (!Number.isInteger(service.port) || service.port < 1 || service.port > 65_535) {
+			this.#fail(new Error(`Service ${service.name} advertises port ${String(service.port)}.`));
+			return;
+		}
+
+		const host = candidateHost(service);
+		if (host === undefined) {
+			this.#fail(new Error(`Service ${service.name} advertises no address reachable from this host.`));
+			return;
+		}
+		if (!isLoopback(host) && scheme !== "https") {
+			this.#fail(new Error(`Service ${service.name} advertises plain HTTP across hosts; Onlyne requires HTTPS there.`));
+			return;
+		}
+
+		const url = `${scheme}://${host.includes(":") ? `[${host}]` : host}:${String(service.port)}${normalizePath(path)}`;
+		const previous = this.#delivered.get(service.fqdn);
+		if (previous === url) return;
+		if (previous !== undefined) {
+			this.#delivered.delete(service.fqdn);
+			this.#options.onUnavailable?.(previous);
+		}
+		void this.#deliver(service.fqdn, url, node);
+	}
+
+	#deliver(fqdn: string, url: string, expectedNode: string): Promise<boolean> {
+		const running = this.#inflight.get(url);
+		if (running !== undefined) return running;
+		const attempt = this.#options
+			.onCandidate(url, SOURCE, expectedNode)
+			.then(() => true)
+			.catch((error: unknown) => {
+				this.#fail(error);
+				return false;
+			});
+		const tracked = attempt.finally(() => {
+			if (this.#inflight.get(url) === tracked) this.#inflight.delete(url);
+		});
+		tracked.then(delivered => {
+			if (delivered && !this.#closing && !this.#delivered.has(fqdn)) this.#delivered.set(fqdn, url);
+		});
+		this.#inflight.set(url, tracked);
+		return tracked;
+	}
+
+	#withdraw(service: BonjourService): void {
+		const url = this.#delivered.get(service.fqdn);
+		if (url === undefined) return;
+		this.#delivered.delete(service.fqdn);
+		this.#options.onUnavailable?.(url);
+	}
+
+	#fail(error: unknown): void {
+		if (this.#closing) return;
+		try {
+			this.#options.onError(error);
+		} catch {
+			// The error sink is the end of the chain; a throwing sink must not kill the mDNS loop.
+		}
+	}
+}
+
+interface Publication {
+	name: string;
+	host: string;
+	port: number;
+	txt: Record<string, string>;
+}
+
+/** Validate everything the advertisement needs before the socket exists. */
+function plan(options: NetworkDiscoveryOptions): Publication {
+	if (options.node_id.length === 0) throw new Error("Onlyne discovery needs a node id.");
+	if (options.instance_id.length === 0) throw new Error("Onlyne discovery needs an instance id.");
+	let endpoint: URL;
+	try {
+		endpoint = new URL(options.endpoint);
+	} catch {
+		throw new Error(`The Onlyne endpoint must be an absolute URL, got ${options.endpoint}.`);
+	}
+	if (endpoint.protocol !== "http:" && endpoint.protocol !== "https:") {
+		throw new Error(`The Onlyne endpoint must use http or https, got ${endpoint.protocol}.`);
+	}
+	const scheme = endpoint.protocol.slice(0, -1);
+	const path = servicePath(endpoint.pathname);
+	const port = endpoint.port === "" ? (scheme === "https" ? 443 : 80) : Number(endpoint.port);
+	if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+		throw new Error(`The Onlyne endpoint must name the listening port, got ${options.endpoint}.`);
+	}
+	const advertised = normalizeHost(endpoint.hostname);
+	if (advertised === undefined) throw new Error(`The Onlyne endpoint has no host, got ${options.endpoint}.`);
+	// A wildcard binding is not a connectable address; publish the interface it
+	// listens on instead, and never the wildcard itself.
+	const host = isWildcard(advertised) ? interfaceAddress(options.bind) : advertised;
+	return {
+		name: options.instance_id,
+		host,
+		port,
+		txt: {
+			protocol: WIRE_PROTOCOL,
+			path,
+			scheme,
+			node_id: options.node_id,
+			instance_id: options.instance_id,
+		},
+	};
+}
+
+/** The advertised address of a wildcard binding: its bind when concrete, else a live interface. */
+function interfaceAddress(bind: string): string {
+	const concrete = normalizeHost(bind);
+	if (concrete !== undefined && !isWildcard(concrete)) return concrete;
+	const ipv4: string[] = [];
+	const ipv6: string[] = [];
+	for (const entries of Object.values(networkInterfaces())) {
+		for (const entry of entries ?? []) {
+			if (entry.internal) continue;
+			const address = normalizeAddress(entry.address);
+			if (address === undefined || address.startsWith("fe80:") || address.startsWith("169.254.")) continue;
+			(address.includes(":") ? ipv6 : ipv4).push(address);
+		}
+	}
+	const chosen = ipv4[0] ?? ipv6[0];
+	if (chosen === undefined) {
+		throw new Error("No interface address can be advertised; set server.bind to a concrete address.");
+	}
+	return chosen;
+}
+
+/**
+ * The address this host can use to reach the advertised service. Addresses that
+ * this host already owns are only applicable when the packet came from this
+ * host: a remote service cannot own them, and a remote loopback is unreachable.
+ */
+function candidateHost(service: BonjourService): string | undefined {
+	const local = localAddresses();
+	const referer = normalizeHost(service.referer?.address);
+	const originLocal = referer !== undefined && (isLoopback(referer) || local.has(referer));
+	for (const raw of service.addresses ?? []) {
+		const address = normalizeAddress(raw);
+		if (address === undefined || isWildcard(address)) continue;
+		if (address.startsWith("fe80:") || address.startsWith("169.254.")) continue;
+		if (address.startsWith("ff") || /^(22[4-9]|23\d)\./.test(address)) continue;
+		if (isLoopback(address)) {
+			if (originLocal) return address;
+			continue;
+		}
+		if (local.has(address) && !originLocal) continue;
+		return address;
+	}
+	const target = normalizeHost(service.host);
+	if (target === undefined || isWildcard(target)) return undefined;
+	if (isLoopback(target)) return originLocal ? target : undefined;
+	return target;
+}
+
+function localAddresses(): Set<string> {
+	const hosts = new Set<string>(["127.0.0.1", "::1", "localhost"]);
+	for (const entries of Object.values(networkInterfaces())) {
+		for (const entry of entries ?? []) {
+			const address = normalizeAddress(entry.address);
+			if (address !== undefined) hosts.add(address);
+		}
+	}
+	return hosts;
+}
+
+function text(service: BonjourService): Record<string, string> {
+	const fields: Record<string, string> = {};
+	const raw: unknown = service.txt;
+	if (raw === null || typeof raw !== "object") return fields;
+	for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+		if (typeof value === "string") fields[key] = value;
+		else if (Array.isArray(value) && typeof value[0] === "string") fields[key] = value[0];
+	}
+	return fields;
+}
+
+function servicePath(pathname: string): string {
+	const path = normalizePath(pathname);
+	if (!path.endsWith(SERVICE_PATH_SUFFIX)) {
+		throw new Error(`The Onlyne endpoint path must end with ${SERVICE_PATH_SUFFIX}, got ${pathname}.`);
+	}
+	return path;
+}
+
+function normalizePath(pathname: string): string {
+	const absolute = pathname.startsWith("/") ? pathname : `/${pathname}`;
+	const trimmed = absolute.replace(/\/+$/, "");
+	return trimmed === "" ? "/" : trimmed;
+}
+
+function normalizeAddress(value: string): string | undefined {
+	let address = value.trim();
+	if (address.startsWith("[") && address.endsWith("]")) address = address.slice(1, -1);
+	const zone = address.indexOf("%");
+	if (zone >= 0) address = address.slice(0, zone);
+	return address.length === 0 ? undefined : address.toLowerCase();
+}
+
+function normalizeHost(value: string | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	const host = normalizeAddress(value);
+	if (host === undefined) return undefined;
+	return host.endsWith(".") ? host.slice(0, -1) : host;
+}
+
+function isLoopback(host: string): boolean {
+	return host === "localhost" || host.endsWith(".localhost") || host === "::1"
+		|| host === "0:0:0:0:0:0:0:1" || host.startsWith("127.");
+}
+
+function isWildcard(host: string): boolean {
+	return host === "0.0.0.0" || host === "::" || host === "0:0:0:0:0:0:0:0";
+}
+

package/src/tui-text.ts

@@ -0,0 +1,73 @@
+import { createTranslator } from './i18n.ts';
+
+const en = {
+  'title': 'Onlyne gateway · {actor} · {endpoint}',
+  'peers.none': 'No nodes discovered yet.',
+  'peers.count': 'Nodes ({count})',
+  'column.delivery': 'deliver',
+  'hint.idle': 'Press [c] to enter an address, or wait for a peer to appear over mDNS.',
+  'label.fingerprint': 'fingerprint',
+  'label.endpoint': 'endpoint',
+  'label.delivery': 'delivery',
+  'value.notExchanged': 'not exchanged',
+  'value.unknown': 'unknown',
+  'confirm.title': 'Confirm the fingerprint of {node}?',
+  'confirm.keys': '  [y] confirm   [n] cancel',
+  'input.prompt': 'address> {value}▏',
+  'help.keys': '[t] request exchange  [a] accept request  [r] revoke  [c] connect address  [q] quit',
+  'notice.cancelled': 'Cancelled.',
+  'notice.enterAddress': 'Enter a node service address, then press Enter to connect; Esc cancels.',
+  'notice.refreshFailed': 'Refresh failed: {error}',
+  'notice.alreadyExchanged': '{node} has already exchanged keys.',
+  'notice.noRequest': '{node} has no request waiting for your confirmation.',
+  'notice.accepted': 'Approved the key of {node}.',
+  'notice.noTrust': '{node} has no trust record.',
+  'notice.revoked': 'Revoked trust for {node}.',
+  'notice.noAddress': 'No address entered.',
+  'notice.connected': 'Connected to {node}.',
+  'notice.submitted': '{node} submitted, current stage {phase}.',
+  'notice.operationFailed': 'Operation failed: {error}',
+  'phase.exchanged': 'verified',
+  'phase.requested': 'awaiting peer',
+  'phase.invited': 'needs approval',
+  'phase.revoked': 'revoked',
+  'list.separator': ', ',
+} as const;
+
+const zh: Record<keyof typeof en, string> = {
+  'title': 'Onlyne 网关 · {actor} · {endpoint}',
+  'peers.none': '还没有发现任何节点。',
+  'peers.count': '节点 ({count})',
+  'column.delivery': '投送',
+  'hint.idle': '用 [c] 输入一个地址，或用 mDNS 等对端出现。',
+  'label.fingerprint': '指纹',
+  'label.endpoint': '端点',
+  'label.delivery': '投送',
+  'value.notExchanged': '未交换',
+  'value.unknown': '未知',
+  'confirm.title': '确认 {node} 的指纹？',
+  'confirm.keys': '  [y] 确认   [n] 取消',
+  'input.prompt': '地址> {value}▏',
+  'help.keys': '[t] 请求交换  [a] 接受申请  [r] 撤销  [c] 连接地址  [q] 退出界面',
+  'notice.cancelled': '已取消。',
+  'notice.enterAddress': '输入节点服务地址，回车连接，Esc 取消。',
+  'notice.refreshFailed': '刷新失败：{error}',
+  'notice.alreadyExchanged': '{node} 已经完成交换。',
+  'notice.noRequest': '{node} 没有等待你确认的申请。',
+  'notice.accepted': '已批准 {node} 的密钥。',
+  'notice.noTrust': '{node} 没有信任记录。',
+  'notice.revoked': '已撤销 {node} 的信任。',
+  'notice.noAddress': '没有输入地址。',
+  'notice.connected': '已连接 {node}。',
+  'notice.submitted': '{node} 已提交，当前阶段 {phase}。',
+  'notice.operationFailed': '操作失败：{error}',
+  'phase.exchanged': '已认证',
+  'phase.requested': '等对方',
+  'phase.invited': '待确认',
+  'phase.revoked': '已撤销',
+  'list.separator': '、',
+};
+
+export type TuiTextKey = keyof typeof en;
+
+export const t = createTranslator({ en, 'zh-CN': zh });

package/src/tui.ts

@@ -0,0 +1,329 @@
+import { trustPhase, type KeyExchange, type OnlyneNode, type TrustPhase } from '@onlyne/lib';
+import type { LogRing } from './log.ts';
+import { t, type TuiTextKey } from './tui-text.ts';
+
+/** One peer as the terminal shows it: a discovery address plus whatever the trust table knows. */
+interface Row {
+  node: string;
+  endpoint?: string;
+  phase?: TrustPhase;
+  fingerprint?: string;
+  /** Resources this gateway serves whose binding points at this node: where events go now. */
+  delivery?: string[];
+}
+
+const PHASE_KEY: Record<TrustPhase, TuiTextKey> = {
+  exchanged: 'phase.exchanged',
+  requested: 'phase.requested',
+  invited: 'phase.invited',
+  revoked: 'phase.revoked',
+};
+
+const NO_PHASE = '—';
+const SHORT = (node: string): string => node.split(':').pop() ?? node;
+
+function failureText(error: unknown): string {
+  if (error instanceof Error && 'error' in error) {
+    const inner = (error as { error?: { message?: string } }).error;
+    if (typeof inner?.message === 'string') return inner.message;
+  }
+  return String(error);
+}
+
+type Mode = { kind: 'list' } | { kind: 'confirm'; exchange: KeyExchange } | { kind: 'input' };
+
+/**
+ * The gateway's foreground surface: one screen for the peers it discovered, the trust stage
+ * of each, and the four actions that change one. Every confirmation shows the fingerprint
+ * first, because that string — not the node id — is what the two operators compare.
+ */
+export class GatewayTui {
+  #rows: Row[] = [];
+  #index = 0;
+  #mode: Mode = { kind: 'list' };
+  #input = '';
+  #message = '';
+  #busy = false;
+  #closed = false;
+  #refreshTimer?: ReturnType<typeof setInterval>;
+  #statusLines: string[] = [];
+
+  constructor(
+    private readonly node: OnlyneNode,
+    private readonly ring: LogRing,
+    private readonly endpoint: string,
+    private readonly onChange: () => void = () => undefined,
+    private readonly status?: () => Promise<string[]>,
+  ) {}
+
+  async start(): Promise<void> {
+    process.stdout.write('\x1b[?1049h\x1b[?25l');
+    if (process.stdin.isTTY) process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', this.#onData);
+    process.stdout.on('resize', this.#onResize);
+    await this.#refresh();
+    this.#refreshTimer = setInterval(() => { void this.#refresh(); }, 1000);
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    clearInterval(this.#refreshTimer);
+    process.stdin.off('data', this.#onData);
+    process.stdout.off('resize', this.#onResize);
+    process.stdin.pause();
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    process.stdout.write('\x1b[?25h\x1b[?1049l');
+  }
+
+  #onResize = (): void => { this.#draw(); };
+
+  #onData = (chunk: string): void => {
+    if (this.#closed) return;
+    // One `data` event can carry a whole paste or a burst of keystrokes, so it is split into
+    // keys rather than treated as one. Each key runs in order; `#busy` still gates actions.
+    for (const token of tokens(chunk)) void this.#handle(token);
+  };
+
+  async #handle(token: Token): Promise<void> {
+    if (this.#busy) return;
+    if (this.#mode.kind === 'confirm') {
+      if (token === 'y') await this.#settle(true);
+      else if (token === 'n' || token === 'esc') { this.#mode = { kind: 'list' }; this.#message = t('notice.cancelled'); this.#draw(); }
+      return;
+    }
+    if (this.#mode.kind === 'input') {
+      if (token === 'esc') { this.#mode = { kind: 'list' }; this.#input = ''; this.#draw(); return; }
+      if (token === 'enter') { await this.#connect(); return; }
+      if (token === 'backspace') { this.#input = this.#input.slice(0, -1); this.#draw(); return; }
+      if (typeof token === 'string' && token.length === 1 && token >= ' ') { this.#input += token; this.#draw(); }
+      return;
+    }
+    if (token === 'q') { await this.close(); this.onChange(); return; }
+    if (token === 'up') { this.#move(-1); return; }
+    if (token === 'down') { this.#move(1); return; }
+    if (token === 'c') { this.#mode = { kind: 'input' }; this.#input = ''; this.#message = t('notice.enterAddress'); this.#draw(); return; }
+    const row = this.#rows[this.#index];
+    if (row === undefined) return;
+    if (token === 't') { await this.#begin(row); return; }
+    if (token === 'a') { await this.#accept(row); return; }
+    if (token === 'r') { await this.#revoke(row); return; }
+  }
+
+  #move(delta: number): void {
+    if (this.#rows.length === 0) return;
+    this.#index = (this.#index + delta + this.#rows.length) % this.#rows.length;
+    this.#draw();
+  }
+
+  async #refresh(): Promise<void> {
+    if (this.#closed) return;
+    try {
+      const [trust, records, status] = await Promise.all([
+        this.node.trust.list(this.node.auth),
+        this.node.discovery.listRecords(),
+        this.status?.() ?? [],
+      ]);
+      this.#statusLines = status;
+      const handlers = new Map<string, string[]>();
+      const resources = await this.node.resources.list(this.node.auth, { page_size: 100 });
+      for (const resource of resources.items) {
+        const list = handlers.get(resource.binding.handler) ?? [];
+        list.push(resource.resource_ref.id);
+        handlers.set(resource.binding.handler, list);
+      }
+      const rows = new Map<string, Row>();
+      for (const record of records) {
+        if (record.node_id === this.node.auth.actor) continue;
+        rows.set(record.node_id, { node: record.node_id, endpoint: record.base_url });
+      }
+      for (const entry of trust) {
+        if (entry.node_id === this.node.auth.actor) continue;
+        const row = rows.get(entry.node_id) ?? { node: entry.node_id };
+        rows.set(entry.node_id, { ...row, phase: trustPhase(entry), fingerprint: entry.fingerprint, endpoint: row.endpoint ?? entry.base_url });
+      }
+      for (const [handler, ids] of handlers) {
+        if (handler === this.node.auth.actor) continue;
+        const row = rows.get(handler) ?? { node: handler };
+        rows.set(handler, { ...row, delivery: ids });
+      }
+      this.#rows = [...rows.values()].sort((a, b) => (a.node < b.node ? -1 : a.node > b.node ? 1 : 0));
+      if (this.#index >= this.#rows.length) this.#index = Math.max(0, this.#rows.length - 1);
+      this.#draw();
+    } catch (error) {
+      this.#message = t('notice.refreshFailed', { error: failureText(error) });
+      this.#draw();
+    }
+  }
+
+  async #begin(row: Row): Promise<void> {
+    if (row.phase === 'exchanged') { this.#message = t('notice.alreadyExchanged', { node: SHORT(row.node) }); this.#draw(); return; }
+    await this.#run(async () => {
+      const exchange = await this.node.trust.begin(this.node.auth, row.node);
+      this.#mode = { kind: 'confirm', exchange };
+      this.#message = '';
+    });
+  }
+
+  async #accept(row: Row): Promise<void> {
+    if (row.phase !== 'invited' || row.fingerprint === undefined) {
+      this.#message = t('notice.noRequest', { node: SHORT(row.node) });
+      this.#draw();
+      return;
+    }
+    const fingerprint = row.fingerprint;
+    await this.#run(async () => {
+      await this.node.trust.accept(this.node.auth, row.node, fingerprint);
+      this.#message = t('notice.accepted', { node: SHORT(row.node) });
+    });
+  }
+
+  async #revoke(row: Row): Promise<void> {
+    if (row.phase === undefined) { this.#message = t('notice.noTrust', { node: SHORT(row.node) }); this.#draw(); return; }
+    await this.#run(async () => {
+      await this.node.trust.revoke(this.node.auth, row.node);
+      this.#message = t('notice.revoked', { node: SHORT(row.node) });
+    });
+  }
+
+  async #connect(): Promise<void> {
+    const value = this.#input.trim();
+    this.#mode = { kind: 'list' };
+    this.#input = '';
+    if (value === '') { this.#message = t('notice.noAddress'); this.#draw(); return; }
+    await this.#run(async () => {
+      const url = new URL(value.includes('://') ? value : `http://${value}`);
+      url.pathname = url.pathname.replace(/\/+$/, '') || '/onlyne/v3';
+      const record = await this.node.discovery.observe(url.href, 'manual');
+      this.#message = t('notice.connected', { node: record.node_id });
+    });
+  }
+
+  async #settle(accept: boolean): Promise<void> {
+    const mode = this.#mode;
+    if (mode.kind !== 'confirm') return;
+    if (!accept) { this.#mode = { kind: 'list' }; this.#message = t('notice.cancelled'); this.#draw(); return; }
+    this.#mode = { kind: 'list' };
+    await this.#run(async () => {
+      const entry = await mode.exchange.confirm(mode.exchange.fingerprint);
+      this.#message = t('notice.submitted', { node: SHORT(entry.node_id), phase: t(PHASE_KEY[trustPhase(entry)]) });
+    });
+  }
+
+  async #run(work: () => Promise<void>): Promise<void> {
+    this.#busy = true;
+    this.#draw();
+    try { await work(); }
+    catch (error) { this.#message = t('notice.operationFailed', { error: failureText(error) }); }
+    finally {
+      this.#busy = false;
+      await this.#refresh();
+    }
+  }
+
+  #draw(): void {
+    if (this.#closed) return;
+    // One cell short of the terminal width: writing the last cell auto-wraps, which would
+    // consume a second row per line and push the frame upward.
+    const width = Math.max(48, (process.stdout.columns ?? 80) - 1);
+    const height = Math.max(16, process.stdout.rows ?? 24);
+    const lines: string[] = [];
+    const push = (text: string): void => { lines.push(fit(text, width)); };
+
+    push(t('title', { actor: this.node.auth.actor, endpoint: this.endpoint }));
+    push(rule(width));
+
+    if (this.#statusLines.length > 0) {
+      const budget = Math.max(3, Math.floor(height / 3));
+      for (const line of this.#statusLines.slice(0, budget)) push(line);
+      if (this.#statusLines.length > budget) push('…');
+      push(rule(width));
+    }
+
+    const peerHeader = this.#rows.length === 0 ? t('peers.none') : t('peers.count', { count: this.#rows.length });
+    push(peerHeader);
+    for (const [index, row] of this.#rows.entries()) {
+      const marker = index === this.#index ? '▸' : ' ';
+      const phase = row.phase === undefined ? NO_PHASE : t(PHASE_KEY[row.phase]);
+      // Delivery is the binding's answer, not the trust stage's: a node can be exchanged and
+      // still receive nothing, and the handler can be a node with no key exchange at all.
+      const delivery = row.delivery === undefined ? '' : t('column.delivery');
+      push(`${marker} ${SHORT(row.node).padEnd(14)} ${phase.padEnd(14)} ${delivery.padEnd(8)} ${row.endpoint ?? ''}`);
+    }
+
+    push(rule(width));
+    const selected = this.#rows[this.#index];
+    if (selected === undefined) {
+      push(t('hint.idle'));
+    } else {
+      push(selected.node);
+      push(`${t('label.fingerprint').padEnd(6)}${selected.fingerprint ?? t('value.notExchanged')}`);
+      push(`${t('label.endpoint').padEnd(6)}${selected.endpoint ?? t('value.unknown')}`);
+      if (selected.delivery !== undefined) push(`${t('label.delivery').padEnd(6)}${selected.delivery.join(t('list.separator'))}`);
+    }
+
+    push(rule(width));
+    if (this.#mode.kind === 'confirm') {
+      const exchange = this.#mode.exchange;
+      push(t('confirm.title', { node: SHORT(exchange.node_id) }));
+      push(`  ${exchange.fingerprint}`);
+      push(t('confirm.keys'));
+    } else if (this.#mode.kind === 'input') {
+      push(t('input.prompt', { value: this.#input }));
+    } else {
+      push(t('help.keys'));
+    }
+    if (this.#message !== '') push(this.#message);
+    if (this.#busy) push('…');
+
+    const logLines = Math.max(0, height - lines.length - 1);
+    if (logLines > 0) {
+      push(rule(width));
+      for (const line of this.ring.tail(logLines)) push(line);
+    }
+
+    let frame = '\x1b[H';
+    for (let index = 0; index < height; index++) {
+      frame += `${lines[index] ?? ''}\x1b[K${index === height - 1 ? '' : '\r\n'}`;
+    }
+    frame += '\x1b[J';
+    process.stdout.write(frame);
+  }
+}
+
+type Token = 'up' | 'down' | 'enter' | 'esc' | 'backspace' | 'y' | 'n' | 'q' | 't' | 'a' | 'r' | 'c' | string;
+
+/** Splits one stdin chunk into keys: CSI arrows, a bare escape, and every printable character. */
+function tokens(chunk: string): Token[] {
+  const out: Token[] = [];
+  let rest = chunk.replace(/\x1b\[20[01]~/g, '');
+  while (rest.length > 0) {
+    if (rest.startsWith('\x1b[A')) { out.push('up'); rest = rest.slice(3); continue; }
+    if (rest.startsWith('\x1b[B')) { out.push('down'); rest = rest.slice(3); continue; }
+    if (rest.startsWith('\x1b[')) {
+      // Any other control sequence is not a key this surface uses; drop it whole.
+      const end = rest.slice(2).search(/[@-~]/);
+      rest = end < 0 ? '' : rest.slice(end + 3);
+      continue;
+    }
+    if (rest.startsWith('\x1b')) { out.push('esc'); rest = rest.slice(1); continue; }
+    const character = rest[0]!;
+    if (character === '\r' || character === '\n') out.push('enter');
+    else if (character === '\x7f' || character === '\b') out.push('backspace');
+    else if (character === '\x03') out.push('q');
+    else if (character >= ' ') out.push(character);
+    rest = rest.slice(1);
+  }
+  return out;
+}
+
+function fit(text: string, width: number): string {
+  if (text.length <= width) return text;
+  return `${text.slice(0, width - 1)}…`;
+}
+
+function rule(width: number): string {
+  return '─'.repeat(width);
+}