Document that BilateralReceipt.extensions is unsigned and untrusted

[willamhou]

Context

BilateralReceipt.extensions (crates/signet-core/src/receipt.rs:71) is explicitly excluded from the signature scope. The code has a comment // unsigned, outside sig scope, but this is not documented in docs/SECURITY.md or the README.

Users who store metadata in extensions may incorrectly assume it is tamper-proof.

What needs to change

1. docs/SECURITY.md — Add a row to the "What gets signed" section noting that extensions is outside the signature scope
2. receipt.rs — Expand the doc comment on the extensions field to explicitly say "UNTRUSTED: not covered by signature"
3. README — If extensions are mentioned anywhere, add a trust caveat

Acceptance criteria

• SECURITY.md explicitly lists extensions as unsigned
• Rust doc comment on the field is clear about trust implications
• No code changes needed, documentation only

Difficulty

Great first issue. Documentation only, no code changes.

[0xbrainkid]

The documentation gap here is important — the distinction between signed and unsigned fields is a security guarantee that users need to understand before building on the library.

One additional framing worth adding to SECURITY.md beyond listing extensions as unsigned: the attack scenario. Without documentation, developers might assume they can rely on extensions for security-relevant metadata (e.g., the agent ID that produced the receipt, the trust score at signing time, the task context). If an attacker can modify extensions after the fact without invalidating the signature, any such metadata becomes worthless as a security control.

Concrete scenarios to document:

• "Do not store agent identity in extensions and then verify the receipt expecting the identity to be tamper-proof — use a dedicated signed field or include identity in the receipt payload."
• "Extensions are appropriate for non-security metadata that aids readability or debugging, not for data that informs authorization decisions."

For SATP/AgentFolio integration with Signet receipts (cross-referencing behavioral trust attestations), we have to know which fields are signed. This documentation would directly inform how attestation providers should structure the data they contribute to receipts.

[willamhou]

Good points, especially the attack scenarios. You're right that developers might assume extensions are tamper-proof without explicit documentation.

I'll add to SECURITY.md:

1. A clear "signed vs unsigned fields" table for each receipt version
2. The attack scenarios you outlined (identity in extensions → forgeable)
3. Guidance: "security-relevant metadata belongs in the signed payload, extensions are for debugging/display only"

On the SATP/AgentFolio integration specifically: if you want to include a trust score or behavioral attestation that a verifier should rely on, it needs to be inside the signature scope. Two approaches:

A. Embed in the signed Action.params — e.g. params: {"tool": "...", "satp_trust_score": 85, "satp_attestation_id": "..."}. This is signed by Ed25519, tamper-proof, but it mixes tool params with trust metadata.

B. Add a signed attestations field to Receipt (new feature) — a separate Option<Vec<Attestation>> inside the signature scope, alongside policy and authorization. Each attestation has a provider, type, value, and timestamp. This keeps trust metadata cleanly separated from tool params while still being signed.

Option B is more principled for cross-protocol integration. Would that work for your SATP use case? I can spec it out if there's interest.