io library

Serving an HttpsServer with dart:io.

A separate library from trust_tasks_https.dart because dart:io does not exist on the web, and the client — which a browser or Flutter web app may well want — should not lose the web for the server's sake.

Classes

BearerAuthenticator
Resolves a bearer token to the VID it authenticates (§3).
HttpsClient
A client for the HTTPS binding (bindings/https/0.2).
HttpsReply
The server's answer.
HttpsRequest
An HTTP request, as far as this binding needs one.
HttpsServer
A Trust Tasks server for the HTTPS binding (bindings/https/0.2).
HttpsTransport
The TransportHandler for one HTTPS exchange.
RequestContext
What a handler is told about the exchange.
StaticBearerAuth
A BearerAuthenticator backed by a fixed token → VID map. For demos and tests; §3 says a production deployment SHOULD bind tokens to identifiers under a controlled trust framework instead.

Enums

ResponseBinding
Which binding of a response to its request did not hold.

Constants

attributionRequiredWireMessage → const String
Wire message for the attribution gate. See HttpsServer.requireAttribution.
bindingUri → const String
The binding's stable identifier (bindings/https/0.2 §1). It never appears on the wire; HTTPS has no envelope to carry it.
defaultAllowedDidMethods → const Set<String>
The DID methods a server with a HttpsServer.proofVerifier accepts in proof.verificationMethod when neither allowedDidMethods nor allowAnyDidMethod: true is passed: did:key, whose key is in the identifier, so verifying it never leaves the process.
defaultClientTimeout → const Duration
Default budget for one exchange, connection included.
defaultMaxResponseBytes → const int
Default cap on a response body: 256 KiB, the request cap the servers apply. A trust-task response is one small JSON document.
defaultRequestTimeout → const Duration
Default wall-clock budget for one request, body read included. A request still open after this is wedged, and holding it is what a slowloris wants.
documentTooLargeWireMessage → const String
Wire message for a document larger than its specification's declared maxDocumentBytes (or HttpsServer.defaultMaxDocumentBytes where it declares none). Names no number: the bound is in the registry for anyone who wants it, and the configured default is deployment detail.
internalErrorWireMessage → const String
Wire message for a handler that threw something other than a Refusal.
malformedBodyWireMessage → const String
Wire message for a body that is not a Trust Task document at all, and for the suppressed identityMismatch answer (§8.1) — the same words for both, so the two cannot be told apart (SPEC §12.4).
maxBodyBytes → const int
The default per-document bound (SPEC §12.4), in bytes: what a document of a specification that declares no maxDocumentBytes may be, and the floor of HttpsServer.bodyLimitBytes. The body is parsed before the sender is authenticated, so an unbounded read would be a pre-authentication memory exhaustion vector. Override it with HttpsServer(defaultMaxDocumentBytes:).
trustTasksPath → const String
The request path, relative to the Trust-Task base (§2, §6.1).

Functions

handleIoRequest(HttpsServer server, HttpRequest request, {Duration requestTimeout = defaultRequestTimeout}) → Future<void>
Answer one dart:io request with server — for an application that owns its own HttpServer and routes only some paths here.
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.
routingKey(String typeUri) → String
The routing key for a Type URI: #request and no fragment route alike, #response keeps its fragment so a response document never reaches a request handler (§4.4.1 item 1).
serve(HttpsServer server, {Object address = '127.0.0.1', int port = 0, SecurityContext? securityContext, Duration requestTimeout = defaultRequestTimeout}) → Future<HttpServer>
Bind address:port and answer every request with server.
statusForCode(String code) → int
Map a framework error code to its HTTP status, per the binding's §4 table.

Exceptions / Errors

DuplicateAbsorbedException
The consumer had already accepted this document (§5.1) and returned no result: 202 while the first execution runs, 204 once it has finished with nothing retained. Not a failure — the task did not fail, it already happened, or is happening.
HttpsClientException
Why HttpsClient.send did not return a response document.
HttpStatusException
A non-2xx answer with no trust-task-error body: a proxy, a 401, a bare 500, or a redirect (which the client does not follow). §4.1: this establishes nothing about the document's state. Retry by re-sending the same bytes (SPEC §8.4).
ResponseDecodeException
A 2xx body that is not the document this client can accept.
ResponseMismatchException
A response that does not belong to the request that was sent.
ResponseProofException
A HttpsClient.responseVerifier is configured and the response's proof is missing (missing) or does not verify.
ResponseTooLargeException
The response body was larger than HttpsClient.maxResponseBytes. Reading stopped there; nothing was decoded.
TransportException
The exchange never produced an answer: a connection or TLS failure, the HttpsClient.timeout, or any other error raised by the HTTP client. Like HttpStatusException, not a statement about the document (§4.1).
TrustTaskErrorException
The server refused with a trust-task-error document. error carries the framework code, which is authoritative; httpStatus is informative (§4).
UnverifiedErrorResponseException
A non-2xx response carried a trust-task-error document that this client, configured with a HttpsClient.responseVerifier, could not attest: it had no proof, its proof did not verify, or its issuer / recipient is not the configured server / this client.