@consiliency/agent-board-cli 1.23.0 → 1.25.0

package/keyslot/provision.sh

@@ -0,0 +1,530 @@
+#!/bin/bash
+# provision.sh --harness <h> [--slot <s>] [--rotate] [--allow-unsealed-key] | [--refresh-loader]:
+# put a key into slot <s> and load it into the slot agent (IF-0-KEYSEAL-1, IF-0-KEYSEAL-6).
+# <s> defaults to <h>.
+#
+# Prints ONE line on success, the reference enrollment consumes:
+#   agent_socket:$XDG_RUNTIME_DIR/agent-board/<s>.sock#<pub43>
+# Exit 0 provisioned, 1 failed or refused, 2 capability absent.
+#
+# MODE (A1), from probe.sh's `outcome`, never its exit code alone:
+#   capable                sealed. --allow-unsealed-key is REFUSED (exit 1): unsealed is never
+#                          chosen on a host that can seal.
+#   incapable              unsealed, only with --allow-unsealed-key; without it exit 2, unless
+#                          the slot already holds a committed unsealed key (then maintained).
+#   incapable-for-keyslot  exit 2, the fix named: no mode survives a reboot.
+#   error                  exit 1 probe_error. An error is never treated as incapable.
+# No downgrade: a slot with a <s>.cred is never turned unsealed; remove the pair first, then
+# provision with a fresh flag. --rotate on an unsealed slot rotates INTO sealed mode, and only
+# on a capable host.
+#
+# SEALED: the private key exists only in keygen.mjs's memory, the pipe into `systemd-creds
+# encrypt`, and later the loader's pipe into ssh-add. It is never a file.
+# UNSEALED: keygen.mjs's PEM goes straight into <s>.key (0600, noclobber); that file is the
+# only plaintext this tool ever writes, and only on the opt-in path. Then the opt-in record
+# <s>.unsealed-optin, then the pin <s>.pub: the pin's rename is the commit.
+#
+# LOADER (A1): each version of the install set lives in an immutable
+# ~/.local/libexec/agent-board/v-<sha16>/; the template runs slot-%i/keyslot-load.sh through a
+# per-slot symlink slot-<s> -> v-<sha16>, recorded in <s>.loader-sha256. Every run points THIS
+# slot at the running tooling's version (restarting its loader when that changed) and leaves
+# every other slot's version alone. --refresh-loader does only that, plus steps 5 and 6, and
+# never re-keys. The first run under this layout migrates the flat layout (c5e358f), all
+# slots under one lock (.loader.lock), template swap last, legacy files removed only after a
+# successful daemon-reload.
+#
+# Transactional: under a per-slot lock, the recovery table below is evaluated first, so an
+# interruption at any step leaves a state the next run finishes. A committed slot is NEVER
+# deleted; only staging files and uncommitted generations are.
+#
+#   found                                               action
+#   nothing                                             fresh: steps 3, 4, 5, 6
+#   *.staging only, or staged beside a committed slot   delete the staging files, re-evaluate
+#   SEALED
+#   <s>.cred + <s>.pub.staging deriving from it         half-committed: mv the pub, then
+#     (the old <s>.pub may exist)                         steps 3, 5 (with a restart), 6
+#   <s>.cred + <s>.pub deriving from it                 committed: steps 3, 5, 6; with
+#                                                         --rotate 3, 4, 5 (restart), 6
+#   UNSEALED
+#   <s>.key + valid opt-in + <s>.pub deriving from key  committed: steps 3, 5, 6; with --rotate
+#                                                         on a capable host 3, 4 sealed, 5, 6
+#   <s>.key with no <s>.pub but a <s>.pub.staging, or   an uncommitted unsealed generation
+#     an empty <s>.key alone (with any opt-in files)      (never printed): delete it, re-evaluate
+#   UNSEALED -> SEALED (--rotate)
+#   <s>.cred + <s>.pub.staging deriving from it, with   half-rotated: mv the pub, re-evaluate
+#     the old <s>.key and opt-in
+#   <s>.cred + <s>.pub deriving from it, with the old   rotated: delete the old <s>.key and
+#     <s>.key (not deriving to the pin) and/or opt-in     opt-in, re-evaluate
+#   anything else                                       slot_inconsistent, exit 1
+set -euo pipefail
+
+here=${BASH_SOURCE[0]%/*}
+[[ $here == "${BASH_SOURCE[0]}" ]] && here=.
+# shellcheck source=lib.sh
+. "$here/lib.sh"
+
+usage="usage: provision.sh --harness <h> [--slot <s>] [--rotate] [--allow-unsealed-key] | [--refresh-loader]"
+harness= slot= rotate=no allow_unsealed=no refresh=no
+while (($#)); do
+  case $1 in
+    --harness) harness=${2-}; shift 2 || keyseal_die "usage: --harness <h>" ;;
+    --slot) slot=${2-}; shift 2 || keyseal_die "usage: --slot <s>" ;;
+    --rotate) rotate=yes; shift ;;
+    --allow-unsealed-key) allow_unsealed=yes; shift ;;
+    --refresh-loader) refresh=yes; shift ;;
+    *) keyseal_die "$usage" ;;
+  esac
+done
+[[ $harness =~ $KEYSEAL_SLOT_RE ]] || keyseal_die "bad_harness"
+slot=${slot:-$harness}
+[[ $slot =~ $KEYSEAL_SLOT_RE ]] || keyseal_die "bad_slot"
+if [[ $refresh == yes && ($rotate == yes || $allow_unsealed == yes) ]]; then
+  keyseal_die "--refresh-loader never re-keys: it takes no --rotate or --allow-unsealed-key"
+fi
+: "${XDG_RUNTIME_DIR:?provision: XDG_RUNTIME_DIR unset}"
+: "${HOME:?provision: HOME unset}"
+keyseal_resolve_bins || exit 1
+seam_active && echo "provision: seam=true" >&2
+
+K=$(keyseal_key_dir)
+cred=$K/$slot.cred pub=$K/$slot.pub key=$K/$slot.key optin=$K/$slot.unsealed-optin
+cred_s=$K/$slot.cred.staging pub_s=$K/$slot.pub.staging optin_s=$K/$slot.unsealed-optin.staging
+base_unit=$KEYSEAL_BASE_UNIT@$slot.service
+load_unit=$KEYSEAL_LOAD_UNIT@$slot.service
+
+# Capability first, before any file exists (KS-9). --refresh-loader never generates a key, so
+# it does not need one.
+want=maintain
+if [[ $refresh == no ]]; then
+  probe_out=$("$here/probe.sh" --json 2>/dev/null) || true
+  outcome=
+  [[ $probe_out =~ \"outcome\":\"([a-z-]+)\" ]] && outcome=${BASH_REMATCH[1]}
+  case $outcome in
+    capable)
+      [[ $allow_unsealed == no ]] || keyseal_die "allow_unsealed_refused: probe.sh reports this host capable of sealing; an unsealed key is never written where a sealed one can be. An existing unsealed slot is turned sealed with provision.sh --harness $harness --slot $slot --rotate (no --allow-unsealed-key)"
+      want=sealed
+      ;;
+    incapable)
+      if [[ $allow_unsealed == yes ]]; then
+        want=unsealed
+      elif [[ -e $key || -L $key ]]; then
+        want=maintain
+      else
+        echo "provision: capability_absent (probe.sh: incapable; this host cannot seal). To accept an unsealed 0600 key for this slot, re-run with --allow-unsealed-key" >&2
+        exit 2
+      fi
+      ;;
+    incapable-for-keyslot)
+      echo "provision: incapable_for_keyslot (probe.sh: no key slot survives a reboot here; run probe.sh for the fix)" >&2
+      exit 2
+      ;;
+    *)
+      echo "provision: probe_error (probe.sh outcome '${outcome:-unreadable}'); refusing, and an error never admits an unsealed key" >&2
+      exit 1
+      ;;
+  esac
+fi
+
+# The loader runs under the user manager, which resolves K from ITS environment.
+keyseal_config_dir_check || keyseal_die "config_dir_mismatch: XDG_CONFIG_HOME/HOME differ from the user manager's (systemctl --user show-environment)"
+
+umask 077
+mkdir -p -m 0700 "$K"
+exec {lock_fd}>"$K/$slot.lock"
+"$FLOCK" -n "$lock_fd" || keyseal_die "slot_busy"
+keyseal_seam_point locked
+
+# Principle 4 on the key directory BEFORE any plaintext can exist (review round 1, Opus B1): an
+# opt-in under a symlinked, foreign-owned or group-writable ancestor could never validate, so
+# the unsealed key it guards would be stranded at rest.
+if [[ $want == unsealed ]] && ! problems=$(keyseal_trusted_ancestors "$K"); then
+  keyseal_die "unsafe_key_dir: $K fails principle 4, so no unsealed key is written: ${problems//$'\n'/; }"
+fi
+
+# No downgrade, judged BEFORE the recovery table: on a host that cannot decrypt, the table
+# could not even derive the committed pin, and nothing here may depend on it.
+if [[ $want == unsealed ]] && [[ -e $cred || -L $cred ]] && [[ -e $pub || -L $pub || -e $pub_s || -L $pub_s ]]; then
+  keyseal_die "downgrade_refused: slot $slot holds a sealed key ($slot.cred + $slot.pub); it is never turned unsealed. Remove that pair first, then provision with a fresh --allow-unsealed-key"
+fi
+
+# ---------------------------------------------------------------------------
+# step 2: recovery
+# ---------------------------------------------------------------------------
+has() { [[ -e $1 || -L $1 ]]; }
+optin_valid() { keyseal_optin_check "$slot" >/dev/null; }
+key_pub() { keyseal_keyfile_pub "$key" 2>/dev/null; }
+
+table_row() {
+  local derived= kp=
+  if ! has "$cred" && ! has "$pub" && ! has "$key" && ! has "$optin" && ! has "$cred_s" && ! has "$pub_s" && ! has "$optin_s"; then
+    echo empty; return
+  fi
+  if has "$key" || has "$optin"; then
+    if has "$cred"; then
+      # unsealed -> sealed rotation, past the blob's rename.
+      derived=$(keyseal_derive_pub "$slot") || derived=
+      [[ -n $derived ]] || { echo inconsistent; return; }
+      if has "$pub_s" && ! has "$cred_s" && [[ $(keyseal_read_pin "$pub_s" || true) == "$derived" ]]; then
+        echo half-rotated; return
+      fi
+      if has "$pub" && [[ $(keyseal_read_pin "$pub" || true) == "$derived" ]]; then
+        kp=$(key_pub) || kp=
+        if [[ -n $kp && $kp == "$derived" ]]; then echo inconsistent; return; fi
+        echo rotated; return
+      fi
+      echo inconsistent; return
+    fi
+    if ! has "$pub"; then
+      # The pin's rename is the unsealed commit: before it, nothing was ever printed.
+      if has "$pub_s" || { has "$key" && [[ -f $key && ! -L $key && ! -s $key ]] && ! has "$optin"; }; then
+        echo uncommitted-unsealed; return
+      fi
+      echo inconsistent; return
+    fi
+    kp=$(key_pub) || kp=
+    if [[ -n $kp && $(keyseal_read_pin "$pub" || true) == "$kp" ]] && optin_valid; then
+      if has "$cred_s" || has "$pub_s" || has "$optin_s"; then echo staging; else echo committed-unsealed; fi
+      return
+    fi
+    echo inconsistent; return
+  fi
+  if ! has "$cred" && ! has "$pub"; then echo staging; return; fi
+  has "$cred" && derived=$(keyseal_derive_pub "$slot") || derived=
+  if [[ -n $derived ]] && has "$pub_s" && ! has "$cred_s" && [[ $(keyseal_read_pin "$pub_s" || true) == "$derived" ]]; then
+    echo half; return
+  fi
+  if [[ -n $derived ]] && has "$pub" && [[ $(keyseal_read_pin "$pub" || true) == "$derived" ]]; then
+    if has "$cred_s" || has "$pub_s" || has "$optin_s"; then echo staging; else echo committed; fi
+    return
+  fi
+  echo inconsistent
+}
+
+# `finished`: this run completed an interrupted commit, so --rotate does not rotate again.
+restart=no generate=no finished=no
+while :; do
+  row=$(table_row)
+  case $row in
+    empty)
+      case $want in
+        sealed) generate=sealed ;;
+        unsealed) generate=unsealed ;;
+        *)
+          if [[ $refresh == yes ]]; then keyseal_die "nothing_to_refresh: slot $slot holds no committed key"; fi
+          echo "provision: capability_absent (probe.sh: incapable, and slot $slot holds no committed key). Re-run with --allow-unsealed-key to accept an unsealed 0600 key" >&2
+          exit 2
+          ;;
+      esac
+      break
+      ;;
+    staging) rm -f -- "$cred_s" "$pub_s" "$optin_s"; sync -- "$K" ;;
+    uncommitted-unsealed) rm -f -- "$key" "$pub_s" "$optin" "$optin_s" "$cred_s"; sync -- "$K" ;;
+    half | half-rotated)
+      mv -f -- "$pub_s" "$pub"
+      sync -- "$K"
+      restart=yes finished=yes
+      ;;
+    rotated)
+      rm -f -- "$optin" "$key"
+      sync -- "$K"
+      restart=yes finished=yes
+      ;;
+    committed)
+      # (want=unsealed cannot reach here: the downgrade refusal above ran first.)
+      if [[ $rotate == yes && $finished == no ]]; then
+        [[ $want == sealed ]] || keyseal_die "rotate_needs_capable: this host cannot seal a new key (probe.sh)"
+        generate=sealed restart=yes
+      fi
+      break
+      ;;
+    committed-unsealed)
+      if [[ $rotate == yes ]]; then
+        [[ $want == sealed ]] || keyseal_die "rotate_needs_capable: --rotate turns an unsealed slot sealed, which needs probe.sh capable; this host is not"
+        generate=sealed restart=yes
+      elif [[ $want == sealed ]]; then
+        echo "provision: upgrade_available: this host can now seal; provision.sh --harness $harness --slot $slot --rotate, then re-enroll and revoke the old identity" >&2
+      fi
+      break
+      ;;
+    *) keyseal_die "slot_inconsistent: $K holds a state the recovery table does not name; nothing was deleted" ;;
+  esac
+done
+keyseal_seam_point recovered
+
+# ---------------------------------------------------------------------------
+# step 3: install, migrate, reload, and check the chain BEFORE any key is loaded. Every
+# layout change holds .loader.lock (outside the slot grammar), across all slots.
+# ---------------------------------------------------------------------------
+unit_dir=$(keyseal_unit_dir)
+libexec=$(keyseal_libexec_dir)
+load_tpl=$unit_dir/$KEYSEAL_LOAD_UNIT@.service
+mkdir -p -- "$unit_dir" "$libexec"
+exec {layout_fd}>"$K/.loader.lock"
+"$FLOCK" -w 60 "$layout_fd" || keyseal_die "loader_busy: another provision holds $K/.loader.lock"
+keyseal_seam_point layout-locked
+
+if [[ -e $unit_dir/$KEYSEAL_BASE_UNIT@.service ]]; then
+  # Adoption (KS-7): an existing base unit is kept only if its directive multiset equals the
+  # shipped one; otherwise refuse, and leave it byte-identical.
+  if [[ $(keyseal_node directives "$unit_dir/$KEYSEAL_BASE_UNIT@.service") != \
+    "$(keyseal_node directives "$here/$KEYSEAL_BASE_UNIT@.service")" ]]; then
+    keyseal_die "base_unit_mismatch: $unit_dir/$KEYSEAL_BASE_UNIT@.service differs from the shipped directive set; refusing to adopt or replace it"
+  fi
+else
+  install -m 0644 -- "$here/$KEYSEAL_BASE_UNIT@.service" "$unit_dir/"
+fi
+
+# Install the set in $1 as its immutable version directory, or verify the one already there.
+# Prints the set sha.
+install_version() {
+  local src=$1 sha d tmp f
+  shift
+  sha=$(keyseal_files_sha "$src" "$@") || keyseal_die "install_set_incomplete in $src"
+  d=$libexec/$(keyseal_version_dirname "$sha")
+  if has "$d"; then
+    [[ -d $d && ! -L $d && $(keyseal_dir_sha "$d" || true) == "$sha" ]] ||
+      keyseal_die "loader_version_mismatch: $d exists and does not hold version $sha; refusing to overwrite an immutable version"
+  else
+    tmp=$(mktemp -d "$libexec/.v-staging.XXXXXX")
+    for f in "$@"; do install -m 0755 -- "$src/$f" "$tmp/"; done
+    chmod 0755 "$tmp"
+    sync -- "$tmp"
+    mv -T -- "$tmp" "$d"
+    sync -- "$libexec"
+  fi
+  printf '%s' "$sha"
+}
+# Point slot $1 at version $2 (atomic rename of a fresh symlink), and record it.
+point_slot() {
+  local s=$1 sha=$2 link tmp
+  link=$(keyseal_slot_link "$s")
+  if has "$link" && [[ ! -L $link ]]; then keyseal_die "slot_link_not_a_symlink: $link"; fi
+  tmp=$libexec/.$KEYSEAL_SLOT_LINK_PREFIX$s.staging
+  rm -f -- "$tmp"
+  ln -s -- "$(keyseal_version_dirname "$sha")" "$tmp"
+  mv -T -f -- "$tmp" "$link"
+  sync -- "$libexec"
+}
+record_slot() {
+  local s=$1 sha=$2 rec
+  rec=$(keyseal_loader_record "$s")
+  printf '%s\n' "$sha" >"$rec.staging"
+  sync -- "$rec.staging"
+  mv -f -- "$rec.staging" "$rec"
+  sync -- "$K"
+}
+template_is() { [[ -f $load_tpl ]] && cmp -s -- "$1" "$load_tpl"; }
+template_is_legacy() {
+  [[ -f $load_tpl ]] || return 1
+  local line
+  while IFS= read -r line; do
+    line=${line#"${line%%[![:space:]]*}"}
+    [[ $line == "ExecStart=$KEYSEAL_LEGACY_LOAD_EXEC" ]] && return 0
+  done <"$load_tpl"
+  return 1
+}
+swap_template() {
+  install -m 0644 -- "$here/$KEYSEAL_LOAD_UNIT@.service" "$load_tpl.staging"
+  mv -f -- "$load_tpl.staging" "$load_tpl"
+  sync -- "$unit_dir"
+}
+
+# Every slot the template serves: each with committed material in K (a blob, pin or key; enabled
+# or not, running or not) and each enabled loader instance (review round 1, adversarial 2).
+all_slots() {
+  local f s
+  {
+    keyseal_enabled_slots
+    for f in "$K"/*.cred "$K"/*.pub "$K"/*.key; do
+      [[ -e $f ]] || continue
+      s=${f##*/}
+      s=${s%.*}
+      [[ $s =~ $KEYSEAL_SLOT_RE ]] && printf '%s\n' "$s"
+    done
+  } | sort -u
+}
+# The slots that hold a key: the ones legacy removal must not strand.
+committed_slots() {
+  local f s
+  for f in "$K"/*.cred "$K"/*.pub "$K"/*.key; do
+    [[ -e $f ]] || continue
+    s=${f##*/}
+    s=${s%.*}
+    [[ $s =~ $KEYSEAL_SLOT_RE ]] && printf '%s\n' "$s"
+  done | sort -u
+}
+
+# Migration from the flat layout: every slot onto a version directory holding the flat files it
+# runs today, THEN the template, THEN the legacy files. Only the flat set c5e358f shipped is
+# migrated: unknown content is never laundered into a recorded version (review round 1, S1).
+if template_is_legacy; then
+  keyseal_legacy_present || keyseal_die "legacy_layout_incomplete: $load_tpl runs the flat loader but $libexec holds no flat install set"
+  keyseal_legacy_known || keyseal_die "legacy_loader_unknown: the flat loader files in $libexec are not the set c5e358f shipped; refusing to migrate them (status.sh reports the chain)"
+  legacy_sha=$(install_version "$libexec" "${KEYSEAL_LEGACY_INSTALL_SET[@]}")
+  keyseal_seam_point migrate-install
+  mapfile -t migrating < <(all_slots)
+  for s in "${migrating[@]}"; do point_slot "$s" "$legacy_sha"; done
+  keyseal_seam_point migrate-link
+  for s in "${migrating[@]}"; do record_slot "$s" "$legacy_sha"; done
+  keyseal_seam_point migrate-record
+  swap_template
+  keyseal_seam_point migrate-swap
+  "$SYSTEMCTL" --user daemon-reload || keyseal_die "daemon_reload_failed after the template swap; the legacy files are kept"
+  keyseal_seam_point migrate-reload
+elif ! template_is "$here/$KEYSEAL_LOAD_UNIT@.service"; then
+  swap_template
+fi
+
+sha=$(install_version "$here" "${KEYSEAL_INSTALL_SET[@]}")
+loader_changed=no
+[[ $(keyseal_read_loader_record "$slot" || true) == "$sha" && $(readlink -- "$(keyseal_slot_link "$slot")" || true) == "$(keyseal_version_dirname "$sha")" ]] || loader_changed=yes
+point_slot "$slot" "$sha"
+keyseal_seam_point link-pointed
+record_slot "$slot" "$sha"
+"$SYSTEMCTL" --user daemon-reload || keyseal_die "daemon_reload_failed"
+keyseal_seam_point pointed
+
+# Legacy flat files: removed only once every slot holding a key has its symlink and
+# daemon-reload has succeeded (above, in this run). A missing symlink is a DELETION
+# precondition, never an error: the files stay, status reports legacy_loader_present (2), and
+# `provision.sh --refresh-loader` for that slot (which has a key, so it can) links it and
+# removes them (review round 1, Gemini 1). An enabled slot with no key cannot load anything,
+# before or after, so it never holds them.
+if keyseal_legacy_present && ! template_is_legacy; then
+  unlinked=
+  while IFS= read -r s; do
+    [[ -z $s || -L $(keyseal_slot_link "$s") ]] || unlinked+=" $s"
+  done < <(committed_slots)
+  if [[ -z $unlinked ]]; then
+    for f in "${KEYSEAL_LEGACY_INSTALL_SET[@]}"; do rm -f -- "${libexec:?}/$f"; done
+    sync -- "$libexec"
+    keyseal_seam_point migrate-cleanup
+  else
+    echo "provision: legacy loader files kept: slot(s)$unlinked have no ${KEYSEAL_SLOT_LINK_PREFIX}<s> symlink yet; provision.sh --refresh-loader for each removes them" >&2
+  fi
+fi
+
+# A version directory goes only when no slot symlink references it; staging leftovers go.
+declare -A referenced=()
+for l in "$libexec/$KEYSEAL_SLOT_LINK_PREFIX"*; do
+  [[ -L $l ]] && referenced[$(readlink -- "$l")]=1
+done
+for d in "$libexec/$KEYSEAL_VERSION_PREFIX"* "$libexec"/.v-staging.*; do
+  [[ -d $d && ! -L $d ]] || continue
+  [[ -n ${referenced[${d##*/}]-} ]] || rm -rf -- "$d"
+done
+
+keyseal_chain_check "$slot" "$here" || keyseal_die "chain check failed before loading any key:"$'\n'"$KEYSEAL_CHAIN_PROBLEMS"
+[[ $KEYSEAL_LOADER_STATE == current && $KEYSEAL_CHAIN_LEGACY == no ]] ||
+  keyseal_die "loader not current after install ($KEYSEAL_LOADER_STATE)"
+exec {layout_fd}>&-
+
+# ---------------------------------------------------------------------------
+# step 4: generate and commit
+# ---------------------------------------------------------------------------
+if [[ $generate == sealed ]]; then
+  rm -f -- "$cred_s" "$pub_s"
+  # pipefail: a keygen that fails after printing a whole PEM still fails this step (KS-4).
+  node "$here/keygen.mjs" --pub-out "$pub_s" \
+    | "$CREDS" --user encrypt --name="$(keyseal_cred_name "$slot")" - "$cred_s" \
+    || keyseal_die "keygen_or_encrypt_failed; the staging files are deleted by the next run"
+  keyseal_seam_point keygen
+  keyseal_seam_point encrypt
+  sync -- "$cred_s" "$pub_s"
+  mv -f -- "$cred_s" "$cred"
+  sync -- "$K"
+  keyseal_seam_point cred-rename
+  mv -f -- "$pub_s" "$pub"
+  sync -- "$K"
+  keyseal_seam_point pub-rename
+  if has "$optin" || has "$key"; then
+    # An unsealed slot rotated into sealed mode: its old key goes, opt-in first.
+    rm -f -- "$optin"
+    sync -- "$K"
+    keyseal_seam_point optin-remove
+    rm -f -- "$key"
+    sync -- "$K"
+    keyseal_seam_point key-remove
+  fi
+elif [[ $generate == unsealed ]]; then
+  rm -f -- "$pub_s" "$optin_s"
+  # The opt-in path: the PEM goes into <s>.key, 0600 (umask 077), never over an existing file.
+  (set -C && node "$here/keygen.mjs" --pub-out "$pub_s" >"$key") ||
+    keyseal_die "keygen_failed; the uncommitted key is deleted by the next run"
+  keyseal_seam_point keygen
+  sync -- "$key" "$pub_s"
+  mid=$(keyseal_machine_id) || keyseal_die "machine_id_unreadable: $MACHINE_ID_FILE"
+  {
+    printf 'version=1\n'
+    printf 'machine_id=%s\n' "$mid"
+    printf 'uid=%s\n' "$(keyseal_uid)"
+    printf 'slot=%s\n' "$slot"
+    printf 'pub_sha256=%s\n' "$(keyseal_sha256_file "$pub_s")"
+    printf 'granted_at=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  } >"$optin_s"
+  sync -- "$optin_s"
+  mv -f -- "$optin_s" "$optin"
+  sync -- "$K"
+  keyseal_seam_point optin-rename
+  # BEFORE the pin's rename (the commit), re-read both halves under the loader's own predicate:
+  # the opt-in against the staged pin, the key's public key against it. A failure is still an
+  # uncommitted generation, nothing was printed, so it is deleted now (review round 1, B1).
+  kp=$(keyseal_keyfile_pub "$key") || kp=
+  if ! problems=$(keyseal_optin_verify "$optin" "$pub_s" "$slot" "$(keyseal_uid)" "$mid") ||
+    [[ $kp != "$(keyseal_read_pin "$pub_s" || true)" ]]; then
+    rm -f -- "$key" "$optin" "$pub_s"
+    sync -- "$K"
+    keyseal_die "slot_inconsistent: the opt-in does not validate against the staged pin (${problems//$'\n'/; }); the uncommitted key is deleted"
+  fi
+  mv -f -- "$pub_s" "$pub"
+  sync -- "$K"
+  keyseal_seam_point pub-rename
+  echo "provision: slot $slot is UNSEALED by opt-in: $key is a plaintext 0600 key (probe.sh: incapable). status.sh reports it; provision.sh --rotate once this host can seal" >&2
+fi
+pin=$(keyseal_read_pin "$pub") || keyseal_die "slot_inconsistent: no pin after commit"
+
+# ---------------------------------------------------------------------------
+# step 5: enable and start; restart on rotate or recovery, reload on a new loader version
+# ---------------------------------------------------------------------------
+"$SYSTEMCTL" --user enable --now "$base_unit" "$load_unit" >/dev/null 2>&1 || true
+for u in "$base_unit" "$load_unit"; do
+  [[ $("$SYSTEMCTL" --user is-enabled "$u" 2>/dev/null || true) == enabled ]] || keyseal_die "not_enabled: $u"
+done
+keyseal_seam_point enable
+if [[ $restart == yes ]]; then
+  "$SYSTEMCTL" --user restart "$base_unit" >/dev/null 2>&1 || true
+elif [[ $loader_changed == yes ]]; then
+  "$SYSTEMCTL" --user restart "$load_unit" >/dev/null 2>&1 || true
+fi
+keyseal_seam_point load
+
+# ---------------------------------------------------------------------------
+# step 6: every path ends with the agent holding exactly the pin
+# ---------------------------------------------------------------------------
+# Waits while the loader may still be running; a loader that has finished (active or
+# failed) with the wrong key set is a mismatch now, not in 5 s.
+holds_pin() {
+  local i
+  for ((i = 0; i < KEYSEAL_SOCK_WAIT_STEPS; i++)); do
+    keyseal_agent_holds_exactly "$slot" "$pin" && return 0
+    case $("$SYSTEMCTL" --user is-active "$load_unit" 2>/dev/null || true) in
+      active | failed) return 1 ;;
+    esac
+    "$SLEEP" 0.1
+  done
+  return 1
+}
+if ! holds_pin; then
+  "$SYSTEMCTL" --user restart "$base_unit" >/dev/null 2>&1 || true
+  holds_pin || keyseal_die "pin_not_loaded: the slot agent does not hold exactly the committed key after one restart"
+fi
+
+printf 'agent_socket:%s#%s\n' "$(keyseal_sock_path "$slot")" "$pin"
+if [[ $rotate == yes ]]; then
+  cat >&2 <<EOT
+provision: slot $slot rotated. Next, in order:
+  1. re-enroll the new key (owner): it is not yet known to the board;
+  2. re-point the harness at the new reference printed above;
+  3. revoke the old key (owner) once the harness signs with the new one.
+EOT
+fi

package/keyslot/seam.sh

@@ -0,0 +1,48 @@
+# shellcheck shell=bash
+# The test seam. An override is honoured only under KEYSEAL_TEST_ROOT, and only when it
+# resolves inside that root; anything else is refused, never silently replaced by the
+# default, so a stray variable in a real environment cannot redirect a binary.
+
+# 0 when the seam is active (a test run), else 1. Scripts stamp their output with it.
+seam_active() { [[ -n ${KEYSEAL_TEST_ROOT-} ]]; }
+
+# seam_resolve <VAR> <default>: print the value of $VAR when it is set and confined to
+# KEYSEAL_TEST_ROOT, else <default> when $VAR is unset or empty; otherwise print
+# seam_override_refused to stderr and return 1.
+seam_resolve() {
+  local var=$1 default=$2 override root real
+  override=${!var-}
+  if [[ -z $override ]]; then
+    printf '%s' "$default"
+    return 0
+  fi
+  if ! seam_active; then
+    printf 'seam_override_refused: %s is set without KEYSEAL_TEST_ROOT\n' "$var" >&2
+    return 1
+  fi
+  # realpath only on this branch: the production path never depends on it.
+  root=$(/usr/bin/realpath -m -- "$KEYSEAL_TEST_ROOT") || root=
+  real=$(/usr/bin/realpath -m -- "$override") || real=
+  if [[ -z $root || $root == / || -z $real || $real/ != "$root"/* ]]; then
+    printf 'seam_override_refused: %s is outside KEYSEAL_TEST_ROOT\n' "$var" >&2
+    return 1
+  fi
+  printf '%s' "$override"
+}
+
+# seam_pause <point> <sleep-binary>: under KEYSEAL_TEST_ROOT only, when KEYSEAL_TEST_FAIL_AT is
+# <point> and KEYSEAL_TEST_FAIL_MODE is `pause`, create $KEYSEAL_TEST_ROOT/paused.<point> and wait
+# (at most 60 s) for $KEYSEAL_TEST_ROOT/resume. The loader's only seam: it never moves, writes or
+# deletes anything else, so the TEST does whatever the pause is for. A no-op in production.
+seam_pause() {
+  seam_active || return 0
+  [[ ${KEYSEAL_TEST_FAIL_AT-} == "$1" && ${KEYSEAL_TEST_FAIL_MODE-} == pause ]] || return 0
+  : >"$KEYSEAL_TEST_ROOT/paused.$1"
+  local i
+  for ((i = 0; i < 1200; i++)); do
+    [[ -e $KEYSEAL_TEST_ROOT/resume ]] && return 0
+    "$2" 0.05
+  done
+  printf 'seam_pause_timeout %s\n' "$1" >&2
+  return 1
+}