trust_tasks library

The Trust Tasks framework runtime for Dart — the SPEC.md §7.2 consumer pipeline, the document envelope, and the transport seam.

Hand-written, unlike everything under lib/specs/, which is generated from the spec registry by scripts/build-dart-bindings.mjs. Shipped in the same package so a consumer gets the types and the checks that make them meaningful from one dart pub add, as trust-tasks-rs, @openvtc/trust-tasks and trust-tasks-go do.

The entry point is consumeInbound.

Importing a specification

This library deliberately exports the runtime only. Dart's export is flat — there is no namespaced re-export — so exporting 500 generated libraries here would collide on the first shared definition anyone calls Ext. Import the one specification you need directly, with a prefix:

import 'package:trust_tasks/trust_tasks.dart';
import 'package:trust_tasks/specs/acl/grant/v0_1/payload.dart' as acl_grant;

Parity

This package mirrors trust-tasks-rs, @openvtc/trust-tasks and trust-tasks-go check for check. A Dart consumer must reach the same verdict on the same document as any of them, or the reference implementations disagree about what conforms. Where a signature differs it is because Dart's type system forced it, and the reason is written at the difference.

Dependencies

None, deliberately: the cryptosuite and the JSON Schema engine are the consumer's to choose, so ProofVerifier and PayloadValidator are interfaces this package does not implement.

Classes

Accepted<R>: Every check passed and the handler completed without producing a document — a fire-and-forget task.
AcceptPayloadUnvalidated
AcceptProofUnverified
Ceremony: Records that a document is a step of a Trust Ceremony — a flow composed of several Trust Tasks (SPEC.md §4.11).
CeremonyPrev: A reference to a predecessor step (SPEC.md §4.11).
Conflict: Already accepted under a different digest. §7.2 item 11 requires idConflict, and requires that this not be treated as a retry.
ConsistencyError: Raised when in-band and transport-derived identity disagree (§7.2 item 6).
ConsumeChecks: The two stateful §7.2 checks: the freshness bound over issuedAt / expiresAt, and the duplicate-execution record of item 11.
ConsumeOutcome<R>: The outcome of consumeInbound.
Duplicate: Already accepted under the same digest — a §8.4 retry, or a replay. The caller MUST NOT execute again.
DuplicateOutcome<R>: SPEC §7.2 item 11: a document with this id and this content was already accepted for execution. The handler was not called, and the consequential effect did not happen a second time. This is the §8.4 retry being absorbed, which is what makes retrying safe.
ErrorPayload: The payload of an error response (SPEC.md §8.2).
Fresh: Not seen before. The caller may execute.
FreshnessPolicy: How a consumer bounds a document in time before acting on it.
GuardedReplay
Handled<R>: Every check passed and the caller's handler produced a response.
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 (§8.2).
NotConsequentialReplay
PartyResolution: The result of resolveParties: either the resolved parties or a mismatch.
PayloadPolicy: How consumeInbound performs SPEC §7.2 item 2 — payload-schema validation.
PayloadValidator: Evaluates a payload against its schema (SPEC §7.2 item 2).
Proof: A W3C Data Integrity Proof object (SPEC.md §4.7). Opaque to the framework, which never inspects it beyond noticing that it is present.
ProofPolicy: How consumeInbound treats a document's proof member (§7.2 item 7).
ProofVerifier: Verifies a document's Data Integrity proof (SPEC §4.7).
Rejected<R>: A framework check failed, or the handler refused. Either way the document is already addressed per §8.1 — emit it over the transport.
RejectProofIfPresent
RejectReason: Why a consumer rejected a document, and the §8.3 code it maps to.
ReplayGuard: The consumer-side record that makes SPEC §7.2 item 11 true.
ReplayPolicy: How a consumer applies SPEC §7.2 item 11 in consumeInbound.
ReplayVerdict: What a ReplayGuard says about a document offered for execution.
ResolvedParties: Party identity after §4.8.1 precedence — the values a consumer applies for every subsequent framework rule referencing the issuer or recipient.
SpecPolicy: The per-specification declarations a consumer needs to apply SPEC §7.2 items 5b, 7 and 8. Generated libraries export this as spec / responseSpec.
StaticTransport: A fixed-identity handler, for tests and for transports resolved out-of-band.
Suppressed<R>: §8.1: the rejection was identityMismatch and the transport authenticated no sender, so no response may be emitted — one would be an oracle.
TransportContext: What the transport authenticated about an inbound message.
TransportHandler: A transport binding's plug-in for the framework.
TrustTaskDocument: A single Trust Task document, per SPEC.md §4.2.
UnauthenticatedTransport: A handler for transports that authenticate nothing — an unauthenticated HTTP POST, a public queue, paper. Party identity comes entirely from the in-band members and whatever proof they carry.
ValidatePayload
VerifyProof

