feat(net): add DNS, UDP, TCP listener and TLS endpoints
This commit is contained in:
1 parent
ee0c6cc80a
commit
ff3f19a2ea
20 files changed
+1327
-61
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user