Crate trust_tasks_capability_client

Expand description

Client-side wire helpers for the capability Trust Task families — governance/capability/* (enable / disable / list a community capability) and git-trust/* (grant / revoke commit-signing trust).

This crate owns the documents, not a transport: it builds request documents, parses inbound envelope replies, classifies them, and (behind the signing feature) attaches a Data-Integrity proof. Each consumer keeps its own send/receive plumbing but shares this wire layer, so a capability producer (a community service) and a management UI cannot drift on the contract.

§Layers

Envelope: capability documents travel as the trust-tasks-didcomm binding envelope (TRUST_TASK_ENVELOPE_TYPE); parse_envelope_document turns an inbound body into (threadId, document).
Builders: build_document plus the family-specific build_list_document, build_toggle_document, build_git_trust_grant, build_git_trust_revoke.
Replies: classify_git_trust_reply (for grant/revoke writers) and parse_capability_reply (for governance management UIs).

§Retries versus fresh attempts

This crate is a producer, and the producer half of SPEC §7.2 item 11 is §8.4: a retry is a bit-for-bit identical resend. As of trust-tasks-rs 0.12.0 there is a consumer that enforces it — the record is keyed on the document id and compared against the whole document — and the DIDComm and TSP bindings now keep that record by default. So the two ways of sending a request again have become genuinely different operations:

Intent	What to send	What the consumer does
The first send may not have arrived	`previous` itself, unchanged	Absorbs it; returns whatever the first execution determined
Something about the request changed	`new_attempt(&previous)`	Treats it as the new document it is
Anything else under a reused `id`	—	Rejects it with `idConflict`

“Something about the request changed” is wider than it sounds: a re-stamped issuedAt or a re-signed proof over identical content is already a different document. That is deliberate — §8.4 says a producer that “retries” by re-signing “has not retried”, and the whole point of item 11’s comparison is that an id alone cannot tell the retry it must absorb from the conflict it must reject.

build_document and every builder over it mint a fresh id per call, so a caller that rebuilds is already minting a new attempt. new_attempt covers the case where the document has already been built (and possibly signed) and is about to be sent again.

Signing is deliberately not here — it is a thin Data-Integrity call each consumer makes with its own signer (a service reuses its credential signer; a client signs with the persona key), so this crate stays free of any crypto dependency. Sign the built document over its canonical form (the document minus its proof member, eddsa-jcs-2022) and set the proof member.

§Versioning

This crate exposes trust-tasks-rs types in its own public API, so a breaking change there breaks this crate’s callers even when nothing here changes. cargo-semver-checks cannot catch that: it compares each crate’s rustdoc against that crate’s own published baseline, and does not track type identity across dependency versions. The crates that share trust-tasks-rs in their public API are therefore released as one compatibility unit with a single shared version — see version_group in release-plz.toml.

Structs§

CapabilitySummary: One capability entry as rendered by a management UI.
ReplyPolicy: How much a caller is willing to infer from a non-conforming peer.

Enums§

CapabilityClientError: Errors from document construction.
CapabilityReply: The classification of a governance/capability/* reply.
WriteOutcome: The classification of a git-trust write reply.

Constants§

CAPABILITY_DISABLE_TYPE
CAPABILITY_ENABLE_TYPE
CAPABILITY_LIST_TYPE: governance/capability/* type URIs.
GIT_TRUST_ALREADY_GRANTED_CODE: The extended error code git-trust/grant declares for “an active grant already exists for this subject and resource” (SPEC §8.5; the code is declared in the registry entry’s errorCodes front matter).
GIT_TRUST_ALREADY_GRANTED_CODE_CAMEL: The lowerCamelCase spellings of the two codes above.
GIT_TRUST_GRANT_TYPE: git-trust/* type URIs.
GIT_TRUST_NOT_GRANTED_CODE: The extended error code git-trust/revoke declares for “no active grant exists for this subject and resource”.
GIT_TRUST_NOT_GRANTED_CODE_CAMEL: See GIT_TRUST_ALREADY_GRANTED_CODE_CAMEL.
GIT_TRUST_REVOKE_TYPE
TRUST_TASK_ENVELOPE_TYPE: The trust-tasks-didcomm binding envelope type (what a registry’s DIDComm Trust Task handler listens for).

Functions§

build_document: Build a capability Trust Task addressed issuer → recipient.
build_git_trust_grant: Build a git-trust/grant: grant subject commit-signing trust for resource (an org or org/repo slug).
build_git_trust_revoke: Build a git-trust/revoke.
build_list_document: Build a governance/capability/list request (status all).
build_toggle_document: Build a governance/capability/enable or /disable request. On enable, config.authority defaults to the community’s own DID — the community is the authority its capability records are issued under.
classify_git_trust_reply: Classify the reply to a git-trust/grant or git-trust/revoke write.
classify_git_trust_reply_with_policy: classify_git_trust_reply with an explicit ReplyPolicy.
correlation_thread: The thread an exchange started by doc is correlated by: its own threadId, or its id where it opens the exchange (SPEC §4.9’s fallback, which is the value respond_with and reject_with will thread the reply to).
new_attempt: A new attempt at the request previous carried: the same addressing, type and payload under a fresh id, a fresh issuedAt, and no proof.
parse_capability_reply: Classify a governance/capability/* reply document. None when it is not part of this family, or is not threaded to expected_thread_id.
parse_envelope_document: Parse a DIDComm envelope body into (threadId, document). None when the body is not a threaded Trust Task document.
parse_envelope_document_for: Parse a DIDComm envelope body into the document it carries, only if that document is threaded to expected_thread_id.
parse_envelope_reply: Parse an inbound envelope body directly into a reply to the request threaded expected_thread_id — the entry point for a UI’s inbound dispatch, which holds only a Value.
replies_to: Whether reply is threaded to expected_thread_id — SPEC §4.9 correlation, and the precondition for acting on any reply.