@ccmsg/cli 0.1.0

package/src/dispatch/dispatch.ts

@@ -0,0 +1,128 @@
+import {
+  type Capability,
+  type InstanceId,
+  isRoleAllowed,
+  OP_ATTRIBUTES,
+  OP_SCHEMAS,
+  opAttributes,
+  type OpName,
+  validationErrors,
+} from "@ccmsg/protocol";
+import type { Handlers, Requester } from "./handler.ts";
+import { type DispatchResult, failure, OpError, reply } from "./result.ts";
+
+/** What dispatch needs from the instance around it. */
+export interface DispatchDeps {
+  /** This instance's own id, compared with the destination of an
+   * `instance-local` op to decide whether the op is ours to run. */
+  readonly self: InstanceId;
+  /** The capabilities this instance has, as `hello` reports them. */
+  readonly capabilities: ReadonlySet<Capability>;
+  /** The instance that owns the subject of an `instance-local` op, or
+   * `undefined` when no other instance owns it and we answer ourselves.
+   * The routing table behind this is the `peers` topic (daemon-v2 §7.3). */
+  readonly resolveInstance: (op: OpName, frame: Record<string, unknown>) => InstanceId | undefined;
+  readonly handlers: Handlers;
+}
+
+function isOpName(op: string): op is OpName {
+  return Object.hasOwn(OP_ATTRIBUTES, op);
+}
+
+/** Decide one frame.
+ *
+ * The six steps of daemon-v2 §3.2 are written once, here, and read the op
+ * attribute table for every op. Adding an op is a row in the table plus a
+ * schema and an implementation — never a check in this function (M1). */
+export async function dispatch(
+  frame: unknown,
+  conn: Requester,
+  deps: DispatchDeps,
+): Promise<DispatchResult> {
+  const identity = conn.identity;
+  if (typeof frame !== "object" || frame === null || Array.isArray(frame)) {
+    return failure(undefined, "bad_request", "a request must be a JSON object");
+  }
+  const fields = frame as Record<string, unknown>;
+
+  const rawId = fields["request_id"];
+  const requestId = typeof rawId === "string" && rawId.length > 0 ? rawId : undefined;
+  const op = fields["op"];
+  if (typeof op !== "string") {
+    return failure(requestId, "bad_request", "a request must carry an op name");
+  }
+  if (requestId === undefined) {
+    return failure(undefined, "bad_request", "a request must carry a request_id");
+  }
+
+  // 1. the op is in the contract
+  if (!isOpName(op)) {
+    return failure(requestId, "unknown_op", `no such op: ${op}`);
+  }
+  const attrs = opAttributes(op);
+
+  // 2. the arguments pass the op's schema
+  const problems = validationErrors(OP_SCHEMAS[op].request, fields);
+  if (problems.length > 0) {
+    return failure(requestId, "invalid_args", problems.join("; "));
+  }
+
+  // 3. the identity `hello` settles, when the op needs one
+  if (attrs.needs_hello && identity.state !== "settled") {
+    return failure(requestId, "hello_required", `${op} needs an identity settled by hello`);
+  }
+
+  // 4. the connection's role is one the op allows. An anonymous connection has
+  // no role to compare, and the ops it may reach (`needs_hello: false`) are
+  // open to every role, so there is nothing to refuse here.
+  if (identity.state === "settled" && !isRoleAllowed(op, identity.role)) {
+    return failure(requestId, "forbidden", `${op} is not open to ${identity.role}`);
+  }
+
+  // 5. the capability the op declares, when it declares one
+  if (attrs.capability !== undefined && !deps.capabilities.has(attrs.capability)) {
+    return failure(
+      requestId,
+      "capability_unavailable",
+      `${op} needs the ${attrs.capability} capability, which this instance does not have`,
+    );
+  }
+
+  // 6. an instance-local op whose subject belongs elsewhere goes to mesh.
+  //
+  // A request that has already been here is dropped before that: a cycle in
+  // the routing would otherwise send it round the same instances until every
+  // deadline expired (§7.3). It is answered rather than left unanswered,
+  // because the caller learns the same thing sooner and the code is the one
+  // the contract gives a destination that could not be reached.
+  const hops = fields["hops"];
+  if (Array.isArray(hops) && hops.includes(deps.self)) {
+    return failure(requestId, "instance_unreachable", `${op} came back to ${deps.self}`);
+  }
+  if (attrs.locality === "instance-local") {
+    const asked = fields["to_instance"];
+    const target = typeof asked === "string" ? asked : deps.resolveInstance(op, fields);
+    if (target !== undefined && target !== deps.self) {
+      return { kind: "forward", to: target, frame: fields };
+    }
+  }
+
+  // 7. the implementation, which starts from "validated and allowed"
+  try {
+    const body = await deps.handlers[op]({
+      op,
+      args: fields,
+      conn,
+      identity: identity.state === "settled" ? identity : undefined,
+      // The one route by which a role reaches an implementation (§3.2).
+      role: attrs.scope === "role" && identity.state === "settled" ? identity.role : undefined,
+    });
+    return reply(requestId, body);
+  } catch (cause) {
+    if (cause instanceof OpError) return failure(requestId, cause.code, cause.message);
+    // Anything else is the implementation failing for a reason that is not the
+    // caller's: the arguments passed the op's schema and the call was allowed,
+    // so re-reading the arguments would tell the caller nothing.
+    return failure(requestId, "internal_error", `the op failed: ${String(cause)}`);
+  }
+}

package/src/dispatch/handler.ts

@@ -0,0 +1,55 @@
+import type { OpName, Role } from "@ccmsg/protocol";
+import type { ConnIdentity, SettledIdentity } from "./identity.ts";
+
+/** The connection a request arrived on, as an implementation sees it.
+ *
+ * It is the `Conn` transport accepted, narrowed to what an op may do with it:
+ * read the identity, push frames, and learn that the connection is gone. A
+ * subscription is held by a connection and ends with it (daemon-v2 §6.3), so
+ * this is what the topic mechanism keys its subscribers on. Declared here
+ * rather than imported from transport because dispatch sits below it. */
+export interface Requester {
+  readonly identity: ConnIdentity;
+  /** Push one frame that is not a reply — a topic frame or a connection event. */
+  send(frame: object): void;
+  /** Push one frame after the reply to the request being handled goes out, so
+   * a subscribe's snapshot follows its acknowledgement rather than preceding it. */
+  deferSend(frame: object): void;
+  onClose(listener: () => void): void;
+  /** End the connection. One op needs it: the mesh handshake decides whether a
+   * connection is a peer at all, and a connection that fails it is closed
+   * rather than left open and anonymous (mesh-peer-auth §5.8). */
+  close(code?: number, reason?: string): void;
+}
+
+/** What an op implementation receives.
+ *
+ * The arguments are already validated and the caller is already allowed
+ * (daemon-v2 §3.2): a handler starts from "this may be run", so it holds no
+ * check of its own. */
+export interface HandlerInput {
+  readonly op: OpName;
+  /** The connection the request arrived on. Ops that hold something for the
+   * length of a connection — the subscriptions of daemon-v2 §6.3 — need it;
+   * ops that only answer ignore it. */
+  readonly conn: Requester;
+  /** The whole request frame, validated against the op's request schema. */
+  readonly args: Record<string, unknown>;
+  /** The connection's identity, absent for the two ops that run before `hello`. */
+  readonly identity?: SettledIdentity;
+  /** Set only for ops the attribute table marks `scope: "role"`, where the role
+   * changes what the reply may contain rather than whether the call is allowed.
+   * This is the only route by which a role reaches an implementation
+   * (daemon-v2 §3.2). */
+  readonly role?: Role;
+}
+
+/** An op implementation. It answers with the op's response body (dispatch adds
+ * `ok` and `request_id`, so the body never carries the reply's envelope), and
+ * may answer with a promise of one — dispatch awaits what it returns. */
+export type OpHandler = (input: HandlerInput) => unknown;
+
+/** One handler per op in the contract. The record is total on purpose: an op
+ * added to the attribute table does not compile until it has an implementation
+ * reachable through dispatch (M1). */
+export type Handlers = Readonly<Record<OpName, OpHandler>>;

package/src/dispatch/identity.ts

@@ -0,0 +1,22 @@
+import type { Role, Sid } from "@ccmsg/protocol";
+
+/** What dispatch knows about the connection a frame arrived on.
+ *
+ * transport settles this (daemon-v2 §3.1): a connection starts anonymous and
+ * becomes `settled` when `hello` binds a role, and a session's `sid`, to it.
+ * Nothing else about the connection reaches dispatch — the authorization steps
+ * read the op attribute table, not the connection. */
+export type ConnIdentity = AnonymousIdentity | SettledIdentity;
+
+export interface AnonymousIdentity {
+  readonly state: "anonymous";
+}
+
+export interface SettledIdentity {
+  readonly state: "settled";
+  readonly role: Role;
+  /** Present when the role is a session, which is the only role that names one. */
+  readonly sid?: Sid;
+}
+
+export const ANONYMOUS: AnonymousIdentity = { state: "anonymous" };

