From b15f18834bde04b4308751a58d97d42c52bf0d09 Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Tue, 27 Oct 2026 21:15:29 -0700 Subject: [PATCH 01/11] docs(specs): amend NET for the close-out fixes Adds functional requirements for the walkthrough failures and the security bounds found at the close-out, rewrites the first slice around the macOS name and proxy fixes, keeps exact printed text out of the requirements, and records the host-exposure question for the architecture. --- .../18-spec-box-networking.md | 169 +++++++++++++----- 1 file changed, 127 insertions(+), 42 deletions(-) diff --git a/docs/specs/18-spec-box-networking/18-spec-box-networking.md b/docs/specs/18-spec-box-networking/18-spec-box-networking.md index a0d6e47df3..273429008a 100644 --- a/docs/specs/18-spec-box-networking/18-spec-box-networking.md +++ b/docs/specs/18-spec-box-networking/18-spec-box-networking.md @@ -5,7 +5,7 @@ owner: norrietaylor epic: gominimal/inbox#646 arch: https://github.com/gominimal/arch/blob/5c1201517ba07347344fb9725efb06ee39d5c03e/specs/networking/deployment-and-egress-gateway.md arch_sha: "5c1201517ba07347344fb9725efb06ee39d5c03e" -updated: 2026-10-09 +updated: 2026-10-27 --- # NET — Box networking on the local host: preview by name and bounded egress @@ -31,12 +31,9 @@ The scope is local by decision (local-first ordering, 2026-09-15): the un-enrolled local host is the deployment target first, and the architecture does not change with it, only what is built first. The box host's obligations that exist only once a host is enrolled, holds a gateway association, has -joined a mesh, or serves a remote session are bound in three sibling documents -written from the same epic: -[EHE](https://github.com/gominimal/minimal/pull/1418) for the enrolled host's -egress, [GWI](https://github.com/gominimal/minimal/pull/1419) for gateway -ingress, and [MRF](https://github.com/gominimal/minimal/pull/1420) for the mesh -and the remote forward. The identity plane's side of all of it is +joined a mesh, or serves a remote session belong to three sibling documents, +not yet written: EHE for the enrolled host's egress, GWI for gateway ingress, +and MRF for the mesh and the remote forward. The identity plane's side of all of it is [NPOL](https://github.com/gominimal/gatehouse/blob/main/docs/specs/02-spec-network-policy-plane/02-spec-network-policy-plane.md). After this ships, a developer previews a box's server at `.min.internal` @@ -53,7 +50,7 @@ outside the VM and, un-enrolled, redeems store references from the host's own secret stores and GitHub grants the `min` client minted from its own GitHub sign-in (no Gatehouse-brokered grants; Gatehouse §6.10's un-enrolled bullet, ruled 2026-09-17), is the next thing built and is a separate document, -[BEP](https://github.com/gominimal/minimal/pull/1426), that cites this one. It +[BEP](../24-spec-box-egress-proxy/24-spec-box-egress-proxy.md), that cites this one. It depends on these behaviours bound here: box-zone resolution (NET-072, NET-073) and the opt-in host setup that makes its default `dns` steering buildable (NET-122), `egress.allow_dns_hosts` with DNS-pinned admission (NET-066, @@ -80,9 +77,10 @@ box declared deny-all reaches nothing; and a process that gains root inside the VM and spoofs another box's address reaches nothing outside the union of resident boxes' declared egress. -**First slice:** `.min.internal` and `host.min.internal` routed through -the hostname proxy that already ships, own-address sessions on the VM host -included, with every refusal logged (NET-001 to NET-004). +**First slice:** on a macOS host, `http://.min.internal:` opens +a port a box publishes, at its name and through the hostname proxy alike, +and an activation whose declared port cannot be published is refused +(NET-010, NET-069, NET-123, NET-144). ## Users and stories @@ -170,6 +168,16 @@ included, with every refusal logged (NET-001 to NET-004). verify: cargo nextest run -p minvmd released_address_is_not_reused_within_the_answer_ttl +- **NET-147** THE SYSTEM SHALL show each published box's host loopback address in `min ls` and in its machine-readable output. + tier: T0 + verify: cargo nextest run -p minimal ls_shows_box_loopback_address + + +- **NET-144** IF a box's declared ingress port cannot be bound on the host when the box is activated THEN THE SYSTEM SHALL fail the activation before it reports the box active, name the port and what holds it, and create no box. + tier: T0 + verify: cargo nextest run -p minimald activation_refused_when_declared_port_is_held + + - **NET-011** WHEN a session is finalised THE SYSTEM SHALL register `.min.internal` for the box's loopback address. tier: T0 verify: cargo nextest run -p minimald name_registered_at_finalize @@ -247,32 +255,47 @@ included, with every refusal logged (NET-001 to NET-004). verify: cargo nextest run -p minimal activate_and_ls_report_native_surface -- **NET-142** WHEN a box is activated THE SYSTEM SHALL print one host line naming the box, whose resolution clause is `names: .min.internal via 127.0.0.1:`, where `` is the hostname-proxy port. +- **NET-142** WHEN a box is activated THE SYSTEM SHALL print one host line that names the box, tells the user how to open it by name on this host, and gives the hostname-proxy port when the proxy is the path that opens it. tier: T0 verify: cargo nextest run -p minimal activate_prints_one_host_line_per_install_state - - - WHERE host-OS resolution and published addresses are both deployed on the host THE SYSTEM SHALL print the resolution clause as `names: .min.internal resolves on this machine; open it through the HTTP proxy at 127.0.0.1:`, where `` is the hostname-proxy port, or `names: .min.internal resolves on this machine` while the session start has no proxy port. + + - WHERE host-OS resolution and published addresses are both deployed on the host THE SYSTEM SHALL state in the host line that the name resolves on this machine, and whether the box opens at its name directly or through the hostname proxy at its port. tier: T0 verify: cargo nextest run -p minimal activate_host_line_names_native_dns_when_deployed - - - WHILE any `min finalize-install` item is missing THE SYSTEM SHALL end the host line with the install clause `; finish setup: min finalize-install`, whatever its resolution clause. + + - WHILE any `min finalize-install` item is missing THE SYSTEM SHALL end the host line by naming `min finalize-install` as the step that finishes setup. tier: T0 verify: cargo nextest run -p minimal activate_host_line_carries_finish_setup_clause_while_items_missing - - - WHEN `min ls` runs THE SYSTEM SHALL keep its `HOSTNAME PROXY:` and `ZONE ANSWERER:` detail rows, keep the resolution wording of its `NAME SURFACE:` row, and end that row with the same install clause as the activate host line while any item is missing. + + - WHEN `min ls` runs THE SYSTEM SHALL state the same naming surface and the same way to open a box as the activate host line, beside its rows for the hostname-proxy port and the DNS service. tier: T0 - verify: cargo nextest run -p minimal ls_keeps_detail_rows_and_name_surface_clause - + verify: cargo nextest run -p minimal ls_name_surface_matches_activate_host_line + - **NET-019** WHERE host-OS resolution and published addresses are both deployed on the host THE SYSTEM SHALL keep the hostname proxy serving. tier: T0 verify: cargo nextest run -p minimald proxy_keeps_serving_after_supersession -- **NET-020** IF the host-side hostname listener cannot bind or publish THEN THE SYSTEM SHALL print the reason and the remedy in `min session activate`, as `names: ` in place of the activate host line's resolution clause, in both its forms, with the install clause after it when one applies, and in `min ls` on its `HOSTNAME PROXY:` row. +- **NET-020** IF the host-side hostname listener cannot bind or publish THEN THE SYSTEM SHALL print the reason and the remedy in `min session activate`, in place of the host line's statement of how to open the box, with the finish-setup pointer after it when one applies, and in `min ls` on its hostname-proxy row. tier: T0 verify: cargo nextest run -p minimal listener_failure_reported_with_remedy - + + +- **NET-154** WHEN the hostname proxy serves on a port other than its preferred port THE SYSTEM SHALL log a warning that names the preferred port, the reason it was skipped, and the port in use. + tier: T0 + verify: cargo nextest run -p minvmd proxy_substitute_port_logs_warning + + +- **NET-150** WHILE the hostname proxy serves on a substitute port because its preferred port was busy, WHEN the preferred port becomes free THE SYSTEM SHALL serve the proxy on the preferred port as well, without a VM restart. + tier: T0 + verify: cargo nextest run -p minvmd proxy_reclaims_preferred_port_when_free + + +- **NET-151** THE SYSTEM SHALL report in `min ls` every port the hostname proxy serves. + tier: T0 + verify: cargo nextest run -p minimal ls_reports_every_proxy_port + - **NET-021** IF the host-side hostname listener cannot bind or publish THEN THE SYSTEM SHALL retry with backoff until it succeeds. tier: T0 @@ -334,10 +357,15 @@ included, with every refusal logged (NET-001 to NET-004). verify: cargo nextest run -p minimald network_none_attach_works -- **NET-040** WHEN `min session activate --network own_ip --ingress 8080:8080` is run on a fresh install THE SYSTEM SHALL publish `127.0.0.1:8080` on the host so that a request to it returns the in-box server's response. +- **NET-040** WHEN `min session activate --network own_ip --ingress 8080:8080` is run on a fresh install THE SYSTEM SHALL publish port 8080 at the box's host loopback address so that a request to it returns the in-box server's response. tier: T0 verify: ./scripts/session-e2e.sh fresh_install_own_ip_ingress_publishes_loopback - + + +- **NET-148** IF `min session attach` ends with an error THEN THE SYSTEM SHALL restore the terminal before it prints the error. + tier: T0 + verify: cargo nextest run -p minimal attach_error_printed_after_terminal_restore + - **NET-041** WHEN the installer completes THE SYSTEM SHALL verify that the switch binary is present and executable. tier: T0 @@ -376,6 +404,15 @@ included, with every refusal logged (NET-001 to NET-004). tier: T0 verify: cargo nextest run -p minimald expose_rejected_leaves_no_partial_mapping + - IF `min net expose` asks for a port outside the box's dynamic range THEN THE SYSTEM SHALL refuse the request with a message that names the range the box allows. + tier: T0 + verify: cargo nextest run -p minimald expose_out_of_range_refusal_names_range + + +- **NET-145** IF `min net expose` asks for public exposure on a host that offers none THEN THE SYSTEM SHALL refuse the request, tell the user that public exposure is not available on this host, exit non-zero, and publish nothing. + tier: T0 + verify: cargo nextest run -p minimald expose_public_refused_without_public_surface + - **NET-048** THE SYSTEM SHALL ship the VM host daemon and the guest payload in the Linux amd64 install. tier: T0 @@ -427,10 +464,23 @@ included, with every refusal logged (NET-001 to NET-004). verify: cargo nextest run -p minimal ls_shows_vm_per_box -- **NET-058** WHILE two VMs run, WHEN attach or `min net expose` names a box THE SYSTEM SHALL resolve the VM from the box name without a global flag. +- **NET-152** THE SYSTEM SHALL list in `min ls` the boxes of every VM the user created, a stopped VM included, and mark each box on a stopped VM as stopped. + tier: T0 + verify: cargo nextest run -p minimal ls_lists_boxes_on_stopped_vm + + +- **NET-058** WHILE more than one VM runs, WHEN a command names a box THE SYSTEM SHALL resolve the VM from the box name without a global flag. tier: T0 verify: cargo nextest run -p minimal box_name_resolves_vm_without_flag - + + - IF a command names a box that no running VM holds THEN THE SYSTEM SHALL say that no running VM holds a box of that name and name the `--vm` flag. + tier: T0 + verify: cargo nextest run -p minimal unknown_box_names_vm_flag + + - IF a command names a box on a stopped VM THEN THE SYSTEM SHALL say which stopped VM holds the box and give the command that starts that VM. + tier: T0 + verify: cargo nextest run -p minimal box_on_stopped_vm_names_start_command + - **NET-059** WHILE two VMs run THE SYSTEM SHALL route hostnames from both through the host's hostname surface at the same time. tier: T0 @@ -447,6 +497,11 @@ included, with every refusal logged (NET-001 to NET-004). verify: cargo nextest run -p minimal policy_shows_effective_egress +- **NET-146** THE SYSTEM SHALL show in `min ls`, for every box, the effective egress posture that `min session policy` shows for that box. + tier: T0 + verify: cargo nextest run -p minimal ls_egress_matches_session_policy + + - **NET-062** WHILE a box runs with an own address, IF it opens a connection to a destination its egress rules do not allow THEN THE SYSTEM SHALL drop the connection without resetting it. tier: T2 verify: cargo nextest run -p minimald disallowed_egress_dropped_not_reset @@ -517,12 +572,12 @@ included, with every refusal logged (NET-001 to NET-004). local VM run until the VM lanes export the switch binary to the harness step; then it is verified in CI. --> -- **NET-069** IF a request through the hostname proxy targets a port the target box did not declare THEN THE SYSTEM SHALL refuse it with the same refusal as a direct connection. +- **NET-069** IF a request through the hostname proxy targets a port the target box has not published THEN THE SYSTEM SHALL refuse it with the same refusal as a direct connection. tier: T2 verify: cargo nextest run -p minimald proxy_undeclared_port_refused_like_direct - property: for every target box, every undeclared port, and every proxied request to it, the refusal equals the direct-connection refusal + property: for every target box, every port it has not published, and every proxied request to it, the refusal equals the direct-connection refusal harness: kani_frame_verdict_admits_nothing_undeclared; bound and purity constraint under Tiers in Design reasoning - + - **NET-070** IF a request through the hostname proxy comes from a caller whose egress rules deny the target THEN THE SYSTEM SHALL refuse it. tier: T2 @@ -627,7 +682,16 @@ included, with every refusal logged (NET-001 to NET-004). - **NET-080** WHILE a host-address box is declared deny-all THE SYSTEM SHALL complete the daemon's own package fetch on the same host and record it as node-plane traffic. tier: T0 verify: cargo nextest run -p minimald daemon_fetch_survives_cohort_deny - + + +- **NET-155** WHEN the daemon runs a package build that executes code on behalf of a box THE SYSTEM SHALL place the build's processes under that box's egress verdict, and never under the daemon's node-plane classification. + tier: T0 + verify: cargo nextest run -p minimald box_package_build_under_box_egress_verdict + + - IF the box's egress verdict refuses a destination a package build needs THEN THE SYSTEM SHALL fail the build and report the refused destination and the box whose rules refused it. + tier: T0 + verify: cargo nextest run -p minimald box_package_build_refusal_names_destination_and_box + - **NET-081** WHERE the host is VM-backed THE SYSTEM SHALL apply per-box source-addressed egress rules derived from the expanded box specs outside the VM. tier: T0 @@ -658,6 +722,16 @@ included, with every refusal logged (NET-001 to NET-004). verify: cargo nextest run -p minvmd retract_of_declared_port_refused +- **NET-156** WHILE the box host is VM-backed, IF a flow from the node or from a box targets the host-gateway alias at a destination that is neither a configured host exposure nor in the node-plane baseline set THEN THE SYSTEM SHALL refuse the flow. + tier: T0 + verify: cargo nextest run -p minvmd host_alias_refused_outside_exposures_and_baseline + + +- **NET-157** WHILE the box host is VM-backed, WHEN the system refuses an own-address box's egress THE SYSTEM SHALL record the refusal in a log on the host, outside the VM. + tier: T0 + verify: cargo nextest run -p minvmd egress_refusal_logged_on_host + + - **NET-138** WHERE the host is VM-backed THE SYSTEM SHALL hold, outside the VM, one table of every published namespace on the node — each live box, the node itself and the host-address cohort — with its switch address, its host loopback address, its name, its admitted port set and its egress rules, filled from the host-side creator's expanded spec and the host-side helper's own allocation. tier: T0 verify: cargo nextest run -p minvmd host_table_holds_every_published_namespace @@ -837,10 +911,10 @@ included, with every refusal logged (NET-001 to NET-004). tier: T0 verify: cargo nextest run -p minimald ingress_revocation_unbinds_forwarder_and_terminates_connections - - IF a declared port's forwarder cannot bind THEN THE SYSTEM SHALL report the failure with the reason and publish neither the name nor a substitute address for that port. + - IF a declared port's forwarder cannot bind after the box is active THEN THE SYSTEM SHALL report the failure with the reason and publish neither the name nor a substitute address for that port. tier: T0 verify: cargo nextest run -p minimald failed_forwarder_bind_is_reported_not_substituted - + - **NET-122** WHILE a part of the install is missing on this host, WHEN the operator runs `min finalize-install` THE SYSTEM SHALL name what is missing and run the exact script that installs it, with the script's one privilege elevation as the only prompt. tier: T0 @@ -986,16 +1060,17 @@ included, with every refusal logged (NET-001 to NET-004). ## Non-goals - Public exposure, gateway ingress, and the enrolled dynamic-ingress path over - the box's identity socket (formerly NET-028 to NET-034 and NET-042): - [GWI](https://github.com/gominimal/minimal/pull/1419). + the box's identity socket (formerly NET-028 to NET-034 and NET-042): the + gateway-ingress spec (GWI), not yet written. The refusal on a host that + offers no public exposure is bound here (NET-145). - The gateway association, the signed policy feed, the pin and the ceiling, address blocks from the control plane and their heartbeat reporting, relay reach and WireGuard over WebSocket, renumbering, and local names under - enrolment (formerly NET-005, NET-008, NET-086 to NET-101, and NET-103): - [EHE](https://github.com/gominimal/minimal/pull/1418). + enrolment (formerly NET-005, NET-008, NET-086 to NET-101, and NET-103): the + enrolled-host egress spec (EHE), not yet written. - Mesh join, peer documents, remote box names, and `min net forward` against a - remote session (formerly NET-106 and NET-112 to NET-119): - [MRF](https://github.com/gominimal/minimal/pull/1420). + remote session (formerly NET-106 and NET-112 to NET-119): the mesh and + remote-forwarding spec (MRF), not yet written. - Box-to-box reach across hosts by named-network grant: MRF's non-goal, blocked on an architecture ruling that has not been made. - An operator recipe for pods as box hosts: EHE's non-goal, destined for the Box @@ -1012,11 +1087,11 @@ included, with every refusal logged (NET-001 to NET-004). host-enrolment work ([gominimal/inbox#648](https://github.com/gominimal/inbox/issues/648)). No requirement here assumes an enrolled host. -- Certificate-authenticated remote attach from the CLI: - [CRA](https://github.com/gominimal/minimal/pull/1374). +- Certificate-authenticated remote attach from the CLI: the remote-attach + spec (CRA), not yet written. - The daemon as a mesh-reachable session host, the relay tier, and the browser - client: [MMI](https://github.com/gominimal/minimal/pull/1356) and - [MCC](https://github.com/gominimal/minimal/pull/1355). + client: the mesh-ingress (MMI) and browser-client (MCC) specs, not yet + written. - Sealed secrets and the hosted Box Egress Proxy: the broker document ([gominimal/inbox#625](https://github.com/gominimal/inbox/issues/625)). - BareMetalVM, the sixth deployment style ([architecture, Deployment @@ -1360,6 +1435,16 @@ refusal holds only inside the VM, below the escape boundary. covered by: NET-006, NET-007, NET-127 ## Open questions +- [NEEDS CLARIFICATION (HIGH): what configures a host exposure, and must a box + also declare its reach to one? The design admits box-to-host reach over the + host-gateway alias only for explicitly configured host exposures, and names + no surface that configures one. Until one exists, no box reaches a host + service at `host.min.internal`, and NET-156 refuses every port outside the + node-plane baseline set. One option is an exposure the host's operator + names, reachable from every box on the host whatever its egress rules, with + Minimal's own listeners excluded by rule. A second adds a box-side + declaration, so reach needs both the host's exposure and the box's egress + rule. The architecture owns the choice and where the host half lives.] - [NEEDS CLARIFICATION (MEDIUM): can one machine-wide box-name service serve several users of the same host? The service runs as one operator. Its channel's peer check admits that operator's daemons only (NET-122). A From 478fce4c6bf111b03473f318c5ea2e4e0902dee7 Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Tue, 27 Oct 2026 22:35:54 -0700 Subject: [PATCH 02/11] docs(specs): scope NET's host-address mirror to box binds A listener of the node's own is never mirrored, per the architecture ruling on the macOS host-address mirror. --- docs/specs/18-spec-box-networking/18-spec-box-networking.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specs/18-spec-box-networking/18-spec-box-networking.md b/docs/specs/18-spec-box-networking/18-spec-box-networking.md index 273429008a..8fa5c3eb9b 100644 --- a/docs/specs/18-spec-box-networking/18-spec-box-networking.md +++ b/docs/specs/18-spec-box-networking/18-spec-box-networking.md @@ -770,10 +770,10 @@ and an activation whose declared port cannot be published is refused verify: cargo nextest run -p minvmd host_table_row_withdrawn_within_60s_of_box_end verify: cargo nextest run -p minvmd a_reloaded_row_awaits_its_box_under_the_resume_bound - - WHILE a host-address box is published THE SYSTEM SHALL admit the node's mirrored binds for it at the node's address at any port. + - WHILE a host-address box is published THE SYSTEM SHALL admit the node's mirrored binds for it at the node's address at any port a host-address box binds; a listener of the node's own is never mirrored. tier: T0 verify: cargo nextest run -p minvmd host_address_mirrored_binds_admitted_unfiltered - + - **NET-082** WHERE the host is VM-backed THE SYSTEM SHALL boot the guest with IPv6 disabled so that no IPv6 route ever appears in the guest. tier: T0 From d646e544bbc30615c9a795cbe57d0031a06c78c8 Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Tue, 27 Oct 2026 22:48:06 -0700 Subject: [PATCH 03/11] docs(specs): say NET's proxy parity is a verdict, not a status Per the architecture ruling: a refused verdict reads 403, an admitted request with no listener reads 502, in every network mode. --- docs/specs/18-spec-box-networking/18-spec-box-networking.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specs/18-spec-box-networking/18-spec-box-networking.md b/docs/specs/18-spec-box-networking/18-spec-box-networking.md index 8fa5c3eb9b..26f9a1f0e1 100644 --- a/docs/specs/18-spec-box-networking/18-spec-box-networking.md +++ b/docs/specs/18-spec-box-networking/18-spec-box-networking.md @@ -577,7 +577,7 @@ and an activation whose declared port cannot be published is refused verify: cargo nextest run -p minimald proxy_undeclared_port_refused_like_direct property: for every target box, every port it has not published, and every proxied request to it, the refusal equals the direct-connection refusal harness: kani_frame_verdict_admits_nothing_undeclared; bound and purity constraint under Tiers in Design reasoning - + - **NET-070** IF a request through the hostname proxy comes from a caller whose egress rules deny the target THEN THE SYSTEM SHALL refuse it. tier: T2 @@ -590,7 +590,7 @@ and an activation whose declared port cannot be published is refused tier: T1 verify: cargo nextest run -p minimald proxy_parity_across_network_modes property: for every network mode, every rule set, and every request, the hostname proxy's verdict equals the direct connection's verdict - + - **NET-135** THE SYSTEM SHALL route through the hostname proxy only HTTP/1.1 requests and CONNECT tunnels, and close a connection that opens with the HTTP/2 prior-knowledge preface. tier: T0 From 1e23f914e1a49dbde24790212477025c9563d855 Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Tue, 27 Oct 2026 22:52:28 -0700 Subject: [PATCH 04/11] docs(specs): split NET's host-alias refusal by identity Per the architecture ruling: box and cohort flows never get the baseline set, the design's resolver and Box Egress Proxy openings are admitted, and the host record of a refused egress is per flow and rate-capped. --- .../18-spec-box-networking.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/specs/18-spec-box-networking/18-spec-box-networking.md b/docs/specs/18-spec-box-networking/18-spec-box-networking.md index 26f9a1f0e1..6e50711cbb 100644 --- a/docs/specs/18-spec-box-networking/18-spec-box-networking.md +++ b/docs/specs/18-spec-box-networking/18-spec-box-networking.md @@ -722,15 +722,20 @@ and an activation whose declared port cannot be published is refused verify: cargo nextest run -p minvmd retract_of_declared_port_refused -- **NET-156** WHILE the box host is VM-backed, IF a flow from the node or from a box targets the host-gateway alias at a destination that is neither a configured host exposure nor in the node-plane baseline set THEN THE SYSTEM SHALL refuse the flow. +- **NET-156** WHILE the box host is VM-backed, IF a flow from a box or from the host-address cohort targets the host-gateway alias at a destination that is not a configured host exposure, not the gateway resolver's port, and not a credentialed-lane box's steered flow to the node-local Box Egress Proxy THEN THE SYSTEM SHALL refuse the flow. tier: T0 - verify: cargo nextest run -p minvmd host_alias_refused_outside_exposures_and_baseline - + verify: cargo nextest run -p minvmd host_alias_refused_outside_exposures_for_boxes + + +- **NET-158** WHILE the box host is VM-backed, IF a flow with the node-plane identity targets the host-gateway alias at a destination that is not a configured host exposure, not the gateway resolver's port, not the node-local Box Egress Proxy, and not in the node-plane baseline set THEN THE SYSTEM SHALL refuse the flow. + tier: T0 + verify: cargo nextest run -p minvmd host_alias_admits_baseline_for_node_plane_only + - **NET-157** WHILE the box host is VM-backed, WHEN the system refuses an own-address box's egress THE SYSTEM SHALL record the refusal in a log on the host, outside the VM. tier: T0 verify: cargo nextest run -p minvmd egress_refusal_logged_on_host - + - **NET-138** WHERE the host is VM-backed THE SYSTEM SHALL hold, outside the VM, one table of every published namespace on the node — each live box, the node itself and the host-address cohort — with its switch address, its host loopback address, its name, its admitted port set and its egress rules, filled from the host-side creator's expanded spec and the host-side helper's own allocation. tier: T0 @@ -1439,8 +1444,9 @@ refusal holds only inside the VM, below the escape boundary. also declare its reach to one? The design admits box-to-host reach over the host-gateway alias only for explicitly configured host exposures, and names no surface that configures one. Until one exists, no box reaches a host - service at `host.min.internal`, and NET-156 refuses every port outside the - node-plane baseline set. One option is an exposure the host's operator + service at `host.min.internal`: NET-156 refuses every port outside the + design's openings for a box, and NET-158 adds the node-plane baseline set for + the node alone. One option is an exposure the host's operator names, reachable from every box on the host whatever its egress rules, with Minimal's own listeners excluded by rule. A second adds a box-side declaration, so reach needs both the host's exposure and the box's egress From 91f5b5e423c04f0ff958756b1a6c052306545902 Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Wed, 28 Oct 2026 12:55:15 -0700 Subject: [PATCH 05/11] docs(specs): verify NET-069 for a withdrawn runtime port The proxy refusal property covers a port published while the box runs and later withdrawn. Name the test that publishes, withdraws and compares the proxied refusal with a direct one. --- docs/specs/18-spec-box-networking/18-spec-box-networking.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/specs/18-spec-box-networking/18-spec-box-networking.md b/docs/specs/18-spec-box-networking/18-spec-box-networking.md index 6e50711cbb..278f0f2778 100644 --- a/docs/specs/18-spec-box-networking/18-spec-box-networking.md +++ b/docs/specs/18-spec-box-networking/18-spec-box-networking.md @@ -575,6 +575,7 @@ and an activation whose declared port cannot be published is refused - **NET-069** IF a request through the hostname proxy targets a port the target box has not published THEN THE SYSTEM SHALL refuse it with the same refusal as a direct connection. tier: T2 verify: cargo nextest run -p minimald proxy_undeclared_port_refused_like_direct + verify: cargo nextest run -p minimald proxy_refuses_a_withdrawn_port_like_direct property: for every target box, every port it has not published, and every proxied request to it, the refusal equals the direct-connection refusal harness: kani_frame_verdict_admits_nothing_undeclared; bound and purity constraint under Tiers in Design reasoning From 0503ba40f8ef3a808cee22b636cada4ca16657de Mon Sep 17 00:00:00 2001 From: Norrie Taylor <91171431+norrietaylor@users.noreply.github.com> Date: Sat, 31 Oct 2026 01:52:15 +0000 Subject: [PATCH 06/11] docs(specs): add NET's host-exposure halves from the arch#110 ruling The networking design v0.9.2 (gominimal/arch#155) names the two halves of a host exposure, so the HIGH open question on what configures one closes. - NET-159: the host's half is the client config.toml's [host-exposures] table; a project minimal.toml section is ignored with a warning. - NET-160: the box's half is host.min.internal in egress.allow_dns_hosts. - NET-161: each flow is decided by the current table; a removed exposure ends its established flows. - NET-162: an entry on a port a Minimal listener holds is refused at load, naming the holder. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01J3Guwr3mQPqSeGMcjzVjTd --- .../18-spec-box-networking.md | 44 +++++++++++++------ 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/docs/specs/18-spec-box-networking/18-spec-box-networking.md b/docs/specs/18-spec-box-networking/18-spec-box-networking.md index 278f0f2778..9fe7a3fde2 100644 --- a/docs/specs/18-spec-box-networking/18-spec-box-networking.md +++ b/docs/specs/18-spec-box-networking/18-spec-box-networking.md @@ -726,13 +726,41 @@ and an activation whose declared port cannot be published is refused - **NET-156** WHILE the box host is VM-backed, IF a flow from a box or from the host-address cohort targets the host-gateway alias at a destination that is not a configured host exposure, not the gateway resolver's port, and not a credentialed-lane box's steered flow to the node-local Box Egress Proxy THEN THE SYSTEM SHALL refuse the flow. tier: T0 verify: cargo nextest run -p minvmd host_alias_refused_outside_exposures_for_boxes - + - **NET-158** WHILE the box host is VM-backed, IF a flow with the node-plane identity targets the host-gateway alias at a destination that is not a configured host exposure, not the gateway resolver's port, not the node-local Box Egress Proxy, and not in the node-plane baseline set THEN THE SYSTEM SHALL refuse the flow. tier: T0 verify: cargo nextest run -p minvmd host_alias_admits_baseline_for_node_plane_only +- **NET-159** THE SYSTEM SHALL take the host exposures of a box host from the `[host-exposures]` table of the client's `config.toml` alone, where each entry names one exposure, its host-loopback port and its protocol. + tier: T0 + verify: cargo nextest run -p minvmd host_exposures_read_from_client_config + + - IF a project `minimal.toml` carries a `[host-exposures]` section THEN THE SYSTEM SHALL ignore the section and warn that a project file cannot configure a host exposure. + tier: T0 + verify: cargo nextest run -p boxes project_host_exposures_ignored_with_warning + + +- **NET-160** WHILE the box host is VM-backed, IF a flow from a box targets the host-gateway alias at a configured host exposure, and the box's `egress.allow_dns_hosts` does not name `host.min.internal`, and its `egress.allow_subnets` does not cover the alias THEN THE SYSTEM SHALL refuse the flow. + tier: T0 + verify: cargo nextest run -p minvmd host_alias_exposure_needs_the_box_to_name_the_host + + +- **NET-161** WHILE the box host is VM-backed, WHEN the `[host-exposures]` table changes THE SYSTEM SHALL decide each later flow to the host-gateway alias by the changed table. + tier: T0 + verify: cargo nextest run -p minvmd host_alias_admits_a_port_the_current_table_opens + + - WHEN a change to the `[host-exposures]` table removes an exposure THE SYSTEM SHALL end each established flow to that exposure. + tier: T0 + verify: cargo nextest run -p minvmd host_exposure_removal_ends_established_flows + + +- **NET-162** IF an entry of the `[host-exposures]` table names a port that a Minimal listener holds, such as the box-name answerer, the hostname proxy, the node-local Box Egress Proxy or a node-plane baseline endpoint at the host-gateway alias, THEN THE SYSTEM SHALL refuse that entry when it loads the table and name the listener that holds the port. + tier: T0 + verify: cargo nextest run -p minvmd host_exposure_on_minimal_listener_port_refused + + - **NET-157** WHILE the box host is VM-backed, WHEN the system refuses an own-address box's egress THE SYSTEM SHALL record the refusal in a log on the host, outside the VM. tier: T0 verify: cargo nextest run -p minvmd egress_refusal_logged_on_host @@ -1240,7 +1268,8 @@ zone is answered only to lookups that originate on the machine (NET-006); answering only loopback addresses was the weaker reading considered. `host.min.internal` resolves from every box (NET-003) and reach over it is local reach evaluated under the box's egress rules, default-deny except -configured host exposures ([design §7.1][design] local names): a deny-all box +configured host exposures ([design §7.1][design] local names; the two halves of an +exposure in design v0.9.2 §7.1, NET-159 to NET-162): a deny-all box resolves the name and reaches nothing (NET-079), and the daemon's own package fetch is node-plane traffic, not the box's (NET-080). Making the host's loopback a baseline exception for every box was considered and rejected: it @@ -1441,17 +1470,6 @@ refusal holds only inside the VM, below the escape boundary. covered by: NET-006, NET-007, NET-127 ## Open questions -- [NEEDS CLARIFICATION (HIGH): what configures a host exposure, and must a box - also declare its reach to one? The design admits box-to-host reach over the - host-gateway alias only for explicitly configured host exposures, and names - no surface that configures one. Until one exists, no box reaches a host - service at `host.min.internal`: NET-156 refuses every port outside the - design's openings for a box, and NET-158 adds the node-plane baseline set for - the node alone. One option is an exposure the host's operator - names, reachable from every box on the host whatever its egress rules, with - Minimal's own listeners excluded by rule. A second adds a box-side - declaration, so reach needs both the host's exposure and the box's egress - rule. The architecture owns the choice and where the host half lives.] - [NEEDS CLARIFICATION (MEDIUM): can one machine-wide box-name service serve several users of the same host? The service runs as one operator. Its channel's peer check admits that operator's daemons only (NET-122). A From 37308cba045e28d501b049a9b21eedbacfcb0f4b Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Tue, 3 Nov 2026 12:35:49 -0700 Subject: [PATCH 07/11] docs(specs): bind NET's host exposures on native own-address boxes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit NET-160 and NET-161 bound only a VM-backed host. Design v0.9.2 §7.1 Lanes applies the table to own_ip boxes on every host and not to a native host_ip box, so both now bind an own-address box on a native host, each with a minimald test. NET-159 makes tcp the protocol of an entry that names none. NET-058's parent drops its WHILE two VMs run clause, so its unknown-box and stopped-VM refusals bind with one VM too. --- .../18-spec-box-networking.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/specs/18-spec-box-networking/18-spec-box-networking.md b/docs/specs/18-spec-box-networking/18-spec-box-networking.md index c5a46cfe47..e485f5495d 100644 --- a/docs/specs/18-spec-box-networking/18-spec-box-networking.md +++ b/docs/specs/18-spec-box-networking/18-spec-box-networking.md @@ -483,10 +483,10 @@ box that holds it returns to `running`. These terms follow the decision in verify: cargo nextest run -p minimal ls_lists_boxes_on_stopped_vm -- **NET-058** WHILE two VMs run, WHEN attach, exec, a task run, `min net forward` or `min net expose` names a box THE SYSTEM SHALL resolve the VM from the box name without a global flag. +- **NET-058** WHEN attach, exec, a task run, `min net forward` or `min net expose` names a box THE SYSTEM SHALL resolve the VM that holds the box from the box name, without a global flag. tier: T0 verify: cargo nextest run -p minimal box_name_resolves_vm_without_flag - + - IF a command names a box that no running VM holds THEN THE SYSTEM SHALL say that no running VM holds a box of that name and name the `--vm` flag. tier: T0 verify: cargo nextest run -p minimal unknown_box_names_vm_flag @@ -745,7 +745,7 @@ box that holds it returns to `running`. These terms follow the decision in verify: cargo nextest run -p minvmd host_alias_admits_baseline_for_node_plane_only -- **NET-159** THE SYSTEM SHALL take the host exposures of a box host from the `[host-exposures]` table of the client's `config.toml` alone, where each entry names one exposure, its host-loopback port and its protocol. +- **NET-159** THE SYSTEM SHALL take the host exposures of a box host from the `[host-exposures]` table of the client's `config.toml` alone, where each entry names one exposure, its host-loopback port and its protocol, and an entry that names no protocol is `tcp`. tier: T0 verify: cargo nextest run -p minvmd host_exposures_read_from_client_config @@ -754,18 +754,21 @@ box that holds it returns to `running`. These terms follow the decision in verify: cargo nextest run -p boxes project_host_exposures_ignored_with_warning -- **NET-160** WHILE the box host is VM-backed, IF a flow from a box targets the host-gateway alias at a configured host exposure, and the box's `egress.allow_dns_hosts` does not name `host.min.internal`, and its `egress.allow_subnets` does not cover the alias THEN THE SYSTEM SHALL refuse the flow. +- **NET-160** WHILE the box host is VM-backed or the box is an own-address box, IF a flow from a box targets the host-gateway alias at a configured host exposure, and the box's `egress.allow_dns_hosts` does not name `host.min.internal`, and its `egress.allow_subnets` does not cover the alias THEN THE SYSTEM SHALL refuse the flow. tier: T0 verify: cargo nextest run -p minvmd host_alias_exposure_needs_the_box_to_name_the_host - + verify: cargo nextest run -p minimald native_own_ip_host_exposure_needs_the_box_to_name_the_host + -- **NET-161** WHILE the box host is VM-backed, WHEN the `[host-exposures]` table changes THE SYSTEM SHALL decide each later flow to the host-gateway alias by the changed table. +- **NET-161** WHILE the box host is VM-backed or the box is an own-address box, WHEN the `[host-exposures]` table changes THE SYSTEM SHALL decide each later flow to the host-gateway alias by the changed table. tier: T0 verify: cargo nextest run -p minvmd host_alias_admits_a_port_the_current_table_opens + verify: cargo nextest run -p minimald native_own_ip_follows_the_current_host_exposures_table - WHEN a change to the `[host-exposures]` table removes an exposure THE SYSTEM SHALL end each established flow to that exposure. tier: T0 verify: cargo nextest run -p minvmd host_exposure_removal_ends_established_flows + verify: cargo nextest run -p minimald native_own_ip_exposure_removal_ends_established_flows - **NET-162** IF an entry of the `[host-exposures]` table names a port that a Minimal listener holds, such as the box-name answerer, the hostname proxy, the node-local Box Egress Proxy or a node-plane baseline endpoint at the host-gateway alias, THEN THE SYSTEM SHALL refuse that entry when it loads the table and name the listener that holds the port. From 14bfe2de0b2c275e58a02f03567094c0ee66c524 Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Tue, 3 Nov 2026 14:48:55 -0700 Subject: [PATCH 08/11] docs(specs): bind NET's box-name reach and shadowed host exposures MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Covers the gominimal/arch#110 ruling's remaining points (networking design v0.9.2 §7.1): NET-163 admits a box-zone name in allow_dns_hosts to the named box under its ingress, exact names only; a NET-162 sub-requirement keeps Minimal's own ports excluded for an entry's lifetime; NET-159 records MINVMD_HOST_EXPOSURE_PORTS (#2331) as temporary. --- .../18-spec-box-networking.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/specs/18-spec-box-networking/18-spec-box-networking.md b/docs/specs/18-spec-box-networking/18-spec-box-networking.md index e485f5495d..f9227d810e 100644 --- a/docs/specs/18-spec-box-networking/18-spec-box-networking.md +++ b/docs/specs/18-spec-box-networking/18-spec-box-networking.md @@ -626,6 +626,16 @@ box that holds it returns to `running`. These terms follow the decision in verify: cargo nextest run -p minimald box_zone_connection_enforced_at_connect +- **NET-163** WHEN a box's `egress.allow_dns_hosts` names a box-zone name THE SYSTEM SHALL admit the box's flows to the address the name answers with, under the target box's ingress rules. + tier: T0 + verify: cargo nextest run -p minimald zone_name_in_allow_dns_hosts_admits_the_named_box + verify: cargo nextest run -p minvmd zone_name_rule_admits_sibling_lease_under_its_ingress + + - IF a box's `egress.allow_dns_hosts` names a box-zone name `` and a flow from the box targets a parallel instance `-` that no entry of the list names THEN THE SYSTEM SHALL refuse the flow. + tier: T0 + verify: cargo nextest run -p minimald zone_name_rule_does_not_cover_a_parallel_instance + + - **NET-074** WHERE the deny-all default is in force and the opt-out flag is not set, WHEN a box is created with an `egress` section, or an own-address box with none, THE SYSTEM SHALL give each destination allow list the expanded section leaves absent, `allow_subnets` and `allow_dns_hosts`, no reach in that dimension, so that an own-address box with no `egress` section reaches no external address. tier: T0 verify: cargo nextest run -p minimald own_ip_default_deny_all @@ -748,7 +758,7 @@ box that holds it returns to `running`. These terms follow the decision in - **NET-159** THE SYSTEM SHALL take the host exposures of a box host from the `[host-exposures]` table of the client's `config.toml` alone, where each entry names one exposure, its host-loopback port and its protocol, and an entry that names no protocol is `tcp`. tier: T0 verify: cargo nextest run -p minvmd host_exposures_read_from_client_config - + - IF a project `minimal.toml` carries a `[host-exposures]` section THEN THE SYSTEM SHALL ignore the section and warn that a project file cannot configure a host exposure. tier: T0 verify: cargo nextest run -p boxes project_host_exposures_ignored_with_warning @@ -775,6 +785,10 @@ box that holds it returns to `running`. These terms follow the decision in tier: T0 verify: cargo nextest run -p minvmd host_exposure_on_minimal_listener_port_refused + - WHILE the `[host-exposures]` table holds an entry, WHEN a Minimal listener binds the entry's port THE SYSTEM SHALL refuse each later flow from a box to that port at the host-gateway alias and record in a log on the host that the listener shadows the entry. + tier: T0 + verify: cargo nextest run -p minvmd host_exposure_shadowed_by_a_later_minimal_listener + - **NET-157** WHILE the box host is VM-backed, WHEN the system refuses an own-address box's egress THE SYSTEM SHALL record the refusal in a log on the host, outside the VM. tier: T0 From 9e8ceebf488c31c74432c915c915487073bc7e44 Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Tue, 3 Nov 2026 15:18:33 -0700 Subject: [PATCH 09/11] docs(specs): fold the NET amendment's review into the spec Takes main's NET-138 dormant-creation text back, which the main merge lost. Scopes NET-163 to a box's name on a host with an interposition point, keeps the allow_subnets fall-through for a parallel instance, and leaves host.min.internal to NET-160. NET-058 names the host-side commands in BCLI's spellings, and its unknown-box refusal no longer overlaps the stopped-VM one. Also binds the native host_ip network view, splits the unmirrored node listener into its own requirement, defines Minimal's own listeners, fixes the NET-069 and NET-144 verify lines and the first slice's citation, and bumps the arch pin to design v0.9.2 (gominimal/arch#155). --- .../18-spec-box-networking.md | 56 +++++++++++-------- 1 file changed, 33 insertions(+), 23 deletions(-) diff --git a/docs/specs/18-spec-box-networking/18-spec-box-networking.md b/docs/specs/18-spec-box-networking/18-spec-box-networking.md index f9227d810e..b2157f0a2b 100644 --- a/docs/specs/18-spec-box-networking/18-spec-box-networking.md +++ b/docs/specs/18-spec-box-networking/18-spec-box-networking.md @@ -3,9 +3,9 @@ id: NET title: "Box networking on the local host: preview by name and bounded egress" owner: norrietaylor epic: gominimal/inbox#646 -arch: https://github.com/gominimal/arch/blob/5c1201517ba07347344fb9725efb06ee39d5c03e/specs/networking/deployment-and-egress-gateway.md -arch_sha: "5c1201517ba07347344fb9725efb06ee39d5c03e" -updated: 2026-10-27 +arch: https://github.com/gominimal/arch/blob/8640f85e193d11b8feb1ae64a0d4db287e67f064/specs/networking/deployment-and-egress-gateway.md +arch_sha: "8640f85e193d11b8feb1ae64a0d4db287e67f064" +updated: 2026-11-03 --- # NET — Box networking on the local host: preview by name and bounded egress @@ -80,7 +80,7 @@ resident boxes' declared egress. **First slice:** on a macOS host, `http://.min.internal:` opens a port a box publishes, at its name and through the hostname proxy alike, and an activation whose declared port cannot be published is refused -(NET-010, NET-069, NET-123, NET-144). +(NET-010, NET-016, NET-123, NET-144). ## Users and stories @@ -189,7 +189,9 @@ box that holds it returns to `running`. These terms follow the decision in - **NET-144** IF a box's declared ingress port cannot be bound on the host when the box is activated THEN THE SYSTEM SHALL fail the activation before it reports the box active, name the port and what holds it, and create no box. tier: T0 - verify: cargo nextest run -p minimald activation_refused_when_declared_port_is_held + verify: cargo nextest run -p minimald activation_refused_when_declared_port_is_held_by_a_host_program + verify: cargo nextest run -p minimald activation_refused_when_declared_port_is_held_by_another_box_at_the_fallback + verify: cargo nextest run -p minimald activation_refused_when_declared_port_is_held_reported_when_the_verdict_lands_absent - **NET-011** WHEN a session is finalised THE SYSTEM SHALL register `.min.internal` for the box's loopback address. @@ -483,11 +485,11 @@ box that holds it returns to `running`. These terms follow the decision in verify: cargo nextest run -p minimal ls_lists_boxes_on_stopped_vm -- **NET-058** WHEN attach, exec, a task run, `min net forward` or `min net expose` names a box THE SYSTEM SHALL resolve the VM that holds the box from the box name, without a global flag. +- **NET-058** WHEN `min box attach`, `min box exec`, `min box show --network`, `min box rm` or `min net forward` names a box THE SYSTEM SHALL resolve the VM that holds the box from the box name, without a global flag. tier: T0 verify: cargo nextest run -p minimal box_name_resolves_vm_without_flag - - - IF a command names a box that no running VM holds THEN THE SYSTEM SHALL say that no running VM holds a box of that name and name the `--vm` flag. + + - IF a command names a box that no VM holds THEN THE SYSTEM SHALL say that no VM holds a box of that name and name the `--vm` flag. tier: T0 verify: cargo nextest run -p minimal unknown_box_names_vm_flag @@ -589,7 +591,7 @@ box that holds it returns to `running`. These terms follow the decision in - **NET-069** IF a request through the hostname proxy targets a port the target box has not published THEN THE SYSTEM SHALL refuse it with the same refusal as a direct connection. tier: T2 verify: cargo nextest run -p minimald proxy_undeclared_port_refused_like_direct - verify: cargo nextest run -p minimald proxy_refuses_a_withdrawn_port_like_direct + verify: cargo nextest run -p minimald proxy_forwards_runtime_published_port property: for every target box, every port it has not published, and every proxied request to it, the refusal equals the direct-connection refusal harness: kani_frame_verdict_admits_nothing_undeclared; bound and purity constraint under Tiers in Design reasoning @@ -626,15 +628,15 @@ box that holds it returns to `running`. These terms follow the decision in verify: cargo nextest run -p minimald box_zone_connection_enforced_at_connect -- **NET-163** WHEN a box's `egress.allow_dns_hosts` names a box-zone name THE SYSTEM SHALL admit the box's flows to the address the name answers with, under the target box's ingress rules. +- **NET-163** WHILE the box host is VM-backed or the box is an own-address box, IF a box's `egress.allow_dns_hosts` names the name of another box THEN THE SYSTEM SHALL admit the box's flows to that box's address under that box's ingress rules. tier: T0 verify: cargo nextest run -p minimald zone_name_in_allow_dns_hosts_admits_the_named_box verify: cargo nextest run -p minvmd zone_name_rule_admits_sibling_lease_under_its_ingress - - - IF a box's `egress.allow_dns_hosts` names a box-zone name `` and a flow from the box targets a parallel instance `-` that no entry of the list names THEN THE SYSTEM SHALL refuse the flow. + + - WHILE the box host is VM-backed or the box is an own-address box, IF a box's `egress.allow_dns_hosts` names ``, and a flow from the box targets a parallel instance `-` that no entry of the list names, and its `egress.allow_subnets` does not cover the instance's address THEN THE SYSTEM SHALL refuse the flow. tier: T0 verify: cargo nextest run -p minimald zone_name_rule_does_not_cover_a_parallel_instance - + - **NET-074** WHERE the deny-all default is in force and the opt-out flag is not set, WHEN a box is created with an `egress` section, or an own-address box with none, THE SYSTEM SHALL give each destination allow list the expanded section leaves absent, `allow_subnets` and `allow_dns_hosts`, no reach in that dimension, so that an own-address box with no `egress` section reaches no external address. tier: T0 @@ -758,7 +760,7 @@ box that holds it returns to `running`. These terms follow the decision in - **NET-159** THE SYSTEM SHALL take the host exposures of a box host from the `[host-exposures]` table of the client's `config.toml` alone, where each entry names one exposure, its host-loopback port and its protocol, and an entry that names no protocol is `tcp`. tier: T0 verify: cargo nextest run -p minvmd host_exposures_read_from_client_config - + - IF a project `minimal.toml` carries a `[host-exposures]` section THEN THE SYSTEM SHALL ignore the section and warn that a project file cannot configure a host exposure. tier: T0 verify: cargo nextest run -p boxes project_host_exposures_ignored_with_warning @@ -769,6 +771,10 @@ box that holds it returns to `running`. These terms follow the decision in verify: cargo nextest run -p minvmd host_alias_exposure_needs_the_box_to_name_the_host verify: cargo nextest run -p minimald native_own_ip_host_exposure_needs_the_box_to_name_the_host + - WHERE the box host is native, WHEN `min box show --network` reports a host-address box THE SYSTEM SHALL state that the host's `[host-exposures]` table does not apply to the box, in place of a list of exposures. + tier: T0 + verify: cargo nextest run -p minimal native_host_ip_network_view_says_host_exposures_do_not_apply + - **NET-161** WHILE the box host is VM-backed or the box is an own-address box, WHEN the `[host-exposures]` table changes THE SYSTEM SHALL decide each later flow to the host-gateway alias by the changed table. tier: T0 @@ -781,14 +787,14 @@ box that holds it returns to `running`. These terms follow the decision in verify: cargo nextest run -p minimald native_own_ip_exposure_removal_ends_established_flows -- **NET-162** IF an entry of the `[host-exposures]` table names a port that a Minimal listener holds, such as the box-name answerer, the hostname proxy, the node-local Box Egress Proxy or a node-plane baseline endpoint at the host-gateway alias, THEN THE SYSTEM SHALL refuse that entry when it loads the table and name the listener that holds the port. +- **NET-162** IF an entry of the `[host-exposures]` table names a port that a listener or socket of Minimal's own holds, such as the box-name answerer, the hostname proxy, the node-local Box Egress Proxy, a node-plane baseline endpoint at the host-gateway alias or a daemon socket, THEN THE SYSTEM SHALL refuse that entry when it loads the table and name the listener that holds the port. tier: T0 verify: cargo nextest run -p minvmd host_exposure_on_minimal_listener_port_refused - - WHILE the `[host-exposures]` table holds an entry, WHEN a Minimal listener binds the entry's port THE SYSTEM SHALL refuse each later flow from a box to that port at the host-gateway alias and record in a log on the host that the listener shadows the entry. + - WHILE the `[host-exposures]` table holds an entry, WHEN a listener or socket of Minimal's own binds the entry's port THE SYSTEM SHALL refuse each later flow from a box to that port at the host-gateway alias and record in a log on the host that the listener shadows the entry. tier: T0 verify: cargo nextest run -p minvmd host_exposure_shadowed_by_a_later_minimal_listener - + - **NET-157** WHILE the box host is VM-backed, WHEN the system refuses an own-address box's egress THE SYSTEM SHALL record the refusal in a log on the host, outside the VM. tier: T0 @@ -832,11 +838,15 @@ box that holds it returns to `running`. These terms follow the decision in tier: T0 verify: cargo nextest run -p minvmd host_table_row_withdrawn_within_60s_of_box_end verify: cargo nextest run -p minvmd a_reloaded_row_awaits_its_box_under_the_resume_bound - - - WHILE a host-address box is published THE SYSTEM SHALL admit the node's mirrored binds for it at the node's address at any port a host-address box binds; a listener of the node's own is never mirrored. + + - WHILE a host-address box is published THE SYSTEM SHALL admit the node's mirrored binds for it at the node's address at any port a host-address box binds. tier: T0 verify: cargo nextest run -p minvmd host_address_mirrored_binds_admitted_unfiltered + - IF a process of the node's own binds a listener in the host-address namespace THEN THE SYSTEM SHALL leave the listener unmirrored at the node's address. + tier: T0 + verify: cargo nextest run -p minvmd node_own_listener_never_mirrored + - **NET-082** WHERE the host is VM-backed THE SYSTEM SHALL boot the guest with IPv6 disabled so that no IPv6 route ever appears in the guest. tier: T0 @@ -1358,7 +1368,7 @@ NET-072); `egress.deny_subnets` (NET-060, NET-067) has no crate counterpart and is introduced here, in the same spelling, from design §5.3's `egress_deny_subnets`. The architecture's canonical Box Spec fields are the flat `egress_allow_dns`, `egress_allow_subnets` and `egress_deny_subnets` -([box.toml](https://github.com/gominimal/arch/blob/5c1201517ba07347344fb9725efb06ee39d5c03e/box.toml); design §4.3, +([box.toml](https://github.com/gominimal/arch/blob/8640f85e193d11b8feb1ae64a0d4db287e67f064/box.toml); design §4.3, §5.3, §7.1), and the box-spec schema work ([gominimal/inbox#570](https://github.com/gominimal/inbox/issues/570)) owns the reconciliation. Three shipped rules are superseded: 03-spec R2.1's parse-time @@ -1524,6 +1534,6 @@ refusal holds only inside the VM, below the escape boundary. admitted by address rules alone ([design §5.3][design]); and the per-box enforcement the host records under NET-079 covers addresses, never names.] -[design]: https://github.com/gominimal/arch/blob/5c1201517ba07347344fb9725efb06ee39d5c03e/specs/networking/deployment-and-egress-gateway.md -[arch]: https://github.com/gominimal/arch/blob/5c1201517ba07347344fb9725efb06ee39d5c03e/architecture.md -[gatehouse]: https://github.com/gominimal/arch/blob/5c1201517ba07347344fb9725efb06ee39d5c03e/specs/authn-authz/gatehouse-spec.md +[design]: https://github.com/gominimal/arch/blob/8640f85e193d11b8feb1ae64a0d4db287e67f064/specs/networking/deployment-and-egress-gateway.md +[arch]: https://github.com/gominimal/arch/blob/8640f85e193d11b8feb1ae64a0d4db287e67f064/architecture.md +[gatehouse]: https://github.com/gominimal/arch/blob/8640f85e193d11b8feb1ae64a0d4db287e67f064/specs/authn-authz/gatehouse-spec.md From 62a41c8b892fe188ae7591d275bc85473e09d3b2 Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Tue, 3 Nov 2026 15:30:38 -0700 Subject: [PATCH 10/11] docs(specs): bind NET-058 to the commands that ship today NET-058 names min session attach, exec, policy and destroy, which its verify test exercises, and its comment names the min box forms that BCLI gives as their successors. The statement moves to those forms when BCLI's tasks ship them. --- docs/specs/18-spec-box-networking/18-spec-box-networking.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specs/18-spec-box-networking/18-spec-box-networking.md b/docs/specs/18-spec-box-networking/18-spec-box-networking.md index b2157f0a2b..33bfb0fa87 100644 --- a/docs/specs/18-spec-box-networking/18-spec-box-networking.md +++ b/docs/specs/18-spec-box-networking/18-spec-box-networking.md @@ -485,10 +485,10 @@ box that holds it returns to `running`. These terms follow the decision in verify: cargo nextest run -p minimal ls_lists_boxes_on_stopped_vm -- **NET-058** WHEN `min box attach`, `min box exec`, `min box show --network`, `min box rm` or `min net forward` names a box THE SYSTEM SHALL resolve the VM that holds the box from the box name, without a global flag. +- **NET-058** WHEN `min session attach`, `min session exec`, `min session policy`, `min session destroy` or `min net forward` names a box THE SYSTEM SHALL resolve the VM that holds the box from the box name, without a global flag. tier: T0 verify: cargo nextest run -p minimal box_name_resolves_vm_without_flag - + - IF a command names a box that no VM holds THEN THE SYSTEM SHALL say that no VM holds a box of that name and name the `--vm` flag. tier: T0 verify: cargo nextest run -p minimal unknown_box_names_vm_flag From 9e1c71aa234e1785f25618a45fcdef8819c423f1 Mon Sep 17 00:00:00 2001 From: Norrie Taylor Date: Tue, 3 Nov 2026 15:44:59 -0700 Subject: [PATCH 11/11] docs(specs): list NET-058 in BCLI's alias Rollout NET-058 now names min session policy, destroy and exec, so each alias stays open until NET-058 moves to the min box form. NET-160's new sub-bullet cites the min session policy alias too. --- docs/specs/28-spec-box-cli/28-spec-box-cli.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specs/28-spec-box-cli/28-spec-box-cli.md b/docs/specs/28-spec-box-cli/28-spec-box-cli.md index 8dec937b68..73ae990bb0 100644 --- a/docs/specs/28-spec-box-cli/28-spec-box-cli.md +++ b/docs/specs/28-spec-box-cli/28-spec-box-cli.md @@ -584,11 +584,11 @@ The box model is `docs/specs/29-spec-box-local-first` (BOX): the record, the spe **Merged requirements and scripts cite spellings BCLI-042 and BCLI-046 remove.** These requirements and scripts on main use an old spelling. `scripts/session-e2e.sh` is the VM lane's session proof, and BCLI-049's verify line runs it. Each alias it calls stays open until it moves: - `min session activate`: NET-018, NET-020, NET-035, NET-040, NET-049, NET-051 and NET-122, the last in a sub-bullet's comment. A BOX-001 sub-bullet cites it too. The installer's closing card names `min session activate --attach .` (`docs/specs/07-spec-installer`, R10.4). The lifecycle-hooks spec cites `min session activate --no-hooks` (`docs/specs/11-spec-lifecycle-hooks`). Scripts: `scripts/session-e2e.sh`, `scripts/bulk-upload-e2e.sh`, `scripts/stress-session-e2e.sh` and `scripts/kernel-bump-review.sh`. -- `min session policy`: NET-044, NET-061, NET-075, NET-130 (in a sub-bullet's comment), NET-140 and NET-146, and BEP-085's comment. The draft GWI-003 cites it too. Script: `scripts/session-e2e.sh`. +- `min session policy`: NET-044, NET-058, NET-061, NET-075, NET-130 (in a sub-bullet's comment), NET-140, NET-146 and a NET-160 sub-bullet's comment, and BEP-085's comment. The draft GWI-003 cites it too. Script: `scripts/session-e2e.sh`. - `min session hooks`: the lifecycle-hooks spec. Script: `scripts/session-e2e.sh`. - `min session rename`: no requirement. Script: `scripts/session-e2e.sh`. -- `min session destroy`: BEP-043. Scripts: `scripts/session-e2e.sh`, and `scripts/bulk-upload-e2e.sh`, whose cleanup runs `session destroy --all --force`. -- `min session exec`: a NET-015 sub-bullet and TEL-031. Script: `scripts/session-e2e.sh`. +- `min session destroy`: NET-058 and BEP-043. Scripts: `scripts/session-e2e.sh`, and `scripts/bulk-upload-e2e.sh`, whose cleanup runs `session destroy --all --force`. +- `min session exec`: NET-058, a NET-015 sub-bullet and TEL-031. Script: `scripts/session-e2e.sh`. - Bare `min stop`: TEL-011, and the installer's R5.5. The installer, `scripts/install.sh`, runs `min stop` and matches its refusal for live sessions by message. Without that match it runs `min stop --force`. The end-to-end scripts `scripts/session-e2e.sh`, `scripts/stress-session-e2e.sh` and `scripts/bulk-upload-e2e.sh`, and the installer's tests in `scripts/install_test.sh`, call `min stop` too. BCLI-042's sub-bullet ends an alias's window one release after the requirements and scripts listed for it above use the new spelling. So the installer changes first. Once bare `min stop` fails, an installer that still calls it does not see the refusal it matches. It then force-stops every upgrade.