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 — from the library dart run trust_tasks:generate wrote into your own package:

import 'package:trust_tasks/trust_tasks.dart';
import 'package:my_app/trust_tasks/acl/grant/v0_3/payload.dart' as acl_grant;

The prebuilt libraries under package:trust_tasks/specs/ have the same surface, and are deprecated.

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
AuthenticatorFailed
The HTTPS bearer authenticator threw. The request carried on as unauthenticated, which is what an authenticator that fails has done.
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.
DocumentMalformed
The bytes are not a Trust Task document at all — not JSON, not an object, or no string id / type (§7.2 item 1). Answered as a malformed body.
DocumentParse<P>
What parseTrustTaskDocument made of a decoded JSON value.
DocumentRejected
A document was refused with a routed error response — any framework check, or a handler's Refusal. error is exactly what was sent.
DocumentSuppressed
A refusal that §8.1 forbids answering — an identityMismatch with no authenticated sender — so nothing (HTTPS: an answer indistinguishable from a malformed body) was sent. consumeInbound's Suppressed says callers SHOULD log it; this is that log line.
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.
HandlerFailed
A handler threw something other than a Refusal. Answered internalError; the exception is here and nowhere else.
InMemoryReplayGuard
A bounded, in-process ReplayGuard: a 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).
InternalFailure
Something failed outside every step above — an encoder that threw on the response, an adapter's I/O — and was answered internalError (or a bare 500) rather than escaping.
IssuerScopedReplayGuard
A ReplayGuard that is told which party a document is attributed to: the issuer SPEC §4.8.1 resolved for it, null when there is none.
NotConsequentialReplay
ParsedDocument<P>
The value was a Trust Task document; here it is.
PartyResolution
The result of resolveParties: either the resolved parties or a mismatch.
PayloadDecodeFailed
The envelope parsed, but the payload did not decode as the specification's type. Answered malformedRequest, without the decoder's words (§12.4).
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).
ProofRejected
The proof verifier did not accept a document's proof. Answered proofInvalid with a constant message (§10.4, §12.4).
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.
ServerEvent
Something a binding server or consumer reports to its ServerEventHook.
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<P>
A single Trust Task document, per SPEC.md §4.2.
TypeUri
A parsed Trust Task Type URI.
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.
UnparsableDocument<P>
The value was not a Trust Task document this consumer can read. Refuse it with reason, which is malformedRequest; nothing in the value is trustworthy enough to address the refusal to, so answer it the way your transport answers a body that does not parse.
ValidatePayload
VerifyProof
VersionAccepted<P>
The document may be consumed as the implemented version.
VersionRead<P>
The outcome of readForVersion.
VersionRefused<P>
The document is not one the implemented version may read.

Enums

TypeUriError
Why a string failed to parse as a TypeUri.
TypeUriVariant
The #request / #response fragment of a Type URI (SPEC.md §4.4.1).

Extension Types

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

Constants

