aamio 0.5.5 → 0.6.0

package/src/aamio.js

@@ -198,6 +198,300 @@ export function hashPrefix(key, length = 8) {
   return keyHash(key).slice(0, length);
 }
 
+// -------------------------------------------------------------- domain keys
+//
+// Which public aamio keys a website says are its own. A site can publish them
+// at https://<domain>/.well-known/aamio-keys.json as
+// {"aamio_keys": 1, "keys": [{"key": "<43 characters>", "name": "support"}]}.
+// This is the format and nothing else: a strict parser, the match, a generator
+// for the file, and the syntax of a domain. It opens no connection and reads no
+// address book. A browser cannot see which address a name resolves to, and a
+// library has no list of websites its user agreed to, so reading a list is for
+// the caller, who also says which key is compared: the result says subject_source
+// supplied_key, and aamio-python and aamio-php have the whole check.
+//
+// Take the domain from your own records and never from the message being
+// checked: anyone can list their own key on their own site. A listed key says
+// that this exact site listed this key when it was read. It is not an identity,
+// an authority to act or proof that a message is true.
+//
+// JSON.parse keeps the last of two members of the same name without a word, so
+// it cannot hold the format's rule about duplicates, and the reader here is its
+// own. test/domain_keys_vectors.json holds what every client answers.
+
+export const DOMAIN_KEYS_VERSION = 1;
+export const DOMAIN_KEYS_PATH = "/.well-known/aamio-keys.json";
+export const DOMAIN_KEYS_MAX_BYTES = 16384;
+export const DOMAIN_KEYS_MAX_KEYS = 64;
+const DOMAIN_MAX_DEPTH = 16;
+const DOMAIN_MAX_INTEGER = 9007199254740991n;
+
+/** A list that is not version 1. reason says why, without echoing the content. */
+export class InvalidDomainKeys extends Error {
+  constructor(reason) {
+    super("invalid domain key list: " + reason);
+    this.name = "InvalidDomainKeys";
+    this.reason = reason;
+  }
+}
+
+/** A public key as aamio writes it: 32 bytes, 43 characters, one spelling only. */
+export function canonicalKey(value) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(value)) return false;
+  // A last character carrying bits past the 32 bytes decodes to the same bytes
+  // as another string; only the one an encoder writes is the key.
+  return b64url(unb64url(value)) === value;
+}
+
+/** A name a list can carry: 1 to 64 characters of a-z, 0-9, dot, underscore and dash. */
+export function validDomainKeyName(value) {
+  return typeof value === "string" && /^[a-z0-9._-]{1,64}$/.test(value);
+}
+
+/**
+ * The exact host a list is read from, in lowercase, or null. Plain ASCII names of
+ * two labels or more. No port, path, IP literal, trailing dot, underscore or
+ * space is trimmed into shape. Internationalised names, xn-- labels, wait until
+ * every client converts them the same way. www.example.org and example.org are
+ * different places, and no parent domain lends its list to a child.
+ */
+export function normaliseDomain(value) {
+  // ASCII first: toLowerCase makes a k of the Kelvin sign.
+  if (typeof value !== "string" || !/^[\x00-\x7f]*$/.test(value)) return null;
+  const domain = value.toLowerCase();
+  const labels = domain.split(".");
+  if (domain.length < 1 || domain.length > 253 || labels.length < 2) return null;
+  for (const label of labels) {
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label) || label.startsWith("xn--")) return null;
+  }
+  // A last label of digits or hex is an old spelling of an IPv4 address.
+  return /^(?:[0-9]+|0x[0-9a-f]+)$/.test(labels[labels.length - 1]) ? null : domain;
+}
+
+/** Where the list of this exact domain is, over HTTPS on the default port, or null. */
+export function domainKeysUrl(domain) {
+  const host = normaliseDomain(domain);
+  return host === null ? null : "https://" + host + DOMAIN_KEYS_PATH;
+}
+
+class DomainReader {
+  // JSON with the format's limits. Objects become a Map, so __proto__ is a member
+  // like any other, lists an Array, integers a BigInt and other numbers a number.
+  // A string holds UTF-16, so a lone surrogate stays what it is and a pair is the
+  // character it spells.
+  constructor(text) {
+    this.text = text;
+    this.at = 0;
+  }
+
+  skip() {
+    while (this.at < this.text.length && " \t\r\n".includes(this.text[this.at])) this.at++;
+  }
+
+  bad(reason = "invalid_json") {
+    return new InvalidDomainKeys(reason);
+  }
+
+  value(level) {
+    this.skip();
+    const c = this.text[this.at];
+    if (c === "{") return this.members(level);
+    if (c === "[") return this.rows(level);
+    if (c === '"') return this.string();
+    for (const [word, meaning] of [["true", true], ["false", false], ["null", null]]) {
+      if (this.text.startsWith(word, this.at)) {
+        this.at += word.length;
+        return meaning;
+      }
+    }
+    return this.number();
+  }
+
+  members(level) {
+    if (level > DOMAIN_MAX_DEPTH) throw this.bad("depth_limit");
+    this.at++;
+    const found = new Map();
+    this.skip();
+    if (this.text[this.at] === "}") {
+      this.at++;
+      return found;
+    }
+    for (;;) {
+      this.skip();
+      if (this.text[this.at] !== '"') throw this.bad();
+      const name = this.string();
+      if (found.has(name)) throw this.bad("duplicate_member");
+      this.skip();
+      if (this.text[this.at] !== ":") throw this.bad();
+      this.at++;
+      found.set(name, this.value(level + 1));
+      this.skip();
+      const next = this.text[this.at++];
+      if (next === "}") return found;
+      if (next !== ",") throw this.bad();
+    }
+  }
+
+  rows(level) {
+    if (level > DOMAIN_MAX_DEPTH) throw this.bad("depth_limit");
+    this.at++;
+    const found = [];
+    this.skip();
+    if (this.text[this.at] === "]") {
+      this.at++;
+      return found;
+    }
+    for (;;) {
+      found.push(this.value(level + 1));
+      this.skip();
+      const next = this.text[this.at++];
+      if (next === "]") return found;
+      if (next !== ",") throw this.bad();
+    }
+  }
+
+  string() {
+    const simple = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
+    this.at++;
+    let out = "";
+    for (;;) {
+      if (this.at >= this.text.length) throw this.bad();
+      const c = this.text[this.at++];
+      if (c === '"') return out;
+      if (c < " ") throw this.bad();
+      if (c !== "\\") {
+        out += c;
+        continue;
+      }
+      const escape = this.text[this.at++];
+      if (escape === "u") {
+        const digits = this.text.slice(this.at, this.at + 4);
+        if (!/^[0-9a-fA-F]{4}$/.test(digits)) throw this.bad();
+        this.at += 4;
+        out += String.fromCharCode(parseInt(digits, 16));
+      } else if (Object.hasOwn(simple, escape ?? "")) {
+        out += simple[escape];
+      } else {
+        throw this.bad();
+      }
+    }
+  }
+
+  number() {
+    const rest = this.text.slice(this.at);
+    const found = /^-?(?:0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?/.exec(rest);
+    if (found === null) throw this.bad();
+    this.at += found[0].length;
+    if (found[1] !== undefined || found[2] !== undefined) {
+      if (!Number.isFinite(Number(found[0]))) throw this.bad("non_finite_number");
+      return Number(found[0]);
+    }
+    const value = BigInt(found[0]);
+    if (value > DOMAIN_MAX_INTEGER || value < -DOMAIN_MAX_INTEGER) throw this.bad("integer_range");
+    return value;
+  }
+}
+
+/**
+ * The entries of a version 1 list, as { key } or { key, name }, from the exact
+ * bytes. A duplicate key, a duplicate member name in any object or one bad entry
+ * makes the whole document invalid: a list is never valid with the bad part left
+ * out. Throws InvalidDomainKeys.
+ */
+export function parseDomainKeys(raw) {
+  if (!(raw instanceof Uint8Array)) throw new InvalidDomainKeys("not_bytes");
+  if (raw.length > DOMAIN_KEYS_MAX_BYTES) throw new InvalidDomainKeys("body_limit");
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw);
+  } catch {
+    throw new InvalidDomainKeys("not_utf8");
+  }
+  if (text.startsWith("\ufeff")) throw new InvalidDomainKeys("byte_order_mark");
+  const reader = new DomainReader(text);
+  const value = reader.value(1);
+  reader.skip();
+  if (reader.at !== text.length) throw new InvalidDomainKeys("invalid_json");
+  if (!(value instanceof Map)) throw new InvalidDomainKeys("object_required");
+  // A BigInt and nothing looser: 1.0, 1e0 and true are not the integer 1.
+  if (value.get("aamio_keys") !== BigInt(DOMAIN_KEYS_VERSION)) throw new InvalidDomainKeys("unsupported_version");
+  const rows = value.get("keys");
+  if (!Array.isArray(rows) || rows.length > DOMAIN_KEYS_MAX_KEYS) throw new InvalidDomainKeys("invalid_keys");
+  const seen = new Set();
+  const entries = [];
+  for (const row of rows) {
+    if (!(row instanceof Map) || !canonicalKey(row.get("key"))) throw new InvalidDomainKeys("invalid_key");
+    const key = row.get("key");
+    if (seen.has(key)) throw new InvalidDomainKeys("duplicate_key");
+    seen.add(key);
+    const entry = { key };
+    // has, since a name of null is a bad name and not a missing one.
+    if (row.has("name")) {
+      if (!validDomainKeyName(row.get("name"))) throw new InvalidDomainKeys("invalid_name");
+      entry.name = row.get("name");
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+
+/**
+ * Whether this exact document lists key, and under name when one is given.
+ *
+ * status is listed, not_listed or invalid. not_listed is no evidence of fraud: a
+ * key rotated out, the wrong name or the wrong domain look the same. The document
+ * hash is of the exact bytes compared, for comparison and fault finding; the
+ * domain did not sign it. The key is the caller's to choose and to answer for,
+ * which the result says as subject_source.
+ */
+export function matchDomainKey(raw, key, name = null) {
+  const subject_source = "supplied_key";
+  if (!canonicalKey(key)) return { status: "invalid", reason: "invalid_subject_key", subject_source };
+  if (name !== null && !validDomainKeyName(name)) return { status: "invalid", reason: "invalid_requested_name", subject_source };
+  let entries;
+  try {
+    entries = parseDomainKeys(raw);
+  } catch (error) {
+    if (!(error instanceof InvalidDomainKeys)) throw error;
+    return { status: "invalid", reason: "invalid_document", detail: error.reason, subject_source };
+  }
+  const document_sha256 = sha256hex(raw);
+  for (const entry of entries) {
+    if (entry.key === key && (name === null || entry.name === name)) {
+      return { status: "listed", reason: "key_listed", matched_name: entry.name ?? null, document_sha256, subject_source };
+    }
+  }
+  return { status: "not_listed", reason: "key_or_name_not_listed", document_sha256, subject_source };
+}
+
+/**
+ * The file for a site to publish, as bytes. They are fixed, so every generator
+ * gives the same file for the same list: two spaces of indentation, aamio_keys
+ * before keys, key before name, ASCII only, and a line break at the end. An empty
+ * list is allowed, since that is how a site says it lists no key, so callers ask
+ * for it on purpose. A list this would refuse to read is refused here as well.
+ */
+export function makeDomainKeys(entries) {
+  const rows = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    if (!canonicalKey(entry?.key)) throw new InvalidDomainKeys("invalid_key");
+    if (seen.has(entry.key)) throw new InvalidDomainKeys("duplicate_key");
+    seen.add(entry.key);
+    let row = '    {\n      "key": "' + entry.key + '"';
+    if (entry.name !== undefined && entry.name !== null) {
+      if (!validDomainKeyName(entry.name)) throw new InvalidDomainKeys("invalid_name");
+      row += ',\n      "name": "' + entry.name + '"';
+    }
+    rows.push(row + "\n    }");
+  }
+  if (rows.length > DOMAIN_KEYS_MAX_KEYS) throw new InvalidDomainKeys("invalid_keys");
+  const list = rows.length === 0 ? "[]" : "[\n" + rows.join(",\n") + "\n  ]";
+  const raw = utf8('{\n  "aamio_keys": ' + DOMAIN_KEYS_VERSION + ',\n  "keys": ' + list + "\n}\n");
+  parseDomainKeys(raw);
+  return raw;
+}
+
 export const threadSigningInput = (w, bodyText) => "aamio-v1\n" + w + "\n" + sha256hex(bodyText);
 export const presenceSigningInput = (key, bodyText) => "aamio-presence-v1\n" + key + "\n" + sha256hex(bodyText);
 export const presenceDeleteSigningInput = (key, bodyText) => "aamio-presence-delete-v1\n" + key + "\n" + sha256hex(bodyText);

package/src/node-identity.js

@@ -0,0 +1,162 @@
+import { constants } from "node:fs";
+import { lstat, mkdtemp, open, rename, rmdir, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { Keys } from "./aamio.js";
+
+function identityError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+const missingHome = () => identityError("home_not_initialized", "No Aamio home exists at the selected path.");
+const badKey = () => identityError("key_unreadable", "The Aamio home must contain a readable key file with a 64-character lowercase hexadecimal seed.");
+const initFailed = () => identityError("home_init_failed", "Could not create a private Aamio home. Choose a new directory under an existing writable parent on a local disk.");
+
+function publicIdentity(keys) {
+  return { key: keys.public, hash: keys.hash, hash_prefix: keys.hash.slice(0, 8) };
+}
+
+/** Read only the public identity of a local Aamio home. No runtime or owner lock is opened. */
+export async function readIdentity(home) {
+  return publicIdentity(await readKeys(home));
+}
+
+/** The keys of a local Aamio home, for a runtime that holds the home. The seed stays in memory. */
+export async function readKeys(home) {
+  if (typeof home !== "string" || !home) throw missingHome();
+  try {
+    await lstat(home);
+  } catch (error) {
+    if (error.code === "ENOENT") throw missingHome();
+    throw badKey();
+  }
+
+  const file = join(home, "key");
+  let handle;
+  try {
+    if (!(await lstat(file)).isFile()) throw badKey();
+    handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size < 64 || stat.size > 4096) throw badKey();
+    // Bound the read even if a different process changes the file after stat().
+    const bytes = Buffer.alloc(stat.size + 1);
+    let used = 0;
+    while (used < bytes.length) {
+      const { bytesRead } = await handle.read(bytes, used, bytes.length - used, used);
+      if (bytesRead === 0) break;
+      used += bytesRead;
+    }
+    if (used !== stat.size) throw badKey();
+    const match = /^[ \t\v\r\n]*([0-9a-f]{64})[ \t\v\r\n]*$/.exec(bytes.toString("utf8", 0, used));
+    if (!match) throw badKey();
+    return Keys.fromSeedHex(match[1]);
+  } catch {
+    throw badKey();
+  } finally {
+    if (handle) await handle.close();
+  }
+}
+
+// This empty folder receives the seed only after its DACL is protected and verified.
+// The key inherits the current user's rule. No path or key is interpolated into a command.
+const windowsAcl = `
+$ErrorActionPreference = 'Stop'
+$path = $env:AAMIO_INIT_STAGE
+$me = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$acl = New-Object System.Security.AccessControl.DirectorySecurity
+$acl.SetAccessRuleProtection($true, $false)
+$inherit = [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($me, 'FullControl', $inherit, 'None', 'Allow')
+$acl.AddAccessRule($rule)
+[System.IO.Directory]::SetAccessControl($path, $acl)
+$actual = [System.IO.Directory]::GetAccessControl($path)
+$rules = $actual.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])
+if (-not $actual.AreAccessRulesProtected -or $rules.Count -ne 1 -or
+    $rules[0].IdentityReference.Value -ne $me.Value -or $rules[0].AccessControlType -ne 'Allow' -or
+    $rules[0].InheritanceFlags -ne $inherit -or $rules[0].FileSystemRights -ne 'FullControl') { exit 1 }
+`;
+
+async function protectWindowsFolder(folder) {
+  const systemRoot = process.env.SystemRoot || "C:\\Windows";
+  const powershell = join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+  await promisify(execFile)(powershell, ["-NoProfile", "-NoLogo", "-NonInteractive", "-Command", windowsAcl], {
+    windowsHide: true, timeout: 15000,
+    env: { SystemRoot: systemRoot, AAMIO_INIT_STAGE: folder },
+  });
+}
+
+async function syncFolder(folder) {
+  if (process.platform === "win32") return;
+  const directory = await open(folder, constants.O_RDONLY);
+  try {
+    await directory.sync();
+  } finally {
+    await directory.close();
+  }
+}
+
+async function discardStage(folder) {
+  // These are the only two paths this invocation created. Never walk a home or remove its locks.
+  try {
+    await unlink(join(folder, "key"));
+  } catch (error) {
+    if (error.code !== "ENOENT") throw initFailed();
+  }
+  try {
+    await rmdir(folder);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw initFailed();
+  }
+}
+
+/** Initialize an absent home, or read its existing identity. No other runtime state is written. */
+export async function initIdentity(home) {
+  if (typeof home !== "string" || !home) throw missingHome();
+  const destination = resolve(home);
+  try {
+    return await readIdentity(destination);
+  } catch (error) {
+    if (error.code !== "home_not_initialized") throw error;
+  }
+  const parent = dirname(destination);
+  let stage;
+  try {
+    stage = await mkdtemp(join(parent, ".aamio-init-"));
+    if (process.platform === "win32") await protectWindowsFolder(stage);
+    const keys = Keys.generate();
+    const keyFile = await open(join(stage, "key"), "wx", 0o600);
+    try {
+      await keyFile.writeFile(Buffer.from(keys.seed).toString("hex") + "\n", "utf8");
+      await keyFile.sync();
+    } finally {
+      await keyFile.close();
+    }
+    await syncFolder(stage);
+    try {
+      return await readIdentity(destination);
+    } catch (error) {
+      if (error.code !== "home_not_initialized") throw error;
+    }
+    // POSIX rename can replace a completely empty directory created in this last instant.
+    // It cannot replace a directory containing a key, an owner lock, or any runtime state.
+    try {
+      await rename(stage, destination);
+    } catch (moveError) {
+      try {
+        return await readIdentity(destination);
+      } catch (readError) {
+        if (readError.code === "key_unreadable") throw readError;
+        throw moveError;
+      }
+    }
+    stage = undefined;
+    await syncFolder(parent);
+    return publicIdentity(keys);
+  } catch (error) {
+    if (error.code === "key_unreadable") throw error;
+    throw initFailed();
+  } finally {
+    if (stage) await discardStage(stage);
+  }
+}

package/src/node-lock.js

@@ -0,0 +1,203 @@
+import { constants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { open, readFile, realpath, rename, unlink } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { join } from "node:path";
+import { DEFAULT_BASE } from "./aamio.js";
+
+/*
+ * One live runtime per home, whichever client it is. aamio-python and
+ * aamio-php take the operating system's lock on owner.lock for as long as they
+ * run: flock() on Linux and macOS, a lock on its first byte on Windows, which
+ * PHP's flock() covers by locking the whole file. The system lets go of it when
+ * the process ends, however it ends, so no lock outlives its owner and none is
+ * ever taken by age.
+ *
+ * Node has no flock(). Each system gets the nearest thing the other clients'
+ * lock sees, so that a home has one owner whichever client starts first:
+ *
+ *   Windows  owner.lock opened with no sharing: libuv's UV_FS_O_EXLOCK, which
+ *            Node passes through but does not name. While Python or PHP holds
+ *            the file open and locked, the open fails with EBUSY. While Node
+ *            holds it, they cannot open it, and refuse the home.
+ *   Linux    util-linux flock locks a duplicate of Node's open file descriptor
+ *            and exits. The lock stays on the shared open file description
+ *            until Node closes its handle or exits.
+ *   BSD      O_EXLOCK with the open, which is flock()'s lock, on macOS and the
+ *            BSDs. Not yet tried on a Mac.
+ *
+ * Where none of these can be had, the home is not taken: held by nobody and
+ * not by this one either, nothing proves it free.
+ */
+
+export const OWNER_LOCK = "owner.lock";
+// The pid file the other clients write beside owner.lock. It names the owner
+// in the message a second runtime gives, and os_lock says its writer held the
+// lock, so a runtime that holds the lock now knows that writer is gone.
+export const PID_FILE = "lock";
+
+// libuv opens the file with no sharing for this flag on Windows.
+const WINDOWS_NO_SHARING = 0x10000000;
+// BSD's O_EXLOCK, the same value on macOS, FreeBSD and OpenBSD.
+const BSD_EXLOCK = 0x20;
+const BSD = ["darwin", "freebsd", "openbsd"];
+
+// Homes this process holds, for a plainer message when it asks twice.
+const held = new Set();
+
+function lockError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function unavailable(home, path, why) {
+  return lockError("lock_unavailable",
+    `cannot establish exclusive ownership of ${home}: ${path} could not be opened or locked (${why}). ` +
+    "Restore file access or locking support, or use a different AAMIO_HOME on a local disk.");
+}
+
+/** Opens owner.lock in a way that only one process can hold it. The holder, or null when another holds it. */
+async function holdWithOpen(home, path, flags, busy) {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDWR | constants.O_CREAT | flags, 0o600);
+  } catch (error) {
+    if (busy.includes(error.code)) return null;
+    throw unavailable(home, path, error.code || error.message);
+  }
+  return { release: () => handle.close() };
+}
+
+/** Pass Node's descriptor as fd 3. flock(1) exits before the caller starts serving. */
+async function holdWithFlock(home, path, command) {
+  const conflict = 42; // Outside util-linux's sysexits range and distinct from generic failure (1).
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDWR | constants.O_CREAT, 0o600);
+    const child = spawn(command, ["-x", "-n", "-E", String(conflict), "3"], {
+      stdio: ["ignore", "ignore", "pipe", handle.fd],
+    });
+    let diagnostic = "";
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => { diagnostic += chunk; });
+    const [code, signal] = await once(child, "close");
+    if (code === 0) return { release: () => handle.close() };
+    if (code !== conflict) {
+      throw new Error(diagnostic.trim() || `flock ended with ${signal || code}`);
+    }
+  } catch (error) {
+    await handle?.close();
+    const reason = handle && error.code === "ENOENT"
+      ? "the flock command was not found: install util-linux"
+      : error.code || error.message;
+    throw unavailable(home, path, reason);
+  }
+  await handle.close();
+  return null;
+}
+
+/** 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);
+  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);
+  throw unavailable(home, path, `no lock the other clients see is known for ${platform}`);
+}
+
+async function readPidFile(home) {
+  try {
+    const value = JSON.parse(await readFile(join(home, PID_FILE), "utf8"));
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writePidFile(home, value) {
+  const path = join(home, PID_FILE);
+  const temporary = join(home, `lock.${randomUUID()}.tmp`);
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    try {
+      await handle.writeFile(JSON.stringify(value, null, 2), "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, path);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+}
+
+/** True, false, or null when it cannot be told: a pid that answers signal 0 is alive, and one that is not there is not. */
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error.code === "ESRCH") return false;
+    if (error.code === "EPERM") return true;
+    return null;
+  }
+}
+
+/**
+ * An owner the lock cannot see: a client from before owner.lock, which wrote
+ * the pid file alone. One that held the lock says so with os_lock, and is gone,
+ * since this process holds the lock now. Not known to be gone is not gone.
+ */
+async function checkOlderOwner(home) {
+  const last = await readPidFile(home);
+  if (!last || !Number.isSafeInteger(last.pid) || last.pid === process.pid || last.os_lock === true) return;
+  const alive = pidAlive(last.pid);
+  if (alive === null) {
+    throw lockError("home_in_use",
+      `could not determine whether aamio (pid ${last.pid}) is still using ${home}; the lock is left untouched. ` +
+      "Stop the other runtime, or use a different AAMIO_HOME. Do not remove the lock unless you have confirmed its owner has stopped.");
+  }
+  if (alive) {
+    throw lockError("home_in_use",
+      `another aamio (pid ${last.pid}) is using ${home}. Stop it, or use a different AAMIO_HOME. If no aamio is running, ` +
+      `the one that took the lock stopped without letting go of it: delete ${join(home, PID_FILE)} and start again.`);
+  }
+}
+
+/**
+ * Takes a home for this process, as the other clients do: owner.lock held,
+ * and the pid file written with os_lock. Throws home_in_use when another
+ * runtime has it, and lock_unavailable when the lock cannot be had at all.
+ * release() lets go of both, the pid file first, so a runtime that takes the
+ * lock the moment it is free finds none of this one's to wonder about.
+ */
+export async function takeHome(home, { host = process.env.AAMIO_HOST || DEFAULT_BASE, ...options } = {}) {
+  const real = await realpath(home);
+  if (held.has(real)) throw lockError("home_in_use", `another aamio in this process is already using ${home}`);
+  const holder = await holdOwnerLock(home, options);
+  if (holder === null) {
+    const last = await readPidFile(home);
+    const named = Number.isSafeInteger(last?.pid) ? ` (pid ${last.pid})` : "";
+    throw lockError("home_in_use", `another aamio${named} is using ${home}. Stop it, or use a different AAMIO_HOME.`);
+  }
+  try {
+    await checkOlderOwner(home);
+    await writePidFile(home, { pid: process.pid, at: Math.floor(Date.now() / 1000), host, os_lock: true });
+  } catch (error) {
+    await holder.release();
+    throw error;
+  }
+  held.add(real);
+  let released = false;
+  return {
+    async release() {
+      if (released) return;
+      released = true;
+      const last = await readPidFile(home);
+      if (last?.pid === process.pid) await unlink(join(home, PID_FILE)).catch(() => {});
+      await holder.release();
+      held.delete(real);
+    },
+  };
+}