@consiliency/agent-board-cli 1.27.0 → 1.28.0

package/keyslot/status.sh

@@ -1,6 +1,15 @@
 #!/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>.
+# status.sh --harness <h> [--slot <s>] [--json] [--scan-cache fresh|use|only] [--scan-timeout <s>]:
+# what does slot <s> hold, measured, and is it chained and loaded? (IF-0-KEYSEAL-3,
+# IF-0-KEYSEAL-6). <s> defaults to <h>.
+#
+# SCAN CACHE (IF-552-2, #552): check 6's result is cached per slot under
+# <state root>/agent-board/keyslot-scan/<slot>.json, valid for 24 h and only for the same seam,
+# uid, machine, slot, mode, exemption, pin, blob, scope and scanner. `fresh` (the default, a hand
+# run) never reads it and scans; `use` reads it and scans on a miss; `only` never scans, and a
+# miss is exit 2 `scan_not_cached`. A match is never cached: it writes a tombstone. The whole
+# scan stage runs under one `timeout` (--scan-timeout, default 1800 s); a scan that gives up is
+# exit 2 `scan_timed_out` and is never cached. Progress goes to stderr; stdout stays JSON.
 #
 # 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
@@ -34,6 +43,8 @@
 #   legacy_loader_present  flat-layout loader files (pre-A1) are present, or the installed
 #                          template still runs them
 #   nothing_committed, undeterminable
+#   scan_not_cached        --scan-cache only, and no valid cache (the scan is not judged)
+#   scan_timed_out         the scan stage hit --scan-timeout (the scan is not judged)
 # 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
