Hugging Face sign-in as a value-free native credential: status rows, guard, deny rules, per-host token policy - #268

Scope

• What this PR changes: makes the Hugging Face sign-in a value-free native credential on every host, so the GPU workstation can host and qualify models (including gated ones) with our Hugging Face keys without any agent seeing the token.
• Base commit: 3ff52117 (current origin/main).
• Lane: lane:foundation
• Owned paths touched:
  • adoption/credential-inventory.json: two native rows, huggingface-native (token) and huggingface-native-stored (stored_tokens), under ${HF_HOME:-${XDG_CACHE_HOME:-$HOME/.cache}/huggingface}
  • scripts/credential_status.py: the template prefix, HUGGING_FACE_HUB_TOKEN in must_not_be_set (HF_TOKEN was already there), and HF_TOKEN_PATH reported by name
  • scripts/hooks/secret_path_guard.py: both store paths, the legacy name, a block on hf auth token, and $HF_TOKEN_PATH as a pointer
  • Read deny rules in .claude/settings.json and the Claude settings template
  • .gitignore and SENSITIVE_BASENAME: stored_tokens
  • docs/secret-storage.md: a Hugging Face section
  • docs/decisions/2026-09-24-secret-storage.md: an addendum pinning the huggingface_hub v2.0.0 tag commit 97c5f5f2
  • tests

The policy it documents:

• Each host signs in natively with hf auth login in the user's own terminal. The token is fine-grained, with read access to gated repos only, one per host so each can be revoked alone. It goes in at the hidden prompt, never with --token and never with --add-to-git-credential. Check it with hf auth whoami and python3 scripts/credential_status.py.
• Agents may run hf download <repo> --revision <40-hex> --local-dir … and hf cache verify. hf reads the store itself, so the value never enters agent context. hf auth token is blocked.
• New model-serving units serve from pinned local directories with HF_HUB_OFFLINE=1.
• Workers that need no Hub access set HF_HUB_DISABLE_IMPLICIT_TOKEN=1. That behaviour was verified against the installed huggingface_hub 1.32.0 get_token_to_send.

Evidence-class table

Local commands run

$ uv run … -m unittest <17 modules that pin the guard, inventory, settings, template or gitignore>
Ran 917 tests … FAILED (failures=1, skipped=4)
  # the one failure is test_host_profile_copy_is_verbatim: the installed user-scope guard on this host predates this
  # branch. CI skips it (IN_CI). After merge, `tools/adoption/install_claude_profile.py --only guard` refreshes it.
$ uv run … scripts/validate.py                 # passed (5511 hashed files)
$ uv run … scripts/build_ecosystem.py --check  # passed
$ python3 scripts/credential_status.py         # huggingface-native / -stored: missing; result ok

adoption/hooks/claude/SHA256SUMS is refreshed for the new guard bytes.

Decision record

An addendum to docs/decisions/2026-09-24-secret-storage.md covers the Hugging Face row, the environment policy and the rejected alternatives: a per-provider 0600 env file, --token, a git credential, and exporting HF_TOKEN.

Review

An independent Opus reviewer returned ready with 5 low findings. A Sonnet repair round fixed all 5: the implicit-token wording, the guard pass-throughs recorded as known gaps, the $HF_TOKEN_PATH wording, stored_tokens in .gitignore and SENSITIVE_BASENAME, and the v2.0.0 SHA. A Sonnet re-check returned ready with no new defects. Codex cross-family review is unavailable until 2026-09-30.

Host evidence

None. No sign-in was performed; the user signs in natively. After merge: refresh the host guard with install_claude_profile.py --only guard, the user runs hf auth login in their own terminal, then hf auth whoami and credential_status.py should report ok.

Checklist

• No workflow changes. [x] No secrets printed, logged or committed; no token file was opened. [x] No paid surface. [x] Peer files preserved.

🤖 Generated with Claude Code