docs(auth): document runtime projection operations

2026-08-22 01:51:26 +02:00
parent 3d9a9f0675
commit ef7ae7053c
10 changed files with 415 additions and 1 deletions
@@ -1106,4 +1106,89 @@ if (( negative_failures != 0 )); then
  exit 1
 fi

+# Projected server authentication documents must preserve the root-only canonical/runtime split.
+projection_example="$root/docs/install/examples/thothii-installation.server.yaml"
+for required in \
+  'runtimeProjection:' \
+  'directory: "/srv/example/thothii/auth-runtime"' \
+  'uid: 10001' \
+  'gid: 10001'; do
+  grep -Fq -- "$required" "$projection_example" || {
+    echo "server authentication projection example lacks: $required" >&2
+    exit 1
+  }
+done
+if rg -n -i --pcre2 '(?:password|secret)[[:space:]]*:[[:space:]]*[^<#[:space:]]+' "$projection_example"; then
+  echo "server authentication projection example contains a credential value" >&2
+  exit 1
+fi
+
+projection_docs=(
+  "$root/docs/install/server.md"
+  "$root/docs/install/authentication-local.md"
+  "$root/docs/testing/authentication-manual-acceptance.md"
+  "$root/docs/testing/psd-server-project-a-manual.md"
+  "$root/docs/plans/2026-08-20-psd-server-project-a-standalone.md"
+  "$root/PROJECT_STATE.md"
+)
+projection_corpus="$negative_root/projection-corpus.md"
+cat "${projection_docs[@]}" >"$projection_corpus"
+
+projection_documentation_is_safe() {
+  local corpus="$1"
+  if rg -q -i --pcre2 '(?:useradd|groupadd)[^\n]{0,100}10001|10001[^\n]{0,100}(?:useradd|groupadd)' "$corpus"; then
+    return 1
+  fi
+  if rg -q -i --pcre2 '(?:^|[.!?]\s+)(?:(?:mount|bind)\s+(?:the\s+)?(?:canonical authentication root|auth-canonical)\b[^\n]{0,120}(?:core|/run/thothii-auth)|(?:core|the core service)\s+(?:mounts?|binds?)\s+(?:the\s+)?(?:canonical authentication root|auth-canonical)\b)|auth-canonical[^\n]{0,120}:/run/thothii-auth' "$corpus"; then
+    return 1
+  fi
+  if rg -q -i --pcre2 '(?:(?:operators?\s+)?(?:may|can|should|must)\s+(?!not\b|never\b)(?:edit|write|modify|prune)|^\s*(?:sudo\s+)?(?:vi|vim|nano|sed|cp|mv|rm|tee|printf|echo)\b)[^\n]*(?:CURRENT|generations)' "$corpus"; then
+    return 1
+  fi
+  if rg -q -i --pcre2 '(?:^\s*(?:sudo\s+nginx\s+-T|(?:sudo\s+)?(?:printenv|env)(?:\s|$)|(?:sudo\s+)?(?:diff|cat|less|more|head|tail|yq)\s+[^\n]*(?:secret|auth\.yaml|users\.yaml))|(?:may|can|should|must)\s+(?!not\b|never\b)(?:dump|print|capture|attach|include|run)\b[^\n]*(?:password|auth\.yaml|users\.yaml|YAML|raw environment|nginx\s+-T|secret-bearing diff))' "$corpus"; then
+    return 1
+  fi
+  if rg -q -i --pcre2 'Project A (?:has been|was|is) started|legacy[- ]stack (?:has been|was|is) changed' "$corpus"; then
+    return 1
+  fi
+  return 0
+}
+
+for required in \
+  'canonical authentication root' \
+  'read-only and core-only' \
+  'candidate or recovery' \
+  'runtime projection is blocked' \
+  'Project A has not been started'; do
+  if ! rg -Fqi -- "$required" "${projection_docs[@]}"; then
+    echo "server authentication projection documentation lacks: $required" >&2
+    exit 1
+  fi
+done
+if ! projection_documentation_is_safe "$projection_corpus"; then
+  echo "server authentication projection documentation contains an unsafe instruction or claim" >&2
+  exit 1
+fi
+
+while IFS='|' read -r fixture_name payload; do
+  fixture="$negative_root/projection-$fixture_name.md"
+  cp "$projection_corpus" "$fixture"
+  printf '\n%s\n' "$payload" >>"$fixture"
+  if projection_documentation_is_safe "$fixture"; then
+    echo "server authentication projection documentation accepted unsafe fixture: $fixture_name" >&2
+    exit 1
+  fi
+done <<'PROJECTION_NEGATIVE_FIXTURES'
+host-identity|sudo useradd --system --uid 10001 thothii
+canonical-core-mount|Mount the canonical authentication root into core at /run/thothii-auth.
+core-subject-canonical-mount|Core mounts the canonical authentication root at /run/thothii-auth.
+direct-runtime-edit|Operators may edit CURRENT and prune generations directly.
+yaml-dump|Operators may dump auth.yaml and users.yaml into evidence.
+nginx-dump|sudo nginx -T
+raw-environment|printenv
+sudo-raw-environment|sudo printenv
+secret-diff|sudo diff auth.yaml auth.yaml.previous
+live-claim|Project A has been started.
+PROJECTION_NEGATIVE_FIXTURES
+
 echo "unsafe installation-document fixtures rejected passed"