Extension Types

StandardCode: A framework-defined standard error code (SPEC.md §8.3).

Constants

defaultMaxAge → const Duration: The acceptance window consequentialChecks applies.
defaultReplayCapacity → const int: The record count InMemoryReplayGuard retains when given no explicit capacity.
defaultSkew → const Duration: The clock-skew tolerance SPEC §4.2 sanctions ("typically ≤ 60s").
expiryNotAfterIssuance → const String: Wire-safe reason for a malformedRequest from expiresAt <= issuedAt.
futureIssuedAt → const String: Wire-safe reason for a malformedRequest from a future-dated issuedAt.
idConflictWireMessage → const String: Wire message for idConflict (SPEC §7.2 item 11, §8.3).
issuedAtRequired → const String: Wire-safe reason for a malformedRequest from a missing issuedAt.
packageVersion → const String: The released version of package:trust_tasks.
proofInvalidWireMessage → const String: Wire message for proofInvalid.
proofNotAcceptedByPolicy → const String: Wire message for the RejectProofIfPresent path.
replayRecordUnavailable → const String: Wire message for a replay-record outage. A constant, so a store's hostname or connection string never reaches the wire (SPEC §12.4).
staleWireMessage → const String: Wire message for a document outside the consumer's acceptance window.
trustTaskErrorTypeUri → const String: The Type URI a consumer emits error responses under.

Functions

