@onlyne/node-host 3.1.0 → 3.2.0

package/src/index.ts

@@ -1,82 +0,0 @@
-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

@@ -1,158 +0,0 @@
-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

@@ -1,103 +0,0 @@
-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,
-  });
-}