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.
POSTto<basePath>/trust-tasks, else404/405.Content-Type: application/json, else415.text/plainis a type a browser may POST cross-origin without a preflight; requiring JSON makes the browser refuse on this server's behalf.- Body within bodyLimitBytes, else
413; parses as a Trust Task document, else400. - Bearer token → transport-authenticated sender.
- Expiry and recipient; freshness; identity cross-check (§4.8.1) — §7.2
order, as
consumeInboundruns them, over the envelope. With no authenticated sender the identity cross-check runs first, so a misaddressed document is suppressed (§8.1). - Attribution gate — see requireAttribution.
- Route lookup. A
typeregistered as it is routes to its handler; a later version of a registered specification whose declaredextendschain (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 isunsupportedVersion; a specification with no registered version isunsupportedType. - The body against the route's
maxDocumentBytes(or defaultMaxDocumentBytes), elsemalformedRequest. A document read forward alongextendsis held only to bodyLimitBytes: its own version may declare a larger bound than the one it is read as. - Payload decode, then the DID-method pre-screen — see
allowedDidMethods. With a verifier and no explicit choice, only
did:keypasses. - 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}) -
proofVerifiernull means proof-bearing documents are refused withmalformedRequestrather 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.verificationMethodmay name; any other ({'key'},{'web', 'webvh'}) is refused before the verifier runs, as is averificationMethodthat is not a DID URL at all. Verifying means resolving, and resolving adid:webis 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
maxDocumentBytesamong the registered request specifications, and never less than defaultMaxDocumentBytes. A larger body is answered413before 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
extendsindex 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 (seeextensionChain).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
recipientis 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, withproofRequired. 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
handlerfor the specificationspecdescribes. -
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
handlerfor a fire-and-forget specification — one that defines no success response (SPEC §4.4.1). Success is answered204 No Content. -
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited