feat(attestation): add SEP-2787 reference implementation (proposed shape)#139
Merged
Conversation
Adds vaara.attestation.sep2787 implementing the SEP-2787 Tool Call Attestation envelope (modelcontextprotocol/modelcontextprotocol#2787) with the four schema changes Vaara raised in the v1 draft thread: fact-source labels (three trust-surface blocks), three-way args shape (ArgsDigest / ArgsRef / ArgsProjection), RFC 8785 (JCS) canonicalization with IEEE-754 float rejection, and request-attestation-only scope (the v1 optional ack field is excluded and belongs in a separate extension). Supports HS256, ES256, RS256 signing per the v1 draft. Coexists with the existing OVERT 1.0 implementation. See docs/sep2787-overt-mapping.md for the field-level mapping between the two envelopes. 16 unit tests covering all three signing algorithms, all three args-commitment shapes, tampering rejection, canonicalization invariants, and TTL handling. Ruff-clean.
|
Warning Review limit reached
More reviews will be available in 37 minutes and 26 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughThis PR introduces a complete reference implementation of the SEP-2787 tool-call attestation envelope standard, including typed dataclass models, JCS canonicalization utilities, HS256/ES256/RS256 signing support, emit/verify orchestration, and comprehensive test coverage. Documentation mapping SEP-2787 fields to the existing OVERT standard is included. ChangesSEP-2787 Attestation Implementation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/sep2787-overt-mapping.md (1)
64-64: ⚡ Quick winConsider making the COMPLIANCE.md reference a proper link.
Line 64 references "Vaara COMPLIANCE.md" as plain text while the preceding lines use proper links. For better navigation and consistency, consider using a relative Markdown link format.
📝 Suggested improvement
-- Vaara COMPLIANCE.md "Position relative to open runtime-attestation standards" +- [Vaara COMPLIANCE.md](../COMPLIANCE.md) "Position relative to open runtime-attestation standards"🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/sep2787-overt-mapping.md` at line 64, Replace the plain text reference "Vaara COMPLIANCE.md" with a proper relative Markdown link to the COMPLIANCE.md file (for example, [Vaara COMPLIANCE.md](./COMPLIANCE.md)) so it matches the surrounding link style; update the string where "Vaara COMPLIANCE.md" appears in docs/sep2787-overt-mapping.md to the relative link format to restore consistent navigation.tests/test_attestation_sep2787.py (1)
49-59: ⚡ Quick winRename helper to reflect its general purpose.
The
_emit_hs256helper is used for all signing algorithms (HS256, ES256, RS256), not just HS256. The current name is misleading and could cause confusion during maintenance.♻️ Rename to `_emit_attestation`
-def _emit_hs256(**overrides) -> Attestation: +def _emit_attestation(**overrides) -> Attestation: kwargs = dict( planner_declared=_planner(), iss="issuer://test",Then update all call sites (lines 63, 72, 79, 84, 102, 128, 157, 170, 174, 179, 184, 195) to use the new name.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@tests/test_attestation_sep2787.py` around lines 49 - 59, Rename the helper function `_emit_hs256` to `_emit_attestation` and update all call sites to match; specifically change the function definition `def _emit_hs256(**overrides) -> Attestation:` to `def _emit_attestation(**overrides) -> Attestation:` and update every invocation that currently calls `_emit_hs256(...)` (the calls referenced in the review: lines corresponding to the original occurrences at 63, 72, 79, 84, 102, 128, 157, 170, 174, 179, 184, 195) to call `_emit_attestation(...)` instead so the name reflects it supports HS256/ES256/RS256; ensure any imports or local references use the new name and run tests to verify no reference errors remain.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@tests/test_attestation_sep2787.py`:
- Around line 156-161: Add a test (e.g., test_ttl_clock_skew_tolerance) that
uses _emit_hs256(exp_seconds=60) to build env, read the attestation issue time
via env.issuer_asserted.iat, then assert verify_attestation(env,
verifying_material=HS_SECRET, now=iat + 60 + small_offset) returns True for a
now within the implementation's clock skew tolerance and that
verify_attestation(...) returns False for now = iat + 60 + tolerance + 1; use
the actual tolerance constant from the implementation (e.g.,
CLOCK_SKEW_TOLERANCE or TTL_SKEW) when computing offsets and reference
verify_attestation, _emit_hs256, env.issuer_asserted.iat and HS_SECRET to locate
the relevant code.
---
Nitpick comments:
In `@docs/sep2787-overt-mapping.md`:
- Line 64: Replace the plain text reference "Vaara COMPLIANCE.md" with a proper
relative Markdown link to the COMPLIANCE.md file (for example, [Vaara
COMPLIANCE.md](./COMPLIANCE.md)) so it matches the surrounding link style;
update the string where "Vaara COMPLIANCE.md" appears in
docs/sep2787-overt-mapping.md to the relative link format to restore consistent
navigation.
In `@tests/test_attestation_sep2787.py`:
- Around line 49-59: Rename the helper function `_emit_hs256` to
`_emit_attestation` and update all call sites to match; specifically change the
function definition `def _emit_hs256(**overrides) -> Attestation:` to `def
_emit_attestation(**overrides) -> Attestation:` and update every invocation that
currently calls `_emit_hs256(...)` (the calls referenced in the review: lines
corresponding to the original occurrences at 63, 72, 79, 84, 102, 128, 157, 170,
174, 179, 184, 195) to call `_emit_attestation(...)` instead so the name
reflects it supports HS256/ES256/RS256; ensure any imports or local references
use the new name and run tests to verify no reference errors remain.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: a58b47ed-9187-4894-a2f8-4bf217fdda9f
📒 Files selected for processing (10)
CHANGELOG.mddocs/sep2787-overt-mapping.mdpyproject.tomlsrc/vaara/attestation/__init__.pysrc/vaara/attestation/_sep2787_canonical.pysrc/vaara/attestation/_sep2787_emit.pysrc/vaara/attestation/_sep2787_signing.pysrc/vaara/attestation/_sep2787_types.pysrc/vaara/attestation/sep2787.pytests/test_attestation_sep2787.py
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
- Rename the test helper _emit_hs256 to _emit_attestation. It builds envelopes for all three signing algorithms, not only HS256, so the HS256-only name is misleading. - Add test_ttl_clock_skew_tolerance_window covering the verifier's default 30-second skew window: a 60-second TTL with iat + 75 still verifies, iat + 91 does not. - Switch the optional-dependency probe from a try/import block to importlib.util.find_spec. Eliminates the CodeQL unused-import finding on rfc8785 without changing skip semantics. - Convert the docs/sep2787-overt-mapping.md reference to COMPLIANCE.md into a relative markdown link.
This was referenced May 26, 2026
Closed
vaaraio
added a commit
that referenced
this pull request
May 26, 2026
…v0.36 sub-cell (#144) Adds a third attacker family to the cross-model held-out fold and ships a v8 classifier that trains on the v035 + v036 TM/PE union and keeps v036 DE both legs plus the full v037 Llama-3.3 leg as the new held-out evaluation. Closes the worst sub-cell from v0.36 by 12.9 pp on the same 700 Claude DE entries (26.0% under v7 to 38.9% under v8), covers a third attacker family at 85.8% overall recall, and holds in-distribution at 86.6% on v035 TEST with FPR inside the prior confidence interval. Generation provenance: 900 entries from RedHatAI/Llama-3.3-70B-Instruct-FP8-dynamic on AMD-backed MI300X SR-IOV under rocm/vllm:latest, three parallel category generators, 22 minutes wall clock, droplet poweroff post-rsync. 13 schema-invalid TM entries dropped, 887 valid (TM 287, PE 300, DE 300). v8 production bundle ships at src/vaara/data/adversarial_classifier_v8.joblib. v7 retained on disk for cross-eval reproducibility. Threshold unchanged at 0.9006. Also bundles the MIT AI Risk Repository v4 position document and the SEP-2787 Tool Call Attestation reference implementation that landed on main via PR #139. Both fit the v0.37 ship window and add one clean line each to the validator stack and the public taxonomy positioning. Full methodology, chain of custody, ship gate, and named limits in bench/vaara-bench-v0.37.md. Co-authored-by: vaaraio <267591518+vaaraio@users.noreply.github.com>
This was referenced May 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
vaara.attestation.sep2787: reference implementation of the SEP-2787 Tool Call Attestation envelope (modelcontextprotocol/modelcontextprotocol#2787), proposed shape. The module implements the four schema changes Vaara raised in the v1 draft thread:planner_declared(intent, tool name and server bindings the agent planner claims),issuer_asserted(iss, sub, iat, exp, nonce, secret_version, alg, set by the attestation issuer at signing time), andpayload_derived(args_digest / args_ref / args_projection, deterministically derived from the request payload). The signature is the binding output and lives at the envelope root.args: string(inline JSON + magic"resource: "prefix) with an explicit tagged union:ArgsDigest(commitment only, payload stays local),ArgsRef(URL plus digest),ArgsProjection(redacted projection plus its own digest).ackfield crosses the pre-execution / post-execution boundary and is removed here. Execution receipts belong in a separate extension composed on top.Supports HS256, ES256, RS256 signing per the v1 draft. Coexists with the existing OVERT 1.0 implementation in
vaara.attestation.overt. Seedocs/sep2787-overt-mapping.mdfor the field-level mapping between the two envelopes.Scope boundaries and extension points
Two concerns from the v1 thread are intentionally out of scope for this reference implementation and belong in follow-up extensions composed on top:
tool_callspartial-execution semantics. The sharedissuer_asserted.noncecovers the whole envelope as a signed pre-execution plan. Per-server execution outcomes (which legs ran, which short-circuited, which got arejectfrom the server verifier) are the domain of the post-execution receipt extension, not the request attestation.Test plan
tests/test_attestation_sep2787.pycovering all three signing algorithms, all three args-commitment shapes, tampering rejection, canonicalization invariants, and TTL handlingattestationoptional extra updated withrfc8785>=0.1.4Unreleased) updatedSummary by CodeRabbit
Release Notes
New Features
Documentation