Skip to content

feat!: add taskDigestMultibase, so a VWC binds to the witness/session it cites - #31

Merged
stormer78 merged 1 commit into
mainfrom
feat/task-digest-multibase
Sep 22, 2026
Merged

stormer78 merged 1 commit into
mainfrom
feat/task-digest-multibase

Conversation

@stormer78

Copy link
Copy Markdown
Contributor

Adds taskDigestMultibase. The only VWC-issuing flow the specifications define requires it, and this crate had no way to produce it.

Specification dependency: trustoverip/dtgwg-cred-spec#56 defines the member in DTG Core Credentials. It is approved but not merged. This PR can merge once #56 is accepted.

What the specifications require

  • witness/session/submit/0.1 (dtgwg-trust-tasks-tf), Conformance item 1: the VWC in the witness's response MUST carry two members. taskContext MUST equal the id of the witness/session document that opened this session. taskDigestMultibase MUST be that document's task digest. The same spec says the member's schema "belongs to DTG Core Credentials". witness/session/0.1's outcomeEvidence declares the binding at /payload/vwc/taskContext and /payload/vwc/taskDigestMultibase. Both are top-level members of the VWC.
  • Trust Tasks §4.9.3 (Binding a Citation to the Document It Names) defines the digest as multibase(multihash(H(JCS(document ∖ proof)))):
    • only the top-level proof is removed; a proof inside payload is content and stays;
    • H is any multihash algorithm, with SHA-256 RECOMMENDED;
    • the encoding is any DigestMultibase form (z or u);
    • a verifier compares decoded multihash bytes;
    • a verifier treats an unimplemented algorithm as unverified, with no fallback to comparing ids.
  • dtgwg-cred-spec#56 makes it a top-level property: "REQUIRED wherever taskContext is REQUIRED, OPTIONAL otherwise". It adds the property as the sixth member under §Digest Encoding, so an issuer emits sha2-256 and base58btc. That is a valid narrowing of §4.9.3, and it makes the task digest exactly digest_multibase_json computed over a Trust Task document.

API

DTGCommon::task_digest_multibase + accessors A modelled member, so a non-string value is refused at parse time. A VWC without it still deserializes.
task_digest_multibase_json(&doc) The task digest. It has its own name because Trust Tasks also defines a step digest that includes the proof, and the two must not stand in for each other. VTI #1630 fixed exactly that confusion.
DTGCredential::new_vwc_for_session(issuer, subject, from, until, &session, digest, ctx) -> Result Reads taskContext and taskDigestMultibase from the session document, so the pair cannot disagree. The edge digest is REQUIRED. Refuses anything except the opening witness/session (NotAWitnessSession): a submit document, a #response, or a document whose threadId is not its own id, which witness/session Conformance item 1 requires.
with_task_citation / set_task_citation Sets both members from one document, on any credential type (for example a vetting/session statement).
cites_task(&doc) -> Result<bool> Checks the id and recomputes the digest, comparing decoded bytes. A credential with no taskDigestMultibase returns Ok(false), never an id-only match. An unimplemented algorithm is an error.
new_vwc Deprecated, because it cannot set the digest.

Why this breaks the API

DTGCommon is not #[non_exhaustive]. Its fields are public, and every constructor builds it with ..Default::default(). Adding a field therefore breaks exhaustive struct literals only, which is the same break 0.3.0 made for credentialStatus. I chose that over the fully additive alternative, which would keep the member in DTGCommon::extra, for two reasons:

  • The specification makes the member REQUIRED on every VWC, beside taskContext, which is already a modelled field.
  • extra is documented as holding members this library does not model, and it would accept a non-string value without complaint.

Marking DTGCommon #[non_exhaustive] now would be worse: it forbids ..Default::default() outside the crate. new_vwc keeps its signature and is deprecated rather than given a new required parameter, following the pattern 0.10.0 used for new_member_vmc → _for.

The wire is unchanged for a credential that lacks the member. An older release carries the member through a round trip in extra, so this release has no upgrade-ordering constraint. I have not bumped the version. The CHANGELOG entry is under [Unreleased], and #[deprecated(since = "0.11.0")] assumes the next release is 0.11.0.