@@ -43,21 +54,30 @@ here=${BASH_SOURCE[0]%/*}
 # shellcheck source=lib.sh
 . "$here/lib.sh"
 
-harness= slot= json=no
+harness= slot= json=no scan_cache=fresh scan_timeout=$KEYSEAL_SCAN_TIMEOUT_S
+usage="usage: status.sh --harness <h> [--slot <s>] [--json] [--scan-cache fresh|use|only] [--scan-timeout <s>]"
 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]" ;;
+    --scan-cache) scan_cache=${2-}; shift 2 || keyseal_die "$usage" ;;
+    --scan-timeout) scan_timeout=${2-}; shift 2 || keyseal_die "$usage" ;;
+    *) keyseal_die "$usage" ;;
   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}"
+[[ $scan_cache == fresh || $scan_cache == use || $scan_cache == only ]] || keyseal_die "bad_scan_cache: $usage"
+[[ $scan_timeout =~ ^[1-9][0-9]{0,6}$ ]] || keyseal_die "bad_scan_timeout: $usage"
+[[ -n ${XDG_RUNTIME_DIR-} ]] || keyseal_die "runtime_dir_unset: XDG_RUNTIME_DIR is unset, so the slot's agent socket cannot be located; run from a login session or export XDG_RUNTIME_DIR=/run/user/$(id -u)"
 : "${HOME:?status: HOME unset}"
 keyseal_resolve_bins || exit 1
+# The scan's cleanup (IF-552-2): the ticker, the stage group and every temp file, on any exit.
+trap keyseal_scan_cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
 
 K=$(keyseal_key_dir)
 cred=$K/$slot.cred pub=$K/$slot.pub key=$K/$slot.key optin=$K/$slot.unsealed-optin
@@ -66,6 +86,7 @@ load_unit=$KEYSEAL_LOAD_UNIT@$slot.service
 declare -A ok detail
 exit2=()
 has() { [[ -e $1 || -L $1 ]]; }
+str_or_null() { if [[ -n $1 ]]; then keyseal_json_str "$1"; else printf null; fi; }
 
 probe_out=$("$here/probe.sh" --json 2>/dev/null) && probe_rc=0 || probe_rc=$?
 outcome=error
@@ -170,20 +191,105 @@ case $mode in
     ;;
 esac
 
-# 6 scan: the unsealed slot's own key file is the one exemption
+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")")
+machine_id=$(keyseal_machine_id) || machine_id=
+
+# 6 scan: the unsealed slot's own key file is the one exemption. IF-552-2: the inputs a cached
+# result is valid for, the cache read (under its lock), then a scan unless a valid cache serves.
 exempt=
 [[ $mode == unsealed ]] && exempt=$key
-if scan=$(keyseal_scan "$pin" "$exempt"); then
-  if [[ $scan == *'"plaintext_matches":[]'* ]]; then ok[scan]=true detail[scan]=""
+stale_temp=$(keyseal_scan_stale_temp)
+keyseal_scan_roots
+KEYSEAL_INPUT=(
+  [seam]=$(keyseal_seam_json)
+  [uid]=$(keyseal_uid)
+  [machine_id]=$(str_or_null "$machine_id")
+  [slot]=$(keyseal_json_str "$slot")
+  [mode]=$(keyseal_json_str "$mode")
+  [exempt]=$(if [[ -n $exempt ]]; then keyseal_json_str "$(keyseal_sha256_str "$exempt")"; else printf null; fi)
+  [pin_sha256]=$pin_sha
+  [blob_sha256]=$blob_sha
+  [scope_sha256]=$(keyseal_json_str "$(keyseal_sha256_str "$(keyseal_scan_scope_json)")")
+  [scanner_sha256]=$(str_or_null "$(keyseal_files_sha "$here" lib.sh status.sh || true)")
+)
+keyseal_cache_read "$slot" "$scan_cache"
+cache_read="$KEYSEAL_CACHE_STATE:$KEYSEAL_CACHE_REASON"
+cache_last=null
+[[ -n $KEYSEAL_CACHE_LAST ]] && cache_last=$(keyseal_json_str "$(keyseal_iso "$KEYSEAL_CACHE_LAST")")
+scan_source=none scan_scanned_at=null scan_age=null scan_duration=null scan_core=
+scan_judged=yes scan_timed_out=no
+if [[ $KEYSEAL_CACHE_STATE == hit ]]; then
+  scan_source=cached scan_core=$KEYSEAL_CACHE_SCAN
+  scan_now=$(keyseal_now) || scan_now=$KEYSEAL_CACHE_SCANNED_AT
+  scan_scanned_at=$(keyseal_json_str "$(keyseal_iso "$KEYSEAL_CACHE_SCANNED_AT")")
+  scan_age=$((scan_now - KEYSEAL_CACHE_SCANNED_AT)) scan_duration=$KEYSEAL_CACHE_DURATION
+elif [[ $scan_cache == only ]]; then
+  scan_judged=no
+  detail[scan]="not judged: no valid scan cache ($KEYSEAL_CACHE_STATE:$KEYSEAL_CACHE_REASON)"
+  exit2+=(scan_not_cached)
+else
+  # scanned_at is the scan's START: a file created after it may be missed.
+  scan_start=$(keyseal_now) || scan_start=0
+  printf 'status: scan: starting (%s:%s)\n' "$KEYSEAL_CACHE_STATE" "$KEYSEAL_CACHE_REASON" >&2
+  keyseal_scan_run "$pin" "$exempt" "$scan_timeout"
+  scan_end=$(keyseal_now) || scan_end=$scan_start
+  scan_duration=$((scan_end - scan_start))
+  ((scan_duration >= 0)) || scan_duration=0
+  case $KEYSEAL_SCAN_OUTCOME in
+    ok)
+      scan_source=fresh scan_core=$(keyseal_scan_core_json)
+      scan_scanned_at=$(keyseal_json_str "$(keyseal_iso "$scan_start")") scan_age=$scan_duration
+      ;;
+    timed_out)
+      scan_judged=no scan_timed_out=yes
+      detail[scan]="not judged: the scan gave up after $scan_timeout s (scan_timed_out)"
+      exit2+=(scan_timed_out)
+      KEYSEAL_CACHE_STATE=not_written KEYSEAL_CACHE_REASON=timed_out
+      ;;
+    *)
+      detail[scan]="the scan did not run to completion"
+      KEYSEAL_CACHE_STATE=not_written KEYSEAL_CACHE_REASON=incomplete
+      ;;
+  esac
+fi
+if [[ -n $scan_core ]]; then
+  if [[ $scan_core == *'"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"
+  ok[scan]=false
+fi
+# A match is never cached: it writes a tombstone. Only a clean, completed, fresh scan commits.
+if [[ $scan_source == fresh ]]; then
+  if [[ ${ok[scan]} == true ]]; then keyseal_cache_commit_clean "$slot" "$scan_start" "$scan_duration" "$scan_core"
+  else keyseal_cache_commit_tombstone "$slot" "$harness"
+  fi
+fi
+if [[ $scan_source == fresh ]]; then
+  n_matches=0 n_candidates=0
+  [[ $scan_core =~ \"candidates\":([0-9]+) ]] && n_candidates=${BASH_REMATCH[1]}
+  [[ ${ok[scan]} == true ]] || n_matches=$(printf '%s' "$scan_core" | keyseal_node count-matches 2>/dev/null || printf '?')
+  printf 'status: scan: done in %s s (%s folders, %s candidates, %s matches)\n' "$scan_duration" "$KEYSEAL_SCAN_FOLDERS" "$n_candidates" "$n_matches" >&2
+elif [[ $scan_source == none && $scan_judged == yes || $scan_timed_out == yes ]]; then
+  printf 'status: scan: done in %s s (%s folders): %s\n' "$scan_duration" "$KEYSEAL_SCAN_FOLDERS" "${detail[scan]}" >&2
+fi
+scan_meta="\"source\":\"$scan_source\",\"scanned_at\":$scan_scanned_at,\"age_s\":$scan_age,\"duration_s\":$scan_duration,\"inputs\":$(keyseal_cache_inputs_json),\"stale_temp\":$stale_temp,\"cache\":{\"mode\":\"$scan_cache\",\"state\":\"$KEYSEAL_CACHE_STATE\",\"reason\":$(str_or_null "$KEYSEAL_CACHE_REASON"),\"read\":$(keyseal_json_str "$cache_read"),\"last_scanned_at\":$cache_last}"
+# A scan that was not judged still names the scope it would have scanned.
+if [[ -n $scan_core ]]; then scan=$(keyseal_scan_with_headers "${scan_core%\}},$scan_meta}")
+else scan="{\"roots\":$(keyseal_json_list ${KEYSEAL_ROOTS[@]+"${KEYSEAL_ROOTS[@]}"}),\"roots_skipped\":$KEYSEAL_ROOTS_SKIPPED_JSON,$scan_meta}"
 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)
+# A scan that was not judged (no valid cache under `only`, or the deadline) is 2, never 1.
+if [[ $scan_judged == no ]]; then
+  judged=()
+  for c in "${hard[@]}"; do [[ $c == scan ]] || judged+=("$c"); done
+  hard=("${judged[@]}")
+fi
 # 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.
@@ -219,17 +325,12 @@ 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=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-cli",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",
   "main": "./dist/index.js",