Crate trust_tasks

Expand description

One dependency line for the Trust Tasks framework.

The framework ships as eight independently-versioned crates, because each transport binding drags in a different (and heavy) dependency tree and you should only pay for the one you use. That split is right for a build; it is a tax at the front door. This crate is the front door: it re-exports the others behind Cargo features so that getting started is one line and one version.

trust-tasks = { version = "0.1", features = ["https", "proof-affinidi"] }

Everything here is a pub use. There are no wrapper types, no shims, and nothing to keep in step: trust_tasks::TrustTask is trust_tasks_rs::TrustTask, and trust_tasks::https::HttpsClient is trust_tasks_https::HttpsClient. Reaching for the underlying crate directly later is a find-and-replace, not a migration.

§Which crates do I need?

(Module names are written out rather than linked: a link to a module behind a Cargo feature you have not enabled is a broken link in your cargo doc.)

I want to…	feature	you get	underlying crate
model a Trust Task document, run the SPEC §7.2 consumer checks	(always on)	crate root: `TrustTask`, `consume_inbound`, `specs`, `RejectReason`	`trust-tasks-rs`
send/receive over HTTPS (typed client + axum server)	`https`	`trust_tasks::https`	`trust-tasks-https`
send/receive over DIDComm v2.1	`didcomm`	`trust_tasks::didcomm`	`trust-tasks-didcomm`
talk to Aries-lineage agents (DIDComm v1)	`didcomm-v1`	`trust_tasks::didcomm_v1`	`trust-tasks-didcomm-v1`
send/receive over the ToIP Trust Spanning Protocol	`tsp`	`trust_tasks::tsp`	`trust-tasks-tsp`
sign a document, or verify an inbound proof	`proof-affinidi`	`trust_tasks::proof`	`trust-tasks-proof`
validate payloads against their JSON Schema at runtime	`validate`	`trust_tasks::validate`, `trust_tasks::schema_index`	`trust-tasks-rs`
verify Trust Ceremony receipts and step digests	`ceremony`	`trust_tasks::ceremony`	`trust-tasks-ceremony`
build/parse `governance/capability/` + `git-trust/` wire documents	`capability-client`	`trust_tasks::capability_client`	`trust-tasks-capability-client`
bridge two bindings in one process	`all-transports`	all four transport modules	—
use `JwtBearerAuth` on the HTTPS server	`https-jwt`	`trust_tasks::https::JwtBearerAuth`	`trust-tasks-https`

Almost every real deployment wants one transport plus proof-affinidi: a task whose specification declares proof REQUIRED (acl/grant/0.1 is one) cannot be produced or consumed without a signer and a verifier.

§What this crate deliberately does not forward

trust-tasks-rs carries 26 per-spec-family features (vault, acl, keys, …) so a size-sensitive build can compile only the families it speaks. Those are not forwarded here. Only the all-specs umbrella is, and it is on by default.

That is a deliberate limit on what a facade is for. Twenty-six more feature names in front of a newcomer is the problem this crate exists to remove, and forwarding them would not even work reliably: Cargo unifies features across the whole dependency graph, so trimming spec families only pays off when nothing else in the graph asks for them. If you are trimming spec families, depend on trust-tasks-rs directly and skip this crate. That is a supported answer, not a workaround — this crate is a convenience for getting started, and you have outgrown it.

The same applies to subtracting a transport crate’s own defaults. Cargo features are additive, so nothing here can turn trust-tasks-https’s server off or close trust-tasks-didcomm-v1’s legacy-basic-message gate. Those need default-features = false on the crate itself.

§A first round trip

See GETTING-STARTED.md at the repo root for a signed acl/grant exchange with both ends written out, the TypeScript equivalent, and the four traps that reliably cost an afternoon. The Rust in that document is extracted from examples/acl_grant_roundtrip.rs in this crate and a test fails if the two drift, so it is code that compiles and runs rather than code that once did.

cargo run -p trust-tasks --features https,proof-affinidi \
    --example acl_grant_roundtrip

§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.

Re-exports§

pub use trust_tasks_rs as rs;
pub use trust_tasks_https as https;https
pub use trust_tasks_didcomm as didcomm;didcomm
pub use trust_tasks_didcomm_v1 as didcomm_v1;didcomm-v1
pub use trust_tasks_tsp as tsp;tsp
pub use trust_tasks_proof as proof;proof-affinidi
pub use trust_tasks_ceremony as ceremony;ceremony
pub use trust_tasks_capability_client as capability_client;capability-client

Modules§

discovery: Helpers for the trust-task-discovery/0.1 exchange.
freshness: Freshness bounds over issuedAt / expiresAt (SPEC.md §4.2, §7.2).
guards: Helpers for spec-handler policy checks that are easy to get wrong and worth centralising.
handlers: Reference TransportHandler implementations.
replay: Duplicate-execution protection — SPEC.md §7.2 item 11, §8.4, §10.1.
schema_indexvalidate: Generated by trust-tasks-codegen — do not edit by hand.
specs: Generated payload types for the Trust Task specifications hosted in this repo’s specs/ registry.
validatevalidate: Runtime JSON Schema validation for Trust Task payloads.

Structs§