package/src/dispatch/index.ts

@@ -0,0 +1,5 @@
+export * from "./caller.ts";
+export * from "./dispatch.ts";
+export * from "./handler.ts";
+export * from "./identity.ts";
+export * from "./result.ts";

package/src/dispatch/result.ts

@@ -0,0 +1,58 @@
+import type { ErrorCode, ErrorResponse, InstanceId } from "@ccmsg/protocol";
+
+/** What dispatch decided about one frame.
+ *
+ * `forward` is the only outcome that is not an answer: the op belongs to
+ * another instance and mesh has to carry it there (daemon-v2 §3.2 step 6).
+ * There is no mesh yet, so dispatch names the destination and stops. */
+export type DispatchResult =
+  /** The frame was not a request and has no answer. The mesh handshake's own
+   * traffic is the only thing that arrives this way: it travels on the
+   * connection being authenticated because that is the connection it is about
+   * (mesh-peer-auth §5), and the contract's op vocabulary has no name for it. */
+  | { readonly kind: "none" }
+  | { readonly kind: "reply"; readonly response: Record<string, unknown> }
+  | { readonly kind: "error"; readonly response: ErrorResponse }
+  | { readonly kind: "forward"; readonly to: InstanceId; readonly frame: Record<string, unknown> };
+
+/** An implementation's refusal, in the contract's own vocabulary.
+ *
+ * The six steps before a handler answer with codes dispatch derives from the
+ * attribute table. The codes an op lists for itself (`topic_unknown` and the
+ * like) are known only to the implementation, so it throws this and dispatch
+ * turns it into the same error envelope every other refusal uses. */
+export class OpError extends Error {
+  constructor(
+    readonly code: ErrorCode,
+    msg: string,
+  ) {
+    super(msg);
+    this.name = "OpError";
+  }
+}
+
+/** The reply envelope, built here and nowhere else so the wire shape stays in
+ * one place (daemon-v2 §11.1). */
+export function reply(
+  requestId: string,
+  body: unknown,
+): Extract<DispatchResult, { kind: "reply" }> {
+  const fields = typeof body === "object" && body !== null ? (body as Record<string, unknown>) : {};
+  return { kind: "reply", response: { ok: true, request_id: requestId, ...fields } };
+}
+
+export function failure(
+  requestId: string | undefined,
+  code: ErrorCode,
+  msg: string,
+): Extract<DispatchResult, { kind: "error" }> {
+  const response: ErrorResponse =
+    requestId === undefined
+      ? { ok: false, error: { code, msg } }
+      : {
+          ok: false,
+          request_id: requestId,
+          error: { code, msg },
+        };
+  return { kind: "error", response };
+}

package/src/files/containment.ts

