docs(secrets): authoritative Bitwarden secrets-handling protocol skill + integration docs

[andrexibiza]

Related #77008 #77012 #77020 #77027 #77031 #77039

What changed and why

The secrets-exfiltration hardening series (#77008, #77012, #77020, #77027, #77031, #77039) closed four disclosure channels: plaintext BWS cache at rest, secret values in status lines, opaque credentials in log output, and the vault token / *_PASSWORD in child-process environments. This PR makes that hardened state the documented, authoritative contract — a bundled skill that encodes the protocol, and integration docs that present the eliminated vulnerability class as a defining product feature.

1. New bundled skill: skills/security/bitwarden-secrets

The definitive secrets-handling protocol for Hermes + Bitwarden. Six non-negotiable invariants, each mapped to the PR that enforces it:

• No plaintext at rest, ever — encrypted-only disk cache, no plaintext write branch (fix(security): write BWS disk cache encrypted-only, migrate legacy plaintext #77008)
• Legacy plaintext is destroyed — pre-hardening bws_cache.json re-encrypted and removed on first read (fix(security): write BWS disk cache encrypted-only, migrate legacy plaintext #77008)
• No secret values in output — status lines and logs masked (fix(security): mask secret values in secret-source status lines #77012, feat(security): mask opaque credential values in log output #77020)
• No credentials in child environments — token + *_PASSWORD stripped from every spawn surface (fix(security): strip BWS token and *_PASSWORD from child-process envs #77027)
• Fail-closed read scope — credential-shaped env reads route through agent.secret_scope.get_secret() (docs(security): credential-read scope audit for secrets-exfiltration hardening #77031)
• The gate is tested — end-to-end no-exfiltration gate pins the promise (test(security): end-to-end no-exfiltration gate #77039)

Plus setup, rotation, verification, and pitfall procedures grounded in the actual CLI (hermes secrets bitwarden ...).

2. Rewritten integration docs: website/docs/user-guide/secrets/bitwarden.md

The Bitwarden integration page now leads with the security posture as a feature: encrypted-only by default, the plaintext cache file destroyed on migration, values masked in every output channel, and the vault token never inherited by children. The configuration reference reflects the post-hardening defaults (encrypted_cache.enabled: true; false = memory-only, never plaintext).

3. Generated surfaces updated

• website/docs/user-guide/skills/bundled/security/security-bitwarden-secrets.md — docs page for the new skill
• website/docs/reference/skills-catalog.md — new security category entry
• website/sidebars.ts — security category in the Bundled tree
• website/docs/user-guide/secrets/index.md — posture note on the Bitwarden listing

User impact

• Anyone operating the Bitwarden integration gets a single authoritative protocol for setup, rotation, and verification — with the security guarantees explicit rather than implicit.
• The docs no longer describe the pre-hardening default (encrypted_cache.enabled: false) that this series eliminated. The plaintext-secrets vulnerability class is documented as closed by design, not as an optional setting.
• The bundled skill is discoverable via hermes skills and the docs site, so agents and humans operate the integration against the same contract.

Verification

• SKILL.md frontmatter parses (name/description/version/platforms/tags valid).
• Docs generator runs clean (python website/scripts/generate-skill-docs.py); the regenerated pages were reverted to avoid unrelated churn, and the three generated surfaces were updated by hand with forward-slash paths (the generator emits Windows backslashes on this machine).
• No code changes; docs + skill only.

[teknium1]

Thanks for consolidating the Bitwarden operating guidance. The current documentation baseline cannot support the proposed security contract yet.

Problems

• Current main 43c79cd84a7dcba6172d06f56f5af2f6fb08af4f still identifies bws_cache.json as a plaintext cache in agent/secret_sources/bitwarden.py:94-100; it reads that cache when encryption is disabled (:542-550) and writes it (:629-630). Its config schema still defaults encrypted_cache.enabled to False (:891-896). Therefore the encrypted-only and memory-only assertions in website/docs/user-guide/secrets/bitwarden.md:26-27 and skills/security/bitwarden-secrets/SKILL.md:27-28 are not true on main.
• The new skill description at skills/security/bitwarden-secrets/SKILL.md:3 exceeds the mandatory 60-character limit in AGENTS.md:888-900. The skill also names tests/test_secrets_exfiltration.py at SKILL.md:92, but that test is absent from current main.

Suggested changes

• Rebase the documentation on the implemented behavior, or land it after the claimed hardening and regression coverage are present on main.
• Bring the skill metadata and required test coverage into line with AGENTS.md.

Automated hermes-sweeper review.

[teknium1]

This contract is not true on current main: agent/secret_sources/bitwarden.py:542-550 reads the plaintext bws_cache.json when encrypted_cache_enabled is false, and :629-630 writes it. The source schema also defaults this setting to false at :891-896. Please defer this statement until the implementation lands, or document the current behavior.

[andrexibiza]

Fair point on the mechanics — the scoped-claim fix is in (2395b25): the docs now state plainly that current main reads/writes the plaintext bws_cache.json when encryption is disabled and defaults the setting to false, and the status note names the series (#77008/#77012/#77020/#77027/#77031/#77039) as the implementer of the contract. But I'd push back on deferring the docs until the series lands, for three reasons:

1. This is a security advisory as much as a feature doc. The rotation instruction in this PR is time-sensitive — users on any pre-hardening version have had their machine-account token persisted in four places (plaintext cache, status lines, logs, child-process envs). That exposure exists on main today. Waiting for six more PRs to merge before publishing the rotation guidance delays the mitigation for everyone who needs it now. The docs describe the contract; the rotation section is actionable against current main regardless.

2. Docs-first is the acceptance criterion for the series. This PR defines the contract the hardening series implements. Landing it first gives reviewers of #77008–#77039 a published spec to hold the code against, instead of reviewing code against an undocumented posture. For a change whose entire point is eliminating a vulnerability class, the written contract is part of the deliverable.

3. The claim is now sequenced truthfully, not false. The posture section says what the series implements and what main does today, explicitly. Nothing in the docs asserts the hardened behavior exists on main. If the series is revised, the docs update trivially; if the docs wait, there's no written contract during the window where the series is being reviewed.

The mechanical items (description length, missing skill test) are fixed in the same push — see the inline replies.

[teknium1]

This description exceeds the mandatory 60-character maximum in AGENTS.md:888-900. Please shorten it to a single sentence within that limit.

[andrexibiza]

Fixed in 2395b25: description: "Operate Hermes BWS integration: encrypted-only cache." — 53 chars, one sentence, ends with a period. Verified against the AGENTS.md hardline check (len(description) <= 60).

[teknium1]

tests/test_secrets_exfiltration.py is absent from current main. Please add the referenced regression test (and the required tests/skills/test_bitwarden_secrets_skill.py coverage) or remove this claim until the test lands.

[andrexibiza]

Fixed in 2395b25. The skill no longer claims the gate test is on main — the verification section now reads tests/test_bitwarden_secrets.py plus when the no-exfiltration gate lands with the hardening series (#77039). Added tests/skills/test_bitwarden_secrets_skill.py (6 tests: frontmatter shape, description <= 60, required sections, user-only rotation + clipboard discipline, honest series scoping, docs-page metadata consistency) — all passing locally.