net.quic: 13b - Retry packet construction, tokens, anti-amplification

Completes Phase 13b (Retry + address validation, RFC 9000 SS8/SS8.1/SS17.2.5):

- encode_retry_packet (retry.v): builds a complete Retry packet, reusing
  compute_retry_integrity_tag directly (already side-agnostic -- no new
  crypto needed for the tag itself). Round-trips through the already-
  existing, independently-written client-role verify_retry_integrity_tag/
  parse_retry_packet -- proving the exact code that will receive this in
  production actually accepts it, not just that it looks well-formed.

- generate_retry_token/validate_retry_token/validate_retry_token_for_attempt
  (retry_token.v, new): AEAD-sealed (AES-128-GCM) address-validation tokens.
  AEAD authentication alone satisfies RFC 9000 SS8.1.4's "difficult to
  guess" and integrity requirements -- no separate random component needed
  beyond the nonce GCM itself requires. validate_retry_token_for_attempt
  adds the two context-dependent checks SS8.1.4 calls for: bound client
  address must match, and a short expiry window. NEW_TOKEN-frame issuance
  (SS8.1.3, tokens reusable across future connections) is out of scope --
  v1 only issues tokens via Retry. Full single-use replay tracking beyond
  the expiry window is deferred to 13d (needs a real listening socket to
  own a consumed-token cache's lifetime); the short window satisfies
  SS8.1.4's "prevented OR limited" replay requirement in the interim.

- AntiAmplificationLimiter (anti_amplification.v, new): RFC 9000 SS8.1's 3x
  pre-validation send limit, deliberately mirroring flow_control.v's
  FlowControlWindow shape. Standalone and tested; not yet wired into any
  datagram-processing loop, since that loop doesn't exist until 13d.

Found and flagged (not fixed here, out of scope): while choosing a CSPRNG
for the token nonce, discovered conn.v's dial() uses V's general-purpose
`rand` module (wyrand-backed, not cryptographically secure) for
original_dcid/scid/client_random -- all security-relevant values that
should use crypto.rand instead (identical API, OS-backed, already used
elsewhere in this codebase). Real gap in already-merged Phase 9 code
(PR #28129), flagged as a separate follow-up task.

Full net.quic suite 57/57, ./vnew missdoc clean, ./vnew fmt -w applied.

Author: Richard Wheeler

vlib/net/quic/PROGRESS.md

@@ -1288,10 +1288,39 @@ stacked-PR convention as Phase 12's 12a-12d.
         verification is NOT exercised end-to-end (no EC certificate
         fixture in this repo — the same documented gap as
         `encode_certificate_verify`'s own tests).
-- [ ] **13b** — Retry + address validation: Retry packet + opaque token
-      minting/validation (`retry.v` currently only verifies), RFC 9000 §8.1
-      anti-amplification 3x accounting (already flagged as a deferred,
-      server-only branch in `loss_detection.v`/`coalesce.v`).
+- [x] **13b** — Retry + address validation:
+  - [x] `encode_retry_packet` (`retry.v`) — builds a complete Retry packet,
+        reusing `compute_retry_integrity_tag` directly (already
+        side-agnostic). Round-trips through the already-existing,
+        independently-written client-role `verify_retry_integrity_tag`/
+        `parse_retry_packet` — the strongest cross-check available: not
+        just "well-formed," but "the exact code that will receive this in
+        production accepts it."
+  - [x] `generate_retry_token`/`validate_retry_token`/
+        `validate_retry_token_for_attempt` (`retry_token.v`, new file) —
+        AEAD-sealed (AES-128-GCM), authenticated address-validation tokens
+        satisfying RFC 9000 §8.1.4's difficult-to-guess and integrity
+        requirements via the AEAD tag itself. NEW_TOKEN-frame issuance
+        (§8.1.3, tokens reusable across future connections) is explicitly
+        out of scope — v1 only issues tokens via Retry. Single-use replay
+        tracking beyond a short expiry window is deferred to 13d, once a
+        real listening socket exists to own a consumed-token cache's
+        lifetime; a short `max_age_ms` window satisfies §8.1.4's "prevented
+        OR limited" replay requirement in the interim.
+  - [x] `AntiAmplificationLimiter` (`anti_amplification.v`, new file) —
+        RFC 9000 §8.1's 3x pre-validation send limit, mirroring
+        `flow_control.v`'s `FlowControlWindow` shape deliberately. A
+        standalone, tested accounting primitive — not yet wired into any
+        connection/datagram-processing loop, since that loop doesn't exist
+        until 13d.
+  - **Found and flagged, not fixed here (out of scope for this PR)**: while
+    picking a CSPRNG for the token nonce, discovered `conn.v`'s `dial()`
+    uses V's general-purpose `rand` module (wyrand-backed, NOT
+    cryptographically secure) for `original_dcid`/`scid`/`client_random` —
+    all three are security-relevant values that should use `crypto.rand`
+    instead (same API, OS-backed, already used elsewhere in this codebase).
+    This is a real gap in already-merged code (Phase 9, PR #28129), not
+    Phase 13 work — flagged as a separate follow-up task, not fixed inline.
 - [ ] **13c** — Connection ID lifecycle: `NEW_CONNECTION_ID`/
       `RETIRE_CONNECTION_ID` frames (currently fall through `frame.v`'s
       generic "not yet implemented" branch), stateless reset token

vlib/net/quic/anti_amplification.v

@@ -0,0 +1,81 @@
+module quic
+
+// AntiAmplificationLimiter enforces RFC 9000 §8's server-side send limit
+// before a client's address is validated: "after receiving packets from an
+// address that is not yet validated, an endpoint MUST limit the amount of
+// data it sends to the unvalidated address to three times the amount of
+// data received from that address." Deliberately dumb: this type only
+// counts bytes and answers "how many more may I send right now" -- it has
+// no opinion on WHEN address validation actually completes (RFC 9000 §8.1
+// lists three independent ways: a Handshake-protected packet was received
+// from the peer, the peer used a server-chosen connection ID with at least
+// 64 bits of entropy, or a Retry/NEW_TOKEN token validated -- deciding
+// which applies, and calling mark_validated() at that moment, is a future
+// caller's job (13d's connection-acceptance path), not this primitive's).
+//
+// Mirrors flow_control.v's FlowControlWindow/ReceiveWindow shape
+// deliberately -- same "dumb accounting primitive, caller decides policy"
+// role, just for a different RFC-mandated limit.
+pub struct AntiAmplificationLimiter {
+mut:
+	received  u64
+	sent      u64
+	validated bool
+}
+
+// note_received records `n` more bytes as received from this (still
+// possibly unvalidated) address. RFC 9000 §8.1: "servers MUST count all of
+// the payload bytes received in datagrams that are uniquely attributed to a
+// single connection. This includes datagrams that contain packets that are
+// successfully processed and datagrams that contain packets that are all
+// discarded" -- the caller must count full UDP datagram payload bytes for
+// every datagram attributed to this connection attempt, including ones
+// this endpoint ultimately drops, not just the bytes of packets it
+// successfully processes; this type has no visibility into that
+// distinction and trusts the caller's count entirely.
+pub fn (mut l AntiAmplificationLimiter) note_received(n u64) {
+	l.received += n
+}
+
+// mark_validated permanently lifts the send limit -- RFC 9000 §8.1 imposes
+// it only "prior to validating the client address"; once validated, this
+// endpoint is constrained solely by its congestion controller, a
+// completely separate mechanism (loss_detection.v/congestion_control.v)
+// this type has no relationship to. There is no corresponding "un-validate"
+// -- address validation, once achieved, does not lapse.
+pub fn (mut l AntiAmplificationLimiter) mark_validated() {
+	l.validated = true
+}
+
+// is_validated reports whether mark_validated has been called.
+pub fn (l &AntiAmplificationLimiter) is_validated() bool {
+	return l.validated
+}
+
+// available_to_send reports how many more bytes this endpoint may send
+// right now without exceeding RFC 9000 §8.1's 3x limit -- max_u64 once
+// validated, meaning this limit no longer applies at all, not merely that
+// it has become large.
+pub fn (l &AntiAmplificationLimiter) available_to_send() u64 {
+	if l.validated {
+		return max_u64
+	}
+	limit := l.received * 3
+	if l.sent >= limit {
+		return 0
+	}
+	return limit - l.sent
+}
+
+// note_sent records `n` more bytes as sent to this address, failing if that
+// would exceed the current limit -- callers must check available_to_send()
+// (or catch this error) BEFORE actually sending, never discover the
+// violation only after the fact, the same convention
+// FlowControlWindow.consume() already establishes for the analogous
+// send-side check elsewhere in this module.
+pub fn (mut l AntiAmplificationLimiter) note_sent(n u64) ! {
+	if !l.validated && l.sent + n > l.received * 3 {
+		return error('quic: anti-amplification limit exceeded: attempted to send ${n} bytes, only ${l.available_to_send()} available (received ${l.received}, already sent ${l.sent})')
+	}
+	l.sent += n
+}

vlib/net/quic/anti_amplification_test.v

@@ -0,0 +1,65 @@
+module quic
+
+fn test_anti_amplification_starts_at_zero() {
+	lim := AntiAmplificationLimiter{}
+	assert lim.available_to_send() == 0
+	assert lim.is_validated() == false
+}
+
+fn test_anti_amplification_allows_up_to_3x_received() {
+	mut lim := AntiAmplificationLimiter{}
+	lim.note_received(100)
+	assert lim.available_to_send() == 300
+	lim.note_sent(300)!
+	assert lim.available_to_send() == 0
+}
+
+fn test_anti_amplification_rejects_over_limit_send() {
+	mut lim := AntiAmplificationLimiter{}
+	lim.note_received(100)
+	lim.note_sent(301) or {
+		assert err.msg().contains('anti-amplification limit exceeded')
+		return
+	}
+	assert false, 'expected sending 301 bytes on a 300-byte budget to fail'
+}
+
+fn test_anti_amplification_accumulates_across_multiple_receives() {
+	mut lim := AntiAmplificationLimiter{}
+	lim.note_received(50)
+	lim.note_received(50)
+	assert lim.available_to_send() == 300
+}
+
+fn test_anti_amplification_tracks_remaining_budget_across_sends() {
+	mut lim := AntiAmplificationLimiter{}
+	lim.note_received(100)
+	lim.note_sent(120)!
+	assert lim.available_to_send() == 180
+	lim.note_sent(180)!
+	assert lim.available_to_send() == 0
+}
+
+fn test_anti_amplification_mark_validated_lifts_the_limit() {
+	mut lim := AntiAmplificationLimiter{}
+	lim.note_received(10)
+	lim.note_sent(30)!
+	assert lim.available_to_send() == 0
+
+	lim.mark_validated()
+	assert lim.is_validated()
+	assert lim.available_to_send() == max_u64
+	// A send far exceeding any pre-validation budget must now succeed.
+	lim.note_sent(1_000_000_000)!
+}
+
+fn test_anti_amplification_receiving_more_raises_the_budget_even_after_a_send() {
+	mut lim := AntiAmplificationLimiter{}
+	lim.note_received(100)
+	lim.note_sent(300)!
+	assert lim.available_to_send() == 0
+
+	lim.note_received(50)
+	// New limit is 3*150=450, already sent 300 -> 150 more available.
+	assert lim.available_to_send() == 150
+}

vlib/net/quic/retry.v

@@ -107,6 +107,84 @@ pub fn parse_retry_packet(buf []u8, original_dcid []u8, original_scid []u8) !Qui
 	}
 }
 
+// RetryPacketParams is everything encode_retry_packet needs.
+pub struct RetryPacketParams {
+pub:
+	// The Source Connection ID from the client's Initial packet that
+	// provoked this Retry -- becomes this Retry packet's OWN Destination
+	// Connection ID (an echo, not a new value; see parse_retry_packet's
+	// doc comment for the same field semantics on the parse side).
+	client_scid []u8
+	// This server's newly chosen connection ID for the retried connection
+	// attempt -- becomes this Retry packet's Source Connection ID. RFC
+	// 9000 §17.2.5.1: "This value MUST NOT be equal to the Destination
+	// Connection ID field of the packet sent by the client" -- checked
+	// below (against `original_dcid`, not `client_scid`; a Retry echoing
+	// the client's SCID back as its own new DCID is normal, expected
+	// behavior, not the degenerate case this MUST forbids).
+	server_scid []u8
+	// The Destination Connection ID from the client's Initial packet --
+	// required for BOTH compute_retry_integrity_tag's own AAD (RFC 9001
+	// §5.8) and as the address-validation token's own claim (see
+	// generate_retry_token, retry_token.v).
+	original_dcid []u8
+	// The AEAD key this server uses for its own address-validation
+	// tokens -- see retry_token.v's own key-length/rotation doc comments.
+	token_key []u8
+	// A caller-serialized identifier for the client's current source
+	// address (IP + port), bound into the token so a later Initial
+	// presenting it can be checked against the ADDRESS IT ARRIVES FROM --
+	// opaque to this function and retry_token.v alike; the caller decides
+	// the exact byte representation as long as it's used consistently
+	// between issuance and validation.
+	client_addr []u8
+	// A caller-supplied monotonic timestamp (matching this module's
+	// existing time.sys_mono_now()-sourced convention, e.g.
+	// idle_timeout.v's `now u64` parameters) recording when this token was
+	// issued, for the short-expiry check RFC 9000 §8.1.4 recommends
+	// ("SHOULD ensure that tokens sent in Retry packets are only accepted
+	// for a short time").
+	issued_at_ms u64
+}
+
+// encode_retry_packet constructs a complete Retry packet (RFC 9000
+// §17.2.5), including a fresh address-validation token (generate_retry_token,
+// retry_token.v) and the Retry Integrity Tag (compute_retry_integrity_tag,
+// this file -- already side-agnostic, reused directly rather than
+// duplicated). The header's Unused 4 bits (RFC 9000 §17.2.5, Figure 18) are
+// set to zero: "The value in the Unused field is set to an arbitrary value
+// by the server; a client MUST ignore these bits" -- zero is as arbitrary
+// as any other value and keeps the packet deterministic for testing.
+pub fn encode_retry_packet(p RetryPacketParams) ![]u8 {
+	// RFC 9000 §17.2.5.1: "This value MUST NOT be equal to the Destination
+	// Connection ID field of the packet sent by the client" -- a Retry
+	// violating this would be silently discarded by any compliant client
+	// (parse_retry_packet's own anti-loop check, this file), so refusing
+	// to construct one here catches a caller's CID-generation bug before
+	// it produces a packet that could never actually complete a handshake.
+	if p.server_scid == p.original_dcid {
+		return error("quic: Retry server_scid must not equal the client's original Initial dcid (RFC 9000 §17.2.5.1)")
+	}
+
+	token := generate_retry_token(p.token_key, RetryTokenClaims{
+		client_addr:   p.client_addr
+		original_dcid: p.original_dcid
+		issued_at_ms:  p.issued_at_ms
+	})!
+
+	header := QuicLongHeader{
+		typ:     .retry
+		version: quic_v1
+		dcid:    p.client_scid
+		scid:    p.server_scid
+	}
+	mut packet := encode_long_header(header, 0, 0)!
+	packet << token
+	tag := compute_retry_integrity_tag(p.original_dcid, packet)!
+	packet << tag
+	return packet
+}
+
 // compute_retry_integrity_tag computes the expected 16-byte Retry
 // Integrity Tag (RFC 9001 §5.8) given the ORIGINAL destination connection
 // ID the client used in the Initial packet that provoked this Retry

vlib/net/quic/retry_test.v

@@ -193,3 +193,58 @@ fn test_verify_retry_integrity_tag_discards_when_already_processed_other_packet(
 	ok := verify_retry_integrity_tag(original_dcid, packet, true)!
 	assert ok == false
 }
+
+// encode_retry_packet (Phase 13b, server-role construction). Round-tripped
+// through this same file's own verify_retry_integrity_tag/
+// parse_retry_packet -- the client-role functions, written and tested in an
+// earlier phase, completely independently of this server-role code. This
+// is the strongest possible cross-check available in this module: it isn't
+// merely "does this look like a well-formed packet," it's "does the exact
+// client code that will actually receive this in production accept it."
+
+fn test_encode_retry_packet_round_trips_through_client_verification() {
+	client_scid := [u8(0x55), 0x66, 0x77, 0x88]
+	original_dcid := [u8(0xaa), 0xbb, 0xcc, 0xdd]
+	server_scid := [u8(9), 10, 11, 12]
+	key := []u8{len: retry_token_key_len, init: 0x42}
+	client_addr := [u8(192), 168, 1, 1, 0x1f, 0x90]
+
+	packet := encode_retry_packet(
+		client_scid:   client_scid
+		server_scid:   server_scid
+		original_dcid: original_dcid
+		token_key:     key
+		client_addr:   client_addr
+		issued_at_ms:  500
+	)!
+
+	ok := verify_retry_integrity_tag(original_dcid, packet, false)!
+	assert ok
+	parsed := parse_retry_packet(packet, original_dcid, client_scid)!
+	assert parsed.dcid == client_scid
+	assert parsed.scid == server_scid
+	assert parsed.retry_token.len > 0
+
+	// The retried Initial's token is exactly parsed.retry_token -- validate
+	// it the way the server's own future connection-acceptance path would.
+	claims := validate_retry_token_for_attempt(key, parsed.retry_token, client_addr, 500, 30000)!
+	assert claims.original_dcid == original_dcid
+	assert claims.client_addr == client_addr
+	assert claims.issued_at_ms == 500
+}
+
+fn test_encode_retry_packet_rejects_server_scid_equal_to_original_dcid() {
+	original_dcid := [u8(0xaa), 0xbb, 0xcc, 0xdd]
+	encode_retry_packet(
+		client_scid:   [u8(1), 2, 3, 4]
+		server_scid:   original_dcid // degenerate: RFC 9000 §17.2.5.1 forbids this
+		original_dcid: original_dcid
+		token_key:     []u8{len: retry_token_key_len}
+		client_addr:   [u8(1)]
+		issued_at_ms:  0
+	) or {
+		assert err.msg().contains('must not equal')
+		return
+	}
+	assert false, 'expected an error when server_scid equals original_dcid'
+}