aamio 0.6.3 → 0.7.0

package/src/node-archive.js

@@ -0,0 +1,349 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, readFile, readdir, rename, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { sha256hex } from "./aamio.js";
+
+/*
+ * What the local runtime keeps of what was said, and for how long. The
+ * service forgets a thread when it expires. A home does not, unless it is told
+ * to: archive/ holds what was read, sent and posted, decrypted, one file per
+ * channel and one JSON record per line. It is the archive aamio-python and
+ * aamio-php keep, in the same files, under the same policy in config.json:
+ * keep, which is what a home without a choice has, off, or so many days, with
+ * a ceiling on size. "Ephemeral" is about the network.
+ *
+ * Everything here works on the files of a home it is given. The runtime
+ * decides when to write and what a failure means.
+ */
+
+export const ARCHIVE_MODES = ["keep", "off", "days"];
+export const DEFAULT_POLICY = Object.freeze({ mode: "keep", days: null, max_mb: null });
+
+// What a channel may be called when its name is also a file's: letters,
+// digits, dots, dashes and underscores, starting with a letter or a digit.
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+// Names Windows takes for a device, with or without an extension after them.
+const DEVICE = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/i;
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function archiveError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+/** Whether a label can be a file's name as it is: nothing in it leaves the folder or names a device. */
+export function isSafeLabel(label) {
+  return typeof label === "string" && SAFE_NAME.test(label) && !DEVICE.test(label) && !label.endsWith(".");
+}
+
+/**
+ * The file a channel's records go in, without its extension. The label, when
+ * it can be a file's name. A label that cannot, one another runtime let
+ * through with a path or a device in it, is kept under a name made of its
+ * hash, inside the folder: written as it stood, ../../notes put what was read
+ * on that channel outside the home, in a file no policy ever pruned.
+ */
+export function archiveName(label) {
+  return isSafeLabel(label) ? label : "channel-" + sha256hex(String(label)).slice(0, 16);
+}
+
+/**
+ * The text of a file of the home, past a byte order mark at its start. An
+ * editor on Windows may leave one in front of a file that is whole otherwise.
+ * The state the runtime keeps was read past it, and the rest of the home was
+ * not: a policy file with a mark was read as no choice at all, so an archive
+ * told to keep nothing was kept again, and nothing said so (a check of 12
+ * November 2026). The three runtimes read the home's own files past the mark.
+ * The key is not one of them: it holds the seed and nothing else. And what
+ * comes from outside the home, a message, a card, an add-on's answer, is read
+ * as it is.
+ */
+export const pastMark = (text) => (text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+
+/**
+ * A file of the home as text, past one byte order mark, or an error when it
+ * is not UTF-8. Read with replacement characters, a policy file with one
+ * stray byte was a choice here and no choice in the other two runtimes, and
+ * a record written back by a prune came back changed (a check of 12 November
+ * 2026). The decoder drops one mark itself.
+ */
+export async function homeText(path) {
+  return new TextDecoder("utf-8", { fatal: true }).decode(await readFile(path));
+}
+
+/** The lines of a file as bytes, the first one past a byte order mark, each with the text it holds when that is UTF-8. */
+async function rawLines(path) {
+  let bytes = await readFile(path);
+  if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) bytes = bytes.subarray(3);
+  const lines = [];
+  let start = 0;
+  while (start < bytes.length) {
+    let end = bytes.indexOf(0x0a, start);
+    if (end === -1) end = bytes.length;
+    const raw = bytes.subarray(start, end);
+    let text = null;
+    try {
+      text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw);
+    } catch {
+      text = null;
+    }
+    lines.push({ raw, text });
+    start = end + 1;
+  }
+  return lines;
+}
+
+/** The archive policy of a home. No file, or one that says nothing usable, means keep, which is what every version did. */
+export async function readPolicy(home) {
+  let stored = null;
+  try {
+    const config = JSON.parse(await homeText(join(home, "config.json")));
+    stored = isObject(config) ? config.archive : null;
+  } catch {
+    stored = null;
+  }
+  const policy = { ...DEFAULT_POLICY };
+  if (isObject(stored) && ARCHIVE_MODES.includes(stored.mode)) {
+    policy.mode = stored.mode;
+    if (Number.isInteger(stored.days) && stored.days > 0) policy.days = stored.days;
+    if (typeof stored.max_mb === "number" && Number.isFinite(stored.max_mb) && stored.max_mb > 0) policy.max_mb = stored.max_mb;
+  }
+  if (policy.mode === "days" && !policy.days) policy.mode = "keep";
+  return policy;
+}
+
+/** keep, off or days:N, as typed on the command line, with a ceiling in megabytes when one is given. Throws invalid_archive. */
+export function parsePolicy(text, maxMb = null) {
+  const said = String(text ?? "").trim().toLowerCase();
+  const policy = { ...DEFAULT_POLICY };
+  const days = /^days:([0-9]{1,6})$/.exec(said);
+  if (said === "keep" || said === "off") policy.mode = said;
+  else if (days && Number(days[1]) > 0) Object.assign(policy, { mode: "days", days: Number(days[1]) });
+  else throw archiveError("invalid_archive", `the archive is keep, off or days:N with N a whole number of days, not ${JSON.stringify(said)}`);
+  if (maxMb !== null && maxMb !== undefined) {
+    if (typeof maxMb !== "number" || !Number.isFinite(maxMb) || maxMb <= 0) throw archiveError("invalid_archive", "--max-mb is a size above zero");
+    policy.max_mb = maxMb;
+  }
+  return policy;
+}
+
+/** One sentence a person or a model can act on. The words are aamio-python's. */
+export function describePolicy(policy) {
+  const size = policy.max_mb ? ` and never more than ${policy.max_mb} MB, oldest first out` : "";
+  if (policy.mode === "off") {
+    return "Nothing decrypted is written to this machine. The key, the read keys of open threads and the outbox with sealed bytes still are, since the runtime cannot work without them.";
+  }
+  if (policy.mode === "days") {
+    return `Decrypted messages and receipts are kept in archive/ for ${policy.days} days${size}, then removed. The service itself keeps nothing past a thread's expiry: this archive is yours, on this machine.`;
+  }
+  return `Decrypted messages and receipts are kept in archive/ until you remove them${size}. The service itself keeps nothing past a thread's expiry: this archive is yours, on this machine. \`aamio archive days:30\` gives it a lifetime, \`aamio archive off\` stops it.`;
+}
+
+/** After a rename the new name is on disk only when the folder is. Windows has no such call for a folder, and journals the rename. */
+async function syncFolder(folder) {
+  if (process.platform === "win32") return;
+  try {
+    const handle = await open(folder, constants.O_RDONLY);
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    // The files are in place. Only that the folder outlives a power cut is not known.
+  }
+}
+
+/**
+ * One record at the end of a channel's file, private from its first byte and
+ * on the disk before this returns. A crash in the middle of a write leaves a
+ * last line with no end: appended to as it was, the next record became part
+ * of that line, and a reader passed over both.
+ */
+export async function appendRecord(home, name, record) {
+  const folder = join(home, "archive");
+  await mkdir(folder, { recursive: true, mode: 0o700 });
+  const path = join(folder, name + ".jsonl");
+  let torn = false;
+  try {
+    const existing = await open(path, "r");
+    try {
+      const { size } = await existing.stat();
+      if (size > 0) {
+        const last = Buffer.alloc(1);
+        await existing.read(last, 0, 1, size - 1);
+        torn = last[0] !== 10;
+      }
+    } finally {
+      await existing.close();
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const handle = await open(path, "a", 0o600);
+  try {
+    await handle.writeFile((torn ? "\n" : "") + JSON.stringify(record) + "\n", "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * The lines of a file as they are, each with the time its record gives, or
+ * null when it gives none. A line that is not UTF-8 gives none, and is kept
+ * byte for byte: what cannot be told old is not thrown away as old, and not
+ * written back changed either.
+ */
+async function linesOf(path) {
+  const found = [];
+  for (const { raw, text } of await rawLines(path)) {
+    if (text !== null && !text.trim()) continue;
+    if (text === null && !raw.length) continue;
+    let at = null;
+    try {
+      const record = text === null ? null : JSON.parse(text);
+      if (isObject(record) && typeof record.at === "number" && Number.isFinite(record.at)) at = record.at;
+    } catch {
+      at = null;
+    }
+    found.push({ at, line: Buffer.concat([raw, Buffer.from("\n")]) });
+  }
+  return found;
+}
+
+/** The files of the archive, by the name before .jsonl, sorted. An archive that is not there has none. */
+export async function archiveNames(home) {
+  let names;
+  try {
+    names = await readdir(join(home, "archive"));
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  return names.filter((name) => name.endsWith(".jsonl")).map((name) => name.slice(0, -".jsonl".length)).sort();
+}
+
+/**
+ * The records of one kind a file holds, oldest first. A file that is not
+ * there holds none: an empty archive is a home that was told to keep nothing,
+ * or has read nothing yet. A line that is no record is passed over.
+ */
+export async function archivedRecords(home, name, kind) {
+  let lines;
+  try {
+    lines = await rawLines(join(home, "archive", name + ".jsonl"));
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "EISDIR") return [];
+    throw error;
+  }
+  const found = [];
+  for (const { text } of lines) {
+    // A line that is not UTF-8 is no record, as one cut short by a crash is not.
+    if (text === null || !text.trim()) continue;
+    try {
+      const record = JSON.parse(text);
+      if (isObject(record) && record.kind === kind) found.push(record);
+    } catch {
+      // A line cut short by a crash, or not written by a runtime: it is no record.
+    }
+  }
+  return found;
+}
+
+/**
+ * Removes what the policy no longer keeps: records past their days, and the
+ * oldest ones past the ceiling. A record that cannot be dated is kept: what
+ * cannot be told old is not thrown away as old. Each file that changes is
+ * written beside itself and renamed over, so a crash in the middle leaves the
+ * old file whole. With everything, the whole archive goes. Gives how many
+ * records went and how many bytes are left.
+ */
+export async function pruneArchive(home, policy, { now = Date.now() / 1000, everything = false } = {}) {
+  const folder = join(home, "archive");
+  const names = await archiveNames(home);
+  if (!names.length) return { removed: 0, bytes: 0 };
+  let removed = 0;
+  if (everything) {
+    for (const name of names) {
+      const path = join(folder, name + ".jsonl");
+      removed += (await linesOf(path)).length;
+      await unlink(path);
+    }
+    await syncFolder(folder);
+    return { removed, bytes: 0 };
+  }
+  const horizon = policy.mode === "days" && policy.days ? now - policy.days * 86400 : null;
+  const kept = new Map();
+  const before = new Map();
+  for (const name of names) {
+    const all = await linesOf(join(folder, name + ".jsonl"));
+    before.set(name, all.length);
+    kept.set(name, all.filter((record) => !(horizon !== null && record.at !== null && record.at < horizon)));
+    removed += all.length - kept.get(name).length;
+  }
+  const ceiling = policy.max_mb ? Math.floor(policy.max_mb * 1024 * 1024) : null;
+  if (ceiling !== null) {
+    let total = 0;
+    const oldest = [];
+    for (const [name, records] of kept) {
+      for (const [index, record] of records.entries()) {
+        const size = record.line.length;
+        total += size;
+        oldest.push({ at: record.at ?? now, name, index, size });
+      }
+    }
+    oldest.sort((a, b) => a.at - b.at || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0) || a.index - b.index);
+    const gone = new Map();
+    for (const record of oldest) {
+      if (total <= ceiling) break;
+      total -= record.size;
+      if (!gone.has(record.name)) gone.set(record.name, new Set());
+      gone.get(record.name).add(record.index);
+      removed += 1;
+    }
+    for (const [name, indexes] of gone) kept.set(name, kept.get(name).filter((_, index) => !indexes.has(index)));
+  }
+  let left = 0;
+  for (const [name, records] of kept) {
+    const text = Buffer.concat(records.map((record) => record.line));
+    left += text.length;
+    if (records.length === before.get(name)) continue;
+    const path = join(folder, name + ".jsonl");
+    const temporary = join(folder, `${name}.jsonl.${randomUUID()}.tmp`);
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+      try {
+        await handle.writeFile(text);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temporary, path);
+    } catch (error) {
+      await unlink(temporary).catch(() => {});
+      throw error;
+    }
+  }
+  if (removed) await syncFolder(folder);
+  return { removed, bytes: left };
+}
+
+/** What the archive holds now, and what the policy means, in the shape aamio-python's archive command answers. */
+export async function archiveStatus(home, policy) {
+  let files = 0;
+  let bytes = 0;
+  let oldest = null;
+  for (const name of await archiveNames(home)) {
+    const path = join(home, "archive", name + ".jsonl");
+    files += 1;
+    bytes += (await stat(path)).size;
+    for (const record of await linesOf(path)) {
+      if (record.at !== null && (oldest === null || record.at < oldest)) oldest = record.at;
+    }
+  }
+  return { policy, means: describePolicy(policy), files, bytes, oldest_at: oldest === null ? null : Math.floor(oldest) };
+}

package/src/node-doctor.js

@@ -0,0 +1,292 @@
+// aamio doctor for the Node runtime: one answer to three questions, as aamio-python and aamio-php give it. Does this
+// client fit the service, who can read the home, and what is kept. Nothing here is a guess reported as a finding:
+// what could not be checked says so, and is never called fine. The compatibility check and the check of the home are
+// aamio-python's (aamio/compat.py and aamio/storage.py), with the same verdicts and the same words, so the three
+// runtimes say the same of one home and one service.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+
+// ------------------------------------------------------------------ compatibility
+
+export const PROTOCOL = 1;
+
+// Without these there is nothing this client can do.
+export const NEEDS = ["threads", "signing", "long-poll"];
+
+// With these it does more. What each one is for, so a missing one can be explained to whoever asks.
+export const USES = {
+  allowlist: "opening an inbox only named keys, or only signed messages, may write to",
+  reset: "being told when a cursor belongs to an earlier thread at the address",
+  gate: "reading what an inbox asks of writers before sending",
+  pow: "doing the proof of work an inbox asks for",
+  receipts: "taking a receipt for a thread",
+  presence: "publishing and looking up where a key can be reached",
+  board: "the open board of needs and offers",
+  scopes: "unlisted posts for a group of agents",
+  "read-limits": "asking for a small answer with X-Limit and X-Max-Bytes, so a busy thread does not arrive all at once",
+  "sealed-claim": "having the service refuse a message that calls itself sealed and is readable",
+  "canonical-keys": "one key being one string, so allowlists and a reader's own check compare the same strings",
+};
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * Whether this client and a service fit, decided from what the service says it can do in its descriptor, as read
+ * from /.well-known/aamio.json. full: every capability this client uses is declared; partial: the client works and
+ * some of what it offers will not; refuse: another protocol, or something the client cannot work without is missing.
+ */
+export function compatCheck(descriptor) {
+  const declared = isObject(descriptor) ? descriptor.protocol : null;
+  const details = { client_protocol: PROTOCOL, service_version: isObject(descriptor) ? (descriptor.version ?? null) : null };
+  if (!isObject(declared) || !Array.isArray(declared.capabilities)) {
+    return Object.assign(details, {
+      verdict: "partial",
+      why: "This service does not declare a protocol or its capabilities, as services before 0.7.1 did not. The client works with those as far as it has been tested, and cannot tell from here what is missing.",
+      missing: [],
+    });
+  }
+  details.service_protocol = declared.version ?? null;
+  const offered = new Set(declared.capabilities.map((item) => String(item)));
+  if (declared.version !== PROTOCOL) {
+    return Object.assign(details, { verdict: "refuse", missing: [], why: `The service speaks protocol ${JSON.stringify(declared.version ?? null)} and this client speaks ${PROTOCOL}. Use a client made for that protocol.` });
+  }
+  const lacking = NEEDS.filter((name) => !offered.has(name));
+  if (lacking.length) {
+    return Object.assign(details, { verdict: "refuse", missing: lacking, why: `The service does not offer ${lacking.join(", ")}, and this client cannot work without it.` });
+  }
+  const missing = Object.keys(USES).filter((name) => !offered.has(name));
+  details.missing = missing;
+  details.unknown_to_this_client = [...offered].filter((name) => !NEEDS.includes(name) && !(name in USES)).sort();
+  if (missing.length) {
+    return Object.assign(details, { verdict: "partial", why: "The client works with this service. Not offered there: " + missing.map((name) => `${name} (${USES[name]})`).join("; ") + "." });
+  }
+  return Object.assign(details, { verdict: "full", why: "Everything this client uses is offered by this service." });
+}
+
+// ------------------------------------------------------------------ who can read the home
+
+// Who may have access to a private folder on Windows without it being a finding: the system itself, the
+// administrators of the machine, and whoever created or owns the file. Everything else is somebody else.
+const WINDOWS_EXPECTED = new Set(["S-1-5-18", "S-1-5-32-544", "S-1-3-0", "S-1-3-4"]);
+
+// SDDL writes the well known accounts as two letters and everyone else as a full SID. An alias not here stays as
+// the two letters it was written as, which reads as an account nobody recognises and is reported: the safe direction
+// for a check about who can read your keys.
+const SDDL_SIDS = {
+  BA: "S-1-5-32-544", SY: "S-1-5-18", CO: "S-1-3-0", CG: "S-1-3-1", WD: "S-1-1-0", AU: "S-1-5-11", BU: "S-1-5-32-545",
+  BG: "S-1-5-32-546", PU: "S-1-5-32-547", IU: "S-1-5-4", NU: "S-1-5-2", AN: "S-1-5-7", LS: "S-1-5-19", NS: "S-1-5-20",
+  RC: "S-1-5-12", OW: "S-1-3-4", AC: "S-1-15-2-1", AO: "S-1-5-32-548", SO: "S-1-5-32-549", PO: "S-1-5-32-550",
+  BO: "S-1-5-32-551", RE: "S-1-5-32-552", RU: "S-1-5-32-554", SU: "S-1-5-6", PS: "S-1-5-10", ED: "S-1-5-9",
+};
+
+const WINDOWS_NAMES = {
+  "S-1-1-0": "Everyone",
+  "S-1-5-11": "Authenticated Users",
+  "S-1-5-32-545": "Users",
+  "S-1-5-32-546": "Guests",
+  "S-1-5-4": "Interactive",
+};
+
+/** Findings from `sid|rights|type` lines, one per access rule. me is the current user's SID. */
+export function windowsAclFindings(lines, me) {
+  const findings = [];
+  for (const line of lines) {
+    const parts = String(line).trim().split("|").map((part) => part.trim());
+    if (parts.length !== 3 || parts[0] === "" || parts[2].toLowerCase() !== "allow") continue;
+    const [sid, rights] = parts;
+    if (sid === me || WINDOWS_EXPECTED.has(sid)) continue;
+    const who = WINDOWS_NAMES[sid] ?? sid;
+    findings.push({ who, rights, problem: `${who} has access to this folder (${rights}), so the key and everything else in it can be read by others on this machine` });
+  }
+  return findings;
+}
+
+/**
+ * A Windows tool by its place in System32, so another whoami.exe earlier on the path is not the one asked: Git Bash
+ * puts its own first, which answers /user with a usage error, and the second way read nothing.
+ */
+function systemTool(...parts) {
+  const path = join(process.env.SystemRoot || process.env.windir || "C:\\Windows", "System32", ...parts);
+  return existsSync(path) ? path : parts[parts.length - 1];
+}
+
+function run(command, args) {
+  const done = spawnSync(command, args, { encoding: "utf8", timeout: 30_000, windowsHide: true });
+  if (done.error) throw done.error;
+  if (done.status !== 0) throw Object.assign(new Error(String(done.stderr || done.stdout || `${command} failed`).trim().slice(0, 200)), { code: "EFAILED" });
+  return done.stdout;
+}
+
+/** The folder's access rules, read with Get-Acl, and the current user's SID. */
+export function windowsRulesGetAcl(path, runner = run) {
+  const quoted = String(path).replaceAll("'", "''");
+  const script = "$me = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value; 'me|' + $me; "
+    + `(Get-Acl -LiteralPath '${quoted}').Access | ForEach-Object { `
+    + "$sid = try { $_.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value } catch { $_.IdentityReference.Value }; "
+    + "'{0}|{1}|{2}' -f $sid, $_.FileSystemRights, $_.AccessControlType }";
+  const lines = runner(systemTool("WindowsPowerShell", "v1.0", "powershell.exe"), ["-NoProfile", "-NonInteractive", "-Command", script]).split(/\r?\n/).filter((line) => line.trim());
+  const meLine = lines.find((line) => line.startsWith("me|"));
+  return { me: meLine ? meLine.slice(3).trim() : "", rules: lines.filter((line) => !line.startsWith("me|")) };
+}
+
+const unsupported = (message) => Object.assign(new Error(message), { name: "ValueError" });
+
+/** icacls writes UTF-16. Read strictly, so a file cut short is not read as a shorter list. */
+function utf16(bytes) {
+  if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) return new TextDecoder("utf-16be", { fatal: true }).decode(bytes.subarray(2));
+  const body = bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe ? bytes.subarray(2) : bytes;
+  return new TextDecoder("utf-16le", { fatal: true }).decode(body);
+}
+
+/**
+ * The same rules as Get-Acl, read with two .exe calls and no PowerShell module: whoami for the SID, and icacls for
+ * the folder's access list as SDDL, which gives SIDs where what icacls prints gives account names in the machine's
+ * language. Returns what windowsRulesGetAcl returns, so one parser reads both.
+ */
+export function windowsRulesIcacls(path, runner = run, readExport = (file) => readFileSync(file)) {
+  const fields = runner(systemTool("whoami.exe"), ["/user", "/fo", "csv", "/nh"]).trim().split(",").map((part) => part.trim().replaceAll('"', ""));
+  const me = fields.length ? fields[fields.length - 1] : "";
+  if (!me.startsWith("S-1-")) throw unsupported("whoami did not give a SID");
+  // Resolved once, so a relative path and its exported name are the same folder. icacls /save writes the final name only.
+  const target = resolve(path);
+  const folder = mkdtempSync(join(tmpdir(), "aamio-acl-"));
+  let exported;
+  try {
+    const saved = join(folder, "acl.txt");
+    runner(systemTool("icacls.exe"), [target, "/save", saved]);
+    exported = utf16(readExport(saved)).split(/\r\n|\n|\r/);
+  } finally {
+    rmSync(folder, { recursive: true, force: true });
+  }
+  if (exported.length && exported[exported.length - 1] === "") exported.pop();
+  if (exported.length !== 2 || exported[0].toLowerCase() !== basename(target).toLowerCase()) {
+    throw unsupported("icacls did not export exactly the requested folder");
+  }
+  // The complete access list, not fragments of a cut one. NO_ACCESS_CONTROL is not an empty private list. A root can
+  // carry S: as well, its integrity label, which grants nothing: only the D: rules belong here.
+  const matched = /^D:(?:P|AI|AR)*((?:\([^()]*\))*)(?:S:(?:P|AI|AR)*(?:\([^()]*\))*)?$/.exec(exported[1]);
+  if (!matched) throw unsupported("icacls wrote an incomplete or unsupported access control list");
+  const rules = [];
+  for (const [, ace] of matched[1].matchAll(/\(([^()]*)\)/g)) {
+    const parts = ace.split(";");
+    if (parts.length !== 6) throw unsupported("icacls wrote an unsupported access rule");
+    const [kind, rights, sid] = [parts[0].trim(), parts[2].trim(), parts[5].trim()];
+    if (!["A", "D"].includes(kind) || !rights || !sid || parts[3] || parts[4]) throw unsupported("icacls wrote an incomplete or unsupported access rule");
+    // A is allow, and only allow rules say who can read this. A deny rule that takes access away is not a finding.
+    if (kind === "D") continue;
+    rules.push(`${SDDL_SIDS[sid.toUpperCase()] ?? sid}|${rights}|allow`);
+  }
+  return { me, rules };
+}
+
+const errorName = (error) => error?.code === "ENOENT" ? "FileNotFoundError" : error?.code === "ETIMEDOUT" ? "TimeoutExpired" : error?.name === "ValueError" ? "ValueError" : "OSError";
+
+/**
+ * Who can read the home, as far as this platform lets us find out. private is true, false, or null when it could not
+ * be checked, and a null is never reported as a yes.
+ */
+export function homeCheck(home, { platform = process.platform, getAcl = windowsRulesGetAcl, icacls = windowsRulesIcacls } = {}) {
+  const result = { home, private: null, how: null, findings: [] };
+  let folder;
+  try {
+    folder = statSync(home);
+  } catch {
+    folder = null;
+  }
+  if (!folder || !folder.isDirectory()) {
+    result.how = "not checked: there is no such folder yet";
+    return result;
+  }
+  if (platform === "win32") {
+    result.how = "the folder's access control list, read with Get-Acl. Mode bits say nothing on Windows.";
+    let read;
+    try {
+      read = getAcl(home);
+    } catch (first) {
+      // Get-Acl lives in a PowerShell module that does not load everywhere. icacls is an .exe and needs none.
+      try {
+        read = icacls(home);
+        result.how = `the folder's access control list, read with icacls after Get-Acl was not available (${errorName(first)}). Mode bits say nothing on Windows.`;
+      } catch (second) {
+        result.how = `not checked: the access control list could not be read, by Get-Acl (${errorName(first)}) or by icacls (${errorName(second)})`;
+        result.fix = `Run \`icacls "${home}"\` and see that only you, SYSTEM and Administrators are listed.`;
+        return result;
+      }
+    }
+    result.findings = windowsAclFindings(read.rules, read.me);
+    result.private = result.findings.length === 0;
+    if (result.findings.length) result.fix = `Remove the inherited access and keep your own: icacls "${home}" /inheritance:r /grant:r "%USERNAME%":(OI)(CI)F`;
+    return result;
+  }
+  result.how = "owner and mode bits of the folder and every file in it";
+  const me = typeof process.getuid === "function" ? process.getuid() : null;
+  const visit = (path, isFolder) => {
+    let found;
+    try {
+      found = statSync(path);
+    } catch {
+      return;
+    }
+    if (me !== null && found.uid !== me) result.findings.push({ path, problem: `owned by another user (uid ${found.uid})` });
+    else if (found.mode & 0o077) result.findings.push({ path, problem: `readable by others (mode ${(found.mode & 0o777).toString(8)})` });
+    if (!isFolder) return;
+    let entries;
+    try {
+      entries = readdirSync(path, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) visit(join(path, entry.name), entry.isDirectory());
+  };
+  visit(home, true);
+  result.private = result.findings.length === 0;
+  if (result.findings.length) result.fix = `chmod -R go-rwx "${home}"`;
+  return result;
+}
+
+// ------------------------------------------------------------------ the answer
+
+/** GET a path of the service: the status and the body, and 0 with no body when no answer came. */
+async function ask(runtime, path) {
+  try {
+    const response = await runtime.client.fetch(runtime.client.base + path, { method: "GET", headers: { Accept: "application/json" }, signal: AbortSignal.timeout(15_000) });
+    const text = await response.text();
+    let body = null;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = text;
+    }
+    return { status: response.status, body };
+  } catch {
+    return { status: 0, body: null };
+  }
+}
+
+/** One answer to three questions: does this client fit the service, who can read the home, what is kept. */
+export async function doctor(runtime, version) {
+  const health = await ask(runtime, "/health");
+  const service = { host: runtime.host, reachable: health.status === 200 };
+  if (health.status === 200 && isObject(health.body)) {
+    service.version = health.body.version ?? null;
+    service.revision = health.body.revision ?? null;
+  } else {
+    service.problem = `no answer from /health (${health.status}), so nothing below about the service was checked`;
+  }
+  const descriptor = await ask(runtime, "/.well-known/aamio.json");
+  const fits = compatCheck(descriptor.status === 200 ? descriptor.body : null);
+  if (descriptor.status !== 200) {
+    fits.verdict = "unknown";
+    fits.why = `the descriptor could not be read (${descriptor.status}), so compatibility was not checked`;
+  }
+  return {
+    client: { name: "aamio-js", version, protocol: PROTOCOL },
+    service,
+    compatibility: fits,
+    storage: homeCheck(runtime.home),
+    archive: await runtime.archiveStatus(),
+    outbox_pending: runtime.outboxPending().length,
+  };
+}

package/src/node-lock.js

@@ -97,8 +97,17 @@ async function holdWithFlock(home, path, command) {
 }
 
 /** The operating system's lock on owner.lock. The holder, or null when another process holds it. */
-export async function holdOwnerLock(home, { flock = "flock", platform = process.platform } = {}) {
-  const path = join(home, OWNER_LOCK);
+export async function holdOwnerLock(home, options = {}) {
+  return holdFile(home, join(home, OWNER_LOCK), options);
+}
+
+/**
+ * The operating system's lock on one file of a home, taken the way owner.lock
+ * is taken: the holder, or null when another process holds it. The list of
+ * enabled add-ons has such a lock beside it, addons.json.lock, which
+ * aamio-python and aamio-php take as they take owner.lock.
+ */
+export async function holdFile(home, path, { flock = "flock", platform = process.platform } = {}) {
   if (platform === "win32") return holdWithOpen(home, path, WINDOWS_NO_SHARING, ["EBUSY"]);
   if (BSD.includes(platform)) return holdWithOpen(home, path, BSD_EXLOCK | constants.O_NONBLOCK, ["EAGAIN", "EWOULDBLOCK"]);
   if (platform === "linux") return holdWithFlock(home, path, flock);