@ccmsg/cli 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",

package/src/auth/admin.ts

@@ -51,7 +51,10 @@ export interface Administered {
 }
 
 /** Run one administrative request. */
-export function handleAdmin(at: Administered, request: AdminRequest): DispatchResult {
+export async function handleAdmin(
+  at: Administered,
+  request: AdminRequest,
+): Promise<DispatchResult> {
   const auth = at.auth;
   try {
     switch (request.admin) {
@@ -77,7 +80,7 @@ export function handleAdmin(at: Administered, request: AdminRequest): DispatchRe
       case "passkey_list":
         return reply(request.request_id, { credentials: auth.list() });
       case "passkey_remove": {
-        const { closed } = auth.remove(request.sub);
+        const { closed } = await auth.remove(request.sub);
         return reply(request.request_id, { sub: request.sub, closed });
       }
     }

package/src/auth/auth.ts

@@ -316,8 +316,8 @@ export class Auth {
   }
 
   /** Remove one person: the tombstones, and every connection they hold. */
-  remove(sub: Subject): { records: AuthRecord[]; closed: number } {
-    const records = this.deps.records.remove(sub);
+  async remove(sub: Subject): Promise<{ records: AuthRecord[]; closed: number }> {
+    const records = await this.deps.records.remove(sub);
     return { records, closed: this.disconnect(sub) };
   }
 
@@ -340,8 +340,8 @@ export class Auth {
   }
 
   /** Take what a peer wrote on `auth.records`, and act on the removals in it. */
-  merge(records: readonly AuthRecord[]): void {
-    const { removed } = this.deps.records.merge(records);
+  async merge(records: readonly AuthRecord[]): Promise<void> {
+    const { removed } = await this.deps.records.merge(records);
     for (const sub of removed) this.disconnect(sub);
   }
 
@@ -479,7 +479,7 @@ export class Auth {
       ...(from.ip === undefined ? {} : { registered_ip: from.ip }),
       ...(from.userAgent === undefined ? {} : { registered_user_agent: from.userAgent }),
     };
-    this.deps.records.write(credentialKey(claims.sub, verified.credentialId), record, at);
+    await this.deps.records.write(credentialKey(claims.sub, verified.credentialId), record, at);
     return this.mint(claims.sub);
   }
 
@@ -589,7 +589,7 @@ export class Auth {
     );
     await this.#spendAnywhere(args.challenge);
     const at = this.#now();
-    this.deps.records.write(
+    await this.deps.records.write(
       credentialKey(record.sub, record.credential_id),
       {
         ...record,
@@ -654,7 +654,7 @@ export class Auth {
   // --- tokens (DR-0001 §2.4) ---
 
   /** Make a family for this person, minted by this instance. */
-  mint(sub: Subject): MintedSession {
+  async mint(sub: Subject): Promise<MintedSession> {
     const at = this.#now();
     const family: TokenFamily = {
       kind: "token_family",
@@ -664,7 +664,7 @@ export class Auth {
       refresh: { value: token(), expires_at: at + REFRESH_TTL_MS },
     };
     const id = randomBytes(8).toString("hex");
-    this.deps.records.write(familyKey(sub, id), family, at);
+    await this.deps.records.write(familyKey(sub, id), family, at);
     return { session: { sub, access: family.access }, refresh: family.refresh };
   }
 
@@ -698,7 +698,7 @@ export class Auth {
       } satisfies AuthRotateArgs)) as AuthRotateResult;
       return { session: { sub: answer.sub, access: answer.access }, refresh: answer.refresh };
     }
-    const rotated = this.rotate(value, from);
+    const rotated = await this.rotate(value, from);
     return { session: { sub: rotated.sub, access: rotated.access }, refresh: rotated.refresh };
   }
 
@@ -714,7 +714,7 @@ export class Auth {
     const owner = this.deps.records.owning(value, digestOf(value));
     if (owner === undefined) return;
     if (owner.body.iss === this.deps.self) {
-      this.#failReused(value);
+      await this.#failReused(value);
       return;
     }
     try {
@@ -730,10 +730,10 @@ export class Auth {
 
   /** Rotate a family this instance minted. The one writer's own operation, and
    * what `auth.rotate` runs on its behalf. */
-  rotate(value: Base64Url, from: RefreshFrom = {}): AuthRotateResult {
+  async rotate(value: Base64Url, from: RefreshFrom = {}): Promise<AuthRotateResult> {
     const held = this.deps.records.byRefresh(value);
     if (held === undefined) {
-      this.#failReused(value);
+      await this.#failReused(value);
       throw new OpError("auth_invalid", "この refresh token は使えません");
     }
     if (held.body.iss !== this.deps.self) {
@@ -777,7 +777,7 @@ export class Auth {
       // holds wherever the reused value is presented (contract, `TokenFamily`).
       retired: retire(held.body, at),
     };
-    this.deps.records.write(held.key, rotated, at);
+    await this.deps.records.write(held.key, rotated, at);
     return { sub: rotated.sub, access: rotated.access, refresh: rotated.refresh };
   }
 
@@ -789,7 +789,7 @@ export class Auth {
    * before it past its grace, and any generation this instance rotated away
    * while it has been running. A value older than what any of those covers
    * matches nothing and is refused as a stranger. */
-  #failReused(value: Base64Url): void {
+  async #failReused(value: Base64Url): Promise<void> {
     const digest = digestOf(value);
     const now = this.#now();
     for (const held of this.deps.records.families()) {
@@ -805,7 +805,7 @@ export class Auth {
       this.deps.log?.("a refresh token was reused after it was rotated away", {
         sub: held.body.sub,
       });
-      this.deps.records.fail(held.key);
+      await this.deps.records.fail(held.key);
       // The tokens are gone, and so is what they were holding open: a
       // connection that outlived the family it was admitted on would be the
       // stolen token still working.
@@ -932,7 +932,7 @@ export function authHandlers(auth: Auth) {
       // the URL and the count of tries against it (DR-0001 §2.2).
       return { kind: "register", claims: auth.resolveRegistration(args.token, args.code) };
     },
-    "auth.rotate": (input: HandlerInput): AuthRotateResult => {
+    "auth.rotate": (input: HandlerInput): Promise<AuthRotateResult> => {
       const args = input.args as unknown as AuthRotateArgs;
       // The receiving instance's account of the person, taken as stated: it is
       // the only one that saw them, and `last_refresh` is a hint nothing is

package/src/auth/records.ts

@@ -1,5 +1,6 @@
-import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import type {
   AuthRecord,
   AuthTombstone,
@@ -81,9 +82,13 @@ export interface RecordsDeps {
  * and in the authenticator, and losing a family logs its person out. */
 export class AuthRecords {
   readonly #records = new Map<string, AuthRecord>();
-  #loaded = false;
 
-  constructor(private readonly deps: RecordsDeps) {}
+  /** The writes already asked for, as one chain. */
+  #writing: Promise<void> = Promise.resolve();
+
+  constructor(private readonly deps: RecordsDeps) {
+    this.#read();
+  }
 
   #now(): Timestamp {
     return (this.deps.now ?? Date.now)();
@@ -94,7 +99,6 @@ export class AuthRecords {
    * Answers whether the set moved, which is what decides whether the change is
    * worth writing down and passing on. */
   accept(record: AuthRecord): boolean {
-    this.#load();
     const held = this.#records.get(record.key);
     if (held !== undefined && held.updated_at >= record.updated_at) return false;
     if (this.#refused(record)) return false;
@@ -135,13 +139,18 @@ export class AuthRecords {
    * millisecond, which a rotation and the mint before it easily do, must not
    * silently drop the second. So the instant is moved past what is held rather
    * than compared against it. */
-  write(key: string, body: AuthRecord["body"], now: Timestamp = this.#now()): boolean {
-    this.#load();
+  async write(
+    key: string,
+    body: AuthRecord["body"],
+    now: Timestamp = this.#now(),
+  ): Promise<boolean> {
     const held = this.#records.get(key);
     const at = held === undefined ? now : Math.max(now, held.updated_at + 1);
     const record: AuthRecord = { key, updated_at: at, body };
     if (!this.accept(record)) return false;
-    this.#persist();
+    // Handed to the peers once it is written down, so no peer holds a record
+    // this instance would not have after a restart.
+    await this.#persist();
     this.deps.publish([record]);
     return true;
   }
@@ -156,7 +165,7 @@ export class AuthRecords {
    * This instance is its only writer, so a copy coming back is a copy of an
    * older state — which is exactly what a failed family looks like from a peer
    * that has not heard yet, and taking it would undo the failure. */
-  merge(records: readonly AuthRecord[]): { changed: number; removed: Subject[] } {
+  async merge(records: readonly AuthRecord[]): Promise<{ changed: number; removed: Subject[] }> {
     let changed = 0;
     const removed: Subject[] = [];
     for (const record of records) {
@@ -165,7 +174,7 @@ export class AuthRecords {
       changed += 1;
       if (record.body.kind === "tombstone") removed.push(record.body.sub);
     }
-    if (changed > 0) this.#persist();
+    if (changed > 0) await this.#persist();
     return { changed, removed };
   }
 
@@ -175,7 +184,7 @@ export class AuthRecords {
    * lengths of time. A family expires with its refresh token, so the mark over
    * it only has to outlive the longest one; a credential has no expiry of its
    * own, so the mark over it has none either (DR-0001 §2.6). */
-  remove(sub: Subject): AuthRecord[] {
+  async remove(sub: Subject): Promise<AuthRecord[]> {
     const at = this.#now();
     const credential: AuthTombstone = { kind: "tombstone", sub, deleted_at: at };
     const family: AuthTombstone = {
@@ -189,7 +198,7 @@ export class AuthRecords {
       { key: familyPrefix(sub), updated_at: at, body: family },
     ];
     for (const mark of marks) this.accept(mark);
-    this.#persist();
+    await this.#persist();
     this.deps.publish(marks);
     return marks;
   }
@@ -197,13 +206,11 @@ export class AuthRecords {
   /** Whether this subject has been removed, which is what a registration for
    * one has to be refused by. */
   removed(sub: Subject): boolean {
-    this.#load();
     const held = this.#records.get(credentialPrefix(sub));
     return held?.body.kind === "tombstone";
   }
 
   credentials(): CredentialRecord[] {
-    this.#load();
     const found: CredentialRecord[] = [];
     for (const record of this.#records.values()) {
       if (record.body.kind === "credential") found.push(record.body);
@@ -228,7 +235,6 @@ export class AuthRecords {
   }
 
   families(): { key: string; body: TokenFamily }[] {
-    this.#load();
     const found: { key: string; body: TokenFamily }[] = [];
     for (const record of this.#records.values()) {
       if (record.body.kind === "token_family") found.push({ key: record.key, body: record.body });
@@ -275,12 +281,11 @@ export class AuthRecords {
    * the key, which is exactly what a revoked family needs. It is kept for the
    * same seven days a removal's is: past the longest refresh token, there is
    * nothing left for a returning peer to revive. */
-  fail(key: string): void {
-    this.#load();
+  async fail(key: string): Promise<void> {
     const held = this.#records.get(key);
     if (held === undefined || held.body.kind !== "token_family") return;
     const at = this.#now();
-    this.write(key, {
+    await this.write(key, {
       kind: "tombstone",
       sub: held.body.sub,
       deleted_at: at,
@@ -306,7 +311,6 @@ export class AuthRecords {
 
   /** Every record, for the snapshot a peer's subscription is answered with. */
   all(): AuthRecord[] {
-    this.#load();
     this.#expire();
     return [...this.#records.values()];
   }
@@ -330,9 +334,19 @@ export class AuthRecords {
     }
   }
 
-  #load(): void {
-    if (this.#loaded) return;
-    this.#loaded = true;
+  /** Settle once every write asked for so far has landed. What a stop waits on
+   * before it lets go of the config home (DESIGN §8.5 step 4). */
+  async flush(): Promise<void> {
+    await this.#writing;
+  }
+
+  /** The file, read as this is built — before the instance is accepting
+   * anything, so nobody is waiting on it (DR-0015). Reading it when the first
+   * authentication asked would put the read inside the turn that answers it,
+   * and the `auth.records` snapshot is answered from what is held rather than
+   * from a promise. A file that is not there is an instance nobody has
+   * registered against, which is what an empty set says. */
+  #read(): void {
     let text: string;
     try {
       text = readFileSync(this.#file(), "utf8");
@@ -356,21 +370,34 @@ export class AuthRecords {
     this.#expire();
   }
 
-  #persist(): void {
+  /** The set as it stands, written whole.
+   *
+   * The body is taken here, before anything is awaited, so what is written is
+   * the set as it was when the change was answered; the writes are chained so
+   * that two of them cannot be racing for one file and the older land last
+   * (DR-0015). */
+  #persist(): Promise<void> {
     this.#expire();
-    mkdirSync(this.deps.dir, { recursive: true, mode: 0o700 });
-    const file = this.#file();
-    const temporary = `${file}.ccmsg-${String(process.pid)}-${String(Date.now())}`;
-    // The set holds tokens, so the file is the instance's own to read: it is
-    // created with the mode rather than fixed afterwards, so there is no
-    // instant at which it stands readable by anyone else.
-    writeFileSync(temporary, JSON.stringify([...this.#records.values()]), { mode: 0o600 });
-    try {
-      renameSync(temporary, file);
-    } catch (cause) {
-      unlinkSync(temporary);
-      throw cause;
-    }
+    const body = JSON.stringify([...this.#records.values()]);
+    const written = this.#writing.then(async () => {
+      await mkdir(this.deps.dir, { recursive: true, mode: 0o700 });
+      const file = this.#file();
+      const temporary = `${file}.ccmsg-${String(process.pid)}-${String(Date.now())}`;
+      // The set holds tokens, so the file is the instance's own to read: it is
+      // created with the mode rather than fixed afterwards, so there is no
+      // instant at which it stands readable by anyone else.
+      await writeFile(temporary, body, { mode: 0o600 });
+      try {
+        await rename(temporary, file);
+      } catch (cause) {
+        await unlink(temporary);
+        throw cause;
+      }
+    });
+    // The chain carries the order, not the outcome: a write that failed is
+    // answered to its own caller, and the ones behind it still go.
+    this.#writing = written.catch(() => {});
+    return written;
   }
 
   #file(): string {
@@ -383,11 +410,6 @@ export function recordsDir(stateDir: string): string {
   return join(stateDir, AUTH_DIR);
 }
 
-/** The parent of a path, made when a caller wants to write into it. */
-export function ensureDir(file: string): void {
-  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
-}
-
 /** Whether an instance is the one allowed to write this family (DR-0001 §2.4). */
 export function writes(family: TokenFamily, self: InstanceId): boolean {
   return family.iss === self;

package/src/daemon/supervise.ts

@@ -275,18 +275,26 @@ export class Supervisor {
       }
       return await op(unit);
     }
-    const answers: (T | { dir: string; error: { code: string; msg: string } })[] = [];
     // Taken as a list first: each step below waits, and a request arriving in
     // between may add or remove one — what `--all` answers about is the set as
     // it stood when it was asked.
     const units = Array.from(this.#units.values());
-    for (const unit of units) {
-      try {
-        answers.push(await op(unit));
-      } catch (cause) {
-        if (!(cause instanceof CommandError)) throw cause;
-        answers.push({ dir: unit.target.dir, error: { code: cause.code, msg: cause.message } });
+    // Every config home at once. Each is a child process of its own, and a
+    // start that waits on one of them serving is not a reason the next one has
+    // not been asked to start yet (DR-0015). The answers are still the units in
+    // the order they were taken, because that is the list the caller asked
+    // about.
+    const settled = await Promise.allSettled(units.map((unit) => op(unit)));
+    const answers: (T | { dir: string; error: { code: string; msg: string } })[] = [];
+    for (const [index, outcome] of settled.entries()) {
+      if (outcome.status === "fulfilled") {
+        answers.push(outcome.value);
+        continue;
       }
+      const cause: unknown = outcome.reason;
+      if (!(cause instanceof CommandError)) throw cause;
+      const unit = units[index] as Supervised;
+      answers.push({ dir: unit.target.dir, error: { code: cause.code, msg: cause.message } });
     }
     return answers;
   }

package/src/files/containment.ts

@@ -1,4 +1,5 @@
 import { realpathSync } from "node:fs";
+import { realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import type { FileKind, Role, Sid } from "@ccmsg/protocol";
 import { OpError } from "../dispatch/index.ts";
@@ -69,11 +70,11 @@ 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 {
+  async locate(args: PathArgs, viewer: Viewer = {}): Promise<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 };
+    const named = await this.absolute(args, roots);
+    const real = await canonical(named);
+    return { ...(await this.admit(args.kind, real, roots)), named };
   }
 
   /** An absolute path with no kind: which surface admits it, if any.
@@ -81,7 +82,7 @@ export class Containment {
    * 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 {
+  async identify(sid: Sid, path: string, viewer: Viewer = {}): Promise<Located | undefined> {
     let roots: SessionRoots;
     try {
       roots = this.rootsFor(sid, viewer);
@@ -90,10 +91,10 @@ export class Containment {
     }
     if (!isAbsolute(path)) return undefined;
     const named = resolve(path);
-    const real = canonical(named);
+    const real = await canonical(named);
     for (const kind of KINDS) {
       try {
-        return { ...this.admit(kind, real, roots), named };
+        return { ...(await this.admit(kind, real, roots)), named };
       } catch {
         // The next surface may admit it; running out of surfaces is the miss.
       }
@@ -106,15 +107,15 @@ export class Containment {
    * 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 {
+  async inbox(sid: Sid, path: string, viewer: Viewer = {}): Promise<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 base = await canonical(cwd);
     const named = resolve(base, path);
-    const real = canonical(named);
+    const real = await canonical(named);
     const inbox = join(base, INBOX);
     if (!within(real, inbox)) {
       throw new OpError("path_not_writable", `only ${INBOX}/ takes a written file`);
@@ -123,7 +124,7 @@ export class Containment {
   }
 
   /** The directory a listing or a walk starts from. */
-  root(args: DirArgs, viewer: Viewer = {}): Located {
+  root(args: DirArgs, viewer: Viewer = {}): Promise<Located> {
     return this.locate({ sid: args.sid, kind: args.kind, path: args.path ?? "" }, viewer);
   }
 
@@ -142,13 +143,13 @@ export class Containment {
   }
 
   /** Turn an op's `path` into an absolute one, in the shape its kind states. */
-  private absolute(args: PathArgs, roots: SessionRoots): string {
+  private async absolute(args: PathArgs, roots: SessionRoots): Promise<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}`);
+      return resolve(await canonical(root), `.${sep}${args.path}`);
     }
     if (!isAbsolute(args.path)) {
       throw new OpError("path_forbidden", `a ${args.kind} path is absolute`);
@@ -159,17 +160,21 @@ export class Containment {
   /** 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"> {
+  private async admit(
+    kind: FileKind,
+    real: string,
+    roots: SessionRoots,
+  ): Promise<Omit<Located, "named">> {
     if (kind === "contained") {
-      const root = roots.root === undefined ? undefined : canonical(roots.root);
+      const root = roots.root === undefined ? undefined : await 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) {
+      const folders = await Promise.all(roots.workspace_folders.map(canonical));
+      if (!folders.some((folder) => within(real, folder))) {
         throw new OpError("path_forbidden", "the path is in no workspace folder of this session");
       }
       return { kind, real, path: real };
@@ -179,7 +184,9 @@ export class Containment {
     // 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);
+    const named = (await Promise.all(roots.external_files.map(canonical))).some(
+      (each) => each === real,
+    );
     if (!named) {
       throw new OpError("path_forbidden", "the path is not one this session's transcript named");
     }
@@ -234,7 +241,23 @@ const KINDS = ["contained", "workspace", "external"] as const;
  * 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 {
+export async function canonical(path: string): Promise<string> {
+  const absolute = resolve(path);
+  try {
+    return await realpath(absolute);
+  } catch {
+    const parent = dirname(absolute);
+    if (parent === absolute) return absolute;
+    try {
+      return join(await realpath(parent), basename(absolute));
+    } catch {
+      return absolute;
+    }
+  }
+}
+
+/** The synchronous form required while `session.status` states its value synchronously (DESIGN §6); an asynchronous topic value uses `canonical` as the single path. */
+export function canonicalSync(path: string): string {
   const absolute = resolve(path);
   try {
     return realpathSync(absolute);