@@ -0,0 +1,263 @@
+import { realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import type { FileKind, Role, Sid } from "@ccmsg/protocol";
+import { OpError } from "../dispatch/index.ts";
+
+/** The three allowlists one session reaches files through.
+ *
+ * They are the session's own facts, not the caller's: the browsable root is
+ * where the session works, the workspace folders are what its editor names, and
+ * the external files are the paths its transcript named outside both. Whoever
+ * holds those facts states them here, and a session that stated none is a
+ * session no path is admitted for — nothing is guessed from a neighbouring
+ * value. */
+export interface SessionRoots {
+  /** Where `contained` paths are relative to: the repository container the
+   * session greeted with, or its working directory. Absent when the session
+   * greeted with neither, which admits no contained path at all. */
+  readonly root?: string;
+  /** Where `file_write` puts a file. Kept apart from `root`, which may be the
+   * container above the working copy. */
+  readonly cwd?: string;
+  /** Absolute folder paths, each admitting its whole subtree. */
+  readonly workspace_folders: readonly string[];
+  /** Absolute file paths, each admitting exactly itself. */
+  readonly external_files: readonly string[];
+}
+
+/** Who states a session's allowlists. */
+export interface RootsSource {
+  roots(sid: Sid): SessionRoots | undefined;
+}
+
+/** One path, decided.
+ *
+ * `real` is what the filesystem calls it and what every later operation uses;
+ * `path` is the shape the kind implies, which is what the reply states back. */
+export interface Located {
+  readonly kind: FileKind;
+  readonly real: string;
+  readonly path: string;
+  /** The same path with its own last segment unresolved: what was named, not
+   * what it points at. An op that acts on the name rather than on the file —
+   * `file_delete`, which unlinks a name — asks what kind of thing was named,
+   * and only this distinguishes a file from a symlink to one. */
+  readonly named: string;
+}
+
+/** The whole file-access decision, for every op that names a path.
+ *
+ * One function rather than a check per handler: a handler starts from "this
+ * path may be reached" the way it already starts from "this call is allowed",
+ * so the three surfaces, the symlink resolution behind them and the visible
+ * range a caller has are decided in one place and cannot come apart.
+ *
+ * `Viewer` is that visible range, and it is where the role of a `scope: "role"`
+ * op arrives (§3.2): a session reads its own session's files, a person reads
+ * any session's, and a role the rule does not name reaches nothing rather than
+ * being guessed at. An op the attribute table gives no `scope` states no role
+ * here, and needs none — dispatch has already settled who may call it. */
+export interface Viewer {
+  /** Present only for an op the attribute table marks `scope: "role"`, which
+   * is the one route by which a role reaches an implementation (§3.2). */
+  readonly role?: Role;
+  /** The session the connection speaks for, when it speaks for one. */
+  readonly sid?: Sid;
+}
+
+export class Containment {
+  constructor(private readonly source: RootsSource) {}
+
+  /** A path named by kind, as an op's arguments give it. */
+  locate(args: PathArgs, viewer: Viewer = {}): Located {
+    const roots = this.rootsFor(args.sid, viewer);
+    const named = this.absolute(args, roots);
+    const real = canonical(named);
+    return { ...this.admit(args.kind, real, roots), named };
+  }
+
+  /** An absolute path with no kind: which surface admits it, if any.
+   *
+   * The surfaces are tried in the order the contract states, and the answer is
+   * one value for every refusal — outside the allowlists, or simply not there —
+   * so a caller cannot learn from it whether a path it may not read exists. */
+  identify(sid: Sid, path: string, viewer: Viewer = {}): Located | undefined {
+    let roots: SessionRoots;
+    try {
+      roots = this.rootsFor(sid, viewer);
+    } catch {
+      return undefined;
+    }
+    if (!isAbsolute(path)) return undefined;
+    const named = resolve(path);
+    const real = canonical(named);
+    for (const kind of KINDS) {
+      try {
+        return { ...this.admit(kind, real, roots), named };
+      } catch {
+        // The next surface may admit it; running out of surfaces is the miss.
+      }
+    }
+    return undefined;
+  }
+
+  /** Where `file_write` writes, which is the one destination no kind names: the
+   * session's working directory, and within it the inbox the destination is
+   * fixed to (DR-0019). A name that leaves the inbox is refused as unwritable
+   * rather than as forbidden — the path is reachable, and only writing there
+   * is not. */
+  inbox(sid: Sid, path: string, viewer: Viewer = {}): Located {
+    const roots = this.rootsFor(sid, viewer);
+    const cwd = roots.cwd;
+    if (cwd === undefined || !isAbsolute(cwd)) {
+      throw new OpError("path_forbidden", `${sid} states no working directory to write into`);
+    }
+    const base = canonical(cwd);
+    const named = resolve(base, path);
+    const real = canonical(named);
+    const inbox = join(base, INBOX);
+    if (!within(real, inbox)) {
+      throw new OpError("path_not_writable", `only ${INBOX}/ takes a written file`);
+    }
+    return { kind: "contained", real, named, path: relativeTo(base, real) };
+  }
+
+  /** The directory a listing or a walk starts from. */
+  root(args: DirArgs, viewer: Viewer = {}): Located {
+    return this.locate({ sid: args.sid, kind: args.kind, path: args.path ?? "" }, viewer);
+  }
+
+  private rootsFor(sid: Sid, viewer: Viewer): SessionRoots {
+    if (!sees(sid, viewer)) {
+      throw new OpError(
+        "path_forbidden",
+        `the files of ${sid} are outside this connection's range`,
+      );
+    }
+    const roots = this.source.roots(sid);
+    if (roots === undefined) {
+      throw new OpError("path_forbidden", `nothing is known about the files of ${sid}`);
+    }
+    return roots;
+  }
+
+  /** Turn an op's `path` into an absolute one, in the shape its kind states. */
+  private absolute(args: PathArgs, roots: SessionRoots): string {
+    if (args.kind === "contained") {
+      const root = roots.root;
+      if (root === undefined || !isAbsolute(root)) {
+        throw new OpError("path_forbidden", "this session states no root to be contained by");
+      }
+      return resolve(canonical(root), `.${sep}${args.path}`);
+    }
+    if (!isAbsolute(args.path)) {
+      throw new OpError("path_forbidden", `a ${args.kind} path is absolute`);
+    }
+    return args.path;
+  }
+
+  /** Whether a resolved path is inside the surface it claims. The check runs on
+   * what the filesystem resolved, so a symlink pointing out of a root is
+   * refused however it was spelled (DR-0008 §3). */
+  private admit(kind: FileKind, real: string, roots: SessionRoots): Omit<Located, "named"> {
+    if (kind === "contained") {
+      const root = roots.root === undefined ? undefined : canonical(roots.root);
+      if (root === undefined || !within(real, root)) {
+        throw new OpError("path_forbidden", "the path is outside the session's root");
+      }
+      return { kind, real, path: relativeTo(root, real) };
+    }
+    if (kind === "workspace") {
+      const folder = roots.workspace_folders.find((each) => within(real, canonical(each)));
+      if (folder === undefined) {
+        throw new OpError("path_forbidden", "the path is in no workspace folder of this session");
+      }
+      return { kind, real, path: real };
+    }
+    // `external` admits exactly the files the transcript named, so both sides
+    // of the comparison go through this same resolution (DR-0024 §3.2) — a
+    // path spelled through a symlink and the same file spelled directly are
+    // one entry, and a path since replaced by a symlink resolves elsewhere and
+    // is no longer in the list.
+    const named = roots.external_files.some((each) => canonical(each) === real);
+    if (!named) {
+      throw new OpError("path_forbidden", "the path is not one this session's transcript named");
+    }
+    return { kind, real, path: real };
+  }
+}
+
+/** Which sessions a caller may name, for every `scope: "role"` op.
+ *
+ * A session sees the session it speaks for, a person sees every session. A
+ * role the rule does not name sees nothing — the attribute table decides who
+ * may call an op, and a role it later admits is one this rule has to be told
+ * about rather than one it guesses a range for. An op with no `scope` states
+ * no role, and has none to narrow by: dispatch already settled who may call it.
+ *
+ * The visible range is one function rather than one per op: `transcript_read`
+ * and the file ops narrow by the same rule, and two spellings of it could come
+ * apart while both still passing their own tests. */
+export function sees(sid: Sid, viewer: Viewer): boolean {
+  switch (viewer.role) {
+    case undefined:
+      return true;
+    case "user":
+      return true;
+    case "session":
+      return viewer.sid === sid;
+    default:
+      return false;
+  }
+}
+
+export interface PathArgs {
+  readonly sid: Sid;
+  readonly kind: FileKind;
+  readonly path: string;
+}
+
+export interface DirArgs {
+  readonly sid: Sid;
+  readonly kind: FileKind;
+  readonly path?: string;
+}
+
+/** The directory `file_write` writes into, relative to the working directory. */
+const INBOX = join("docs", "inbox");
+
+const KINDS = ["contained", "workspace", "external"] as const;
+
+/** What the filesystem calls a path, whether or not it is there yet.
+ *
+ * A path that does not exist is resolved as far as its parent and given its own
+ * last segment back, so a file about to be created is decided by where it would
+ * land rather than being refused for not being there. A parent that does not
+ * resolve either leaves the path as written, which no surface admits. */
+export function canonical(path: string): string {
+  const absolute = resolve(path);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    const parent = dirname(absolute);
+    if (parent === absolute) return absolute;
+    try {
+      return join(realpathSync(parent), basename(absolute));
+    } catch {
+      return absolute;
+    }
+  }
+}
+
+/** Whether a resolved path is the root or below it. Shared with the launcher,
+ * whose roots come from config rather than from a session: what "inside" means
+ * is the same question, and two spellings of it could come apart. */
+export function within(path: string, root: string): boolean {
+  return path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+
+/** A contained path as the contract states it: relative to the root, with the
+ * root itself the empty string. */
+function relativeTo(root: string, real: string): string {
+  return real === root ? "" : real.slice(root.length + 1);
+}