defaultExpiryHorizon → const Duration
The expiry horizon FreshnessPolicy.consequential applies: the furthest after issuedAt a stated expiresAt is honoured.
defaultMaxAge → const Duration
The acceptance window consequentialChecks applies.
defaultReplayCapacity → const int
The live-record count InMemoryReplayGuard retains when given no explicit capacity: 100 000.
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.
maxNestingDepth → const int
The deepest nesting of maps and lists a consumed document may have, the document itself counting as one level. The same figure as the recursion limit of serde_json, which trust-tasks-rs parses documents with.
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.
checkCriticalExtensions(Object? payload, String? schema, [Iterable<String> recognized = const []]) → RejectReason?
Apply SPEC §4.5.2 to payload, read under schema — the payload schema of the specification the document is consumed under (SpecPolicy.payloadSchema, JSON text), or null to read every level. recognized is every ext namespace this consumer implements.
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<P> doc, required String myVid, required DateTime now, String newErrorId() = newUrnUuid, required Object? payloadToJson(P payload), required Object? responseToJson(R response), required Handler<P, R> handler, Clock? clock, Map<String, dynamic>? received, Map<String, String>? extendsIndex}) → 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<P>(TrustTaskDocument<P> 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.
emitServerEvent(ServerEventHook? hook, ServerEvent event) → void
Call hook with event, if there is a hook, swallowing whatever it throws.
enforceAudienceBinding<P>(TrustTaskDocument<P> 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<P>(TrustTaskDocument<P> 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.
exceedsNestingDepth(Object? value, [int limit = maxNestingDepth]) → bool
Whether value, a decoded JSON tree, nests maps and lists more than limit levels deep.
extendedCode(String typeUri, String local) → String
Build an extended error code under a specification's own slug (SPEC §8.5).
extendsTo(String receivedTypeUri, String implementedTypeUri, {Map<String, String> index = generated.extendsIndex}) → bool
Whether a document typed receivedTypeUri may be read as the version implementedTypeUri names, because the former's declared extends chain reaches the latter. Same specification only — the same authority, form and slug (TypeUri.isSameSpecification); fragments are ignored.
extensionChain(String typeUri, {Map<String, String> index = generated.extendsIndex}) → List<String>
The versions typeUri's declared extends chain reaches, nearest first, excluding the version itself.
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.
isErrorDocument(Map<String, dynamic> doc) → bool
Whether the JSON document doc is an error response — its type is a trust-task-error Type URI — rather than a success response.
isErrorResponse<P>(TrustTaskDocument<P> 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.
newUrnUuid() → String
A fresh urn:uuid: identifier — a version-4 UUID from a cryptographically secure source, for the id of a request, response or error document.
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.
parseTrustTaskDocument<P>(Object? json, P payloadFromJson(Object? payload)) → DocumentParse<P>
Decode json — the result of jsonDecode on a received body — into a document, or say why it is not one, without throwing.
prunePayload(Object? payload, String schemaJson) → Object?
payload with every object member schemaJson does not know removed, where the schema closes the object with additionalProperties: false.
readForVersion<P>(Map<String, dynamic> received, SpecPolicy spec, P payloadFromJson(Object? payload), {Map<String, String> index = generated.extendsIndex}) → VersionRead<P>
Read received as the version spec describes, following a declared extends chain forward (SPEC §5.2).
recordExpiry<P>(TrustTaskDocument<P> 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<P>(TrustTaskDocument<P> request, String id, RejectReason reason, {Clock? clock}) → Refusal
Build a handler-side refusal addressed to the original producer.
reject<P>(TransportHandler handler, TrustTaskDocument<P> doc, String id, RejectReason reason, {Clock? clock}) → ErrorResponse?
Build the error response for doc, applying the §8.1 routing rules.
rejectWith<P>(TrustTaskDocument<P> request, String id, ErrorPayload payload, {Clock? clock}) → ErrorResponse
Build the error response for request, addressed to its original producer.
rejectWithRecipient<P>(TrustTaskDocument<P> request, String id, ErrorPayload payload, String? recipient, {Clock? clock}) → ErrorResponse
Build the error response for request, addressed to an explicit recipient.
resolveParties<P>(TransportHandler handler, TrustTaskDocument<P> doc) → PartyResolution
Apply §4.8.1 precedence to produce the final ResolvedParties.
respondWith<P, R>(TrustTaskDocument<P> 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<P>(TrustTaskDocument<P> doc, DateTime now, String myVid) → RejectReason?
SPEC §7.2 items 4 and 5a — expiry and wrong-recipient.
validateFreshness<P>(TrustTaskDocument<P> 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<P> doc, ResolvedParties parties)
The business handler, called only once every framework check has passed.
ServerEventHook = FutureOr<void> Function(ServerEvent event)
Receives ServerEvents. May be asynchronous; it is not awaited.

Exceptions / Errors

Refusal
Thrown by a Handler to refuse with a specific error response.
ReplayGuardFullException
Thrown by InMemoryReplayGuard.claim when every slot holds a record still inside its retention window. consumeInbound answers it unavailable.
TypeUriFormatException
Thrown by TypeUri.parse for a string that is not a Trust Task Type URI.