HttpsServer class final

A Trust Tasks server for the HTTPS binding (bindings/https/0.2).

Register a handler per specification with on (or onAck for a specification that defines no success response), then hand each request to handle. Serve it with serve from package:trust_tasks_https/io.dart, or adapt handle to any other HTTP server.

final server = HttpsServer(
  localVid: 'did:web:maintainer.example',
  auth: StaticBearerAuth({'s3cret': 'did:web:org.example'}),
)..on<acl_grant.Payload, acl_grant.Response>(
    spec: acl_grant.spec,
    decode: acl_grant.Payload.fromJson,
    encode: (p) => p.toJson(),
    encodeResponse: (r) => r.toJson(),
    handler: (doc, ctx) async => acl_grant.Response(entry: doc.payload.entry),
  );

Request pipeline

In this order, which matches trust-tasks-https in Rust. Everything that can make the server do work an unauthenticated sender chose — above all resolving a did:web inside the proof verifier, an outbound request to a host named in the body — runs after the cheap, local refusals.

  1. POST to <basePath>/trust-tasks, else 404 / 405.
  2. Content-Type: application/json, else 415. text/plain is a type a browser may POST cross-origin without a preflight; requiring JSON makes the browser refuse on this server's behalf.
  3. Body within bodyLimitBytes, else 413; parses as a Trust Task document, else 400.
  4. Bearer token → transport-authenticated sender.
  5. Expiry and recipient; freshness; identity cross-check (§4.8.1) — §7.2 order, as consumeInbound runs them, over the envelope. With no authenticated sender the identity cross-check runs first, so a misaddressed document is suppressed (§8.1).
  6. Attribution gate — see requireAttribution.
  7. Route lookup. A type registered as it is routes to its handler; a later version of a registered specification whose declared extends chain (SPEC §5.2) reaches a registered version routes to the highest such version, read as that version (readForVersion). Any other version of a registered specification is unsupportedVersion; a specification with no registered version is unsupportedType.
  8. The body against the route's maxDocumentBytes (or defaultMaxDocumentBytes), else malformedRequest. A document read forward along extends is held only to bodyLimitBytes: its own version may declare a larger bound than the one it is read as.
  9. Payload decode, then the DID-method pre-screen — see allowedDidMethods. With a verifier and no explicit choice, only did:key passes.
  10. Proof verification, the per-specification policy, the duplicate-execution claim (§7.2 item 11), and the handler — consumeInbound.

Steps 5 and 6 depend on nothing a route holds. They run before the lookup so that a sender the attribution gate refuses gets the same answer whether or not its type is registered: the route table is not readable without attribution, just as enableDiscovery keeps it unreadable without authentication. The lookup still precedes every step that can make an outbound request.

Observability

Pass onEvent to see what the wire deliberately does not say — the exception behind an internalError, the identity disagreement behind a suppressed refusal, why a proof failed. See ServerEvent. The hook never changes an answer, and whatever it throws is dropped.

Constructors

HttpsServer({String? localVid, BearerAuthenticator? auth, ProofVerifier? proofVerifier, PayloadValidator? payloadValidator, ReplayGuard? replayGuard, bool replayProtection = true, FreshnessPolicy freshness = FreshnessPolicy.consequential, bool requireAttribution = true, Set<String>? allowedDidMethods, bool allowAnyDidMethod = false, String basePath = '', DateTime clock() = DateTime.now, ServerEventHook? onEvent, int defaultMaxDocumentBytes = maxBodyBytes, Map<String, String>? extendsIndex})
proofVerifier null means proof-bearing documents are refused with malformedRequest rather than accepted unverified — silently dropping a producer's proof would mislead it about what the exchange guarantees.

Properties

allowedDidMethods → Set<String>?
The DID methods a proof.verificationMethod may name; any other ({'key'}, {'web', 'webvh'}) is refused before the verifier runs, as is a verificationMethod that is not a DID URL at all. Verifying means resolving, and resolving a did:web is an outbound request to a host the sender picked; this bounds where that can go. Null screens nothing.
final
auth → BearerAuthenticator
Maps bearer tokens to VIDs. The default authenticates nobody.
final
bodyLimitBytes → int
The largest request body this server reads, in bytes: the largest maxDocumentBytes among the registered request specifications, and never less than defaultMaxDocumentBytes. A larger body is answered 413 before a byte of it is parsed.
no setter
defaultMaxDocumentBytes → int
The size bound, in bytes of the request body, for a document whose specification declares no maxDocumentBytes — and the floor of bodyLimitBytes. Defaults to maxBodyBytes (256 KiB).
final
extendsIndex → Map<String, String>?
The extends index forward routing follows; null uses the generated one, which covers the public registry. A server of third-party (§6.5) specifications passes its own, keyed the same way (see extensionChain).
final
freshness → FreshnessPolicy
The acceptance window over issuedAt / expiresAt, and so also how long each replay record is kept: SPEC §7.2 makes them one bound.
final
hashCode → int
The hash code for this object.
no setterinherited
localVid → String?
This server's VID: the transport-authenticated recipient (§3), and what an in-band recipient is checked against.
final
onEvent → ServerEventHook?
Told what happened to each request, for logs and metrics; see ServerEvent. Null reports nothing. Never changes an answer: it is called after the decision, not awaited, and whatever it throws is dropped.
final
payloadValidator → PayloadValidator?
Validates payloads against their schema (§7.2 item 2). Null skips it; the typed decode still refuses a payload of the wrong shape.
final
proofVerifier → ProofVerifier?
Verifies in-band proofs; see the constructor.
final
replayGuard → ReplayGuard
The duplicate-execution record. The default is in-process, which is correct for one process and wrong behind a load balancer: each replica would accept the same document once (§5.1 item 6). Supply a shared store.
final
replayProtection → bool
Keep the §7.2 item 11 record. Defaults to true.
final
requireAttribution → bool
Refuse a document with neither a transport-authenticated sender nor a proof, with proofRequired. Defaults to true.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

enableDiscovery({bool public = false, String frameworkVersion = '0.6.0', bool advertiseAcceptanceWindow = true}) → void
Answer trust-task-discovery (SPEC §10), versions 0.4, 0.3, 0.2 and 0.1, with every Type URI this server has a handler for, read at request time. Each version is answered in the version it was asked.
handle(HttpsRequest request) → Future<HttpsReply>
Answer one request. Never throws.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
on<P, R>({required SpecPolicy spec, required P decode(Map<String, dynamic> json), required Object? encode(P payload), required Object? encodeResponse(R payload), required Future<R> handler(TrustTaskDocument<P> doc, RequestContext ctx)}) → void
Register handler for the specification spec describes.
onAck<P>({required SpecPolicy spec, required P decode(Map<String, dynamic> json), required Object? encode(P payload), required Future<void> handler(TrustTaskDocument<P> doc, RequestContext ctx)}) → void
Register handler for a fire-and-forget specification — one that defines no success response (SPEC §4.4.1). Success is answered 204 No Content.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited