Skip to content

docs(specs): add the minimald mesh ingress spec for the remote sessions epic - #1356

Closed
mitodrummer wants to merge 7 commits into
mainfrom
docs/spec-minimald-mesh-ingress
Closed

mitodrummer wants to merge 7 commits into
mainfrom
docs/spec-minimald-mesh-ingress

Conversation

@mitodrummer

@mitodrummer mitodrummer commented Sep 4, 2026 •

Copy link
Copy Markdown
Member

Supersession, narrowed. The deployment and egress-gateway design (specs/networking/deployment-and-egress-gateway.md) now owns the transport mechanism. On a pinned host the mesh and attach paths transit the node's Egress Gateway, which forwards in a role the design calls exactly a D7 relay (§4.5). What the networking spec in preparation is expected to take from this document is the daemon's side of that design (§4.1, §4.5): the relay leg and path choice (MMI-008, MMI-009). Whether the relay group follows minrelay depends on the consolidation the design leaves open (§12, item 1). The authentication surface (MMI-020 to MMI-039), terminal state (MMI-051 to MMI-055) and heartbeats (MMI-060, MMI-061) stay here either way.

Summary

The daemon side of the remote-sessions epic's browser story, and the relay that reaches a daemon behind NAT: WireGuard over a TLS WebSocket terminating SSH at the daemon's own tunnel address; a Certified state admitted only on an identity-plane certificate, with the arch's decision function and vectors; owner-only reads and mutations in v1 as the ratified interim for Gatehouse §7.4's sessions-are-boxes mapping; the reaper, KRL feed and revocation; a repaint on every re-attach, named close signals, detached-not-exited on transport loss, and an attachment state in the listing; heartbeats to the identity plane; and minrelay, a stateless forwarder of ciphertext with DPoP-bound tickets. Forty-one requirements, eighteen at T1 with exhaustive properties over finite domains.

Concision pass on 2026-09-09 against the box-provider abstraction spec's shape (gominimal/arch#45): 1,068 lines to 844, Design reasoning as one paragraph per decision, the "what exists today" inventory removed, every open question saying why it survives.

