docs(security): formalize required_for + fallback-authenticator composition

[bokelley]

Summary

Formalizes how required_for (9421 signing requirement) composes with bearer/API-key/mTLS fallback authenticators. Clarifies the normative rule that the training-agent migration (#2582) hit head-on:

• Unauthenticated caller on required_for op → reject (unchanged).
• Unsigned but bearer/API-key/mTLS-authed caller → accept. The fallback is what the verifier advertised as sufficient; required_for doesn't retroactively invalidate the verifier's own authenticator config.
• Malformed signature → still blocks fallback (downgrade defense, unchanged).
• Sellers that want unconditional signing MUST disable their fallback authenticators for that operation — required_for is one lever in the auth chain, not an override.

What changed

• docs/building/implementation/security.mdx:
  • Verifier-checklist preamble: clarifies the rejection branch requires both "no signature" AND "no other valid credential."
  • New subsection "Composition with fallback authenticators" with the full normative rule and a "why this composition, not strict" explanation.
  • required_for capability definition: cross-reference and inline clarification.

No wire / schema changes. Pure spec clarification.

Test plan

• npm run test:unit passes
• npm run typecheck passes
• Mintlify renders the new subsection and anchor resolves correctly
• Anchor #composition-with-fallback-authenticators works from the two cross-reference sites

Closes #2586.

🤖 Generated with Claude Code

[github-actions]

Schema Link Check Results

Commit: 85f1324 - docs(security): promote signing-enforcement postures to admonition block

⚠️ Warnings (schema not yet released)

These schemas exist in source but haven't been released yet. The links will be broken until the next version is published:

• https://adcontextprotocol.org/schemas/v3/enums/specialism.json
  • Schema exists in latest (source) but not yet released in v3
  • Action: This link will work after next 3.x release is published

---

To fix: Either:

1. Wait for the next release and merge this PR after the release is published
2. Use latest instead of a version alias if you need the link to work immediately (note: latest is the development version and may change)
3. Coordinate with maintainers to cut a new release before merging

[bokelley]

Reviewed against upstream issue #2586 and against adcp-client PR #669's requireSignatureWhenPresent({ requiredFor }) semantics. The docs text matches the SDK encoding — specifically the unsigned-bearer-authed-passes / unsigned-unauthenticated-rejects-with-request_signature_required / malformed-sig-blocks-fallback rules. No spec↔SDK drift. Ship it.

One phrasing nit worth a follow-up commit:

Promote the "signing-unconditional" callout. The paragraph currently covers three composition modes in flowing prose. The operative rule for sellers who want enforcement — "configure the fallback authenticator to reject all other credentials" — is the one most likely to be skimmed past on a first read, and it's the rule whose violation turns the whole required_for declaration into security theater. A bold admonition block or a three-bullet list ("to enforce signing unconditionally, do X; to prefer signing but accept bearer, do Y; to treat signing as advisory, do Z") would prevent the "I declared required_for but bearer-authed callers pass — is that correct?" bug report.

Not blocking — the information is all present and accurate. Just reorder for skimmability.

Migration note for our training agent

Our buildAuthenticator already matches the spec (unsigned-bearer-authed passes, credentials-absent throws request_signature_required). No behavior change needed on adoption of adcp-client 5.7. We just replace the hand-composed fallback-with-required_for-check with requireSignatureWhenPresent({ requiredFor, resolveOperation }) once adcp-client PR #669's Blocker 2 is fixed (the pre-check not firing on fallback-throws path).