Skip to main content

trust_tasks 0.12.1 copy "trust_tasks: ^0.12.1" to clipboard
trust_tasks: ^0.12.1 copied to clipboard

Trust Tasks for Dart: a typed payload for every specification in the registry, plus the SPEC section 7.2 consumer pipeline that acts on them safely.

trust_tasks #

Dart bindings for the Trust Tasks framework: a generated payload type for every specification in the registry, and the hand-written SPEC.md §7.2 consumer pipeline that makes those types mean something.

The fourth of four reference implementations, alongside trust-tasks-rs, @openvtc/trust-tasks and trust-tasks-go. All four must reach the same verdict on the same document; npm run check-bindings is what holds them to it.

dart pub add trust_tasks

Requires Dart 3.3 or later. No dependencies — the cryptosuite and the JSON Schema engine are yours to choose, so this package declares interfaces for them and implements neither.

The prebuilt libraries under lib/specs/ are deprecated (all but the framework's own trust_task_* ones) and will be removed in a future release. Pin the tasks you use with the trust-tasks CLI and generate them with dart run trust_tasks:generate — see Generating only the tasks you use. The analyzer reports an import of a deprecated library (deprecated_member_use).

Installing the trust-tasks command #

Pinning tasks and generating their types uses the trust-tasks CLI, one binary for every language. No Rust toolchain is needed — any one of:

  • download the archive for your platform (Linux x86_64/aarch64, Windows x86_64; on macOS use cargo binstall or cargo install) from a trust-tasks-cli-v* release, check it against its .sha256, and put trust-tasks on your PATH;
  • cargo binstall trust-tasks-cli (the same prebuilt archive);
  • cargo install trust-tasks-cli (builds from source, Rust 1.95+).

See GETTING-STARTED for the commands.

What you bring yourself #

Payload validator (SPEC §7.2 item 2) yours — e.g. json_schema behind PayloadValidator, fed payloadSchemaJson
Proof verifier / signer (item 6) trust_tasks_proof — eddsa-jcs-2022, ecdsa-jcs-2019, did:key
Transport HTTPS: trust_tasks_https. DIDComm v2.1: trust_tasks_didcomm. TSP: trust_tasks_tsp (in this repository, not yet on pub.dev)

Importing #

The package's own library exports the runtime only. Dart's export is flat — there is no namespaced re-export — so exporting 500 generated libraries from one barrel would collide on the first shared definition anyone calls Ext. Import the 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; // generated

The prebuilt library of the same version (package:trust_tasks/specs/acl/grant/v0_3/payload.dart) has the same surface, so moving off it is a change to the import line; it is deprecated with the rest of the prebuilt tree.

Each generated library exports a uniform surface:

Identifier
Payload, Response the request and response payload classes
typeUri, responseTypeUri the Trust Task type URIs (responseTypeUri only where the specification defines a success response — SPEC §4.4.1)
payloadSchemaJson, responsePayloadSchemaJson the payload schema as JSON text, cross-file $refs already inlined
spec, responseSpec SpecPolicy values carrying the §7.2 policy flags and the schema above

Paths are snake_cased for Dart's file_names lint, so the slug acl/change-role becomes specs/acl/change_role/v0_3/payload.dart.

Consuming a document #

consumeInbound runs SPEC §7.2 items 2–8, plus the two stateful checks — the duplicate-execution record of item 11 and the freshness bound of item 13 — and then either calls your handler or builds the correctly-routed error response per §8.1.

Read the body with parseTrustTaskDocument, which never throws. TrustTaskDocument.fromJson casts each member, so a received document with a number where id belongs throws a TypeError — an Error, not an Exception — and parseTrustTaskDocument turns that, and a body nested more than maxNestingDepth (128) levels deep, into a malformedRequest reason. Pass the decoded map to consumeInbound as received too: the item-11 digest is then over the document as it arrived, members the payload type does not model included.

// One guard per consumer, not one per document: it IS the record.
final guard = InMemoryReplayGuard();

final json = jsonDecode(body); // a FormatException for text that is not JSON
final doc = switch (parseTrustTaskDocument(
  json,
  (p) => acl_grant.Payload.fromJson(p! as Map<String, dynamic>),
)) {
  ParsedDocument(:final document) => document,
  UnparsableDocument(:final reason) => throw MalformedBody(reason), // yours
};

final outcome = await consumeInbound<acl_grant.Payload, acl_grant.Response>(
  transport: transport,
  spec: acl_grant.spec,
  proofPolicy: ProofPolicy.verify(myVerifier),
  payloadPolicy: PayloadPolicy.validate(mySchemaEngine),
  // acl/grant is consequential: a replayed envelope must not grant twice.
  checks: consequentialChecks(guard),
  doc: doc,
  myVid: 'did:web:maintainer.example',
  now: DateTime.now(),
  payloadToJson: (p) => p.toJson(),
  responseToJson: (r) => r.toJson(),
  received: json as Map<String, dynamic>,
  handler: (accepted, parties) async => respondWith(
    accepted,
    newUrnUuid(),
    acl_grant.Response(entry: await applyGrant(accepted.payload.entry, parties)),
  ),
);

switch (outcome) {
  case Handled(:final response):
    emit(response);
  case Rejected(:final error):
    emit(error); // already addressed per §8.1
  case Suppressed(:final reason):
    log(reason); // §8.1 — no response may be emitted
  case Accepted():
    break; // fire-and-forget (§4.4.1): nothing to emit
  case DuplicateOutcome(:final priorResponse):
    // §7.2 item 11 — already executed. NOT an error. The first execution's
    // response document, as the JSON map that was recorded (`isError` says
    // whether it was a refusal).
    if (priorResponse != null) emitJson(priorResponse);
}

The outcome is a sealed hierarchy, so that switch is exhaustive and the compiler tells you if a case is missing.

payloadPolicy and checks are required. Both have an obvious "skip it" setting, and defaulting to it would silently reproduce the defects they exist to remove: a payload nobody validated, and a consequential task executed twice by an ordinary mediator retry.

Three things worth knowing #

The generated types carry no schema constraints. No minLength, no pattern, no minimum, and no oneOf mutual exclusion — auth/revoke-session's "sessionId xor all" is a class with both members optional. This matches the TypeScript and Go bindings exactly, and it is why payloadSchemaJson ships with every library: SPEC §7.2 item 2 is where those rules are enforced, and you enforce them by handing that schema to a JSON Schema engine through PayloadValidator.

Closed value sets are extension types, not enums. A Dart enum throws on a value it does not know, so a peer on a newer MINOR would crash your parse — in direct conflict with SPEC §5.2's forward-compatibility requirement. An extension type const Effect(String value) is zero-cost, erases to String, keeps == and the named constants, and carries an unrecognised value through without complaint. Compare against the constants and treat anything else as unrecognised.

Absent is not empty. Optional members are nullable, so List<String>? distinguishes absent (null) from present-and-empty ([]) natively. Several specifications make that distinction load-bearing — acl's allowedKeys documents at length that "PRESENT-BUT-EMPTY means authorized on NO keys — the opposite of absent". Dart gets this right for free where Go needed a pointer-to-slice.

Unrecognized top-level members survive a round trip in TrustTaskDocument.extra, per the §7.1 / §7.2 guidance to preserve them.

Generating only the tasks you use #

The package ships a generator that writes the libraries for exactly the task versions an application pins, from a trust-tasks.lock and the bundles vendored beside it (written by the trust-tasks CLI — see consumer-side generation):

dart run trust_tasks:generate --lock trust-tasks.lock --out lib/trust_tasks

It checks each bundle's SHA-256 against the lock before writing anything, needs no network, and owns --out: the directory is rewritten whole, and refused if it is non-empty without the .trust-tasks-generated marker. Each library lands at <out>/<slug>/v<M>_<N>/payload.dart with the same API as its counterpart under package:trust_tasks/specs/, and <out>/extends_index.dart is the index to pass as index: to readForVersion. The framework's own specifications (trust-task-*, trust-ceremony-*) are skipped — import them from the package. A task from a third-party source in the lock (source = "acme", vendored under trust-tasks/@acme/) is generated under <out>/acme/… and keeps its bundle's own Type URI. Output is formatted at language version 3.3 (--language-version to change it). examples/consumer-app-dart is a complete application.

Regenerating #

From the repository root:

npm run build-dart-bindings

The generator runs dart format on its own output, so the Dart SDK must be on your PATH. The bindings-drift job in .github/workflows/dart.yml fails if the committed tree differs from what the generator produces.

A change under specs/ must regenerate all four libraries in the same PR — see the repository CLAUDE.md.

Licence #

Apache-2.0.

1
likes
160
points
6.85k
downloads

Documentation

Documentation
API reference

Publisher

verified publishertrusttasks.org

Weekly Downloads

Trust Tasks for Dart: a typed payload for every specification in the registry, plus the SPEC section 7.2 consumer pipeline that acts on them safely.

Repository (GitHub)
View/report issues
Contributing

License

Apache-2.0 (license)

More

Packages that depend on trust_tasks