Tests (tests/task_citation.rs, 22)

  • Vector from a second implementation. vetting/session/0.1 prints a session document and the taskDigestMultibase of it (zQmWAWEtpUqE3xd3LUpZ8GryGrZMCqH1A5D7bZcayvEfJTK). task_digest_multibase_json reproduces it. The four steps are also recomputed by hand. The Vetting Statement printed there parses, and cites_task accepts it against that session.
  • Proof handling. The digest ignores a top-level proof (signed, unsigned and re-signed copies give one value) and keeps a proof nested in payload.
  • Round trip. A session VWC serializes with taskDigestMultibase at the top level. It parses back into the modelled field (not extra), still cites its session, and digest_multibase() agrees with the digest of the wire form.
  • Decoded-bytes comparison.
    • A base64url (u…) spelling of the same multihash is accepted.
    • A sha2-512 multihash returns UnsupportedDigestAlgorithm, not false.
    • A counterfeit that reuses the session id with different content is refused.
    • A VWC with no digest cites nothing.
  • Constructor refusals. The submit document, the #response, a mismatched or missing threadId, a missing id, and an inverted validity window.

Verification

  • cargo fmt --all --check: pass
  • cargo clippy --all-targets --all-features -- -D warnings: pass. Also passes with --no-default-features.
  • cargo test --all-features: 186 passed, 0 failed
  • cargo test --no-default-features: 170 passed, 0 failed
  • cargo doc --no-deps --all-features: no warnings

Not addressed here

  • The VWC's type on cred-spec main. It is no longer WitnessCredential. The spec now expresses it as a StatementCredential under the dtg:witnessed predicate profile (dtgwg-cred-spec#45). This crate, new_vwc_for_session included, still builds the WD02 WitnessCredential shape. That migration is separate work. taskDigestMultibase is a top-level member either way, so this change carries over.
  • vwcDigestMultibase. In witness/session/submit#response it is taken over the credential including its proof, unlike every digest this crate computes. digest_multibase is the wrong function for it.

Refs OpenVTC/verifiable-trust-infrastructure#1068.

… it cites

witness/session/submit (dtgwg-trust-tasks-tf), Conformance item 1, requires
the delivered VWC to carry `taskContext` equal to the `id` of the
witness/session document that opened the session, and `taskDigestMultibase`
equal to that document's task digest (Trust Tasks §4.9.3). The member's schema
is left to DTG Core Credentials, which proposes it in
trustoverip/dtgwg-cred-spec#56. This crate had no way to produce it, so no VWC
it built could conform to the only issuing flow the specifications define.

- `DTGCommon::task_digest_multibase` (top-level, beside `taskContext`) and
  accessors. A VWC without it still deserializes.
- `task_digest_multibase_json`: JCS over the document minus its top-level
  `proof`, sha2-256 multihash, base58btc. The §Digest Encoding computation
  over a Trust Task document.
- `DTGCredential::new_vwc_for_session` reads both halves of the citation from
  the session document and refuses anything but the opening witness/session
  (`NotAWitnessSession`). `new_vwc` is deprecated.
- `with_task_citation` / `set_task_citation` for any credential type.
- `cites_task` checks both halves, comparing decoded multihash bytes, and
  never falls back to an `id`-only match.

Breaking: `DTGCommon` gains a public field (exhaustive struct literals only).
The vector is the one vetting/session/0.1 publishes, reproduced here.

Signed-off-by: Glenn Gore <glenn.g@affinidi.com>
@stormer78
stormer78 requested a review from a team as a code owner September 22, 2026 10:00
@stormer78
stormer78 merged commit 3eb6def into main Sep 22, 2026
7 checks passed
@stormer78
stormer78 deleted the feat/task-digest-multibase branch September 22, 2026 10:23
@stormer78 stormer78 mentioned this pull request Sep 22, 2026
stormer78 added a commit that referenced this pull request Sep 22, 2026
Cuts 0.11.0, the first published release since 0.9.1. 0.10.0 was merged and
versioned but never tagged, so it never reached crates.io; 0.11.0 carries
its changes together with the taskDigestMultibase work merged in #31.

- Cargo.toml: 0.10.0 -> 0.11.0
- CHANGELOG.md: [Unreleased] moves under [0.11.0] - 2026-09-22, with an
  "Upgrading from 0.9" section for consumers crossing both releases at
  once; the [0.10.0] section is marked as never published
- README.md: the upgrade-ordering table gains a 0.11.0 row and notes that
  0.10.0 first ships in 0.11.0

No code changes. The affinidi-tdk 0.12 -> 0.16 bump (#30) is a
dev-dependency only and is not user-visible.

Signed-off-by: Glenn Gore <glenn.g@affinidi.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant