@push.rocks/smartnftables 2.5.2 → 3.0.0

package/readme.md

@@ -264,9 +264,9 @@ allocation-pool guard policy kinds.
 
 | V2 scope | Required authority and behavior |
 | --- | --- |
-| `routerEgress` | Private `endpoints` and `rules`, one exact `links` binding per endpoint, a separate veth `handoff`, `protection`, and active `generations`. Private veth/TUN/local DNS and egress share one table so terminal private denial cannot override a separate egress table. Optional `publishedPorts` add the inbound second hop from the handoff to a workload endpoint; both directions are classified into the default conntrack zone ahead of every leased classifier, so a published endpoint port is dedicated to its publication and never becomes leased egress. Optional `hostGrants` forward exact host-origin flows from the handoff to a workload endpoint. |
-| `hostTransit` | Exact handoff `link`/`allocations` pairs, complete `protection`, an explicit veth or Ethernet `uplink`, and its current `snatAddress`. It checks each handoff's leased source address and protocol/port range, default conntrack zone, direction, uplink, and protected destinations before outer SNAT. Optional `publishedPorts` add inbound uplink destination NAT inside the same generation. Optional `hostGrants` let the host's own address on a handoff dial exact workload ports. |
-| `allocationPoolGuard` | An authenticated `authorityDigest` and complete current allocation-pool `prefixes`. Installs host-wide IPv4 destination denial before any handoff exists, without link, uplink or SNAT dependencies. Optional `hostGrants` are its only exceptions. |
+| `routerEgress` | Private `endpoints` and `rules`, one exact `links` binding per endpoint, a separate veth `handoff`, `protection`, and active `generations`. Private veth/TUN/local DNS and egress share one table so terminal private denial cannot override a separate egress table. Optional `publishedPorts` add the inbound second hop from the handoff to a workload endpoint, one port or a port range; both directions are classified into the default conntrack zone ahead of every leased classifier, so a published endpoint port is dedicated to its publication and never becomes leased egress. A `symmetric` publication also lets the workload open flows from its published ports. Optional `hostGrants` forward exact host-origin flows from the handoff to a workload endpoint. Optional `workloadGrants` let one workload open one exact port of another, one way. |
+| `hostTransit` | Exact handoff `link`/`allocations` pairs, complete `protection`, an explicit veth or Ethernet `uplink`, and its current `snatAddress`. It checks each handoff's leased source address and protocol/port range, default conntrack zone, direction, uplink, and protected destinations before outer SNAT. Optional `publishedPorts` add inbound uplink destination NAT inside the same generation, one port or a port range, and a `symmetric` publication also carries the workload's own flows from its published ports out through the uplink. Optional `hostGrants` let the host's own address on a handoff dial exact workload ports. Optional `localPlatformEndpoints` serve platform endpoints on the host's own addresses to leased flows. |
+| `allocationPoolGuard` | An authenticated `authorityDigest` and complete current allocation-pool `prefixes`. Installs host-wide IPv4 destination denial before any handoff exists, without link, uplink or SNAT dependencies. Optional `hostGrants` are its only exceptions. Optional `localTcpPortOwners` restrict loopback TCP ports to one local user each. |
 
 `allocationPoolGuard` accepts 1–64 canonical, disjoint RFC1918 prefixes. Supply
 the actual allocation pools, not the broader protected union containing management
@@ -317,7 +317,8 @@ handoffs, unmatched handoff traffic and IPv6 forwarding are denied.
 
 `hostTransit.publishedPorts` is optional. Absent and empty are the same canonical
 policy, so an unpublished scope keeps its exact previous digest and compiled bytes.
-Each entry is `{ protocol, hostPort, targetPort, targetAddress, hostIp }`. `hostIp`
+Each entry is `{ protocol, hostPort, targetPort, targetAddress, hostIp }`, with an
+optional `hostPortEnd` and an optional `symmetric`. `hostIp`
 must be an exact current uplink address, which rtnetlink verifies at apply, recovery
 and inspection; there is no wildcard, secondary-link or default-route inference.
 `targetAddress` must be a current leased `transitSourceAddress` of one allocation,
@@ -328,21 +329,59 @@ including across uplink addresses, and a port published on the `snatAddress` may
 fall inside any leased outbound source-port range of the same protocol, because outer
 SNAT translates to that same address.
 
-A publication compiles inside the generation: one destination NAT rule in this
-table's own prerouting `nat` chain at priority -100, plus three forward admissions
-placed ahead of the capture barrier — original direction NEW and ESTABLISHED, with
-opening TCP restricted to SYN with FIN/RST/ACK clear, and the ESTABLISHED reply.
-Every admission checks both links, the conntrack protocol, the default zone, the
-direction, the translated current address/port and the original conntrack
-destination, so foreign NAT cannot borrow the exception for another flow. Published
-traffic is not source-translated, so the workload observes the actual client address.
-The chain, its translation and its admissions are created, replaced and deleted with
-the generation: a target without the entry, a failed batch, or release removes them,
-and a caller never needs a separate teardown.
-
-Input bounds are 64 entries, but the atomic graph reserve binds first. A publication
-costs four operations and about 6,000 bytes, so roughly a dozen fit beside a small
-host-transit graph and `prepare()` rejects an excessive set before any kernel work.
+`hostPortEnd` publishes the range `hostPort..hostPortEnd`. It must be greater than
+`hostPort`, and `targetPort` must equal `hostPort`: a range keeps every port, so port
+`p` of the uplink reaches port `p` of `targetAddress`. One port has exactly one
+canonical form, without `hostPortEnd`. Ranges follow the same rules as single ports:
+no two publications of one protocol overlap anywhere in the scope, and no published
+port on the `snatAddress` falls inside a leased range. A range translates the
+address only, which never changes a port.
+
+Publications are set elements, not rules. The generation compiles CONSTANT named
+sets and maps of concatenated fields in which the port fields are inclusive
+intervals (the kernel's pipapo backend), so one element holds one port or a whole
+range: `published_port` maps a one-port publication's uplink address, protocols and
+port to its target address and port, `published_address` maps a range to its target
+address alone, and `published_forward` holds every publication's inbound tuple. A
+constant number of rules looks them up whatever the number of publications: one
+destination NAT rule per map in this table's own prerouting `nat` chain at priority
+-100, and four forward admissions ahead of the capture barrier — the ESTABLISHED
+original direction, a NEW opening per protocol with opening TCP restricted to SYN
+with FIN/RST/ACK clear, and the ESTABLISHED reply. Every rule checks the uplink, the
+default zone and the direction, and every key carries the exact handoff (index and
+name), the packet and conntrack protocols, the translated current address and port
+and the original conntrack destination, so foreign NAT cannot borrow the exception
+for another flow. Published traffic is not source-translated, so the workload
+observes the actual client address. The chain, its sets, its translations and its
+admissions are created, replaced and deleted with the generation: a target without
+the entry, a failed batch, or release removes them, and a caller never needs a
+separate teardown. Owner verification reads every set back with its description,
+every element with its interval bounds and map data, and every lookup with its
+registers, so apply, inspection, adoption and recovery reject a changed element
+exactly as they reject a changed rule.
+
+Without `symmetric`, a publication carries inbound flows only: a flow the workload
+opens from its target address and port toward the uplink is denied. With `symmetric:
+true`, a flow from exactly `targetAddress` and the published target port(s) on the
+exact handoff may leave through the uplink, NEW (a TCP opening only with SYN) or
+ESTABLISHED, with its ESTABLISHED replies, and outer source NAT translates it to
+`hostIp` and the published uplink port. These flows are elements of one more map,
+`published_symmetric`, keyed on the handoff, protocols and the live and original
+source and holding the uplink address and port span; four admissions look it up as a
+set and one postrouting rule translates through it. The workload's outbound flows therefore leave
+from the same address and port its clients reach, as Docker host-mode NAT kept them;
+a range keeps each port unless the host itself already holds that exact tuple on
+`hostIp`. The admissions follow the capture barrier, so every protected current or
+original destination, the platform endpoints included, stays denied. A symmetric
+target port may not fall inside a leased range of `targetAddress`, and may not overlap
+the target ports of another publication of the same address and protocol. Absent and
+`false` are the same canonical policy, digest and compiled graph.
+
+Input bounds are 1024 entries. The rule graph does not grow with them: with every
+kind of publication present the host compiles at most eleven rules and four sets,
+about 13,400 bytes of the 100,000-byte rule reserve, and each publication costs
+about 150 to 300 bytes of set elements, which share the target budget described
+under host grants. 64 symmetric ranges take about 19,600 element bytes.
 The caller still owns the route to `targetAddress` through that handoff, the
 workload listener, and every other packet owner on the host. As with leased egress,
 an ACCEPT here cannot override Docker's independent FORWARD DROP; the
@@ -366,7 +405,8 @@ There is no broad ESTABLISHED/RELATED bypass.
 `routerEgress.publishedPorts` is optional and is the second hop of a published
 host port. Absent and empty are the same canonical policy, so an unpublished scope
 keeps its exact previous digest and compiled bytes. Each entry is `{ protocol,
-transitPort, endpointPort, endpointAddress, transitSourceAddress }`.
+transitPort, endpointPort, endpointAddress, transitSourceAddress }`, with an
+optional `transitPortEnd` and an optional `symmetric`.
 `transitSourceAddress` must be a current leased generation address that is present
 on `handoff`, which rtnetlink verifies at apply, recovery and inspection; the
 handoff can carry several current leased addresses, so the arrival address is
@@ -379,11 +419,24 @@ published exactly once across the scope, and a published port may not fall insid
 any leased outbound source-port range of the same protocol on that transit address,
 because source NAT translates to that same address.
 
-A publication compiles inside the generation: one destination NAT rule in this
-table's own prerouting `nat` chain at priority -100, two raw classifications, and
-three forward admissions placed ahead of the capture barrier — original direction
-NEW and ESTABLISHED, with opening TCP restricted to SYN with FIN/RST/ACK clear,
-and the ESTABLISHED reply. The handoff ingress classification precedes the
+`transitPortEnd` publishes the range `transitPort..transitPortEnd`, the second hop of
+a host range. It must be greater than `transitPort`, and `endpointPort` must equal
+`transitPort`, so every port keeps its number on both hops; one port has exactly one
+canonical form, without `transitPortEnd`. No two publications of one protocol overlap
+anywhere in the scope, and no published port falls inside a leased range of its
+transit address. The destination NAT of a range translates the address only.
+
+Publications are set elements here too: `published_arrival` (protocol, transit
+address and port), `published_endpoint` (workload link, protocol, address and port,
+the union of every publication's workload ports as disjoint canonical intervals),
+the `published_port` and `published_address` translation maps and
+`published_forward`, with the port fields as inclusive intervals. A constant number
+of rules looks them up whatever the number of publications: one destination NAT
+rule per map in this table's own prerouting `nat` chain at priority -100, two raw
+classifications, and four forward admissions placed ahead of the capture barrier —
+the ESTABLISHED original direction, a NEW opening per protocol with opening TCP
+restricted to SYN with FIN/RST/ACK clear, and the ESTABLISHED reply. The handoff
+ingress classification precedes the
 barrier's protected-source denial, because the uplink or management network that
 reaches a published port is itself protected space. The endpoint ingress
 classification matches the exact workload link, address and published endpoint
@@ -393,24 +446,47 @@ would otherwise carry the workload's published packets into that generation, whe
 the publication's flow does not exist. Both classifications match the arriving
 tuple only, set no generation zone and leave the flow in the default conntrack
 zone. The private anti-spoof guards still run first, and every admission checks
-both links, the conntrack protocol, the default zone, the direction, the
-translated current address/port and the original conntrack destination.
+the handoff, the default zone and the direction, and looks up the exact workload
+link (index and name), both protocols, the translated current address/port and the
+original conntrack destination.
 
-A published `endpointPort` is therefore dedicated to its publication: a new
+A published endpoint port is therefore dedicated to its publication: a new
 outbound flow that the workload opens from that exact address and port on that
-exact link stays in the default zone too and is not translated by the leased
-outbound source NAT. Published traffic is not source-translated on either hop, so
-the workload observes the actual client address. The chain, its translation, its
-classifications and its admissions are created, replaced and deleted with the
-generation: a target without the entry, a failed batch, or release removes them.
-
-Input bounds are 64 entries, but the atomic graph reserve binds first. A router
-publication costs six operations and about 7,600 bytes, so a combined
-two-endpoint router policy leaves room for roughly five, and `prepare()` rejects an
-excessive set before any kernel work. The caller still owns both hops: the exact
-matching `hostTransit` publication, the route to the workload through this router,
-the workload listener and every other packet owner. A publication grants no egress;
-outbound flows still need their leased grants.
+exact link stays in the default zone too and is never translated by the leased
+outbound source NAT. Without `symmetric` such a flow is denied. Inbound published
+traffic is not source-translated on either hop, so the workload observes the actual
+client address. The chain, its sets, its translations, its classifications and its
+admissions are created, replaced and deleted with the generation: a target without
+the entry, a failed batch, or release removes them.
+
+With `symmetric: true` the workload may open flows from exactly `endpointAddress`
+and the published endpoint port(s) on its exact link toward the handoff, NEW (a TCP
+opening only with SYN) or ESTABLISHED, with their ESTABLISHED replies, and source
+NAT translates them to `transitSourceAddress` and the published transit port. With
+the matching symmetric `hostTransit` publication the flow reaches the uplink from
+`hostIp` and the published uplink port, the same address and port its clients
+reach, as Docker host-mode NAT kept it; a range keeps each port unless that exact
+tuple is already taken on the translated address. These flows are elements of the
+`published_symmetric` map, keyed on the workload link, protocols and the live and
+original source and holding the transit address and port span, behind four
+admissions and one postrouting translation. Both directions are already in the
+default zone through the publication's endpoint and handoff classifications, so no
+leased classifier can capture them. The admissions follow the capture barrier, so
+every protected current or original destination, the platform endpoints included,
+stays denied; outbound flows anywhere else still need their leased grants. The
+endpoint ports of a symmetric publication may not overlap the endpoint ports of
+another publication of the same address and protocol, since each flow has exactly
+one published source. Absent and `false` are the same canonical policy, digest and
+compiled graph.
+
+Input bounds are 1024 entries. The rule graph does not grow with them: with every
+kind of publication present the router compiles at most thirteen rules and six sets,
+about 15,100 bytes of the 100,000-byte rule reserve, and each publication costs
+about 250 to 450 bytes of set elements, which share the target budget with the
+router's endpoints, rules and grants. 64 symmetric ranges take about 28,000 element
+bytes. The caller still owns both hops: the exact matching `hostTransit`
+publication, the route to the workload through this router, the workload listener
+and every other packet owner.
 
 #### Host grants
 
@@ -466,7 +542,7 @@ foreign set exactly as they reject a changed rule; a bound CONSTANT set also
 refuses element changes from any other socket.
 
 Absent and empty are the same canonical policy, so a scope without grants keeps its
-exact previous digest and compiled bytes and has no set. Withdrawing a grant is an
+exact previous digest and compiled bytes and has no host grant set. Withdrawing a grant is an
 ordinary atomic replacement: the batch deletes the previous rules, chains and sets
 by handle and creates the complete target, so a target without the entry, a failed
 batch or release removes it, and an established flow stops with it. Apply grants
@@ -474,14 +550,134 @@ hop by hop from the workload side (router, host transit, guard) and withdraw the
 in the reverse order; each table is atomic on its own, and a partially applied
 grant only stays dark.
 
+#### Host-local platform endpoints
+
+A platform endpoint normally lives elsewhere and host transit forwards leased
+flows to it. When the host serves an endpoint itself — a relay listener, a data
+port or a VPN hub on an address the host holds — the leased flow ends in the
+host's INPUT instead, where every handoff arrival is denied. The optional
+`hostTransit.localPlatformEndpoints` lists the ids of `protection.platformEndpoints`
+the host serves:
+
+```typescript
+protection: { authorityDigest, prefixes: ['10.0.0.0/8', '192.0.2.0/24'], platformEndpoints: [
+  { id: 'relay', address: '192.0.2.2', protocol: 'tcp', port: 8443 }] },
+localPlatformEndpoints: ['relay'],
+```
+
+Each id names an existing endpoint whose address is an exact `requiredIpv4Addresses`
+entry of the uplink or of a handoff link, so rtnetlink verifies that the host holds it
+at apply, recovery and inspection. The refusal of a platform endpoint on a host
+address is lifted only for declared ids; unknown, duplicate or unheld ids reject.
+The router scope grants its workloads the endpoint like any platform endpoint
+(`destination: { kind: 'platform', endpointId }`).
+
+INPUT admits the original direction only from the exact handoff that carries a lease,
+with the lease's transit source address and a source port in one of its ranges for
+the endpoint's protocol, in the default conntrack zone, to the exact endpoint address
+and port in both the live and the originally tracked tuple, NEW (a TCP opening only
+with SYN) or ESTABLISHED. OUTPUT admits only the ESTABLISHED reply back through that
+handoff. A flow translated in transit, another source address or port, another
+endpoint port or protocol and any host-origin opening toward the transit address keep
+meeting the handoff denials. The source port is checked against the leased range in
+both tuples, not for equality between them. Each leased range adds one INPUT and one
+OUTPUT jump when an endpoint of its protocol is declared, and each endpoint adds three
+rules. Absent and empty are the same canonical policy, digest and compiled bytes. The
+caller keeps a declared endpoint's address outside every guarded allocation pool and
+owns the listener.
+
+#### Workload grants
+
+`routerEgress.workloadGrants` is optional: a stateful one-way flow between two
+workloads behind the same router, such as an ingress workload reaching a target
+workload's service port across organizations. Each entry is `{ protocol,
+sourceAddress, destinationAddress, destinationPort }`: `tcp` or `udp`, the exact
+current addresses of two different veth workload endpoints of the scope and one port
+1–65535. Prefixes, wildcards, ranges, router-local and platform-endpoint addresses,
+TUN endpoints, both ends on one endpoint and duplicates reject. The source opens and
+the destination only answers; the reverse direction is a second grant.
+
+Four FORWARD admissions follow the private anti-spoof guards whatever the number of
+grants: ESTABLISHED original direction, a NEW UDP opening, a NEW TCP opening
+restricted to SYN with FIN/RST/ACK clear, and the ESTABLISHED reply, each in the
+default conntrack zone. Every admission looks up the incoming link with the source
+address and the outgoing link with the destination address (index and name) in the
+CONSTANT set `workload_link`, and the protocols with the live and originally tracked
+tuple in the CONSTANT set `workload_grant`, so a spoofed, renamed or translated flow
+never matches and the destination can never open toward the source. Endpoint prefixes
+are protected, so both directions stay in the default zone ahead of every leased
+classifier. Owner verification reads both sets back element by element. Up to 1024
+grants fit; the sets share the scope's target budget with `hostGrants` and every
+other set, and 1024 of each fit together beside the reference router; a scope
+beyond the budget is refused before any kernel work. Absent and empty are the same canonical policy, digest and compiled bytes, and
+withdrawal is an ordinary atomic replacement that also stops established flows.
+
+These flows need no private `rules`. A private rule is stateless: answering through
+private rules needs a reverse rule, which would also let the destination open toward
+the source.
+
+#### Loopback TCP port owners
+
+`allocationPoolGuard.localTcpPortOwners` is optional and restricts a loopback TCP
+service to one local user, such as a container runtime's CRI stream server on
+`127.0.0.1:10010` that only root may reach. Each entry is `{ address, port, uid }`:
+one exact IPv4 loopback host address in `127.0.0.0/8` (not the network or broadcast
+address), one port 1–65535 and one uid 0–4294967294. Prefixes, wildcards, IPv6,
+ranges, uid lists and a second entry for the same address and port reject; the
+limit is 8 entries. Absent and empty are the same canonical policy, so a guard
+without owners keeps its exact previous digest and compiled bytes.
+
+```typescript
+const guard: IManagedNftPolicyV2 = { schemaVersion: 2, revision: 1, scope: {
+  kind: 'allocationPoolGuard', authorityDigest, prefixes: ['10.240.0.0/16'],
+  localTcpPortOwners: [{ address: '127.0.0.1', port: 10010, uid: 0 }] } };
+```
+
+Each entry compiles two rules at the head of the guard's base chains, ahead of the
+host grant admissions and the pool guard, so nothing earlier in the table accepts
+past them:
+
+- OUTPUT (filter priority 0, after ordinary output destination NAT): IPv4 TCP to the
+  exact address and port with `meta skuid != uid` is rejected with a TCP reset, so
+  another user's `connect()` fails at once with `ECONNREFUSED`. This covers every
+  packet, not only the opening, and a flow a foreign output DNAT redirects to the
+  port. `meta skuid` is the socket file's file-system uid as the user namespace owning the
+  network namespace sees it, the initial one on a host: a process in a user namespace
+  that shares the host network namespace is matched by its host uid, and a user
+  namespace's root is not uid 0. A packet without a socket
+  file carries no uid and does not match: a kernel reply, the teardown of an orphaned
+  socket, or an in-kernel socket such as an NFS or CIFS client, which only a privileged
+  mount creates.
+- INPUT: the exact address and port arriving on any interface but loopback (ifindex
+  1 in every network namespace) are dropped, so `route_localnet` or a prerouting DNAT
+  cannot expose the service to another host.
+
+The rules match the exact destination address. The service must bind exactly that
+address; a wildcard listener stays reachable through the host's other addresses.
+IPv6 is not covered, so the service must not listen on `::1` or `::`. A socket keeps
+the uid it was created with, so a root process that hands its connected socket to
+another user delegates that connection. The reject expression needs the kernel's
+`nft_reject_inet` module (autoloaded on stock kernels). Owner verification reads
+back every rule, including the comparison operator, the uid and the reject type, so
+apply, inspection, adoption and recovery reject a changed rule. The entries are
+applied, retained, recovered and released with the rest of the guard's table; after
+a reboot the caller applies its retained intent again, like every other member.
+
 Input bounds are 1024 grants per scope, the maximum a network projection carries.
-Elements have their own 100,000-byte budget beside the 100,000-byte rule graph, and
-are sent 256 to a message. At 1024 grants the reference router needs about 94 KB
-of elements (two sets), host transit about 66 KB and the guard about 45 KB. A
-replacement batch — handle-only deletion of a previous maximum graph, a maximum
-rule graph and maximum elements — stays below 320,000 bytes, which the kernel
-accepts with any `net.core.wmem_max` of at least 160,016 (the Linux default is
-212,992). The private facade IPC carries up to three complete policies in one
+Elements are sent 256 to a message. At 1024 grants the reference router needs about
+98 KB of elements (two sets), host transit about 66 KB and the guard about 45 KB.
+
+Every replacement is one nfnetlink batch in one `sendmsg`, and Linux refuses a
+netlink message larger than the socket send buffer: the requested 1 MiB `SO_SNDBUF`
+is clamped to `net.core.wmem_max` and doubled, 425,984 bytes with the Linux default
+of 212,992. That is the hard ceiling. This package bounds a batch at 320,000 bytes,
+which fits every `wmem_max` of at least 160,016, and splits it: at most 64 bytes of
+batch framing, at most 107,520 bytes for the handle-only deletion of the previous
+graph (fewer than 768 rules, chains and sets of at most 140 bytes each), and
+212,000 bytes for the complete target, of which rules, chains and sets may take at
+most 100,000 and set elements the rest. Scopes that grow with their inputs keep
+those inputs in set elements, so the element share grows where the rule share
+shrinks; `prepare()` refuses a target beyond either bound before any kernel work. The private facade IPC carries up to three complete policies in one
 status and is bounded at 1,048,576 bytes per line; the facade captures at most
 1,000,000 JSON bytes and 65,536 values per request or result. The caller owns the host route
 to the workload through the handoff, selecting the transit host address as the
@@ -489,18 +685,56 @@ socket's source, the workload listener and every other packet owner.
 
 Active overlapping classifiers, duplicate zones/labels and conflicting handoff
 allocations reject. Empty router generations retain private routing while denying
-egress. Input bounds include 32 private endpoints, 128 private rules, 32 active
-generations, 128 total egress grants, 128 protected prefixes, 96 platform endpoints,
-16 ranges per allocation, and 32 host handoffs/active allocations. The complete
-compiled graph still must fit 768 operations and 100,000 bytes; cross-products can
-reach that limit before individual input limits. Exhausted source-port ranges
-drop new flows rather than allocate outside the lease.
-
-The router compiler shares original-direction connection-state and label checks
-per generation and protocol. Each jump still checks the complete current/original
-tuple, links, zone and direction; replies and source NAT keep their exact checks.
-A combined two-endpoint policy with six private rules, five protected prefixes and
-six workload/router grants fits the existing atomic graph limit.
+egress. Router input bounds are 128 private endpoints and links, 1024 private
+rules, 32 active generations and 1024 total egress grants; other bounds include 128
+protected prefixes, 96 platform endpoints, 16 ranges per allocation, and 32 host
+handoffs/active allocations. The complete target must fit the budget above; the
+router's rules grow only with its protected prefixes, so its elements bind first.
+Exhausted source-port ranges drop new flows rather than allocate outside the lease.
+
+The router compiles its private endpoints, directed rules and leased grants into
+named sets and maps behind a fixed set of rules, whatever the number of workloads:
+- `private_link` holds every endpoint link (index and name) and the absent
+  interface of router-local traffic; `private_index` and `private_name` hold every
+  endpoint index and name for the terminal denials, either alone enough to deny;
+  `private_source` holds each link index with its source prefixes. The anti-spoof
+  guard drops a packet on an endpoint link whose address is not one of its
+  prefixes, and anything but IPv4 there.
+- `private_any` and `private_port` hold the directed rules: incoming and outgoing
+  link index (0 for the router itself), addresses, and for a transport rule the
+  protocol and ports.
+- Per kind (platform ahead of the protected barrier, public behind it) and per
+  shape (whether the grant names a source port), `leased_*_zone` maps a workload
+  or router flow's link, protocol and tuple to its generation zone before conntrack,
+  `leased_*_return` maps a translated return to its zone, and `leased_*_flow` maps
+  the link, both protocols, the live and originally tracked tuple and the zone to
+  the grant's source NAT; the filter admissions look it up as a set.
+  `leased_label` holds each generation's zone and label, and `leased_generation`
+  maps a zone to the label a fresh flow receives.
+A key's link index names its link because the rule also finds the interface's
+index and name in `private_link`, whose indices are unique. Every element is
+checked, like every rule, on apply, inspection, adoption and recovery. A decision
+corpus of about 133,000 packets across five router fixtures, frozen from the
+per-rule compiler of 2.6.0, is reproduced exactly by the set-backed compiler.
+
+A router of 64 workloads, each with local DNS, public TCP and UDP egress, grants to
+four platform endpoints and one to three publications, compiles about 66,000 rule
+bytes and 105,000 element bytes; 89 such workloads fit the target budget:
+
+| Workloads | Router rules | Router elements | Host rules | Host elements |
+| --- | --- | --- | --- | --- |
+| 1 | 65,820 | 4,968 | 42,944 | 1,128 |
+| 8 | 65,820 | 16,056 | 42,944 | 2,528 |
+| 32 | 65,820 | 54,072 | 42,944 | 7,328 |
+| 64 | 65,820 | 104,760 | 42,944 | 13,728 |
+
+**Upgrading from 2.x:** version 3 changes the compiled identity of every schema-v2
+`routerEgress` table and of every scope with `publishedPorts`, while their policy
+digests stay unchanged. Reconcile or release against such a table applied by 2.x
+returns `Conflict`: the new engine cannot adopt the old graph. Recover and release
+each such table with the exact previous engine and its retained intent and
+receipt, under the same traffic fence as below, before upgrading; tables of other
+scopes and without publications are unchanged.
 
 **Upgrading from 1.x:** version 2 changes the compiled identity of schema-v2
 `routerEgress` tables. Retained router tables and their receipts cannot be adopted
@@ -619,6 +853,27 @@ A client whose source port equals a leased grant's destination port on that gran
 public address completes the published TCP handshake and receives its UDP reply
 from the published address, so the leased classifiers of the same generation cannot
 capture the workload's published packets.
+Published ranges and symmetric publications are qualified across both hops in the
+same topology, with every publication a set element whose kernel dump matches the
+compiled sets and maps: the first, middle and last port of a UDP range reach their listeners
+with the client address preserved and answer from the published address, the ports
+just outside the range stay dark against pre-policy positive controls, symmetric UDP
+from a range port and from the signalling port and symmetric TCP from the signalling
+port reach the uplink peer from the published address with the same port, a later
+request from that peer reaches the workload on the same flow, the plain publication's
+workload port opens nothing, symmetric flows into the protected union stay denied
+against a pre-policy positive control, leased egress keeps its leased range, and the
+range goes dark with release.
+A 64-workload router is qualified in one batch, every workload in its own namespace
+with local DNS, public TCP and UDP egress, four platform endpoints and a
+publication, the first with the SIP shape: the kernel dumps every private, leased
+and published element and the owner verifies it, and on the first, middle and last
+workload local DNS answers, public UDP egress leaves from the leased range, UDP and
+TCP platform endpoints answer through both hops, the publication reaches its
+listener with the client address preserved, and another workload, a protected
+address outside the platform endpoints and an ungranted platform port stay denied
+against pre-policy positive controls, as does another workload's source address.
+The router compiles 82 rules for the 64 workloads.
 Host grants are qualified across all three tables in the same four-namespace
 topology with leased public egress on every port of both protocols and 1024 grants
 in every scope: a member far from the probed tuples passes, the tuple just outside
@@ -632,6 +887,32 @@ withdrawal in every scope stops new flows and the established one. A full guard
 set persists across owner loss, is re-verified element by element before adoption,
 survives lost-ACK replay and is replaced and released like the rest of the graph,
 and another socket cannot add or delete one of its elements.
+Host-local platform endpoints are qualified from a router namespace against
+pre-policy positive controls: without the member the handoff denials keep both a TCP
+endpoint on the uplink address and a UDP endpoint on the handoff address dark; with
+it the exact leased flows reach them with the transit source preserved, while a
+source port outside the lease or in the other protocol's range, an unleased source
+address, another endpoint port, a flow a foreign prerouting DNAT translated onto the
+endpoint and the host's own opening toward the transit address stay dark; withdrawal
+stops new flows and the established one, and release reopens the path. A graph with
+served endpoints persists across owner loss and survives lost-ACK replay.
+Workload grants are qualified between three workload namespaces behind the router,
+each with leased public egress on every port of both protocols: against pre-policy
+positive controls, the grant opens exactly the source workload's TCP and UDP flows to
+the granted ports with the source preserved; another port, another source workload,
+another destination workload, the destination's TCP and UDP openings toward the
+source stay dark; withdrawal stops new flows and the established one; release reopens
+the path. A set of 1024 grants persists across owner loss, is re-verified element by
+element and survives lost-ACK replay.
+Loopback TCP port owners are qualified against pre-policy positive controls on the
+same listeners: the owning uid (root, and uid 1000 for a second port) connects, every
+other uid is reset with `ECONNREFUSED`, an unowned port and another loopback address
+stay open to every user, a foreign output DNAT to the owned port stays closed to
+another user, and an uplink arrival translated to loopback with `route_localnet`
+enabled is dropped. The policy keeps enforcing after the owner detaches and its
+process is gone, a fresh owner verifies and adopts the exact graph, and release
+reopens every probe. The maximum of eight owners beside the guard persists across
+owner loss and survives lost-ACK replay.
 The arm64 binary is cross-built; native packet qualification is currently x86_64.
 Kernel 6.8 is unsupported. No production activation is implied by these tests.