AsyncDispatcher: Routes a TrustTask<Value> to an async handler registered for its Type URI, carrying a caller-supplied context value alongside it.
Ceremony: Records that a document is a step of a Trust Ceremony (SPEC.md §4.11).
CeremonyPrev: A reference to a predecessor step (SPEC.md §4.11).
ConsumeChecks: The two stateful consumer checks SPEC.md §7.2 requires and that no runtime in this repo implemented before 0.11.18: the freshness bound over issuedAt / expiresAt, and the duplicate-execution record of item 11.
Dispatcher: Routes a TrustTask<Value> to the handler registered for its Type URI.
DocumentDigest: The content identity of a Trust Task document, per SPEC §7.2’s keying paragraph: SHA-256 over the canonical serialization of the whole document.
ErasedVerifier: Adapter wrapping any concrete ProofVerifier as a DynProofVerifier. Produced by erase_verifier.
ErrorPayload: The payload of a trust-task-error/0.5 document, per SPEC.md §8.2.
FreshnessPolicy: How a consumer bounds a document in time before acting on it.
InMemoryReplayGuard: A bounded, in-process ReplayGuard: an LRU map from id to the digest accepted under it, its retention deadline, and the response it produced.
InResponseTo: Names the Trust Task document an ErrorPayload reports on (SPEC.md §8.2).
NoValidator: Pins the validator type on the PayloadPolicy::AcceptUnvalidated path.
Proof: A W3C Data Integrity proof object as required by SPEC.md §4.7.
ReplayGuardError: The record could not be consulted or written.
ResolvedParties: The result of resolving a document’s in-band party identity against the transport context.
SpecPolicy: The flag-driven consumer policy a Trust Task specification declares, read off a generated Payload impl.
TransportContext: What the transport handler observed about an inbound message’s parties.
TrustTask: A single Trust Task document, per SPEC.md §4.2.
TypeUri: Parsed Trust Task Type URI.

Enums§

ConsistencyError: Errors raised when in-band and transport-derived identity disagree (SPEC.md §7.2 item 6; standard code identity_mismatch, §8.3).
ConsumeOutcome: Possible outcomes of consume_inbound.
JsonLdContext: The value of the optional @context member, per SPEC.md §4.6 / JSON-LD.
ParseCodeError: Reason a string fails to parse as a TrustTaskCode.
ParseTypeUriError: Reasons a string fails to parse as a TypeUri.
PayloadPolicy: How consume_inbound performs SPEC.md §7.2 item 2 — payload-schema validation.
ProofPolicy: How consume_inbound handles a document’s proof member, per SPEC.md §7.2 item 7.
RejectReason: Typed rejection conditions a conforming consumer raises while applying SPEC.md §7.2.
ReplayPolicy: How a consumer applies SPEC §7.2 item 11 in consume_inbound.
ReplayVerdict: What a ReplayGuard says about a document offered for execution.
StaleReason: Which of the two acceptance-window failures produced a RejectReason::Stale.
StandardCode: The framework-defined standard error codes (SPEC.md §8.3).
TrustTaskCode: An error code — either a framework-standard code (SPEC.md §8.3) or an extension code namespaced by a spec’s slug (SPEC.md §8.5).
Variant: The #request / #response fragment of a Type URI, per SPEC.md §4.4.1.
VerificationError: Reasons a ProofVerifier rejects a proof.

Constants§

DEFAULT_MAX_AGE: The acceptance window FreshnessPolicy::consequential applies.
DEFAULT_SKEW: The clock-skew tolerance SPEC §4.2 sanctions for temporal comparisons. The spec’s wording is “typically ≤ 60s”; this is that bound.
IDENTITY_MISMATCH_WIRE_MESSAGE: Wire message for identityMismatch (SPEC §8.1, §10.4).
PROOF_INVALID_WIRE_MESSAGE: Wire message for proofInvalid. Constant by design — see RejectReason::wire_message.
PROOF_NOT_ACCEPTED_BY_POLICY: Wire-safe message for the RejectIfPresent rejection path. The in-house diagnostic (“no verifier configured”) would let an unauthenticated probe enumerate which endpoints in a fleet lack verifier coverage; this constant intentionally says nothing about the consumer’s configuration. Verbose diagnostics belong in logs.
STALE_WIRE_MESSAGE: Wire message for a document outside the consumer’s acceptance window.
UNAVAILABLE_WIRE_MESSAGE: Wire message for unavailable. Constant so a backing-store outage does not name the store on the wire.
WRONG_RECIPIENT_WIRE_MESSAGE: Wire message for wrongRecipient — never naming the consumer’s own VID.

Traits§

DynProofVerifier: Object-safe form of ProofVerifier used where a verifier must be stored behind a trait object — for example, on a transport binding’s shared state (Arc<dyn DynProofVerifier>) — so the concrete verifier type can be chosen at builder time rather than being threaded through every generic parameter.
Payload: A Rust type that corresponds to one variant (request or response) of a versioned Trust Task specification.
PayloadValidator: Evaluates a payload against its payload.schema.json (SPEC.md §7.2 item 2).
ProofVerifier: Plug-in seam for verifying a Trust Task document’s proof member.
ReplayGuard: The consumer-side record that makes SPEC §7.2 item 11 true.
RequestPayload: A Payload that names the response payload it is answered with.
TransportHandler: A transport binding’s plug-in for the framework.

Functions§

canonical_json: Serialize value to the deterministic form described in the module documentation: object members ordered, no insignificant whitespace, strings escaped minimally per RFC 8785 §3.2.2.2.
consume_inbound: Run SPEC.md §7.2 item 2 and items 4–8 against doc, then either call handler or build the routed error response per §8.1.
document_digest: Compute the SPEC §7.2 item 11 document identity for doc.
erase_verifier: Wrap a concrete ProofVerifier in an Arc<dyn DynProofVerifier> so it can be stored on shared state — typically on a transport binding’s server-builder. The single-line version of:
sha256_hex: Lowercase-hex SHA-256 of bytes.
trust_task_error_type_uri: The type URI every error response this library emits carries.

Type Aliases§

ErrorResponse: A trust-task-error document — a TrustTask whose payload is an ErrorPayload. This type alias is the form most consumer code holds onto when raising or propagating an error response.