Skip to content

docs(caveats): describe shipped caveat wiring, not "next step" - #60

Merged
hartsock merged 1 commit into
mainfrom
issue-41/fix-stale-caveat-doc
Jul 14, 2026
Merged

docs(caveats): describe shipped caveat wiring, not "next step"#60
hartsock merged 1 commit into
mainfrom
issue-41/fix-stale-caveat-doc

Conversation

@hartsock

Copy link
Copy Markdown
Member

What this PR does

  • Fixes stale prose in the agent-mesh-protocol/src/caveats.rs module doc that claimed wiring caveats into AgentMetadata and enforcing child ⊑ parent "is the next step." Both have shipped and are property-tested; the old text made an enforced security property read as aspirational.
  • Rewrites the paragraph to describe the shipped state: the caveats field is part of the signed cert payload, and attenuation is enforced at two independent points — AgentKey::delegate refuses to mint an amplifying child (MeshError::CaveatAmplification), and CertChain::verify re-checks attenuation at every delegated link, so a forged chain is rejected even when each signature is valid.
  • Preserves the genuine forward reference: OS-level enforcement (Landlock, uid-mapped namespaces) is the remaining future work, and the pointer to docs/decisions/agentic_object_capability_security.md in newt-agent is kept.
  • Adds intra-doc links to AgentKey::delegate, CertChain::verify, and MeshError::CaveatAmplification (all crate::-qualified, resolve cleanly).

Test plan

  • Documentation-only change — no code or test changes.
  • just check passes locally: cargo fmt --all -- --check clean, cargo clippy --workspace --all-targets -- -D warnings clean (zero warnings), and the full cargo test --workspace suite is green.
  • The enforcement tests the new doc references remain green and unchanged: forged_amplifying_chain_fails_verify, delegate_rejects_amplification, multi_level_delegation_attenuates_each_link, tampered_caveats_fails_verify (all in agent-mesh-protocol/src/agent_key.rs).
  • Verified my new intra-doc links produce no rustdoc warnings on caveats.rs.

Out of scope

  • OS-level enforcement (Landlock, uid-mapped namespaces) remains genuinely future work and is described as such in the doc.
  • No changes to the confidentiality model or any other module docs; only the caveats.rs module doc was out of date.

Fixes #41

The caveats.rs module doc claimed that wiring caveats into
`AgentMetadata` and enforcing `child ⊑ parent` "is the next step."
That is stale: both the wiring and the enforcement have shipped and
are property-tested. On the crate's most authoritative source of
truth — the module doc of the type that defines the authority
lattice — this drift made an enforced security property read as
aspirational.

Rewrite the paragraph to describe the shipped state:
- caveats are part of the signed cert payload in `AgentMetadata`
- attenuation is enforced at two independent points:
  `AgentKey::delegate` (mint time, refuses amplifying children with
  `MeshError::CaveatAmplification`) and `CertChain::verify` (verify
  time, structural re-check at every delegated link — a forged chain
  is rejected even when each signature is valid)
- the genuine forward reference (OS-level enforcement: Landlock,
  uid-mapped namespaces) and the newt-agent design-doc pointer are
  preserved.

Documentation only — no code or test changes. Intra-doc links to
`AgentKey::delegate`, `CertChain::verify`, and
`MeshError::CaveatAmplification` resolve cleanly.

Fixes #41

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@hartsock hartsock added the risk:low Low-risk change: scoped, tested, no CI/build/hook edits label Jul 13, 2026
@hartsock
hartsock merged commit ae3ecee into main Jul 14, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:low Low-risk change: scoped, tested, no CI/build/hook edits

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(caveats): fix stale module doc claiming caveat wiring is "the next step"

1 participant