@consiliency/agent-board-cli 1.23.0 → 1.25.0

package/keyslot/status.sh

@@ -0,0 +1,254 @@
+#!/bin/bash
+# status.sh --harness <h> [--slot <s>] [--json]: what does slot <s> hold, measured, and is it
+# chained and loaded? (IF-0-KEYSEAL-3, IF-0-KEYSEAL-6). <s> defaults to <h>.
+#
+# MODE, from provenance only, never from what provision was asked (A1):
+#   sealed        <s>.cred + <s>.pub, the pin derives from a PIPED decrypt of the blob, no
+#                 <s>.key, no opt-in
+#   unsealed      a valid opt-in + <s>.key whose public key equals the pin, no blob
+#   contradiction (exit 1) the blob and <s>.key both present; an opt-in beside a blob; <s>.key
+#                 without a valid opt-in; an opt-in without <s>.key; a pin the key or blob does
+#                 not derive to; a pin or blob missing where the rest is committed; a staging file
+#   undetermined  (exit 2) nothing committed (no blob, pin, key or opt-in at all), or the blob
+#                 could not be read because sealing is broken on this host (probe not capable)
+# The opt-in is opened under principle 4 (O_NOFOLLOW, the opened descriptor this uid's and
+# 0600, every ancestor a real directory nobody else can write) and every field must match:
+# machine_id (sha256(/etc/machine-id)[:16]), uid, slot, and pub_sha256 = sha256(<s>.pub). A
+# record copied from another machine, user or slot fails.
+#
+# Checks: 1 committed (the provenance above), 2 chain (both units' Exec argv, Environment,
+# FragmentPath and drop-ins against the shipped units; the slot's loader symlink, version
+# directory and <s>.loader-sha256), 3 units (both enabled, base active, loader active
+# (exited)), 4 agent (`ssh-add -L` lists exactly the pin), 5 linger, 6 scan (no plaintext copy
+# of the slot key in IF-0-KEYSEAL-5's scope; an unsealed slot's own <s>.key, that path, 0600,
+# this uid's, is the one exemption).
+#
+# EXIT, frozen precedence (A1): 1 on any contradiction or failed check, and 1 BEATS every
+# exit-2 cause; else 2 on any exit-2 cause; else 0. Exit-2 causes:
+#   capability     sealed and probe.sh not `capable`; unsealed and probe.sh neither
+#                  `incapable` nor `capable` (unsealed EXPECTS incapable)
+#   linger_off
+#   upgrade_available      unsealed on a host that is now capable: provision.sh --rotate
+#   loader_outdated        the slot runs its recorded loader version, not the running tooling's
+#   loader_unrecorded      no <s>.loader-sha256 (a slot provisioned before A1)
+#   legacy_loader_present  flat-layout loader files (pre-A1) are present, or the installed
+#                          template still runs them
+#   nothing_committed, undeterminable
+# The remedy for the three loader causes is provision.sh --refresh-loader, which never re-keys.
+# The JSON carries hashes only: never the pin, the reference or any key byte.
+set -euo pipefail
+
+here=${BASH_SOURCE[0]%/*}
+[[ $here == "${BASH_SOURCE[0]}" ]] && here=.
+# shellcheck source=lib.sh
+. "$here/lib.sh"
+
+harness= slot= json=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>" ;;
+    --json) json=yes; shift ;;
+    *) keyseal_die "usage: status.sh --harness <h> [--slot <s>] [--json]" ;;
+  esac
+done
+[[ $harness =~ $KEYSEAL_SLOT_RE ]] || keyseal_die "bad_harness"
+slot=${slot:-$harness}
+[[ $slot =~ $KEYSEAL_SLOT_RE ]] || keyseal_die "bad_slot"
+: "${XDG_RUNTIME_DIR:?status: XDG_RUNTIME_DIR unset}"
+: "${HOME:?status: HOME unset}"
+keyseal_resolve_bins || exit 1
+
+K=$(keyseal_key_dir)
+cred=$K/$slot.cred pub=$K/$slot.pub key=$K/$slot.key optin=$K/$slot.unsealed-optin
+base_unit=$KEYSEAL_BASE_UNIT@$slot.service
+load_unit=$KEYSEAL_LOAD_UNIT@$slot.service
+declare -A ok detail
+exit2=()
+has() { [[ -e $1 || -L $1 ]]; }
+
+probe_out=$("$here/probe.sh" --json 2>/dev/null) && probe_rc=0 || probe_rc=$?
+outcome=error
+[[ $probe_out =~ \"outcome\":\"([a-z-]+)\" ]] && outcome=${BASH_REMATCH[1]}
+round_trip=unknown
+[[ $probe_out =~ \"round_trip\":\"([a-z_]+)\" ]] && round_trip=${BASH_REMATCH[1]}
+
+# 1 committed: the provenance table. The pin is read whatever the provenance, so a
+# contradiction still scans for copies of the pinned key (review round 1, Opus S3).
+contra=()
+mode=undetermined optin_json=null
+pin=$(keyseal_read_pin "$pub") || pin=
+has "$cred" && has "$key" && contra+=("a sealed blob and an unsealed key are both present")
+has "$cred" && has "$optin" && contra+=("an opt-in record beside a sealed blob")
+has "$optin" && ! has "$key" && contra+=("an opt-in record without $slot.key")
+if has "$optin"; then
+  optin_ok=true
+  optin_problems=$(keyseal_optin_check "$slot") || optin_ok=false
+  plist=
+  while IFS= read -r line; do [[ -n $line ]] && plist+="${plist:+,}$(keyseal_json_str "$line")"; done <<<"$optin_problems"
+  optin_json="{\"ok\":$optin_ok,\"problems\":[$plist]}"
+fi
+if has "$key" && ! has "$optin"; then contra+=("$slot.key without an opt-in record"); fi
+if has "$K/$slot.cred.staging" || has "$K/$slot.pub.staging" || has "$K/$slot.unsealed-optin.staging"; then
+  contra+=("staging file present")
+fi
+if ((${#contra[@]} == 0)); then
+  if ! has "$cred" && ! has "$pub" && ! has "$key" && ! has "$optin"; then
+    exit2+=(nothing_committed)
+  elif has "$key"; then
+    # The loader's own predicate (optin.sh): what it would refuse to load is a contradiction.
+    if problems=$(keyseal_unsealed_check "$slot"); then mode=unsealed
+    else contra+=("the unsealed slot does not verify: ${problems//$'\n'/; }")
+    fi
+  elif ! has "$cred"; then contra+=("blob missing")
+  elif [[ -z $pin ]]; then contra+=("pin missing or malformed")
+  else
+    drc=0
+    derived=$(keyseal_derive_pub "$slot") || drc=$?
+    if ((drc == 0)); then
+      if [[ $derived == "$pin" ]]; then mode=sealed; else contra+=("pin does not derive from the blob"); fi
+    elif [[ $outcome == capable ]]; then
+      contra+=("the blob does not decrypt to a key, though sealing works here")
+    else
+      exit2+=(undeterminable)
+    fi
+  fi
+fi
+if ((${#contra[@]})); then
+  mode=contradiction ok[committed]=false
+  detail[committed]=$(printf '%s; ' "${contra[@]}")
+  detail[committed]=${detail[committed]%; }
+else
+  ok[committed]=true detail[committed]=""
+fi
+
+# 2 chain, including the slot's loader version
+if keyseal_chain_check "$slot" "$here"; then ok[chain]=true detail[chain]=""
+else ok[chain]=false detail[chain]=${KEYSEAL_CHAIN_PROBLEMS%$'\n'}
+fi
+legacy=no
+if [[ $KEYSEAL_CHAIN_LEGACY == yes ]] || keyseal_legacy_present; then legacy=yes exit2+=(legacy_loader_present); fi
+if [[ $KEYSEAL_CHAIN_LEGACY == no ]]; then
+  case $KEYSEAL_LOADER_STATE in
+    outdated) exit2+=(loader_outdated) ;;
+    unrecorded) exit2+=(loader_unrecorded) ;;
+  esac
+fi
+
+# 3 units
+state() { "$SYSTEMCTL" --user "$1" "$2" 2>/dev/null || true; }
+sub=$("$SYSTEMCTL" --user show -p SubState "$load_unit" 2>/dev/null || true)
+if [[ $(state is-enabled "$base_unit") == enabled && $(state is-enabled "$load_unit") == enabled &&
+  $(state is-active "$base_unit") == active && $(state is-active "$load_unit") == active && $sub == SubState=exited ]]; then
+  ok[units]=true detail[units]=""
+else
+  ok[units]=false detail[units]="base $(state is-enabled "$base_unit")/$(state is-active "$base_unit"), loader $(state is-enabled "$load_unit")/$(state is-active "$load_unit") ${sub#SubState=}"
+fi
+
+# 4 agent: exactly one identity, and it is the pin. `empty` is told apart from a wrong or
+# extra key: an empty agent can be the CONSEQUENCE of an exit-2 cause (below).
+agent_empty=no
+if [[ -n $pin ]] && keyseal_agent_holds_exactly "$slot" "$pin"; then ok[agent]=true detail[agent]=""
+else
+  held=$(keyseal_agent_keys "$slot" 2>/dev/null) || held="?"
+  if [[ -z $held ]]; then agent_empty=yes; fi
+  n=$(printf '%s' "$held" | "$KEYSEAL_BIN_GREP" -c . || true)
+  [[ $held == "?" ]] && n=
+  ok[agent]=false detail[agent]="the slot agent holds ${n:-an unreadable set of} identities, not exactly the pin"
+fi
+
+# 5 linger, and capability for the measured mode
+linger=$(keyseal_linger)
+if [[ $linger == yes ]]; then ok[linger]=true detail[linger]=""; else ok[linger]=false detail[linger]="linger is $linger"; exit2+=(linger_off); fi
+upgrade=no
+case $mode in
+  sealed) [[ $outcome == capable ]] || exit2+=("capability_$outcome") ;;
+  unsealed)
+    if [[ $outcome == capable ]]; then upgrade=yes exit2+=(upgrade_available)
+    elif [[ $outcome != incapable ]]; then exit2+=("capability_$outcome")
+    fi
+    ;;
+esac
+
+# 6 scan: the unsealed slot's own key file is the one exemption
+exempt=
+[[ $mode == unsealed ]] && exempt=$key
+if scan=$(keyseal_scan "$pin" "$exempt"); then
+  if [[ $scan == *'"plaintext_matches":[]'* ]]; then ok[scan]=true detail[scan]=""
+  else ok[scan]=false detail[scan]="plaintext copy of the slot key found"
+  fi
+else
+  scan='{}' ok[scan]=false detail[scan]="the scan did not run to completion"
+fi
+
+# Nothing committed is 2 by the provenance table: there is no unit, agent or chain to judge.
+hard=(committed chain units agent scan)
+[[ ${exit2[*]} == *nothing_committed* ]] && hard=(committed scan)
+# committed, chain and scan are always hard. A loader that could not run, or an agent it left
+# EMPTY, is the consequence of a sealed slot's capability loss or an undeterminable blob, so it
+# is 2 while one is present (review round 1, Opus B2). A wrong or extra key stays 1.
+soft=no
+# Only causes that EXPLAIN an empty agent (review round 2, Opus N1): a sealed slot whose sealing
+# is gone, or a blob that could not be read. Linger off does not (status needs a running
+# manager), and an unsealed loader never uses sealing.
+for r in "${exit2[@]}"; do
+  case $r in
+    undeterminable) soft=yes ;;
+    # error or incapable: the decrypt itself is gone. incapable-for-keyslot is linger or the ssh
+    # tools, which alone do not stop a decrypt; but probe.sh reports a lost systemd-creds on a
+    # no-linger host as incapable-for-keyslot too, so it counts when the round trip failed.
+    capability_error | capability_incapable) [[ $mode == sealed ]] && soft=yes ;;
+    capability_incapable-for-keyslot) [[ $mode == sealed && $round_trip != equal ]] && soft=yes ;;
+  esac
+done
+if [[ $soft == yes ]]; then
+  still_hard=()
+  for c in "${hard[@]}"; do
+    case $c in
+      agent) [[ ${ok[agent]} == true || $agent_empty == yes ]] || still_hard+=(agent) ;;
+      units)
+        [[ ${ok[units]} == true ]] ||
+          { [[ $(state is-enabled "$base_unit") == enabled && $(state is-enabled "$load_unit") == enabled ]] || still_hard+=(units); }
+        ;;
+      *) still_hard+=("$c") ;;
+    esac
+  done
+  hard=("${still_hard[@]}")
+fi
+rc=0
+for c in "${hard[@]}"; do [[ ${ok[$c]} == true ]] || rc=1; done
+if ((rc == 0 && ${#exit2[@]})); then rc=2; fi
+
+pin_sha=null blob_sha=null
+[[ -n $pin ]] && pin_sha=$(keyseal_json_str "$(keyseal_sha256_str "$pin")")
+[[ -f $cred ]] && blob_sha=$(keyseal_json_str "$(keyseal_sha256_file "$cred")")
+boot_id=$(</proc/sys/kernel/random/boot_id)
+machine_id=$(keyseal_machine_id) || machine_id=
+bool() { if [[ $1 == yes ]]; then printf true; else printf false; fi; }
+reasons=
+for r in "${exit2[@]}"; do reasons+="${reasons:+,}$(keyseal_json_str "$r")"; done
+outdated=no
+[[ ${exit2[*]} == *loader_outdated* ]] && outdated=yes
+str_or_null() { if [[ -n $1 ]]; then keyseal_json_str "$1"; else printf null; fi; }
+
+if [[ $json == yes ]]; then
+  checks=
+  for c in committed chain units agent linger scan; do
+    checks+="${checks:+,}\"$c\":{\"ok\":${ok[$c]},\"detail\":$(keyseal_json_str "${detail[$c]}")}"
+  done
+  printf '{"tool":"status","seam":%s,"host":%s,"uid":%s,"machine_id":%s,"harness":%s,"slot":%s,"mode":%s,"boot_id":%s,"pin_sha256":%s,"blob_sha256":%s,"capability_probe_exit":%s,"probe_outcome":%s,"optin":%s,"loader":{"recorded_sha256":%s,"running_sha256":%s,"state":%s},"upgrade_available":%s,"loader_outdated":%s,"legacy_loader_present":%s,"exit2_reasons":[%s],"checks":{%s},"scan":%s,"exit":%s}\n' \
+    "$(keyseal_seam_json)" "$(keyseal_json_str "$(uname -n)")" "$(keyseal_uid)" "$(str_or_null "$machine_id")" \
+    "$(keyseal_json_str "$harness")" "$(keyseal_json_str "$slot")" "$(keyseal_json_str "$mode")" \
+    "$(keyseal_json_str "$boot_id")" "$pin_sha" "$blob_sha" "$probe_rc" "$(keyseal_json_str "$outcome")" "$optin_json" \
+    "$(str_or_null "$KEYSEAL_LOADER_RECORDED")" "$(str_or_null "$KEYSEAL_LOADER_RUNNING")" \
+    "$(keyseal_json_str "$([[ $KEYSEAL_CHAIN_LEGACY == yes ]] && echo legacy || echo "$KEYSEAL_LOADER_STATE")")" \
+    "$(bool "$upgrade")" "$(bool "$outdated")" "$(bool "$legacy")" "$reasons" "$checks" "$scan" "$rc"
+else
+  for c in committed chain units agent linger scan; do
+    printf '%-9s %s %s\n' "$c" "$([[ ${ok[$c]} == true ]] && echo ok || echo FAIL)" "${detail[$c]}"
+  done
+  printf 'mode      %s\n' "$mode"
+  ((${#exit2[@]})) && printf 'exit 2    %s\n' "${exit2[*]}"
+  printf 'status: exit %s (seam=%s)\n' "$rc" "$(keyseal_seam_json)"
+fi
+exit "$rc"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-cli",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,11 +17,12 @@
   "files": [
     "bin",
     "dist",
+    "keyslot",
     "LICENSE",
     "NOTICE"
   ],
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && node ../../scripts/lib/cli-assets.mjs --write",
     "prepack": "pnpm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run"
@@ -31,8 +32,11 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@consiliency/agent-board-client": "1.39.0",
+    "@consiliency/agent-board-client": "1.40.0",
     "commander": "^14.0.1"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "smol-toml": "1.9.0"
+  }
 }