Add optional event provenance and tamper-evidence guidance (#315) - #320
Add optional event provenance and tamper-evidence guidance (#315)#320MarkovianProtocol wants to merge 3 commits into
Conversation
Adds an informational companion document describing two distinct properties: authenticity and integrity via DSSE, and existence-over-time via an optional commitment to the event canonical hash on an external timeline. Mechanism-agnostic per the discussion in cdevents#315: the document names the class of anchors without endorsing one. No schema changes; nothing is required of an implementer. Signed-off-by: Colin H Winter <hello@markovianprotocol.com>
c92881c to
0f085aa
Compare
| url | ||
| viewUrl | ||
| wpaper | ||
| CDF |
There was a problem hiding this comment.
Why was this section moved?
Typical ordering based is based on ASCII / unicode order which has capital letters first.
There was a problem hiding this comment.
Restored — my edit had re-sorted the file case-insensitively, which moved the capitalized block. The original ordering is back with the additions inserted in place, plus the missing canonicalization entry that caused the CI failure.
Restore the original ordering of .spellcheck-en-custom.txt (capitalized entries first) with additions inserted in place, and add the missing 'canonicalization' entry that failed CI. Move the worked example into examples/event-provenance/ per review preference and point the guide at the in-repo path. Signed-off-by: Colin H Winter <hello@markovianprotocol.com>
| Note on CloudEvents: a message-level signature profile for CloudEvents itself is an open | ||
| discussion in the CloudEvents project | ||
| ([cloudevents/spec#565](https://github.com/cloudevents/spec/issues/565)) rather than a | ||
| finished standard. Applying DSSE to the CDEvent document, as described here, does not |
There was a problem hiding this comment.
The PR is merged, so I believe the discussion is over - FYI @xibz.
Should we refer to that as the recommended approach for signatures (part 1)?
There was a problem hiding this comment.
Updated in the latest commit: the note now points at the merged verifiability extension and recommends it as the signing approach when a CDEvent travels as a CloudEvent — it's DSSE in both cases, so the extension and Part 1 align rather than compete. The extension's own non-goals (stream completeness, ordering, existence over time) are exactly what the Part 2 commitment adds, so the two compose.
| Which anchor to use is an operational and threat-model choice. The only thing CDEvents | ||
| tooling needs to agree on is the commitment itself: the canonicalization | ||
| (RFC 8785) and the hash (SHA-256). Everything about the anchor is out of scope for this | ||
| document and MUST NOT be assumed by consumers. |
afrittoli
left a comment
afrittoli
left a comment
There was a problem hiding this comment.
Thanks for this PR @MarkovianProtocol - much appreciated!
I left a comment about DSSE and CloudEvents, let me know what you think.
I'm not sure if the CloudEvents SDK already supports DSSE. Do you think we should include something in the CDEvents SDKs to support the generation of the sea for the commitment side (part 2)?
I think the docs might benefit from a mermaid diagram showing which part is signed, where the signature is stored, on what the commitment is calculated on and where it is stored, but this can be done as a follow up.
- Add 'runnable' to the spellcheck wordlist (vendored example README) - Exempt event.canonical.json from JSON style linting: its exact bytes are the RFC 8785 canonical serialization the example commits to, so it cannot be reformatted - Update the CloudEvents note: the DSSE verifiability extension has merged; reference it as the recommended signing approach when a CDEvent travels as a CloudEvent, with Part 2 as the composing layer for the extension's stated non-goals Signed-off-by: Colin H Winter <hello@markovianprotocol.com>
|
Thanks for the review. Both CI failures are addressed in the new commit — one with a change worth flagging: On SDK support for the commitment side: yes, and it can stay small and neutral — a helper that emits the canonical bytes and their SHA-256 covers the part every anchor shares, while the anchor choice stays out of the SDK. Whether the CloudEvents SDKs ship DSSE for the verifiability extension yet I don't know; the extension specifies the SDK flow, so CDEvents inherits it wherever those SDKs land. On the diagram: agreed, and happy to contribute it as a follow-up — one sequence showing what is signed, where the signature rides, what the commitment is computed over, and where each is stored. |
2 participants
Adds an optional, informational companion document on event provenance, as invited in #315.
Two properties, kept distinct:
Per the discussion in #315, this is deliberately mechanism-agnostic. The document names the class of anchors — RFC 3161 timestamp authorities, append-only transparency logs, public blockchain inclusion — without endorsing one, and states explicitly that the choice of anchor is out of scope. The only thing CDEvents tooling needs to agree on is the commitment itself: RFC 8785 canonicalization plus SHA-256.
Scope of this PR
event-provenance.md(root level, matching existing document convention).README.mdunder the key assets list.spec.mdor any event definition. Nothing here is required of an implementer.Worked example. A runnable end-to-end example lives outside this repository at MarkovianProtocol/cdevents-provenance so CDEvents takes no dependency on it: a real
dev.cdevents.artifact.published.0.3.0event validated against the published v0.5.1 schema, its JCS canonical bytes, a DSSE envelope, the commitment, and a verifier demonstrating genuine artifacts passing both checks and tampered ones failing both. Happy to vendor it undertools/orconformance/instead if the group prefers it in-tree.Venue, wording, and which anchor mechanisms to list are all open to the group's preference — happy to walk through it at the SIG.
Closes #315