@consiliency/agent-board-cli 1.24.0 → 1.25.0

package/keyslot/lib.sh

@@ -0,0 +1,599 @@
+# shellcheck shell=bash
+# KEYSEAL operator-script library (SL-2): sourced by probe.sh, provision.sh, status.sh and
+# cross-user.sh from the checkout. It is NOT in the install set: only the loader runs with
+# the checkout gone.
+#
+# Names shared with the loader come from constants.sh and seam.sh (SL-1) and are never
+# restated here. This file adds the operator tools' own binaries, the chain check
+# (IF-0-KEYSEAL-3 check 2), the recovery predicates (IF-0-KEYSEAL-1) and the scan
+# (IF-0-KEYSEAL-5).
+
+keyseal_here=${BASH_SOURCE[0]%/*}
+[[ $keyseal_here == "${BASH_SOURCE[0]}" ]] && keyseal_here=.
+# shellcheck source=constants.sh
+. "$keyseal_here/constants.sh"
+# shellcheck source=seam.sh
+. "$keyseal_here/seam.sh"
+# shellcheck source=optin.sh
+. "$keyseal_here/optin.sh"
+
+# The operator tools' binaries, by absolute path. Each has a seam override named
+# KEYSEAL_TEST_<NAME>, honoured only under KEYSEAL_TEST_ROOT (seam.sh).
+KEYSEAL_BIN_SYSTEMCTL=/usr/bin/systemctl
+KEYSEAL_BIN_LOGINCTL=/usr/bin/loginctl
+KEYSEAL_BIN_FLOCK=/usr/bin/flock
+KEYSEAL_BIN_SSH_AGENT=/usr/bin/ssh-agent
+KEYSEAL_BIN_FIND=/usr/bin/find
+KEYSEAL_BIN_XARGS=/usr/bin/xargs
+# /usr/bin/grep, never a PATH lookup: an interactive shell's `grep` may be a shim with
+# different exit semantics.
+KEYSEAL_BIN_GREP=/usr/bin/grep
+
+# The flat layout (c5e358f): its install set and that set's version, sorted as
+# keyseal_files_sha takes them. A test derives the sha from fixtures/legacy-c5e358f.
+KEYSEAL_LEGACY_INSTALL_SET=(constants.sh keyslot-load.sh seam.sh)
+KEYSEAL_LEGACY_SET_SHA=8e7b771be5a461e4d6b032f518e4c790d91b315011ae2d96eda44bc6961c1fdc
+# The loader template's ExecStart before the A1 layout (the flat layout, c5e358f). status.sh
+# recognises an installed template that differs from the shipped one ONLY in this line as the
+# pre-migration layout (legacy_loader_present, 2), not as a chain violation.
+KEYSEAL_LEGACY_LOAD_EXEC='%h/.local/libexec/agent-board/keyslot-load.sh %i'
+
+# IF-0-KEYSEAL-5: the scan scope, exactly. Roots are resolved at scan time.
+KEYSEAL_SCAN_MAX_BYTES=1048576
+KEYSEAL_SCAN_PRUNE_NAMES=(node_modules .git .cache .npm)
+KEYSEAL_SCAN_PRUNE_PATHS=(.local/share/pnpm)
+KEYSEAL_SCAN_HEADERS=('-----BEGIN OPENSSH PRIVATE KEY-----' '-----BEGIN PRIVATE KEY-----')
+# What the scan does not detect, by stable id (reported in every status JSON).
+KEYSEAL_SCAN_NOT_DETECTED=(pruned over_1mib not_owned re_encoded_or_encrypted outside_roots)
+
+keyseal_die() {
+  printf '%s: %s\n' "${0##*/}" "$*" >&2
+  exit 1
+}
+
+# Resolve every binary through the seam into CREDS, SYSTEMCTL, LOGINCTL, SSH_ADD, SLEEP and
+# FLOCK, and the machine-id file into MACHINE_ID_FILE. A refused override returns 1 (the
+# caller exits 1: KS-14).
+keyseal_resolve_bins() {
+  CREDS=$(seam_resolve KEYSEAL_TEST_SYSTEMD_CREDS "$KEYSEAL_BIN_SYSTEMD_CREDS") || return 1
+  SYSTEMCTL=$(seam_resolve KEYSEAL_TEST_SYSTEMCTL "$KEYSEAL_BIN_SYSTEMCTL") || return 1
+  LOGINCTL=$(seam_resolve KEYSEAL_TEST_LOGINCTL "$KEYSEAL_BIN_LOGINCTL") || return 1
+  SSH_ADD=$(seam_resolve KEYSEAL_TEST_SSH_ADD "$KEYSEAL_BIN_SSH_ADD") || return 1
+  SLEEP=$(seam_resolve KEYSEAL_TEST_SLEEP "$KEYSEAL_BIN_SLEEP") || return 1
+  SSH_KEYGEN=$(seam_resolve KEYSEAL_TEST_SSH_KEYGEN "$KEYSEAL_BIN_SSH_KEYGEN") || return 1
+  MACHINE_ID_FILE=$(seam_resolve KEYSEAL_TEST_MACHINE_ID_FILE "$KEYSEAL_MACHINE_ID_FILE") || return 1
+  FLOCK=$KEYSEAL_BIN_FLOCK
+}
+
+# The opt-in's host comparand: the first 16 hex of sha256(/etc/machine-id). rc 1 if unreadable.
+keyseal_machine_id() { keyseal_machine_id_of "$MACHINE_ID_FILE"; }
+
+keyseal_seam_json() { if seam_active; then printf true; else printf false; fi; }
+
+# A JSON string literal. Values here are paths, hashes and short codes.
+keyseal_json_str() {
+  local s=$1
+  s=${s//\\/\\\\}
+  s=${s//\"/\\\"}
+  s=${s//$'\n'/\\n}
+  s=${s//$'\r'/\\r}
+  s=${s//$'\t'/\\t}
+  printf '"%s"' "$s"
+}
+
+keyseal_uid() {
+  if seam_active && [[ -n ${KEYSEAL_TEST_UID-} ]]; then printf '%s' "$KEYSEAL_TEST_UID"; else id -u; fi
+}
+
+keyseal_linger() {
+  "$LOGINCTL" show-user "$(id -u)" -p Linger --value 2>/dev/null || printf unknown
+}
+
+keyseal_sha256_file() { local h; h=$(sha256sum <"$1") || return 1; printf '%s' "${h%% *}"; }
+keyseal_sha256_str() { local h; h=$(printf '%s' "$1" | sha256sum); printf '%s' "${h%% *}"; }
+
+keyseal_unit_dir() { printf '%s/systemd/user' "${XDG_CONFIG_HOME:-$HOME/.config}"; }
+keyseal_libexec_dir() { printf '%s/%s' "$HOME" "$KEYSEAL_LIBEXEC_REL"; }
+keyseal_config_root() { printf '%s' "${XDG_CONFIG_HOME:-$HOME/.config}"; }
+
+# ---------------------------------------------------------------------------
+# Loader versions (A1)
+# ---------------------------------------------------------------------------
+
+# A version: sha256 over one `<name> <sha256>` line per file, names in sorted order. rc 1 if a
+# name is missing or not a regular file.
+keyseal_files_sha() {
+  local dir=$1 f lines= h
+  shift
+  for f in "$@"; do
+    [[ -f $dir/$f && ! -L $dir/$f ]] || return 1
+    h=$(keyseal_sha256_file "$dir/$f") || return 1
+    lines+="$f $h"$'\n'
+  done
+  keyseal_sha256_str "$lines"
+}
+# The version of the install set in directory $1 (KEYSEAL_INSTALL_SET is sorted).
+keyseal_set_sha() { keyseal_files_sha "$1" "${KEYSEAL_INSTALL_SET[@]}"; }
+# The version a version DIRECTORY holds: every entry in it, so a planted extra file changes it.
+keyseal_dir_sha() {
+  local dir=$1 e names=()
+  # Dotfiles too: a planted .x is part of what the directory holds.
+  for e in "$dir"/* "$dir"/.[!.]* "$dir"/..?*; do [[ -e $e || -L $e ]] && names+=("${e##*/}"); done
+  ((${#names[@]})) || return 1
+  keyseal_files_sha "$dir" "${names[@]}"
+}
+
+# v-<prefix> for a 64-hex set sha.
+keyseal_version_dirname() { printf '%s%s' "$KEYSEAL_VERSION_PREFIX" "${1:0:$KEYSEAL_VERSION_HEX}"; }
+keyseal_slot_link() { printf '%s/%s%s' "$(keyseal_libexec_dir)" "$KEYSEAL_SLOT_LINK_PREFIX" "$1"; }
+keyseal_loader_record() { printf '%s/%s.loader-sha256' "$(keyseal_key_dir)" "$1"; }
+
+# The recorded version of slot $1, if well-formed. rc 1 absent, rc 2 malformed.
+keyseal_read_loader_record() {
+  local rec line=
+  rec=$(keyseal_loader_record "$1")
+  [[ -e $rec || -L $rec ]] || return 1
+  [[ -f $rec && ! -L $rec ]] || return 2
+  IFS= read -r line <"$rec" || [[ -n $line ]] || return 2
+  [[ $line =~ ^[0-9a-f]{64}$ ]] || return 2
+  printf '%s' "$line"
+}
+
+# The legacy flat set: ANY member present as a regular file directly in libexec (a partial
+# leftover counts too; it is still legacy_loader_present).
+keyseal_legacy_present() {
+  local f
+  for f in "${KEYSEAL_LEGACY_INSTALL_SET[@]}"; do [[ -f $(keyseal_libexec_dir)/$f ]] && return 0; done
+  return 1
+}
+# The flat set is exactly the one c5e358f shipped (review round 1, Opus S1): never launder
+# unknown content into a recorded version.
+keyseal_legacy_known() {
+  [[ $(keyseal_files_sha "$(keyseal_libexec_dir)" "${KEYSEAL_LEGACY_INSTALL_SET[@]}" || true) == "$KEYSEAL_LEGACY_SET_SHA" ]]
+}
+
+# The slots whose loader instance is enabled: the `.wants` links `enable` writes for
+# `[Install] WantedBy=agent-board-keyslot@%i.service`. One slot per line.
+keyseal_enabled_slots() {
+  local link s dir
+  dir=$(keyseal_unit_dir)
+  for link in "$dir/$KEYSEAL_BASE_UNIT@"*.service.wants/"$KEYSEAL_LOAD_UNIT@"*.service; do
+    [[ -L $link || -e $link ]] || continue
+    s=${link##*/"$KEYSEAL_LOAD_UNIT@"}
+    s=${s%.service}
+    [[ $s =~ $KEYSEAL_SLOT_RE && $link == "$dir/$KEYSEAL_BASE_UNIT@$s.service.wants/"* ]] && printf '%s\n' "$s"
+  done
+}
+
+# Judge slot $1's loader against the running tooling in $2. Sets KEYSEAL_LOADER_STATE:
+#   current     the slot runs the recorded version, and it is the running tooling's
+#   outdated    it runs its recorded version, which differs from the running tooling's (2)
+#   unrecorded  no <slot>.loader-sha256, as on a slot provisioned before A1 (2)
+#   mismatch    the installed files match no recorded version (1): KEYSEAL_LOADER_PROBLEM
+# and KEYSEAL_LOADER_RECORDED / KEYSEAL_LOADER_RUNNING (64-hex, or empty).
+keyseal_loader_check() {
+  local slot=$1 src=$2 rec rc=0 link target
+  KEYSEAL_LOADER_PROBLEM= KEYSEAL_LOADER_RECORDED=
+  KEYSEAL_LOADER_RUNNING=$(keyseal_set_sha "$src") || KEYSEAL_LOADER_RUNNING=
+  rec=$(keyseal_read_loader_record "$slot") || rc=$?
+  if ((rc == 1)); then KEYSEAL_LOADER_STATE=unrecorded; return 0; fi
+  if ((rc != 0)); then KEYSEAL_LOADER_STATE=mismatch KEYSEAL_LOADER_PROBLEM="$slot.loader-sha256 is malformed"; return 0; fi
+  KEYSEAL_LOADER_RECORDED=$rec
+  link=$(keyseal_slot_link "$slot")
+  target=$(keyseal_version_dirname "$rec")
+  if [[ ! -L $link ]]; then
+    KEYSEAL_LOADER_STATE=mismatch KEYSEAL_LOADER_PROBLEM="${link##*/} is not a symlink"
+  elif [[ $(readlink -- "$link") != "$target" ]]; then
+    KEYSEAL_LOADER_STATE=mismatch KEYSEAL_LOADER_PROBLEM="${link##*/} does not point at the recorded version $target"
+  elif [[ -L $(keyseal_libexec_dir)/$target || ! -d $(keyseal_libexec_dir)/$target ]]; then
+    KEYSEAL_LOADER_STATE=mismatch KEYSEAL_LOADER_PROBLEM="$target is not a directory"
+  elif [[ $(keyseal_dir_sha "$(keyseal_libexec_dir)/$target" || true) != "$rec" ]]; then
+    KEYSEAL_LOADER_STATE=mismatch KEYSEAL_LOADER_PROBLEM="the installed files in $target match no recorded version"
+  elif [[ $rec != "$KEYSEAL_LOADER_RUNNING" ]]; then
+    KEYSEAL_LOADER_STATE=outdated
+  else
+    KEYSEAL_LOADER_STATE=current
+  fi
+}
+
+# A test seam point: under KEYSEAL_TEST_ROOT only, KEYSEAL_TEST_FAIL_AT=<point> makes the
+# script fail (exit 1), SIGTERM or SIGKILL itself, or pause until $KEYSEAL_TEST_ROOT/resume
+# exists (KEYSEAL_TEST_FAIL_MODE = fail | term | kill | pause). A no-op in production.
+keyseal_seam_point() {
+  seam_active || return 0
+  [[ ${KEYSEAL_TEST_FAIL_AT-} == "$1" ]] || return 0
+  case ${KEYSEAL_TEST_FAIL_MODE:-fail} in
+    # At keygen and encrypt the `fail` mode belongs to the CHILD (keygen.mjs, the
+    # systemd-creds stub), so what fails the run is the pipeline's own status (KS-4): a
+    # seam exit here would mask a lost pipefail.
+    fail) [[ $1 == keygen || $1 == encrypt ]] || keyseal_die "seam_fail_at $1" ;;
+    term) kill -TERM $$ ;;
+    kill) kill -KILL $$ ;;
+    pause)
+      : >"$KEYSEAL_TEST_ROOT/paused.$1"
+      local i
+      for ((i = 0; i < 1200; i++)); do
+        [[ -e $KEYSEAL_TEST_ROOT/resume ]] && return 0
+        "$SLEEP" 0.05
+      done
+      keyseal_die "seam_pause_timeout $1"
+      ;;
+  esac
+}
+
+# Node helpers. Everything here reads; nothing writes a file. `derive` reads a PEM on stdin
+# (a pipe from decrypt) and prints the raw public key as base64url.
+KEYSEAL_NODE_JS=$(cat <<'JS'
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+const [mode, ...args] = process.argv.slice(1);
+const out = (s) => process.stdout.write(s);
+
+function readStdin() { return fs.readFileSync(0); }
+
+function sshString(buf, off) {
+  if (off + 4 > buf.length) throw new Error("truncated");
+  const n = buf.readUInt32BE(off);
+  if (off + 4 + n > buf.length) throw new Error("truncated");
+  return [buf.subarray(off + 4, off + 4 + n), off + 4 + n];
+}
+
+// ssh-ed25519 wire blob -> raw 32 bytes as base64url, or null.
+function ed25519FromWire(wire) {
+  const [type, off] = sshString(wire, 0);
+  if (type.toString() !== "ssh-ed25519") return null;
+  const [raw] = sshString(wire, off);
+  return raw.length === 32 ? raw.toString("base64url") : null;
+}
+
+// Classify one PEM block for the scan: "match", "nomatch", "encrypted" or "unverifiable".
+function classifyBlock(kind, body, pin) {
+  if (kind === "OPENSSH PRIVATE KEY") {
+    if (!/^[A-Za-z0-9+/=\s]+$/.test(body)) return "unverifiable";
+    const buf = Buffer.from(body.replace(/\s+/g, ""), "base64");
+    const magic = Buffer.from("openssh-key-v1\0");
+    if (!buf.subarray(0, magic.length).equals(magic)) return "unverifiable";
+    let off = magic.length;
+    let cipher; let n;
+    try {
+      [cipher, off] = sshString(buf, off);
+      [, off] = sshString(buf, off); // kdfname
+      [, off] = sshString(buf, off); // kdfoptions
+      if (off + 4 > buf.length) return "unverifiable";
+      n = buf.readUInt32BE(off); off += 4;
+      if (n < 1 || n > 16) return "unverifiable";
+      // The public section is stored in the clear even when the key is encrypted.
+      const pubs = [];
+      for (let i = 0; i < n; i++) { let w; [w, off] = sshString(buf, off); pubs.push(w); }
+      if (cipher.toString() !== "none") return "encrypted";
+      for (const w of pubs) { if (ed25519FromWire(w) === pin && pin) return "match"; }
+      return "nomatch";
+    } catch { return "unverifiable"; }
+  }
+  // PKCS#8 BEGIN PRIVATE KEY is unencrypted by format.
+  try {
+    const key = crypto.createPrivateKey({ key: `-----BEGIN PRIVATE KEY-----\n${body}\n-----END PRIVATE KEY-----\n`, format: "pem" });
+    if (key.asymmetricKeyType !== "ed25519") return "nomatch";
+    return pin && crypto.createPublicKey(key).export({ format: "jwk" }).x === pin ? "match" : "nomatch";
+  } catch { return "unverifiable"; }
+}
+
+// An unencrypted openssh-key-v1 PEM (what keygen.mjs seals) -> Ed25519 KeyObject, built from
+// the private SEED. Every embedded public copy must equal what the seed derives, so the pin
+// cannot be satisfied by a clear-text field that disagrees with the key ssh-agent would load.
+function opensshEd25519(text) {
+  const m = /-----BEGIN OPENSSH PRIVATE KEY-----\s*([A-Za-z0-9+/=\s]+?)\s*-----END OPENSSH PRIVATE KEY-----/.exec(text);
+  if (!m) return null;
+  const buf = Buffer.from(m[1].replace(/\s+/g, ""), "base64");
+  const magic = Buffer.from("openssh-key-v1\0");
+  if (!buf.subarray(0, magic.length).equals(magic)) throw new Error("not openssh-key-v1");
+  let off = magic.length; let cipher; let wire; let priv;
+  [cipher, off] = sshString(buf, off);
+  if (cipher.toString() !== "none") throw new Error("encrypted");
+  [, off] = sshString(buf, off); // kdfname
+  [, off] = sshString(buf, off); // kdfoptions
+  if (off + 4 > buf.length || buf.readUInt32BE(off) !== 1) throw new Error("not exactly one key");
+  off += 4;
+  [wire, off] = sshString(buf, off);
+  [priv] = sshString(buf, off);
+  if (priv.length < 8 || !priv.subarray(0, 4).equals(priv.subarray(4, 8))) throw new Error("checkint mismatch");
+  let p = 8; let type; let pub; let sk;
+  [type, p] = sshString(priv, p);
+  [pub, p] = sshString(priv, p);
+  [sk] = sshString(priv, p);
+  if (type.toString() !== "ssh-ed25519" || pub.length !== 32 || sk.length !== 64) throw new Error("not ed25519");
+  const der = Buffer.concat([Buffer.from("302e020100300506032b657004220420", "hex"), sk.subarray(0, 32)]);
+  const key = crypto.createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+  const x = crypto.createPublicKey(key).export({ format: "jwk" }).x;
+  for (const copy of [pub, sk.subarray(32)]) if (copy.toString("base64url") !== x) throw new Error("public key does not derive from the seed");
+  if (ed25519FromWire(wire) !== x) throw new Error("public section does not derive from the seed");
+  return key;
+}
+
+if (mode === "derive") {
+  const text = readStdin().toString("utf8");
+  const key = opensshEd25519(text) ?? crypto.createPrivateKey({ key: text, format: "pem" });
+  if (key.asymmetricKeyType !== "ed25519") throw new Error("not ed25519");
+  out(`${crypto.createPublicKey(key).export({ format: "jwk" }).x}\n`);
+} else if (mode === "agentkeys") {
+  // `ssh-add -L` on stdin -> one line per identity: the base64url raw key, or `other`.
+  for (const line of readStdin().toString("utf8").split("\n")) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 2) continue;
+    let pub = null;
+    try { pub = ed25519FromWire(Buffer.from(parts[1], "base64")); } catch {}
+    out(`${pub ?? "other"}\n`);
+  }
+} else if (mode === "directives") {
+  // KS-7: the (section, key, value) multiset, minus comments, blanks, Description=,
+  // Documentation=; sorted, one per line.
+  let section = ""; const lines = [];
+  for (const raw of fs.readFileSync(args[0], "utf8").split("\n")) {
+    const l = raw.trim();
+    if (!l || l.startsWith("#") || l.startsWith(";")) continue;
+    const s = /^\[(.+)\]$/.exec(l);
+    if (s) { section = s[1]; continue; }
+    const eq = l.indexOf("=");
+    if (eq <= 0) { lines.push(`!unparseable\t${l}`); continue; }
+    const k = l.slice(0, eq).trim();
+    if (k === "Description" || k === "Documentation") continue;
+    lines.push(`${section}\t${k}\t${l.slice(eq + 1).trim()}`);
+  }
+  out(lines.sort().join("\n") + "\n");
+} else if (mode === "chain") {
+  // IF-0-KEYSEAL-3 check 2 for ONE unit. stdin: `systemctl --user show -p …` output.
+  // args: shipped unit file, expected FragmentPath, slot, home, runtime dir, uid, and an
+  // optional ExecStart= value that replaces the shipped one (the legacy flat line, A1).
+  const [shipped, fragment, slot, home, runtime, uid, execOverride] = args;
+  const EXEC = ["ExecStartPre", "ExecStart", "ExecStartPost", "ExecStop", "ExecStopPost"];
+  const expand = (v) => v.replace(/%([%hti])/g, (_, c) => (c === "%" ? "%" : c === "h" ? home : c === "t" ? runtime : slot));
+  const want = { Environment: [] }; for (const p of EXEC) want[p] = [];
+  let section = "";
+  for (const raw of fs.readFileSync(shipped, "utf8").split("\n")) {
+    const l = raw.trim();
+    if (!l || l.startsWith("#")) continue;
+    const s = /^\[(.+)\]$/.exec(l);
+    if (s) { section = s[1]; continue; }
+    const eq = l.indexOf("=");
+    const k = l.slice(0, eq); const v = l.slice(eq + 1);
+    const val = section === "Service" && k === "ExecStart" && execOverride ? execOverride : v;
+    if (section === "Service" && k in want) want[k].push(expand(val.replace(/^[-@:+!|]+/, "").trim()).split(/\s+/).join(" "));
+  }
+  const got = { Environment: [], DropInPaths: null, FragmentPath: null }; for (const p of EXEC) got[p] = [];
+  const problems = [];
+  for (const line of readStdin().toString("utf8").split("\n")) {
+    if (!line) continue;
+    const eq = line.indexOf("=");
+    const k = line.slice(0, eq); const v = line.slice(eq + 1);
+    if (EXEC.includes(k)) {
+      const m = / argv\[\]=(.*?) ; ignore_errors=/.exec(v);
+      if (!m) { problems.push(`${k}: unparseable record`); continue; }
+      got[k].push(m[1]);
+    } else if (k === "Environment") { if (v) got.Environment.push(v); }
+    else if (k === "DropInPaths") got.DropInPaths = v ? v.split(/\s+/) : [];
+    else if (k === "FragmentPath") got.FragmentPath = v;
+  }
+  for (const p of [...EXEC, "Environment"]) {
+    if (JSON.stringify(got[p]) !== JSON.stringify(want[p])) problems.push(`${p} differs from the shipped unit`);
+  }
+  if (got.FragmentPath !== fragment) problems.push(`FragmentPath is not ${fragment}`);
+  if (got.DropInPaths === null) problems.push("DropInPaths not reported");
+  for (const d of got.DropInPaths ?? []) {
+    let userWritable = true;
+    try {
+      const st = fs.statSync(d); const dst = fs.statSync(require("node:path").dirname(d));
+      const w = (p) => { try { fs.accessSync(p, fs.constants.W_OK); return true; } catch { return false; } };
+      userWritable = String(st.uid) === uid || String(dst.uid) === uid || w(d) || w(require("node:path").dirname(d));
+    } catch {}
+    if (userWritable) problems.push(`drop-in in a user-writable location: ${d}`);
+  }
+  out(JSON.stringify({ ok: problems.length === 0, problems }) + "\n");
+} else if (mode === "classify") {
+  // IF-0-KEYSEAL-5: candidates (NUL-separated file on args[0]) -> JSON. args[3], when set,
+  // is the ONE exempt path (A1: an opted-in unsealed slot's <slot>.key, 0600, this uid's). It
+  // is matched by path, never by inode, and never enters `seen`: a hard link elsewhere is a copy.
+  const pin = process.env.KEYSEAL_SCAN_PIN || "";
+  const uid = Number(args[1]);
+  const max = Number(args[2]);
+  const exempt = args[3] || "";
+  const raw = fs.readFileSync(args[0]).toString("utf8").split("\0").filter(Boolean);
+  const seen = new Set();
+  const res = { candidates: 0, plaintext_matches: [], encrypted_skipped: [], unverifiable: [], exempt: [] };
+  for (const p of raw) {
+    let st;
+    try { st = fs.lstatSync(p); } catch { continue; }
+    if (!st.isFile() || st.uid !== uid || st.size > max) continue;
+    if (exempt && p === exempt && (st.mode & 0o777) === 0o600) {
+      // Overlapping roots ($HOME under /tmp) list one path twice: report it once.
+      if (!res.exempt.includes(p)) res.exempt.push(p);
+      continue;
+    }
+    const id = `${st.dev}:${st.ino}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    let text;
+    try { text = fs.readFileSync(p, "latin1"); } catch { res.unverifiable.push(p); continue; }
+    const lines = text.split("\n").map((l) => l.replace(/\r$/, ""));
+    const verdicts = new Set();
+    for (let i = 0; i < lines.length; i++) {
+      const m = /^-----BEGIN (OPENSSH PRIVATE KEY|PRIVATE KEY)-----$/.exec(lines[i]);
+      if (!m) continue;
+      const end = lines.indexOf(`-----END ${m[1]}-----`, i + 1);
+      if (end < 0) { verdicts.add("unverifiable"); continue; }
+      verdicts.add(classifyBlock(m[1], lines.slice(i + 1, end).join("\n"), pin));
+      i = end;
+    }
+    if (verdicts.size === 0) continue;
+    res.candidates++;
+    if (verdicts.has("match")) res.plaintext_matches.push(p);
+    if (verdicts.has("encrypted")) res.encrypted_skipped.push(p);
+    if (verdicts.has("unverifiable")) res.unverifiable.push(p);
+  }
+  out(JSON.stringify(res) + "\n");
+} else {
+  process.stderr.write(`keyseal node helper: unknown mode ${mode}\n`);
+  process.exit(2);
+}
+JS
+)
+
+keyseal_node() { node -e "$KEYSEAL_NODE_JS" -- "$@"; }
+
+# The raw public key the sealed blob of slot $1 derives to, via a PIPED decrypt: the key
+# exists only in the pipe and in node's memory. Empty output on any failure, with rc 3 when
+# the decrypt failed and rc 4 when it succeeded but no Ed25519 key derives from its output:
+# status.sh tells "no key could be read" (undeterminable when sealing is broken) from "a
+# different key" (a contradiction).
+keyseal_derive_pub() {
+  local slot=$1 cred res st pub
+  cred="$(keyseal_key_dir)/$slot.cred"
+  res=$("$CREDS" --user decrypt --name="$(keyseal_cred_name "$slot")" "$cred" - 2>/dev/null \
+    | keyseal_node derive 2>/dev/null
+  printf '\n%s %s' "${PIPESTATUS[0]}" "${PIPESTATUS[1]}")
+  st=${res##*$'\n'}
+  pub=${res%$'\n'*}
+  pub=${pub%$'\n'}
+  [[ ${st%% *} == 0 ]] || return 3
+  [[ ${st##* } == 0 && -n $pub ]] || return 4
+  printf '%s' "$pub"
+}
+
+# The first line of a file, if it is a well-formed pin (43-char base64url).
+keyseal_read_pin() {
+  local line=
+  [[ -f $1 ]] || return 1
+  IFS= read -r line <"$1" || [[ -n $line ]] || return 1
+  [[ $line =~ ^[A-Za-z0-9_-]{43}$ ]] || return 1
+  printf '%s' "$line"
+}
+
+# The identities the slot agent holds, one per line (base64url raw key, or `other`).
+keyseal_agent_keys() {
+  local out rc
+  out=$(SSH_AUTH_SOCK=$(keyseal_sock_path "$1") "$SSH_ADD" -L 2>/dev/null) && rc=0 || rc=$?
+  # ssh-add -L exits 1 with "The agent has no identities." on an empty agent.
+  if ((rc != 0)); then
+    [[ $out == *"no identities"* ]] && return 0
+    return 1
+  fi
+  printf '%s\n' "$out" | keyseal_node agentkeys
+}
+
+# Exactly one identity, equal to the pin.
+keyseal_agent_holds_exactly() {
+  local keys
+  keys=$(keyseal_agent_keys "$1") || return 1
+  [[ $keys == "$2" ]]
+}
+
+# Effective config dirs: ours and the user manager's must agree (IF-0-KEYSEAL-2). Each side
+# is XDG_CONFIG_HOME if set, else $HOME/.config.
+keyseal_config_dir_check() {
+  local env_out mhome= mxdg= line ours theirs
+  env_out=$("$SYSTEMCTL" --user show-environment) || return 1
+  while IFS= read -r line; do
+    case $line in
+      HOME=*) mhome=${line#HOME=} ;;
+      XDG_CONFIG_HOME=*) mxdg=${line#XDG_CONFIG_HOME=} ;;
+    esac
+  done <<<"$env_out"
+  [[ -n $mhome || -n $mxdg ]] || return 1
+  ours=$(realpath -m -- "${XDG_CONFIG_HOME:-$HOME/.config}")
+  theirs=$(realpath -m -- "${mxdg:-$mhome/.config}")
+  [[ $ours == "$theirs" ]]
+}
+
+# IF-0-KEYSEAL-3 check 2, the chain, for slot $1 against the shipped units and install set
+# in $2 (the scripts/keyslot checkout). Sets KEYSEAL_CHAIN_PROBLEMS (newline-joined; any is
+# exit 1), KEYSEAL_CHAIN_LEGACY (yes when the installed loader template is the pre-A1 flat one,
+# so the slot runs the unmigrated flat files: 2, never judged as a violation), and the
+# keyseal_loader_check variables for the slot's loader version (A1).
+keyseal_chain_check() {
+  local slot=$1 src=$2 unit template shown verdict problems= legacy_verdict
+  local props=ExecStartPre,ExecStart,ExecStartPost,ExecStop,ExecStopPost,Environment,DropInPaths,FragmentPath
+  KEYSEAL_CHAIN_LEGACY=no
+  for template in "$KEYSEAL_BASE_UNIT" "$KEYSEAL_LOAD_UNIT"; do
+    unit="$template@$slot.service"
+    if ! shown=$("$SYSTEMCTL" --user show -p "$props" "$unit"); then
+      problems+="$unit: show failed"$'\n'
+      continue
+    fi
+    verdict=$(printf '%s\n' "$shown" | keyseal_node chain "$src/$template@.service" \
+      "$(keyseal_unit_dir)/$template@.service" "$slot" "$HOME" "$XDG_RUNTIME_DIR" "$(id -u)") || verdict=
+    if [[ $verdict != '{"ok":true,"problems":[]}' && $template == "$KEYSEAL_LOAD_UNIT" ]]; then
+      legacy_verdict=$(printf '%s\n' "$shown" | keyseal_node chain "$src/$template@.service" \
+        "$(keyseal_unit_dir)/$template@.service" "$slot" "$HOME" "$XDG_RUNTIME_DIR" "$(id -u)" \
+        "$KEYSEAL_LEGACY_LOAD_EXEC") || legacy_verdict=
+      if [[ $legacy_verdict == '{"ok":true,"problems":[]}' ]]; then
+        KEYSEAL_CHAIN_LEGACY=yes
+        continue
+      fi
+    fi
+    if [[ $verdict != '{"ok":true,"problems":[]}' ]]; then
+      problems+="$unit: ${verdict:-chain helper failed}"$'\n'
+    fi
+  done
+  keyseal_loader_check "$slot" "$src"
+  # Under the legacy template the flat files are what runs: they must be the shipped flat set.
+  if [[ $KEYSEAL_CHAIN_LEGACY == yes ]] && ! keyseal_legacy_known; then
+    problems+="loader: the legacy loader files are not the shipped flat set (c5e358f)"$'\n'
+  fi
+  if [[ $KEYSEAL_CHAIN_LEGACY == no && $KEYSEAL_LOADER_STATE == mismatch ]]; then
+    problems+="loader: $KEYSEAL_LOADER_PROBLEM"$'\n'
+  fi
+  KEYSEAL_CHAIN_PROBLEMS=$problems
+  [[ -z $problems ]]
+}
+
+# The opt-in record of slot $1 against its pin (optin.sh, the loader's own predicate). Prints
+# the problems, one per line; rc 0 valid.
+keyseal_optin_check() {
+  local mid
+  mid=$(keyseal_machine_id) || mid=unreadable
+  keyseal_optin_verify "$(keyseal_key_dir)/$1.unsealed-optin" "$(keyseal_key_dir)/$1.pub" "$1" "$(keyseal_uid)" "$mid"
+}
+
+# The whole unsealed predicate for slot $1, exactly as keyslot-load.sh runs it before loading.
+keyseal_unsealed_check() {
+  local mid
+  mid=$(keyseal_machine_id) || mid=unreadable
+  keyseal_unsealed_verify "$1" "$(keyseal_uid)" "$mid"
+}
+
+# IF-0-KEYSEAL-5. Prints the scan JSON (the `scan` object of status); rc 0 when it ran, 1
+# when it could not (a failed find/xargs/grep, not "found something"). $2, when set, is the
+# one exempt path: an opted-in unsealed slot's <slot>.key (A1).
+keyseal_scan() {
+  local pin=$1 exempt=${2-} uid list rc_find rc_xargs r json roots=() present=() prune=() h
+  uid=$(id -u)
+  roots=("$HOME" "$XDG_RUNTIME_DIR" "${TMPDIR:-/tmp}" /tmp /var/tmp)
+  for r in "${roots[@]}"; do [[ -d $r ]] && present+=("$r"); done
+  prune=(\()
+  for h in "${KEYSEAL_SCAN_PRUNE_NAMES[@]}"; do prune+=(-name "$h" -o); done
+  for h in "${KEYSEAL_SCAN_PRUNE_PATHS[@]}"; do prune+=(-path "*/$h" -o); done
+  unset 'prune[${#prune[@]}-1]'
+  prune+=(\))
+  local greps=()
+  for h in "${KEYSEAL_SCAN_HEADERS[@]}"; do greps+=(-e "$h" -e "$h"$'\r'); done
+  list=$(mktemp "${XDG_RUNTIME_DIR:-/tmp}/keyseal-scan.XXXXXX") || return 1
+  "$KEYSEAL_BIN_FIND" -H "${present[@]}" -type d "${prune[@]}" -prune -o \
+    -type f -user "$uid" -size -$((KEYSEAL_SCAN_MAX_BYTES + 1))c -print0 2>/dev/null \
+    | "$KEYSEAL_BIN_XARGS" -0 -r "$KEYSEAL_BIN_GREP" -lsZ -x -F "${greps[@]}" -- >"$list"
+  rc_find=${PIPESTATUS[0]} rc_xargs=${PIPESTATUS[1]}
+  # find: 0, or 1 when some directory was unreadable. xargs: 0, or 123 when some grep found
+  # nothing. Anything else means the scan did not run to completion.
+  if ! { ((rc_find <= 1)) && ((rc_xargs == 0 || rc_xargs == 123)); }; then
+    rm -f -- "$list"
+    return 1
+  fi
+  json=$(KEYSEAL_SCAN_PIN=$pin keyseal_node classify "$list" "$uid" "$KEYSEAL_SCAN_MAX_BYTES" "$exempt") || { rm -f -- "$list"; return 1; }
+  rm -f -- "$list"
+  local jr=() jp=() jn=() jh=()
+  for r in "${roots[@]}"; do jr+=("$(keyseal_json_str "$r")"); done
+  for h in "${KEYSEAL_SCAN_PRUNE_NAMES[@]}" "${KEYSEAL_SCAN_PRUNE_PATHS[@]}"; do jp+=("$(keyseal_json_str "$h")"); done
+  for h in "${KEYSEAL_SCAN_NOT_DETECTED[@]}"; do jn+=("$(keyseal_json_str "$h")"); done
+  for h in "${KEYSEAL_SCAN_HEADERS[@]}"; do jh+=("$(keyseal_json_str "$h")"); done
+  local IFS=,
+  printf '{"roots":[%s],"pruned":[%s],"max_bytes":%s,"headers":[%s],"not_detected":[%s],%s\n' \
+    "${jr[*]}" "${jp[*]}" "$KEYSEAL_SCAN_MAX_BYTES" "${jh[*]}" "${jn[*]}" "${json#\{}"
+}