fix: [nomad-step-2] S2.3 — vault-nomad-auth.sh (enable JWT auth + roles + nomad workload identity) (#881)

Wires Nomad → Vault via workload identity so jobs can exchange their
short-lived JWT for a Vault token carrying the policies in
vault/policies/ — no shared VAULT_TOKEN in job env.

- `lib/init/nomad/vault-nomad-auth.sh` — idempotent script: enable jwt
  auth at path `jwt-nomad`, config JWKS/algs, apply roles, install
  server.hcl + SIGHUP nomad on change.
- `tools/vault-apply-roles.sh` — companion sync script (S2.1 sibling);
  reads vault/roles.yaml and upserts each Vault role under
  auth/jwt-nomad/role/<name> with created/updated/unchanged semantics.
- `vault/roles.yaml` — declarative role→policy→bound_claims map; one
  entry per vault/policies/*.hcl. Keeps S2.1 policies and S2.3 role
  bindings visible side-by-side at review time.
- `nomad/server.hcl` — adds vault stanza (enabled, address,
  default_identity.aud=["vault.io"], ttl=1h).
- `lib/hvault.sh` — new `hvault_get_or_empty` helper shared between
  vault-apply-policies.sh, vault-apply-roles.sh, and vault-nomad-auth.sh;
  reads a Vault endpoint and distinguishes 200 / 404 / other.
- `vault/policies/AGENTS.md` — extends S2.1 docs with JWT-auth role
  naming convention, token shape, and the "add new service" flow.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

lib/hvault.sh

@@ -178,6 +178,51 @@ hvault_kv_list() {
   }
 }
 
+# hvault_get_or_empty PATH
+#   GET /v1/PATH. On 200, prints the raw response body to stdout (caller
+#   parses with jq). On 404, prints nothing and returns 0 — caller treats
+#   the empty string as "resource absent, needs create". Any other HTTP
+#   status is a hard error: response body is logged to stderr as a
+#   structured JSON error and the function returns 1.
+#
+#   Used by the sync scripts (tools/vault-apply-*.sh +
+#   lib/init/nomad/vault-nomad-auth.sh) to read existing policies, roles,
+#   auth-method listings, and per-role configs without triggering errexit
+#   on the expected absent-resource case. `_hvault_request` is not a
+#   substitute — it treats 404 as a hard error, which is correct for
+#   writes but wrong for "does this already exist?" checks.
+#
+#   Subshell + EXIT trap: the RETURN trap does NOT fire on set-e abort,
+#   so tmpfile cleanup from a function-scoped RETURN trap would leak on
+#   jq/curl errors under `set -eo pipefail`. The subshell + EXIT trap
+#   is the reliable cleanup boundary.
+hvault_get_or_empty() {
+  local path="${1:-}"
+
+  if [ -z "$path" ]; then
+    _hvault_err "hvault_get_or_empty" "PATH is required" \
+      "usage: hvault_get_or_empty PATH"
+    return 1
+  fi
+  _hvault_check_prereqs "hvault_get_or_empty" || return 1
+
+  (
+    local tmp http_code
+    tmp="$(mktemp)"
+    trap 'rm -f "$tmp"' EXIT
+    http_code="$(curl -sS -o "$tmp" -w '%{http_code}' \
+      -H "X-Vault-Token: ${VAULT_TOKEN}" \
+      "${VAULT_ADDR}/v1/${path}")" \
+      || { _hvault_err "hvault_get_or_empty" "curl failed" "path=$path"; exit 1; }
+    case "$http_code" in
+      2[0-9][0-9]) cat "$tmp" ;;
+      404)         printf '' ;;
+      *)           _hvault_err "hvault_get_or_empty" "HTTP $http_code" "$(cat "$tmp")"
+                   exit 1 ;;
+    esac
+  )
+}
+
 # hvault_policy_apply NAME FILE
 #   Idempotent policy upsert — create or update a Vault policy.
 hvault_policy_apply() {