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
identityMismatchwith 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
idand 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
payloadof 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
idto 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 bare500) 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
proofmember (§7.2 item 7). - ProofRejected
-
The proof verifier did not accept a document's proof. Answered
proofInvalidwith 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
identityMismatchand 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
proofthey 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/#responsefragment 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
issuedAta statedexpiresAtis 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
malformedRequestfromexpiresAt <= issuedAt. - futureIssuedAt → const String
-
Wire-safe reason for a
malformedRequestfrom a future-datedissuedAt. - idConflictWireMessage → const String
-
Wire message for
idConflict(SPEC §7.2 item 11, §8.3). - issuedAtRequired → const String
-
Wire-safe reason for a
malformedRequestfrom a missingissuedAt. - 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.
- 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
valuewith 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 underschema— the payload schema of the specification the document is consumed under (SpecPolicy.payloadSchema, JSON text), ornullto read every level.recognizedis everyextnamespace 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 callhandleror 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
hookwithevent, 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
issuedAtrequirement. -
exceedsNestingDepth(
Object? value, [int limit = maxNestingDepth]) → bool -
Whether
value, a decoded JSON tree, nests maps and lists more thanlimitlevels 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
receivedTypeUrimay be read as the versionimplementedTypeUrinames, because the former's declaredextendschain 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 declaredextendschain 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
identityMismatchreason for a ConsistencyError. -
isErrorDocument(
Map< String, dynamic> doc) → bool -
Whether the JSON document
docis an error response — itstypeis atrust-task-errorType 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
codeis 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 theidof a request, response or error document. -
normalizeCode(
String code) → String -
Normalize a wire
codeto 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 ofjsonDecodeon a received body — into a document, or say why it is not one, without throwing. -
prunePayload(
Object? payload, String schemaJson) → Object? -
payloadwith every object memberschemaJsondoes not know removed, where the schema closes the object withadditionalProperties: false. -
readForVersion<
P> (Map< String, dynamic> received, SpecPolicy spec, P payloadFromJson(Object? payload), {Map<String, String> index = generated.extendsIndex}) → VersionRead<P> -
Read
receivedas the versionspecdescribes, following a declaredextendschain forward (SPEC §5.2). -
recordExpiry<
P> (TrustTaskDocument< P> doc, FreshnessPolicy policy, DateTime now) → DateTime? -
The instant past which a replay record for
docmay 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 explicitrecipient. -
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#responsefragment, 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/#responsefragment 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
policyto this document'sissuedAt/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-errordocument. -
Handler<
P, R> = Future< TrustTaskDocument< Function(TrustTaskDocument<R> ?>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.
consumeInboundanswers itunavailable. - TypeUriFormatException
- Thrown by TypeUri.parse for a string that is not a Trust Task Type URI.