feat(net): add DNS, UDP, TCP listener and TLS endpoints

This commit is contained in:
Marqdo Agent committed 2026-11-21 10:43:08 +08:00
1 parent ee0c6cc80a
commit ff3f19a2ea
20 files changed
+1327 -61

No files matched your search

+46
View File
@@ -0,0 +1,46 @@
# ADR-0047: DNS resolution, UDP and TCP listener endpoints
Status: **Accepted**
Date: 2026-11-21
Relates to: ADR-0034, ADR-0041
Specs: `spec/security.md`, `spec/evaluation.md`
Evidence: `docs/evidence/2026-11-21-net-endpoints.md`
## Context
ADR-0034 opened only an outbound IP-literal TCP stream. That left DNS names,
datagrams and inbound listeners unavailable, and the `--allow-net` grant was
documented as IP-only. The audit RFC's P2 network gap requires real endpoints,
not a `TODO`.
## Decision
* `resource.open("tcp", "host:port", ["read","write"])` now accepts a DNS name
or IP literal. The **host** (not the resolved IP) is checked against the
exact `--allow-net HOST` grant **before** `ToSocketAddrs`; every resolved
address is tried with a 5 s connect timeout.
* Add `resource.open("udp", "host:port", ["read","write"])`: a connected
`UdpSocket` from an ephemeral local port. `resource.read` returns one
datagram (truncated to the destination `Memory` bound, `eof=false`);
`resource.write` sends one datagram.
* Add `resource.open("tcp-listener", "host:port", ["accept"])` plus the
`resource.accept(listener)` builtin. `accept` polls a non-blocking listener
for up to 5 s, returns a new TCP `Resource` in `{ok:true, value:Resource}`,
or `{ok:false, code:"tcp.timeout"}`/`tcp.accept` on failure.
* All three are project-mode only. `pure`/`strict` return `permission.denied`;
the listener still requires the exact host grant.
* Host names are accepted but **not** pinned to an IP: a DNS answer may change
between grant and connect. No TLS, certificate validation, server sockets
outside project mode or UDP broadcast/multicast is added.
* The grant flag remains `--allow-net HOST` (repeatable); its help text now says
host name or IP literal.
## Consequences
* DNS, UDP and inbound TCP are reachable from `.mq.md` without a new builtin
per transport. `resource.accept` is the only new builtin and returns an
opaque handle like `resource.open`.
* TLS still needs a separate decision (certificate validation and trust
anchors); this ADR does not claim TLS.
* `resource.read` on UDP is datagram-based; a zero-length datagram is a
successful empty read, and there is no stream EOF.
+39
View File
@@ -0,0 +1,39 @@
# ADR-0048: TLS client resource endpoint
Status: **Accepted**
Date: 2026-11-21
Relates to: ADR-0034, ADR-0047
Specs: `spec/security.md`, `spec/evaluation.md`
Evidence: `docs/evidence/2026-11-21-tls-endpoint.md`
## Context
ADR-0047 added DNS, UDP and TCP listeners but deliberately left TLS out: a TLS
client needs a trust-anchor policy and certificate validation, not just a
socket. The audit RFC lists TLS as a P2 provider gap.
## Decision
* `resource.open("tls", "host:port", ["read","write"])` connects with TCP,
validates the server certificate with `rustls`, and returns an opaque
`tls` Resource. `resource.read`/`write`/`close` work like TCP.
* The exact host grant (`--allow-net HOST`) is checked before DNS resolution.
`pure`/`strict` refuse; only project mode is supported.
* Trust roots are the platform native roots plus any DER certificates added by
an embedder through `StdHost::with_tls_ca`. There is no CLI flag for a private
CA in this build; the API is for embedders/tests.
* Server-name verification uses the descriptor host, not the resolved IP.
Certificate or handshake failures are fatal `host.error`; a failed handshake
closes the connection and does not return a Resource.
* TLS is client-only. No server TLS acceptor, mutual TLS, ALPN, session
resumption, OCSP or custom root CLI is added.
* `rustls` is used instead of `native-tls` so the build does not require
system OpenSSL headers; it remains a normal Rust dependency.
## Consequences
* `resource.open("tls")` is a real validated TLS client endpoint and is covered
by a local self-signed test that adds an explicit DER root.
* A future CLI `--tls-ca` or provider-managed trust store needs a separate
grant/ADR; this decision does not silently trust unknown certificates.
* TLS server sockets and mutual TLS remain open.