Gatehouse v1.17 and the gateway design (2026-09-10)

  • Heartbeat. MMI-061 carries exactly the §8.2 payload, now with reachability.egw (gateway id, the node's WireGuard key, transport) while a gateway association is up, and addresses ({box_id, addr, epoch} per assigned box address). The interim superset is gone from the heartbeat; that status answers GetMeshStatus alone, which gains the gateway id and association state. MMI-060 reports gateway-association changes and box address assignments within its 5 s.
  • Relay as the gateway's role. A new Design reasoning paragraph frames MMI-071 to MMI-077 as the contract a gateway's forwarding role keeps, with the association in place of MMI-070's registration.
  • T30. A new security invariant covers a compromised relay or gateway on the attach path (Gatehouse T29, T30).
  • Scope. Box address assignment and the gateway association are the deployment design's (§4.1, §4.2), implemented daemon-side by the networking spec. MMI only reports their state. The §6.9 peer document gained no member in v1.17, so MMI-010 and MMI-011 are unchanged.
  • Housekeeping. The status field is dropped (docs(specs): refresh TEMPLATE.md; there is no status field #1368), and the networking citations are now the two documents instead of their issues.

No requirement retired, no ID added. 844 lines to 901.

Retirements

Traceable to no acceptance criterion and no recorded decision; each has a Non-goal with a destination, and no ID is reused:

  • MMI-004 (switch routing unchanged) and MMI-012 (no topology in a drop's log line): restated 03-spec-networking R4.2 and R4.5.
  • MMI-050 and MMI-052 (scrollback retention and replay): no v1 client consumes them; MCC-061 declares no request.
  • MMI-074 (per-node and per-key connection caps): operator configuration. MMI-075 narrowed to the N8-parity budget on unauthenticated opens, which the architecture names; its per-connection frame and byte budget goes with MMI-074.
  • MMI-N01 and MMI-N02 (repaint and forwarding latency bounds): the POC's loopback numbers, no bound decided.
  • Sub-bullets dropped: MMI-039's world-readable key-file check, MMI-070's 90 s keepalive.

Siblings

  • Client core, MCC: docs(specs): add the shared min client core spec for the remote sessions epic #1355.
  • Browser client, WMC: gominimal/webapp#763.
  • Identity plane: Gatehouse v1.17 (§5.3, §5.7, §6.9, §6.11, §7.4, §8.2), architecture D7 and D8.
  • Networking: specs/networking/networking-requirements.md (v2) and specs/networking/deployment-and-egress-gateway.md (v0.2), the inputs of the spec that implements the daemon side. The box-provider abstraction spec (gominimal/arch#45) states the provider's side of readiness (BPA-015) and the data path (BPA-023).

Open questions

Nine. HIGH: whether the relay leg, path choice and relay group fold into the networking spec; the 03-spec-networking Unit 4 amendment. MEDIUM: the ticket's missing mesh-key claim; how a relay reaches a pinned node whose home relay is its gateway (new); the owner subject's provenance; the sandbox username; GetMeshStatus under Certified; on_detach on a dead channel. LOW: source-address enforcement. The heartbeat-superset question is closed: the heartbeat now sends exactly §8.2.

Verification

spec-lint from the installed foundry plugin (spec@foundry 0.3.0): 41 P004 findings, one per named test not yet written, and one F004 for the dropped status field. Foundry main has removed that rule, matching #1368. Self-scored against the spec-review rubric: every covered by: requirement is T1 or argued as a scenario in the Tiers paragraph, no requirement sits on an open question without saying so, and every non-goal has a destination.

🤖 Generated with Claude Code

https://claude.ai/code/session_019SN7GPDMfE3DbTayuqfnQG

…ns epic

The daemon-side spec for gominimal/inbox#513's browser story: a
WireGuard-over-WebSocket ingress beside the existing UDP mesh socket,
termination of the daemon's own tunnel address at its SSH server, a
Certified auth state with certificate decisions that refuse with the
architecture vectors' codes, a per-auth-state RPC allowlist with owner
gated rename and a new StopSession, host certificates, the reaper and
the KRL, named exit signals for supersession and daemon-initiated
closes, detach on transport loss, a framed repaint with scrollback on
re-attach, heartbeats to the control plane, and the relay tier as a new
minrelay binary. Sibling of 13-spec-min-client-core and gominimal/webapp's
browser client spec.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0159ootRPxktgkfcByca684y
@coderabbitai

coderabbitai Bot commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

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

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

Spec lint

docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md — 41 finding(s)

docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:104: P004 MMI-001 names test 'mesh_ingress_ws_frames_reach_the_same_tunnels', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:109: P004 MMI-002 names test 'wg_route_needs_no_client_certificate', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:116: P004 MMI-003 names test 'own_address_terminates_at_the_ssh_server', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:123: P004 MMI-005 names test 'cryptokey_routing_drops_out_of_policy_packets', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:130: P004 MMI-006 names test 'dead_transport_ends_carried_ssh_connections', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:136: P004 MMI-007 names test 'no_inbound_mesh_listener_without_opt_in', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:147: P004 MMI-008 names test 'relay_client_registers_with_sshpop_host', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:159: P004 MMI-009 names test 'direct_endpoint_preferred_over_relay', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:168: P004 MMI-010 names test 'peer_admitted_only_against_a_valid_binding', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:186: P004 MMI-011 names test 'static_peer_table_admits_listed_keys_only', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:194: P004 MMI-020 names test 'mesh_connection_is_never_local', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:200: P004 MMI-021 names test 'auth_none_refused_on_mesh_ingress', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:216: P004 MMI-022 names test 'cert_decision_matches_the_arch_vectors_at_the_fixed_clock', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:232: P004 MMI-023 names test 'session_owner_is_the_creating_subject_or_the_node_subject', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:241: P004 MMI-024 names test 'subject_form_username_is_refused', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:250: P004 MMI-025 names test 'owner_subject_rule_admits_only_the_owner', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:264: P004 MMI-026 names test 'decision_cache_miss_fails_closed_when_the_sts_is_unreachable', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:278: P004 MMI-027 names test 'rpc_allowlist_by_auth_state', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:293: P004 MMI-028 names test 'stop_session_ends_the_process_and_keeps_the_record', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:300: P004 MMI-029 names test 'host_certificate_presented_on_mesh_ingress', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:316: P004 MMI-031 names test 'reaper_closes_at_valid_before_and_the_session_survives', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:330: P004 MMI-033 names test 'rejection_delay_zero_initial_then_one_second', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:336: P004 MMI-034 names test 'krl_reader_reproduces_expected_revoked', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:350: P004 MMI-035 names test 'krl_feed_rejects_a_regressed_seq_across_restart', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:363: P004 MMI-037 names test 'revoked_serial_terminates_a_live_connection', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:370: P004 MMI-038 names test 'absent_auth_config_refuses_every_publickey_offer', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:380: P004 MMI-039 names test 'microvm_reads_auth_config_from_the_state_volume', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:394: P004 MMI-051 names test 'reattach_lands_on_the_current_screen_in_one_frame', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:404: P004 MMI-053 names test 'second_attach_supersedes_the_first_with_a_signal', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:421: P004 MMI-054 names test 'transport_loss_leaves_the_session_running_and_reattachable', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:429: P004 MMI-055 names test 'list_sessions_reports_attachment_state_and_last_activity', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:441: P004 MMI-060 names test 'heartbeat_interval_and_state_change_within_bounds', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:463: P004 MMI-061 names test 'heartbeat_carries_no_session_data', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:478: P004 MMI-070 names test 'node_registration_requires_sshpop_host', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:495: P004 MMI-071 names test 'ticket_bound_to_dpop_key_required', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:506: P004 MMI-072 names test 'frames_forwarded_verbatim_in_order', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:517: P004 MMI-073 names test 'restart_recovers_with_no_persisted_state', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:523: P004 MMI-075 names test 'rate_limit_closes_abusive_connection', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:530: P004 MMI-076 names test 'relay_logs_metadata_only', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:539: P004 MMI-077 names test 'frames_are_addressed_by_client_mesh_key', which was not found in the repository
docs/specs/14-spec-minimald-mesh-ingress/14-spec-minimald-mesh-ingress.md:602: P004 MMI-N05 names test 'unconfigured_daemon_opens_no_mesh_socket', 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@1d6b0403, spec format: How Minimal Writes Specs.

mitodrummer and others added 2 commits September 4, 2026 23:11
The arch stack that closed gominimal/arch#16 to #22 landed on main on
2026-09-07. Bind MMI to the sections instead of the issues: the relay tier
as architecture D7 with `sshpop-host` registration against the `relays`
member of `gatehouse_node_endpoints` and the ticket's claim set (§6.9,
T29), the daemon's mirror view of the peer document (§6.9 v1.14, MMI-010),
`POST /v1/nodes/heartbeat` with the 60 s cadence, 30 s floor, monotonic
`seq` and `reachability` shape (§8.2, MMI-060, MMI-061), sessions as boxes
with the ownership interim ratified (§7.4, MMI-025 to MMI-028), host-cert
principals as the canonical name and wildcard only, never the tunnel
address (§5.3, MMI-029), and the §5.7 wall-warning rule (MMI-031). The
ticket carries no mesh key, so MMI-071 takes it from the §6.9 binding the
client presents beside the ticket. Remove the seven resolved open
questions, keep the Unit 4 amendment as this repo's own, and add two: a
`wg_pub` claim in the ticket, and the heartbeat payload superset.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019SN7GPDMfE3DbTayuqfnQG
@mitodrummer
mitodrummer force-pushed the docs/spec-minimald-mesh-ingress branch from 217eb90 to eda1269 Compare September 8, 2026 04:32
mitodrummer and others added 2 commits September 9, 2026 16:07
Reviewed against the foundry spec-review rubric on 2026-09-09; every
finding in its fix list is applied. Fourteen requirements that back a
security invariant move from T0 to T1 with an exhaustive property over
their finite domain (MMI-002, 007, 012, 021, 023, 024, 025, 031, 035,
037, 038, 061, 076, 077); MMI-072 names the sample its property draws;
the Tiers paragraph says why the seven scenario-shaped ones stay at T0.
Reads under Certified are owner-only in v1: MMI-027's property gains the
owner condition for attach, record, screen and each listed row, and
MMI-026 defines the node-level pair and the evaluation point. The sixth
invariant excepts daemon shutdown. Non-goals gain the owner's remote
create, destroy, exec and sftp and the Sync Files Out story, both bound
by no spec yet; the One Grammar criterion is restored to the epic's
words. Configuration vocabulary defined once; the relay's close codes
named (expired, offline, replaced, over_cap, refused); owner-subject
edge cases stated; MMI-052's interim carrier named; MMI-061 marked as a
superset on the recorded assumption; Rollout and First slice name the
terminal-state group as on for every transport; mechanism clauses
dropped from MMI-001, 039, 061 and 073.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019SN7GPDMfE3DbTayuqfnQG
Concision pass against the box-provider abstraction spec's shape, plus
the note that this document may be superseded by the networking spec in
preparation (arch#46 requirements v2 and arch#39 egress-gateway design
as its inputs): one sentence in Context, a HIGH open question, and the
PR description. Retired, with a Non-goal and destination each, as
traceable to no acceptance criterion and no recorded decision: MMI-004
(switch routing unchanged) and MMI-012 (drop logging), both restating
03-spec-networking; MMI-050 and MMI-052 (scrollback, which no v1 client
consumes); MMI-074 (relay caps), MMI-N01 and MMI-N02 (latency bounds),
operator configuration and undecided bounds. MMI-075 narrowed to the
N8-parity budget on unauthenticated opens; MMI-039's key-file check and
MMI-070's keepalive sub-bullets dropped. Design reasoning rewritten as
one paragraph per decision with the "what exists today" inventory
removed; every open question says why it survives. 1068 lines and 48
requirements to 844 and 41; lint reports only P004.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019SN7GPDMfE3DbTayuqfnQG
mitodrummer and others added 2 commits September 10, 2026 17:10
The heartbeat (MMI-060/061) carries exactly the Gatehouse v1.17 §8.2
payload, now with the gateway association and per-box addresses with
allocation epochs; the interim superset moves to GetMeshStatus alone.
Design reasoning frames the relay contract as the gateway's forwarding
role on pinned hosts (deployment design §4.5), T30 joins T29 in the
security considerations, and the supersession note narrows to the
daemon's relay leg and path choice. Drops the status field.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019SN7GPDMfE3DbTayuqfnQG
@mitodrummer

Copy link
Copy Markdown
Member Author

Closing until local / networking story is complete.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant