Repository navigation
docs(specs): add the minimald mesh ingress spec for the remote sessions epic - #1356
Closed
mitodrummer wants to merge 7 commits into
Closed
mitodrummer wants to merge 7 commits into
mitodrummer wants to merge 7 commits into
Conversation
…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
Contributor
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: trueComment |
Contributor
Spec lint
Advisory. None of this blocks the merge; the review decides. Advisory, and never a merge gate. Linter: |
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0159ootRPxktgkfcByca684y
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
force-pushed
the
docs/spec-minimald-mesh-ingress
branch
from
September 8, 2026 04:32
217eb90 to
eda1269
Compare
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
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
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019SN7GPDMfE3DbTayuqfnQG
Member
Author
|
Closing until local / networking story is complete. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 followsminrelaydepends 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
Certifiedstate 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; andminrelay, 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)
reachability.egw(gateway id, the node's WireGuard key, transport) while a gateway association is up, andaddresses({box_id, addr, epoch}per assigned box address). The interim superset is gone from the heartbeat; that status answersGetMeshStatusalone, which gains the gateway id and association state. MMI-060 reports gateway-association changes and box address assignments within its 5 s.statusfield 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:
Siblings
specs/networking/networking-requirements.md(v2) andspecs/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;
GetMeshStatusunderCertified;on_detachon a dead channel. LOW:source-addressenforcement. The heartbeat-superset question is closed: the heartbeat now sends exactly §8.2.Verification
spec-lintfrom the installed foundry plugin (spec@foundry0.3.0): 41 P004 findings, one per named test not yet written, and one F004 for the droppedstatusfield. Foundry main has removed that rule, matching #1368. Self-scored against the spec-review rubric: everycovered 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