bareTypeUri(String typeUri) → String: A Type URI with any fragment removed.
canonicalJson(Object? value) → String: Serialize value with object members recursively ordered and no insignificant whitespace.
consequentialChecks(ReplayGuard guard) → ConsumeChecks: The posture for a consequential Trust Task (§2): item 11 enforced against guard, and the bounded acceptance window that makes the record droppable.
consumeInbound<P, R>({required TransportHandler transport, required SpecPolicy spec, required ProofPolicy proofPolicy, required PayloadPolicy payloadPolicy, required ConsumeChecks checks, required TrustTaskDocument doc, required String myVid, required DateTime now, required String newErrorId(), required Object? payloadToJson(P payload), required Handler<P, R> handler, Clock? clock}) → Future<ConsumeOutcome<R>>: Run SPEC §7.2 items 4–8 against doc, then either call handler or build the routed error response per §8.1.
documentDigest(TrustTaskDocument doc, Object? payloadToJson(P payload)) → String: The content identity of a document, per SPEC §7.2's keying paragraph: SHA-256 over the canonical serialization of the whole document, as hex.
enforceAudienceBinding(TrustTaskDocument doc, SpecPolicy spec) → RejectReason?: SPEC §7.2 item 8 — a proof-bearing document on a non-bearer specification must carry an in-band recipient, so the proof binds the audience as well as the content (§4.8.2).
enforceSpecPolicy(TrustTaskDocument doc, SpecPolicy spec) → RejectReason?: The policy-driven subset of SPEC §7.2 — items 5b, 7 clause A, and 8, plus §7.3 item 17's issuedAt requirement.
extendedCode(String typeUri, String local) → String: Build an extended error code under a specification's own slug (SPEC §8.5).
familyCode(String typeUri, String namespace, String local) → String: Build an extended error code under a family namespace — a proper path prefix of the specification's slug (SPEC §8.5 rule 2).
identityMismatchReason(ConsistencyError error) → RejectReason: The identityMismatch reason for a ConsistencyError.
isErrorResponse(TrustTaskDocument doc) → bool: Whether a document is an error response rather than a success response.
isStandardCode(String code) → bool: Whether code is a standard §8.3 code, in either casing.
normalizeCode(String code) → String: Normalize a wire code to its canonical 0.2 spelling when it is a standard code, or return it unchanged.
notConsequentialChecks() → ConsumeChecks: The posture for a task that is not consequential, or whose specification "explicitly declares repeated execution safe and intended" — the narrow disapplication item 11 permits.
recordExpiry(TrustTaskDocument doc, FreshnessPolicy policy, DateTime now) → DateTime?: The instant past which a replay record for doc may be dropped — the end of this consumer's willingness to execute it, which SPEC §7.2 makes the same instant as the end of the record's required retention.
refuse(TrustTaskDocument request, String id, RejectReason reason, {Clock? clock}) → Refusal: Build a handler-side refusal addressed to the original producer.
reject(TransportHandler handler, TrustTaskDocument doc, String id, RejectReason reason, {Clock? clock}) → ErrorResponse?: Build the error response for doc, applying the §8.1 routing rules.
rejectWith(TrustTaskDocument request, String id, ErrorPayload payload, {Clock? clock}) → ErrorResponse: Build the error response for request, addressed to its original producer.
rejectWithRecipient(TrustTaskDocument request, String id, ErrorPayload payload, String? recipient, {Clock? clock}) → ErrorResponse: Build the error response for request, addressed to an explicit recipient.
resolveParties(TransportHandler handler, TrustTaskDocument doc) → PartyResolution: Apply §4.8.1 precedence to produce the final ResolvedParties.
respondWith<P, R>(TrustTaskDocument request, String id, R payload, {Clock? clock}) → TrustTaskDocument<R>: Build the success-response document for request, per SPEC §4.4.1 — the request's Type URI with the #response fragment, the parties swapped, and the thread continued.
sha256Hex(List<int> input) → String: FIPS 180-4 SHA-256 over input, as lowercase hex.
sha256HexOfString(String input) → String: SHA-256 over the UTF-8 encoding of input, as lowercase hex.
slugFromTypeUri(String typeUri) → String: The slug of a Type URI, with any #request / #response fragment removed.
systemClock() → String: Stamps responses with the current time in RFC 3339, to the second.
toErrorPayload(RejectReason reason) → ErrorPayload: Turn a RejectReason into the §8.2 payload it maps to.
validateBasic(TrustTaskDocument doc, DateTime now, String myVid) → RejectReason?: SPEC §7.2 items 4 and 5a — expiry and wrong-recipient.
validateFreshness(TrustTaskDocument doc, DateTime now, FreshnessPolicy policy) → RejectReason?: Apply policy to this document's issuedAt / expiresAt. Returns null when the document is acceptable.

Typedefs

Clock = String Function(): Returns the timestamp a built response is stamped with. Injectable so tests are deterministic.
ErrorResponse = TrustTaskDocument<ErrorPayload>: A trust-task-error document.
Handler<P, R> = Future<TrustTaskDocument<R>?> Function(TrustTaskDocument doc, ResolvedParties parties): The business handler, called only once every framework check has passed.

Exceptions / Errors

Refusal: Thrown by a Handler to refuse with a specific error response.

trust_tasks library

Importing a specification

Parity

Dependencies

Classes

Extension Types

Constants

Functions

Typedefs

Exceptions / Errors

trust_tasks package

trust_tasks library