Skip to content

docs(specs): settle box reach to the host alias and the node address - #1946

Merged
norrietaylor merged 9 commits into
mainfrom
docs/net-004-host-alias-default-deny
Oct 8, 2026
Merged

norrietaylor merged 9 commits into
mainfrom
docs/net-004-host-alias-default-deny

Conversation

@norrietaylor

@norrietaylor norrietaylor commented Oct 4, 2026 •

Copy link
Copy Markdown
Member

What

Box-to-host reach over host.min.internal is default-deny except for configured host exposures (design §7.1, local names). This PR states that in the spec at the two places a reader looks for it:

  • NET-003's comment already says resolution is the requirement, not reach. It now says reach over the name is default-deny except configured host exposures, each exposure local reach under the box's egress rules: an allow-all box reaches only the exposures, a deny-all box reaches nothing. NET-134's comment carries the same reading in place of the old "local reach under the box's rules".

  • NET-004's comment now says what "route the connection as host.min.internal" means: the deprecated literal 100.64.255.254 reaches what the name reaches, and nothing more.

  • NET-062's own-address sub-clause gains a fourth opening: the hostname proxy's port on the node address while the node serves the interim proxy (design §7.1, NET-070). Own-address boxes reach the :7654 Host-header proxy at the node address, and the parity rule keeps it from granting more than the caller's own reach. The opening retires with the proxy.

  • NET-010 gains a sub-requirement: a freed host loopback address is held back from allocation for the positive answer TTL (15 s), so a client that resolved the released name cannot reach a different box at it. Its comment names the second, independent hold on the same address: NET-138's withdrawal path holds it until the host has unbound every forward the withdrawn box published there. The allocator hands the address out only after both holds clear.

  • NET-138's interim-channel comment (S10a/AC1): the interim answerer's channel is per user. A helper under another state dir of the same operator publishes into it instead of binding, and the channel admits peers of the same user, plus root for the release verbs only.

NET-003, NET-004, NET-134 and NET-138 change only in their comments; NET-010's hold and NET-062's opening are the normative changes.

Why

#1943 (T79, NET-062's own-address sub-clause) enforces the default on the native relay, which also runs inside the VM on VM-backed hosts. The e2e's NET-003 own-address connect and NET-004 reach assertions relied on the alias being open under a box's own rules. #1943 narrows them, and this PR records the reading they now follow.

Follow-ups, tracked separately: host-exposure configuration, and VM host gate parity with the deprecation notice on a drop.

NET-003 and NET-004 now say, in their comments, that box-to-host reach over
host.min.internal and the deprecated literal is default-deny except
configured host exposures (design 7.1), so the literal grants nothing the
name does not.
@coderabbitai

coderabbitai Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

  • Run on-demand review

This review includes 1 billable file and costs up to $0.25.

  • Ask an admin to make reviews automatic

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Or wait 48 seconds for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Essentials
  • Run ID: c7fc14d2-1140-46c5-b462-0cb9823d92c3
📥 Commits

Reviewing files that changed from the base of the PR and between b43f375 and 32c6e3c.

📒 Files selected for processing (1)
  • docs/specs/18-spec-box-networking/18-spec-box-networking.md
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

Spec lint

docs/specs/18-spec-box-networking/18-spec-box-networking.md — 11 finding(s)

docs/specs/18-spec-box-networking/18-spec-box-networking.md:159: P004 NET-009 names test 'native_resolution_without_proxy_env', which was not found in the repository
docs/specs/18-spec-box-networking/18-spec-box-networking.md:308: P004 NET-040 names test 'fresh_install_own_ip_ingress_publishes_loopback', which was not found in the repository
docs/specs/18-spec-box-networking/18-spec-box-networking.md:313: P004 NET-041 names test 'installer_switch_binary_executable', which was not found in the repository
docs/specs/18-spec-box-networking/18-spec-box-networking.md:351: P004 NET-048 names test 'linux_amd64_manifest_ships_vm_stack', which was not found in the repository
docs/specs/18-spec-box-networking/18-spec-box-networking.md:356: P004 NET-049 names test 'fresh_linux_kvm_activate_local_minvmd', which was not found in the repository
docs/specs/18-spec-box-networking/18-spec-box-networking.md:361: P004 NET-050 names test 'linux_arm64_manifest_ships_vm_stack', which was not found in the repository
docs/specs/18-spec-box-networking/18-spec-box-networking.md:366: P004 NET-051 names test 'fresh_arm64_kvm_activate_local_minvmd', which was not found in the repository
docs/specs/18-spec-box-networking/18-spec-box-networking.md:673: P004 NET-139 names test 'vsock_rpc_refuses_non_host_cid', which was not found in the repository
docs/specs/18-spec-box-networking/18-spec-box-networking.md:690: P004 NET-132 names test 'proxy_sees_each_vm_box_by_its_switch_address', which was not found in the repository
docs/specs/18-spec-box-networking/18-spec-box-networking.md:716: P004 NET-134 names test 'deny_all_box_reaches_proxy_and_no_other_host_port', which was not found in the repository
docs/specs/18-spec-box-networking/18-spec-box-networking.md:740: P004 NET-107 names test 'session_outbound_request', which was not found in the repository

Advisory. None of this blocks the merge; the review decides.

Advisory, and never a merge gate. Linter: gominimal/foundry@f38dff3e, spec format: How Minimal Writes Specs.

NET-062's own-address sub-clause gains a fourth opening: the hostname proxy's
port on the node address, while the node serves the interim proxy (design
7.1, NET-070). Box callers reach the :7654 proxy there, and the proxy grants
nothing beyond the caller's own reach.
@norrietaylor norrietaylor changed the title docs(specs): state that the host alias and its literal are default-deny docs(specs): settle box reach to the host alias and the node address Oct 4, 2026
NET-010 gains a sub-requirement: a freed host loopback address stays out of
allocation for the 15 s positive answer TTL, so a client that resolved the
old name never reaches a different box. Its comment records allocation
through the answerer channel from .2 upward.
@norrietaylor
norrietaylor marked this pull request as ready for review October 6, 2026 05:31
@norrietaylor
norrietaylor requested a review from a team as a code owner October 6, 2026 05:31
@minimal-foundry

minimal-foundry Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Approved: no findings at 32c6e3c55161.

Nothing to do.

Clobber: none: git log on the file shows no recent fix reverted. The prior commit 059f2a6c ("allocate a freed address only once both of its holds clear") introduced the NET-010 sub-clause on this branch, and this PR's diff extends its comment to name the NET-138 hold — consistent, not a revert.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 2 findings, 2 inline.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 2 findings, 2 inline.

@norrietaylor
norrietaylor added this pull request to the merge queue Oct 7, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Oct 7, 2026
NET-003's comment kept "local reach under the box's egress rules" beside
the new default-deny clause, so an allow-all box read two ways, and
NET-134's comment still carried the old reading. Both now say box→host
reach over the name is default-deny except configured host exposures,
each exposure local reach under the box's rules.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — approved

Verdict APPROVE — No findings.

@minimal-foundry minimal-foundry Bot added the review:approved minimal-review approved the current head label Oct 8, 2026
@norrietaylor
norrietaylor added this pull request to the merge queue Oct 8, 2026
Merged via the queue into main with commit 99d1abd Oct 8, 2026
38 checks passed
@norrietaylor
norrietaylor deleted the docs/net-004-host-alias-default-deny branch October 8, 2026 21:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:approved minimal-review approved the current head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants