docs(auth): address authentication guide review

2026-08-18 03:33:00 +02:00
parent f4f38717e1
commit 91925d64bf
12 changed files with 406 additions and 142 deletions
@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)
+tmp=$(mktemp -d "${TMPDIR:-/tmp}/thoth-auth-docs.XXXXXX")
+trap 'rm -rf "$tmp"' EXIT
+
+files=(
+  docs/architecture/authentication.md
+  docs/install/authentication-local.md
+  docs/install/authentication-oidc.md
+  docs/install/authentik.md
+  docs/testing/authentication-manual-acceptance.md
+  docs/architecture/overview.md
+  docs/install/local.md
+  docs/install/server.md
+  docs/install/psd-workspace-setup.md
+  docs/install/reverse-proxy-caddy.md
+  docs/install/reverse-proxy-nginx.md
+  docs/guida-utente.md
+  docs/index.md
+  README.md
+  PROJECT_STATE.md
+  mkdocs.yml
+)
+
+make_fixture() {
+  local name=${1:?fixture name required}
+  local fixture="$tmp/$name"
+  mkdir -p "$fixture"
+  for relative in "${files[@]}"; do
+    mkdir -p "$fixture/$(dirname "$relative")"
+    cp "$root/$relative" "$fixture/$relative"
+  done
+  printf '%s\n' "$fixture"
+}
+
+expect_rejected() {
+  local name=${1:?fixture name required}
+  local fixture_text=${2:?fixture text required}
+  local expected=${3:?expected error required}
+  local fixture output
+  fixture=$(make_fixture "$name")
+  printf '%s\n' "$fixture_text" >>"$fixture/README.md"
+  output="$tmp/$name.output"
+  if "$root/scripts/auth-docs-smoke.sh" --root "$fixture" >"$output" 2>&1; then
+    echo "auth docs fixture unexpectedly passed: $name" >&2
+    exit 1
+  fi
+  rg -Fq "$expected" "$output" || {
+    echo "auth docs fixture failed for the wrong reason: $name" >&2
+    sed -n '1,20p' "$output" >&2
+    exit 1
+  }
+  echo "auth docs negative fixture rejected: $name"
+}
+
+positive=$(make_fixture positive)
+printf '%s\n' \
+  'Use --password-file <file>; never pass a password value.' \
+  'Additional unmapped groups are silently ignored without warnings, alerts, or advisories.' \
+  >>"$positive/README.md"
+"$root/scripts/auth-docs-smoke.sh" --root "$positive" >/dev/null
+echo "auth docs positive fixture passed"
+
+expect_rejected thothctl-intervening \
+  'Run thothctl --installation <descriptor> --json auth check.' \
+  'forbidden authentication CLI wording'
+expect_rejected alternate-admin \
+  'Run thothii-admin users list.' \
+  'forbidden authentication CLI wording'
+expect_rejected password-option \
+  'Run tht auth user add demo --password example-value.' \
+  'plaintext password option'
+expect_rejected yaml-password \
+  'password: example-value' \
+  'plaintext password field'
+expect_rejected json-password \
+  '{"password": "example-value"}' \
+  'plaintext password field'
+expect_rejected unmapped-warning \
+  'Unmapped OIDC groups generate warnings.' \
+  'misleading noise claim for unmapped groups'
+expect_rejected unmapped-alert \
+  'Unmapped provider groups trigger operator alerts.' \
+  'misleading noise claim for unmapped groups'
+expect_rejected unmapped-advisory \
+  'An advisory is emitted for every unmapped group.' \
+  'misleading noise claim for unmapped groups'
+expect_rejected compose-plus \
+  'docker compose --env-file deploy/env/local.env + -f compose.yaml -f deploy/compose.local.yaml up --build -d' \
+  'noncanonical local Compose command'
+
+echo "auth docs smoke fixture suite passed"