@ccmsg/cli 0.1.0

package/src/launcher/launcher.ts

@@ -0,0 +1,190 @@
+import type {
+  Capability,
+  DirTreeArgs,
+  DirTreeResult,
+  LauncherConfigReadResult,
+  LauncherRunArgs,
+  LauncherRunResult,
+} from "@ccmsg/protocol";
+import { type HandlerInput, OpError } from "../dispatch/index.ts";
+import type { LauncherConfig, LauncherTemplateConfig } from "../instance/config.ts";
+import { spawnLaunch } from "./spawn.ts";
+import { insideRoots } from "./roots.ts";
+import { dirTree } from "./tree.ts";
+
+/** The capability the three launcher ops need. A launcher with no roots and no
+ * recipes has no form to answer with, so a client is told there is none rather
+ * than being handed an empty one. */
+export function launcherCapabilities(config?: LauncherConfig): Capability[] {
+  return config === undefined ? [] : ["launcher"];
+}
+
+/** One launch, as everything but the spawning sees it. */
+export interface Launch {
+  /** The shell and its program, ready to run. */
+  readonly argv: readonly string[];
+  /** The checked directory, which is both where the command runs and what it
+   * sees as its working directory. */
+  readonly cwd: string;
+  readonly env: Record<string, string | undefined>;
+  readonly timeoutMs: number;
+}
+
+/** Whoever starts the command. The one part of a launch that touches the host,
+ * kept behind a name so a test can watch a launch being assembled without a
+ * process being started. */
+export type LaunchRunner = (launch: Launch) => Promise<LauncherRunResult>;
+
+export interface LauncherDeps {
+  /** The environment a launched command starts from, before `clean_env`. */
+  readonly env?: Record<string, string | undefined>;
+  readonly run?: LaunchRunner;
+}
+
+/** What the launcher may start, and the two ops that read and use it.
+ *
+ * No value a caller sends is ever spliced into shell text: the parameters reach
+ * the command as shell variables, and the directory is the one the containment
+ * check resolved rather than the one the caller wrote. */
+export class Launcher {
+  readonly #env: Record<string, string | undefined>;
+  readonly #run: LaunchRunner;
+
+  constructor(
+    private readonly config: LauncherConfig,
+    deps: LauncherDeps = {},
+  ) {
+    this.#env = deps.env ?? process.env;
+    this.#run = deps.run ?? spawnLaunch;
+  }
+
+  /** The form: where a session may run, and the recipes it may run under. How
+   * the shell runs one is not reported, because nothing a client does with the
+   * answer depends on it. */
+  configRead(): LauncherConfigReadResult {
+    return {
+      root_dirs: [...this.config.root_dirs],
+      templates: this.config.templates.map((template) => ({
+        name: template.name,
+        command: template.command,
+        params: template.params.map((param) => ({ name: param.name, default: param.default })),
+      })),
+    };
+  }
+
+  tree(args: DirTreeArgs): DirTreeResult {
+    return dirTree(this.config, args);
+  }
+
+  run(args: LauncherRunArgs): Promise<LauncherRunResult> {
+    const cwd = insideRoots(this.config, args.cwd);
+    if (cwd === undefined) {
+      // The op states no refusal for a path, so a directory outside the roots
+      // is answered as what it is from here: an argument this launcher cannot
+      // act on.
+      throw new OpError("invalid_args", `${args.cwd} is not a directory the launcher may start in`);
+    }
+    const template = this.template(args.template);
+    const declared = new Map(template.params.map((param) => [param.name, param.default]));
+    for (const name of Object.keys(args.params)) {
+      if (!declared.has(name)) {
+        throw new OpError(
+          "invalid_args",
+          `${template.name} declares no parameter called ${name}, so nothing would read it`,
+        );
+      }
+    }
+    const values: Record<string, string> = {};
+    for (const [name, fallback] of declared) {
+      values[carrier(name)] = args.params[name] ?? fallback;
+    }
+    return this.#run({
+      argv: shellArgv(
+        template.shell,
+        program([...declared.keys()], args.command ?? template.command),
+      ),
+      cwd,
+      env: { ...cleaned(this.#env, this.config), ...values },
+      timeoutMs: this.config.timeout_secs * 1000,
+    });
+  }
+
+  /** The recipe a launch names, or the default one. An unknown name is refused
+   * rather than replaced with another, because running a different recipe than
+   * the one asked for is worse than running none. */
+  private template(name?: string): LauncherTemplateConfig {
+    if (name === undefined) {
+      const first = this.config.templates[0];
+      if (first === undefined) throw new OpError("invalid_args", "this launcher has no recipe");
+      return first;
+    }
+    const found = this.config.templates.find((template) => template.name === name);
+    if (found === undefined) throw new OpError("invalid_args", `no recipe is called ${name}`);
+    return found;
+  }
+}
+
+export function launcherHandlers(launcher: Launcher) {
+  return {
+    launcher_config_read: (): LauncherConfigReadResult => launcher.configRead(),
+    launcher_run: (input: HandlerInput): Promise<LauncherRunResult> =>
+      launcher.run(input.args as unknown as LauncherRunArgs),
+    dir_tree: (input: HandlerInput): DirTreeResult =>
+      launcher.tree(input.args as unknown as DirTreeArgs),
+  };
+}
+
+/** The environment variable one parameter's value travels in.
+ *
+ * A carrier of its own, in a namespace the shell erases before the command
+ * runs, so the value reaches the command as a plain shell variable and nothing
+ * the command starts inherits it. */
+export function carrier(name: string): string {
+  return `ccmsg_launch_param_${name}`;
+}
+
+/** The shell program: the prologue that moves every parameter out of the
+ * environment, then the recipe's command.
+ *
+ * Both run in one shell. A nested `sh -c` would defeat the whole arrangement,
+ * since a variable that is not exported does not cross into a child. Every
+ * declared parameter is defined, empty rather than absent when nothing supplied
+ * one, so a command run under `set -u` does not abort on a field left blank. */
+export function program(names: readonly string[], command: string): string {
+  const prologue = names
+    .map((name) => `unset -v ${name}; ${name}="$${carrier(name)}"; unset -v ${carrier(name)}`)
+    .join("\n");
+  // A newline rather than `;` so a command opening with a comment or a shell
+  // keyword parses exactly as it was written.
+  return `${prologue}\n${command}`;
+}
+
+export function shellArgv(shell: "bash" | "zsh", command: string): string[] {
+  return shell === "bash"
+    ? ["bash", "-eu", "-o", "pipefail", "-c", command]
+    : ["zsh", "-e", "-u", "-o", "pipefail", "-c", command];
+}
+
+/** The environment a launched command starts from: this instance's own, minus
+ * what `clean_env` names and back again for what `keep_env` does. Keep wins, so
+ * one broad pattern can be written beside its exceptions. */
+function cleaned(
+  env: Record<string, string | undefined>,
+  config: LauncherConfig,
+): Record<string, string | undefined> {
+  const clean = config.clean_env.map(pattern);
+  const keep = config.keep_env.map(pattern);
+  const kept: Record<string, string | undefined> = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (clean.some((each) => each.test(name)) && !keep.some((each) => each.test(name))) continue;
+    kept[name] = value;
+  }
+  return kept;
+}
+
+/** One `clean_env` pattern, where `*` stands for any run of characters and
+ * everything else is literal. */
+function pattern(glob: string): RegExp {
+  const escaped = glob.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replaceAll("\\*", ".*")}$`);
+}

package/src/launcher/roots.ts

@@ -0,0 +1,32 @@
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import type { LauncherConfig } from "../instance/config.ts";
+import { canonical, within } from "../files/index.ts";
+
+/** Whether a directory is one the launcher may act on, and what the filesystem
+ * calls it.
+ *
+ * The comparison runs on what both sides resolve to, so a path spelled through
+ * a symlink out of a root is refused however it was written — the same rule the
+ * file ops go through, asked of the roots config states rather than of the ones
+ * a session states.
+ *
+ * A root that no longer resolves grants nothing and stops nothing: another
+ * configured root may still hold the candidate. */
+export function insideRoots(config: LauncherConfig, path: string): string | undefined {
+  if (!isAbsolute(path)) return undefined;
+  const real = canonical(path);
+  if (!isDirectory(real)) return undefined;
+  for (const root of config.root_dirs) {
+    if (within(real, canonical(root))) return real;
+  }
+  return undefined;
+}
+
+export function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/launcher/spawn.ts

@@ -0,0 +1,81 @@
+import type { LauncherRunResult } from "@ccmsg/protocol";
+import type { Launch } from "./launcher.ts";
+
+/** How long a command stopped for outliving its allowance is given to leave
+ * before it is killed outright. */
+const FORCE_KILL_MS = 500;
+
+/** How long the pipes are read after the command itself has exited.
+ *
+ * A launch that detaches something — which is what starting a session in a
+ * terminal is — leaves that grandchild holding the write end, so end-of-file
+ * may never arrive. Without a bound the reply would wait for the session to
+ * finish. On an ordinary exit every descriptor closes at once and this costs
+ * nothing. */
+const DRAIN_MS = 500;
+
+/** Start one assembled launch and answer with what it did.
+ *
+ * Both pipes are read from the moment the command starts, so output larger than
+ * a pipe buffer cannot stop the command from finishing. */
+export async function spawnLaunch(launch: Launch): Promise<LauncherRunResult> {
+  const child = Bun.spawn([...launch.argv], {
+    cwd: launch.cwd,
+    env: launch.env,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  let timedOut = false;
+  let force: ReturnType<typeof setTimeout> | undefined;
+  const deadline = setTimeout(() => {
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    timedOut = true;
+    child.kill("SIGTERM");
+    force = setTimeout(() => {
+      if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+    }, FORCE_KILL_MS);
+  }, launch.timeoutMs);
+
+  const stdout = collect(child.stdout);
+  const stderr = collect(child.stderr);
+  try {
+    const code = await child.exited;
+    const [out, err] = await Promise.all([stdout(DRAIN_MS), stderr(DRAIN_MS)]);
+    return {
+      stdout: out,
+      stderr: err,
+      // A signal leaves no code to state, so the field is absent rather than
+      // carrying a number that means something else.
+      ...(child.signalCode === null ? { exit_code: code } : {}),
+      timed_out: timedOut,
+    };
+  } finally {
+    clearTimeout(deadline);
+    if (force !== undefined) clearTimeout(force);
+  }
+}
+
+/** Read a pipe as it arrives, and answer with what got there within the grace.
+ *
+ * Not `Response.text()`: that resolves only at end-of-file, which is the one
+ * thing a detached grandchild can postpone forever. */
+function collect(stream: ReadableStream<Uint8Array>): (graceMs: number) => Promise<string> {
+  const chunks: Uint8Array[] = [];
+  const reader = stream.getReader();
+  const drained = (async () => {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value !== undefined) chunks.push(value);
+    }
+  })();
+  return async (graceMs) => {
+    await Promise.race([
+      drained.catch(() => {}),
+      new Promise((resolve) => setTimeout(resolve, graceMs)),
+    ]);
+    await reader.cancel().catch(() => {});
+    return Buffer.concat(chunks).toString("utf8");
+  };
+}

package/src/launcher/tree.ts

@@ -0,0 +1,80 @@
+import { readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { DirTreeArgs, DirTreeEntry, DirTreeResult } from "@ccmsg/protocol";
+import type { LauncherConfig } from "../instance/config.ts";
+import { insideRoots } from "./roots.ts";
+
+/** How far one request may walk, whatever it asks for.
+ *
+ * Design rationale: the depth is the client's to choose, and a walk whose cost
+ * the client sets has no bound at all. Five levels covers the configured depth
+ * plus several lazy expansions, and going deeper stays a matter of asking for a
+ * descendant — which is the same walk, paid for one request at a time. */
+const MAX_DEPTH = 5;
+
+/** The directories a session could be started in.
+ *
+ * Directories only, and only below the configured roots. A root the config does
+ * not hold contributes nothing rather than failing the request: the op states no
+ * refusal for a path, and a tree assembled from several roots would otherwise be
+ * lost whole because one of them went away. */
+export function dirTree(config: LauncherConfig, args: DirTreeArgs): DirTreeResult {
+  const depth = Math.min(MAX_DEPTH, args.depth ?? config.depth);
+  // A filter of nothing is not a filter: an emptied search box shows the tree
+  // rather than hiding all of it.
+  const filter = args.filter === undefined || args.filter === "" ? undefined : args.filter;
+  const entries: DirTreeEntry[] = [];
+  for (const root of args.roots) {
+    const real = insideRoots(config, root);
+    if (real === undefined) continue;
+    entries.push(...walk(config, real, real, depth, filter));
+  }
+  return { entries: sorted(entries) };
+}
+
+function walk(
+  config: LauncherConfig,
+  root: string,
+  at: string,
+  depth: number,
+  filter: string | undefined,
+): DirTreeEntry[] {
+  const entries: DirTreeEntry[] = [];
+  for (const dirent of read(at)) {
+    // Design rationale: dot-directories are left out. This answers "where could
+    // a session run", and a repository's `.git` is not one of those places —
+    // browsing a session's own files is a different op with different rules.
+    if (dirent.name.startsWith(".")) continue;
+    const path = join(at, dirent.name);
+    if (dirent.isSymbolicLink()) {
+      // A link is a place to run only if what it points at is one, so it goes
+      // through the same containment its target would.
+      if (insideRoots(config, path) === undefined) continue;
+    } else if (!dirent.isDirectory()) continue;
+
+    const children = depth > 1 ? walk(config, root, path, depth - 1, filter) : undefined;
+    if (filter !== undefined) {
+      const matches = relative(root, path).includes(filter);
+      // An ancestor of a match survives the filter: without it a match several
+      // levels down would have nothing to hang from.
+      if (!matches && (children === undefined || children.length === 0)) continue;
+    }
+    entries.push({ path, ...(children === undefined ? {} : { children: sorted(children) }) });
+  }
+  return entries;
+}
+
+function read(dir: string) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    // A directory that cannot be read is still a place to run; what it holds is
+    // simply not known, which is the same answer as holding nothing.
+    return [];
+  }
+}
+
+/** Codepoint order, which is the same wherever the daemon runs. */
+function sorted(entries: DirTreeEntry[]): DirTreeEntry[] {
+  return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}

package/src/mesh/index.ts

@@ -0,0 +1,5 @@
+export * from "./keys.ts";
+export * from "./mesh.ts";
+export * from "./probe.ts";
+export * from "./relay.ts";
+export * from "./wire.ts";

package/src/mesh/keys.ts

@@ -0,0 +1,158 @@
+import {
+  createPublicKey,
+  generateKeyPairSync,
+  type JsonWebKeyInput,
+  type KeyObject,
+  randomBytes,
+  sign,
+  verify,
+} from "node:crypto";
+import type { Endpoint } from "@ccmsg/protocol";
+
+/** The handshake format this instance speaks (mesh-peer-auth §5.3). */
+export const MESH_VER = 1;
+
+/** The signature algorithms a proof may be made with.
+ *
+ * A set rather than one name, because the JWS header is not trusted: the header
+ * names an algorithm and this is what decides whether that name may be used at
+ * all, which is what stops `alg: none` and algorithm confusion (§5.7-7). Two
+ * entries have to be expressible for a migration, so it is a set even while it
+ * holds one. */
+export const ALLOWED_ALGS: ReadonlySet<string> = new Set(["EdDSA"]);
+
+/** How long a proof stays valid (§5.9). A handshake within one region completes
+ * in tens to hundreds of milliseconds, and a peer that cannot manage this could
+ * not hold a mesh link anyway. */
+export const PROOF_LIFETIME_MS = 10_000;
+
+/** 128 bits, the floor §5.9 sets for both the challenge and the key id: the only
+ * requirement on either is that it cannot be predicted. */
+const RANDOM_BYTES = 16;
+
+export function randomId(): string {
+  return randomBytes(RANDOM_BYTES).toString("hex");
+}
+
+/** A public key as it travels: a JWK carrying the id it answers to.
+ *
+ * The id is on the key because the receiver compares three of them — the
+ * greeting's, the proof header's, and this one — and a key that arrived without
+ * its own id could not be part of that comparison (§5.7-8). */
+export interface MeshJwk {
+  readonly kty: string;
+  readonly crv?: string;
+  readonly x?: string;
+  readonly kid: string;
+}
+
+/** One connection's signing key.
+ *
+ * It lives as long as the handshake it was made for: created when the dial
+ * starts, fetched once by the peer, and destroyed when the acknowledgement
+ * arrives or the connection goes, whichever comes first (§7). Nothing rotates
+ * it because nothing outlives one connection. */
+export class EphemeralKey {
+  readonly kid = randomId();
+  readonly #private: KeyObject;
+  readonly #public: KeyObject;
+
+  constructor() {
+    const pair = generateKeyPairSync("ed25519");
+    this.#private = pair.privateKey;
+    this.#public = pair.publicKey;
+  }
+
+  jwk(): MeshJwk {
+    return { ...(this.#public.export({ format: "jwk" }) as object), kid: this.kid } as MeshJwk;
+  }
+
+  /** The proof of §5.4: the challenge, and the two endpoint URLs, signed.
+   *
+   * The URLs are signed even though the greeting already carried them, because
+   * the greeting is not signed and therefore states nothing. */
+  proof(claim: ProofClaim): string {
+    const header = { alg: "EdDSA", kid: this.kid };
+    const input = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(claim))}`;
+    return `${input}.${sign(null, Buffer.from(input), this.#private).toString("base64url")}`;
+  }
+}
+
+/** What a proof asserts. */
+export interface ProofClaim {
+  readonly ver: number;
+  readonly iss: Endpoint;
+  readonly aud: Endpoint;
+  readonly challenge: string;
+  /** Unix seconds, as a JWS `exp` is. */
+  readonly exp: number;
+}
+
+/** A proof that has been read but not yet judged: the header's `kid`, and the
+ * claim, both of which the caller compares before any signature is checked. */
+export interface ParsedProof {
+  readonly kid: string;
+  readonly alg: string;
+  readonly claim: ProofClaim;
+}
+
+export class ProofError extends Error {}
+
+/** Read a compact JWS into its parts, refusing anything malformed or signed
+ * with an algorithm outside the allowed set.
+ *
+ * The algorithm is checked here, before the key is even looked at, because the
+ * check exists to decide whether the header may be acted on at all (§5.7-7). */
+export function parseProof(jws: string): ParsedProof {
+  const parts = jws.split(".");
+  if (parts.length !== 3) throw new ProofError("a proof is a compact JWS of three parts");
+  const [rawHeader, rawClaim] = parts as [string, string, string];
+  const header = decode(rawHeader, "header");
+  const alg = header["alg"];
+  const kid = header["kid"];
+  if (typeof alg !== "string" || !ALLOWED_ALGS.has(alg)) {
+    throw new ProofError(`a proof signed with ${String(alg)} is not one this instance accepts`);
+  }
+  if (typeof kid !== "string" || kid === "") throw new ProofError("a proof names its key");
+  const claim = decode(rawClaim, "claim");
+  for (const field of ["ver", "iss", "aud", "challenge", "exp"] as const) {
+    if (claim[field] === undefined) throw new ProofError(`a proof states its ${field}`);
+  }
+  return { kid, alg, claim: claim as unknown as ProofClaim };
+}
+
+/** Whether the signature was made by the key the JWK carries. */
+export function verifyProof(jws: string, jwk: MeshJwk): boolean {
+  const parts = jws.split(".");
+  if (parts.length !== 3) return false;
+  const [rawHeader, rawClaim, rawSignature] = parts as [string, string, string];
+  let key: KeyObject;
+  try {
+    key = createPublicKey({ key: { ...jwk }, format: "jwk" } as JsonWebKeyInput);
+  } catch {
+    return false;
+  }
+  return verify(
+    null,
+    Buffer.from(`${rawHeader}.${rawClaim}`),
+    key,
+    Buffer.from(rawSignature, "base64url"),
+  );
+}
+
+function decode(part: string, what: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+  } catch {
+    throw new ProofError(`a proof's ${what} is not JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new ProofError(`a proof's ${what} is not an object`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function b64url(text: string): string {
+  return Buffer.from(text, "utf8").toString("base64url");
+}