English
Problem
Runtime Host remote access currently depends on a Client reaching a configured endpoint. Users who want private reachability across ordinary NAT must therefore expose an endpoint or separately install, join, and operate a general-purpose overlay network.
External overlays remain valuable routes, but they do not provide a Maka-native flow in which several users can connect their Runtime Hosts through Maka alone, expose only Runtime Host traffic, and optionally help one another establish connectivity.
This issue supersedes the connectivity scope of #3801. Resource authorization and Session sharing are tracked independently in #3843.
Desired outcome
Deliver an application-scoped Runtime Host peer mesh in which devices operated by different users can:
- join through an explicit Mesh invitation;
- establish authenticated direct connections when the network permits;
- discover only Runtime Host endpoints made visible to them;
- recover from address and path changes;
- optionally provide bounded one-hop transit for other permitted peers;
- carry the existing Runtime Host protocol over an end-to-end authenticated secure stream.
The mesh is native connectivity for Maka, not a general machine network. It does not expose arbitrary ports, assign virtual IPs, or replace existing TLS, SSH, acknowledged plaintext, or external-overlay routes.
Architecture boundary
The peer mesh answers only how a Client reaches an expected Runtime Host.
It owns:
- Mesh invitation and admission;
- node authentication;
- scoped Runtime Host discovery and ephemeral reachability;
- direct connection attempts and NAT traversal;
- reconnect and bounded route diagnostics;
- optional, explicitly enabled transit.
It does not own:
- Runtime Host credentials or resource authorization;
- Session visibility, sharing, or collaboration policy;
- Owner approval or Guest execution policy;
- Runtime state, State Root replication, or cross-Host consensus;
- access to unrelated services on a participating machine.
Joining the peer mesh grants no Runtime Host authority. The target Host independently verifies its pinned transport identity and expected Root ID, authenticates the presented Runtime Host credential, and authorizes every operation.
Invitation authority boundary
A Mesh invitation authorizes only connectivity membership and scoped discovery. Its one-time payload, node identity, receipt, durable admission state, and removal authority remain independent from collaboration invitations, Guest principals, Runtime Host credentials, and Session grants.
Milestone 1 creates no Mesh invitation authority; pairwise connectivity uses the existing Owner credential. If Milestone 2 is approved, removing a node from the mesh must not revoke Session grants that remain usable over TLS, SSH, or another transport. Revoking a Session grant must not remove the node from the mesh.
A future QR code or link may package opaque Mesh and collaboration invitation payloads for one scan. The Mesh and Host authorities must validate and commit their own payloads and report their own outcomes. The envelope provides no shared durable membership and no cross-authority atomicity guarantee.
Identity and control state
The design distinguishes:
- State Root identity;
- the target Host's pinned transport identity;
- node identity used for peer connectivity;
- admission to a particular peer mesh;
- Host-local resource credentials and grants.
No additional provider-neutral Host ID is introduced without a concrete invariant that existing target verification cannot express.
Admission, removal, discovery, and reachability need defined security semantics, but this tracker does not prescribe a global membership database, gossip protocol, distributed consensus, or CRDT. Those mechanisms must be justified by measured prototypes and the smallest design that satisfies the product outcome.
Transit model
The first transit capability is deliberately bounded:
- at most one transit hop;
- available only to explicitly permitted peers;
- disabled unless a node operator opts in;
- limited by connection, bandwidth, duration, and health policy;
- end-to-end encrypted and authenticated between Client and target Host;
- unable to grant or exercise Runtime Host authority;
- never an open or public Relay.
A route may be direct, use an explicitly permitted mesh transit, or use an existing external overlay. No route is guaranteed to be available, and the product must report an unreachable topology honestly.
Current gate
Only Milestone 1 is approved for implementation and prototyping. Milestones 2 and 3 describe the intended direction; they do not inherit approval from this tracker or from Milestone 1.
Before either later milestone starts, evidence from the preceding milestone must be reviewed to justify its product value, supported network behavior, security semantics, and added complexity.
Staged delivery
Milestone 1: Pairwise direct peer
- Pair one Client with one expected Host.
- Establish an authenticated secure stream using pinned Host identity, expected Root ID, and the existing Runtime Host credential.
- Measure NAT traversal, reconnect, diagnostics, and cross-platform behavior.
- Ship only as experimental until supported network topologies are evidenced.
Milestone 2: Multi-peer mesh
- Allow multiple independently operated nodes to participate.
- Add a Maka-native Mesh invitation with scoped discovery, removal, and recovery semantics.
- Keep connectivity membership independent from Runtime Host resource authority.
Milestone 3: Cooperative transit
- Validate one consenting node carrying an end-to-end encrypted Runtime Host stream between two permitted peers.
- Define resource limits, operator controls, diagnostics, and failure behavior.
- Treat transit as optional capacity, not a public-service or availability promise.
Each milestone is independently reviewable and must earn the next one. Provider selection follows measured evidence; Maka does not invent a new cryptographic transport protocol.
Acceptance criteria
- Pairwise direct connectivity can be delivered and evaluated independently of the later mesh milestones.
- Devices operated by different users can explicitly participate in the same private Runtime Host peer mesh.
- A Mesh invitation never creates a Guest principal, Runtime Host credential, or Session grant.
- Mesh removal and Session-grant revocation remain independent across every transport.
- Joining the mesh does not reveal a Runtime Host until that Host independently authenticates and authorizes the Client.
- Only authorized Runtime Host endpoints are discoverable; unrelated machine services are not exposed.
- A Client can reach the expected Host directly when the tested topology permits it.
- With three nodes, a Client can reach a target through one consenting transit node when no direct route is available.
- A transit node cannot read Runtime Host application plaintext or use transit authority to operate the target Host.
- Removing a peer prevents future mesh connectivity after the relevant control state propagates.
- Address changes and transient disconnects recover without silently retargeting a Host profile.
- An unreachable topology fails clearly without claiming guaranteed connectivity.
- Existing Local, TLS, SSH, acknowledged plaintext, and external-overlay routes do not regress.
Non-goals
- A general-purpose VPN or tailnet
- Arbitrary IP or port connectivity between participating machines
- Session sharing or collaboration permissions
- A unified invitation, identity, membership, receipt, or revocation authority spanning connectivity and Runtime resources
- Atomic commit across Mesh and collaboration invitation payloads
- Federated Runtime execution or replicated State Roots
- A distributed SQL/CRDT authority
- Arbitrary multi-hop routing in the first implementation
- Public discovery of arbitrary Hosts
- An Apache-operated production Relay or SLA
- Replacing existing external overlays
- Selecting a provider before measured cross-platform prototypes
简体中文
问题
当前 Runtime Host 远程访问依赖 Client 能够连接一个配置好的 endpoint。希望跨普通 NAT 私密连接的用户必须暴露 endpoint,或者额外安装、加入并维护一个通用 overlay network。
External overlay 仍然是有价值的 route,但它不能提供 Maka 原生流程:多个用户只使用 Maka 就能连接各自的 Runtime Hosts、只暴露 Runtime Host 流量,并可选地帮助彼此建立连接。
本 issue 替代 #3801 中的 connectivity 范围。资源授权与 Session sharing 由 #3843 独立跟踪。
期望结果
交付一个 application-scoped Runtime Host peer mesh,使不同用户运营的设备能够:
- 通过明确的 Mesh invitation 加入;
- 在网络条件允许时建立经过认证的 direct connection;
- 只发现对其可见的 Runtime Host endpoints;
- 从地址和路径变化中恢复;
- 可选地为获准 peers 提供有界的单跳 transit;
- 在端到端认证的安全连接上承载现有 Runtime Host protocol。
该 mesh 是 Maka 原生连接能力,不是通用机器网络。它不暴露任意端口、不分配虚拟 IP,也不替换现有 TLS、SSH、acknowledged plaintext 或 external-overlay routes。
架构边界
Peer mesh 只回答:Client 如何到达预期 Runtime Host。
它负责:
- Mesh invitation 与 admission;
- node authentication;
- scoped Runtime Host discovery 与临时 reachability;
- direct connection 与 NAT traversal;
- reconnect 与有界 route diagnostics;
- 可选且明确开启的 transit。
它不负责:
- Runtime Host credentials 或资源授权;
- Session visibility、sharing 或 collaboration policy;
- Owner approval 或 Guest execution policy;
- Runtime state、State Root 复制或跨 Host 共识;
- 访问参与设备上的无关服务。
加入 peer mesh 不授予任何 Runtime Host authority。目标 Host 仍独立验证固定的 transport identity 和 expected Root ID,认证所提供的 Runtime Host credential,并授权每个 operation。
Invitation authority 边界
Mesh invitation 只授权 connectivity membership 和 scoped discovery。它的 one-time payload、node identity、receipt、durable admission state 和 removal authority,必须与 collaboration invitation、Guest principal、Runtime Host credential 和 Session grant 永久独立。
Milestone 1 不建立 Mesh invitation authority;pairwise connectivity 使用现有 Owner credential。如果 Milestone 2 获得批准,将 node 移出 mesh 不得撤销仍可通过 TLS、SSH 或其他 transport 使用的 Session grant;撤销 Session grant 也不得将 node 移出 mesh。
未来一个 QR code 或 link 可以封装 opaque Mesh 与 collaboration invitation payload,以提供一次扫码体验。Mesh 与 Host authorities 必须分别验证并提交各自 payload,并分别报告结果;该 envelope 不提供共享 durable membership,也不保证跨 authority 原子性。
身份与控制面状态
设计区分:
- State Root identity;
- 目标 Host 固定的 transport identity;
- 用于 peer connectivity 的 node identity;
- 特定 peer mesh 的 admission;
- Host-local resource credential 与 grant。
在没有现有 target verification 无法表达的明确不变量前,不增加额外的 provider-neutral Host ID。
Admission、removal、discovery 和 reachability 需要明确的安全语义,但本 tracker 不预设全局 membership database、gossip protocol、distributed consensus 或 CRDT。相关机制必须由可度量 prototype 证明,并采用满足产品结果的最小设计。
Transit 模型
第一版 transit 能力有意保持有界:
- 最多一个 transit hop;
- 只服务明确获准的 peers;
- node operator 未主动开启时保持关闭;
- 受连接数、带宽、持续时间和健康策略限制;
- Client 与目标 Host 之间保持端到端加密和认证;
- 不能授予或行使 Runtime Host authority;
- 永远不成为 open 或 public Relay。
Route 可以是 direct、经过明确允许的 mesh transit,或使用现有 external overlay。任何 route 都不保证一定可用,产品必须诚实报告不可达拓扑。
当前阶段门
当前只批准 Milestone 1 进入实施和 prototype。Milestone 2 和 3 描述预期方向,不会从本 tracker 或 Milestone 1 自动继承批准。
任何后续 milestone 开始前,都必须重新审查上一阶段证据,并分别证明其产品价值、支持的网络行为、安全语义和新增复杂度合理。
分阶段交付
Milestone 1:Pairwise direct peer
- 将一个 Client 与一个预期 Host 配对。
- 使用固定 Host identity、expected Root ID 和现有 Runtime Host credential 建立经过认证的安全连接。
- 度量 NAT traversal、reconnect、diagnostics 和跨平台行为。
- 在支持的网络拓扑得到证据前只作为 experimental 能力交付。
Milestone 2:Multi-peer mesh
- 允许多个独立运营的 nodes 参与。
- 增加 Maka 原生 Mesh invitation、scoped discovery、removal 和 recovery 语义。
- 连接 membership 与 Runtime Host resource authority 保持独立。
Milestone 3:Cooperative transit
- 验证一个自愿节点在两个获准 peers 之间承载端到端加密 Runtime Host stream。
- 定义资源限制、operator controls、diagnostics 和失败行为。
- 把 transit 视为可选容量,而不是公共服务或可用性承诺。
每个 milestone 都可独立审查,并必须证明进入下一阶段的价值。Provider 选择由度量证据决定;Maka 不发明新的加密传输协议。
验收标准
- Pairwise direct connectivity 可以独立于后续 mesh milestones 交付和评估。
- 不同用户运营的设备可以明确参与同一个私有 Runtime Host peer mesh。
- Mesh invitation 永远不会创建 Guest principal、Runtime Host credential 或 Session grant。
- Mesh removal 与 Session-grant revocation 在所有 transport 上保持独立。
- 加入 mesh 后,只有目标 Runtime Host 独立认证并授权 Client,才会暴露该 Host。
- 只能发现获准的 Runtime Host endpoints,不暴露设备上的无关服务。
- 在测试拓扑允许时,Client 可以 direct 连接预期 Host。
- 在三个节点场景中,无法直连时 Client 可以通过一个自愿 transit node 到达目标。
- Transit node 无法读取 Runtime Host 应用明文,也不能使用 transit authority 操作目标 Host。
- 移除 peer 后,相关控制状态传播完成时会阻止后续 mesh 连接。
- 地址变化和暂时断线可以恢复,且不会静默 retarget Host profile。
- 无法连接的拓扑会明确失败,而不是声称保证可达。
- 现有 Local、TLS、SSH、acknowledged plaintext 和 external-overlay routes 不回归。
非目标
- 通用 VPN 或 tailnet
- 参与设备之间的任意 IP 或端口连接
- Session sharing 或 collaboration permissions
- 横跨 connectivity 与 Runtime resource 的统一 invitation、identity、membership、receipt 或 revocation authority
- Mesh 与 collaboration invitation payload 的跨 authority 原子提交
- Federated Runtime execution 或复制 State Root
- Distributed SQL/CRDT authority
- 第一版支持任意多跳路由
- 公开发现任意 Hosts
- Apache 运营的生产 Relay 或 SLA
- 替换现有 external overlays
- 在完成跨平台度量 prototype 前选择 provider
English
Problem
Runtime Host remote access currently depends on a Client reaching a configured endpoint. Users who want private reachability across ordinary NAT must therefore expose an endpoint or separately install, join, and operate a general-purpose overlay network.
External overlays remain valuable routes, but they do not provide a Maka-native flow in which several users can connect their Runtime Hosts through Maka alone, expose only Runtime Host traffic, and optionally help one another establish connectivity.
This issue supersedes the connectivity scope of #3801. Resource authorization and Session sharing are tracked independently in #3843.
Desired outcome
Deliver an application-scoped Runtime Host peer mesh in which devices operated by different users can:
The mesh is native connectivity for Maka, not a general machine network. It does not expose arbitrary ports, assign virtual IPs, or replace existing TLS, SSH, acknowledged plaintext, or external-overlay routes.
Architecture boundary
The peer mesh answers only how a Client reaches an expected Runtime Host.
It owns:
It does not own:
Joining the peer mesh grants no Runtime Host authority. The target Host independently verifies its pinned transport identity and expected Root ID, authenticates the presented Runtime Host credential, and authorizes every operation.
Invitation authority boundary
A Mesh invitation authorizes only connectivity membership and scoped discovery. Its one-time payload, node identity, receipt, durable admission state, and removal authority remain independent from collaboration invitations, Guest principals, Runtime Host credentials, and Session grants.
Milestone 1 creates no Mesh invitation authority; pairwise connectivity uses the existing Owner credential. If Milestone 2 is approved, removing a node from the mesh must not revoke Session grants that remain usable over TLS, SSH, or another transport. Revoking a Session grant must not remove the node from the mesh.
A future QR code or link may package opaque Mesh and collaboration invitation payloads for one scan. The Mesh and Host authorities must validate and commit their own payloads and report their own outcomes. The envelope provides no shared durable membership and no cross-authority atomicity guarantee.
Identity and control state
The design distinguishes:
No additional provider-neutral Host ID is introduced without a concrete invariant that existing target verification cannot express.
Admission, removal, discovery, and reachability need defined security semantics, but this tracker does not prescribe a global membership database, gossip protocol, distributed consensus, or CRDT. Those mechanisms must be justified by measured prototypes and the smallest design that satisfies the product outcome.
Transit model
The first transit capability is deliberately bounded:
A route may be direct, use an explicitly permitted mesh transit, or use an existing external overlay. No route is guaranteed to be available, and the product must report an unreachable topology honestly.
Current gate
Only Milestone 1 is approved for implementation and prototyping. Milestones 2 and 3 describe the intended direction; they do not inherit approval from this tracker or from Milestone 1.
Before either later milestone starts, evidence from the preceding milestone must be reviewed to justify its product value, supported network behavior, security semantics, and added complexity.
Staged delivery
Milestone 1: Pairwise direct peer
Milestone 2: Multi-peer mesh
Milestone 3: Cooperative transit
Each milestone is independently reviewable and must earn the next one. Provider selection follows measured evidence; Maka does not invent a new cryptographic transport protocol.
Acceptance criteria
Non-goals
简体中文
问题
当前 Runtime Host 远程访问依赖 Client 能够连接一个配置好的 endpoint。希望跨普通 NAT 私密连接的用户必须暴露 endpoint,或者额外安装、加入并维护一个通用 overlay network。
External overlay 仍然是有价值的 route,但它不能提供 Maka 原生流程:多个用户只使用 Maka 就能连接各自的 Runtime Hosts、只暴露 Runtime Host 流量,并可选地帮助彼此建立连接。
本 issue 替代 #3801 中的 connectivity 范围。资源授权与 Session sharing 由 #3843 独立跟踪。
期望结果
交付一个 application-scoped Runtime Host peer mesh,使不同用户运营的设备能够:
该 mesh 是 Maka 原生连接能力,不是通用机器网络。它不暴露任意端口、不分配虚拟 IP,也不替换现有 TLS、SSH、acknowledged plaintext 或 external-overlay routes。
架构边界
Peer mesh 只回答:Client 如何到达预期 Runtime Host。
它负责:
它不负责:
加入 peer mesh 不授予任何 Runtime Host authority。目标 Host 仍独立验证固定的 transport identity 和 expected Root ID,认证所提供的 Runtime Host credential,并授权每个 operation。
Invitation authority 边界
Mesh invitation 只授权 connectivity membership 和 scoped discovery。它的 one-time payload、node identity、receipt、durable admission state 和 removal authority,必须与 collaboration invitation、Guest principal、Runtime Host credential 和 Session grant 永久独立。
Milestone 1 不建立 Mesh invitation authority;pairwise connectivity 使用现有 Owner credential。如果 Milestone 2 获得批准,将 node 移出 mesh 不得撤销仍可通过 TLS、SSH 或其他 transport 使用的 Session grant;撤销 Session grant 也不得将 node 移出 mesh。
未来一个 QR code 或 link 可以封装 opaque Mesh 与 collaboration invitation payload,以提供一次扫码体验。Mesh 与 Host authorities 必须分别验证并提交各自 payload,并分别报告结果;该 envelope 不提供共享 durable membership,也不保证跨 authority 原子性。
身份与控制面状态
设计区分:
在没有现有 target verification 无法表达的明确不变量前,不增加额外的 provider-neutral Host ID。
Admission、removal、discovery 和 reachability 需要明确的安全语义,但本 tracker 不预设全局 membership database、gossip protocol、distributed consensus 或 CRDT。相关机制必须由可度量 prototype 证明,并采用满足产品结果的最小设计。
Transit 模型
第一版 transit 能力有意保持有界:
Route 可以是 direct、经过明确允许的 mesh transit,或使用现有 external overlay。任何 route 都不保证一定可用,产品必须诚实报告不可达拓扑。
当前阶段门
当前只批准 Milestone 1 进入实施和 prototype。Milestone 2 和 3 描述预期方向,不会从本 tracker 或 Milestone 1 自动继承批准。
任何后续 milestone 开始前,都必须重新审查上一阶段证据,并分别证明其产品价值、支持的网络行为、安全语义和新增复杂度合理。
分阶段交付
Milestone 1:Pairwise direct peer
Milestone 2:Multi-peer mesh
Milestone 3:Cooperative transit
每个 milestone 都可独立审查,并必须证明进入下一阶段的价值。Provider 选择由度量证据决定;Maka 不发明新的加密传输协议。
验收标准
非目标