Document the federation trust model and signing assumptions explicitly

[dgenio]

Summary

Add an explicit trust-model section to docs/federation.md: what HMAC-signed
manifests do and do not guarantee, the pairwise-shared-secret requirement, secret
distribution/rotation guidance, and the threat boundaries (what a compromised peer
can and cannot do).

Why this matters

Federated capability discovery (federation_discovery.py) verifies manifests with
shared-secret HMAC — meaning any party holding the secret can mint manifests, there
is no non-repudiation, and per-peer secrets are required for isolation. These are
legitimate design choices for a 0.x in-process kernel, but adopters wiring
federation across organizational boundaries must understand them before relying
on them. Honest boundary documentation is a security feature in itself and the
prerequisite for the public-key investigation (ISSUE 61).

Current evidence

• federation_discovery.py:1-56: sign_manifest/verify_manifest use hmac with a caller-supplied shared secret; the envelope embeds a wire-level identifier.
• docs/federation.md exists but does not spell out trust assumptions, secret-handling guidance, or non-goals (verified absence of a threat-model section).
• Open issue docs: add capability-token threat model and misuse cases #122 (capability-token threat model) covers tokens; federation manifests are a distinct trust surface not covered there.

External context

Shared-secret MAC vs public-key signature tradeoffs (no non-repudiation, pairwise
key growth) are standard security-documentation material.

Proposed implementation

1. Extend docs/federation.md: trust assumptions (per-peer secrets, both sides can
   sign), guarantees (integrity, authenticity within the secret-sharing set),
   non-guarantees (non-repudiation, revocation of a leaked secret without
   redistribution), operational guidance (per-peer secrets, rotation steps),
   explicit non-goals.
2. Frame defensively: "Strengthen clarity around…" — no attack walkthroughs.
3. Cross-link ISSUE 61 (public-key investigation) and docs: add capability-token threat model and misuse cases #122.

AI-agent execution notes

• Inspect first: federation_discovery.py (whole module), federation.py, kernel/_federation.py, docs/federation.md, tests/test_federation_discovery.py.
• Verify each documented claim against code (e.g., what exactly is covered by the HMAC — payload bytes? canonicalization?) — the docs must match implementation precisely.
• No code changes in this issue; if doc-writing reveals a code gap, file separately.

Acceptance criteria

• docs/federation.md has a trust-model section covering assumptions, guarantees, non-guarantees, and secret-handling guidance.
• Every claim is traceable to specific code behavior.
• Cross-links to docs: add capability-token threat model and misuse cases #122 and the token threat-model docs exist.

Test plan

Documentation review against source; make ci (docs don't break builds, but
examples referenced must run).

Documentation plan

The deliverable is documentation; CHANGELOG Added (docs).

Migration and compatibility notes

Not expected to require migration.

Risks and tradeoffs

Documenting limits may give some adopters pause — that is the correct outcome for
out-of-scope uses, and it builds the trust that drives long-term adoption.

Suggested labels

documentation, security, ecosystem

[dgenio]

Good first contribution — where to start: this should be a source-verified documentation change, not a crypto redesign. Read src/weaver_kernel/federation_discovery.py end-to-end, then docs/federation.md and the Security Contract. Add one concise trust-model section covering exactly what the current shared-secret HMAC guarantees/doesn't guarantee, plus per-peer-secret/rotation guidance. Cite code behavior rather than general security claims; if you discover an implementation gap, file it separately instead of changing runtime code in the same PR.