[Tracking] Peer connectivity and scoped Runtime Host sharing

[M4n5ter]

English

Problem

Runtime Host remote access currently assumes that a Client can directly reach a configured endpoint and that an authenticated remote Client acts as an owner-like principal.

This leaves two product goals unsolved:

1. A user should be able to reach their Host without exposing a public endpoint, configuring port forwarding, or depending on direct network reachability.
2. A Host owner should be able to share selected Sessions with another person without exposing the rest of the Host, its Projects, settings, credentials, or filesystem.

These goals cannot be implemented safely by adding p2p as another transport kind or by treating every paired peer as a remote owner.

The current model also binds a Host profile to one connection method and endpoint. Adaptive connectivity may move among LAN, direct, NAT-traversed, relayed, TLS, or SSH paths without changing the logical Host.

This issue intentionally opens a new multi-principal, resource-scoped access phase beyond the remote-owner scope completed in #2522.

Related:

• [Tracking] Runtime Host remote access and production hardening #2522
• Runtime Host architecture

Desired outcome

Runtime Host becomes a privately reachable execution node that:

• is identified independently of its current network address or connectivity provider;
• can be reached through automatic direct or relayed connectivity;
• supports multiple independently authenticated users and devices;
• lets the owner share explicit Sessions with bounded permissions;
• keeps all authorization, approval, execution, and projection decisions inside the Host;
• preserves the existing Runtime Host protocol, canonical state, recovery, and single-writer authority.

“Share your Host” is a product entry point. It does not imply Host-wide access: the actual authority is always an explicit resource grant.

Architecture thesis

Connectivity answers how a Client reaches a Host.

Authentication answers which user and device connected.

Authorization answers which resources that user may observe or change.

Execution policy answers what Runtime work an accepted intent may cause.

These layers must remain independent:

User
  └─ Device
       │ authenticate
       ▼
Peer Connectivity
  LAN / Direct / Hole Punching / Relay
       │ secure stream
       ▼
Runtime Host
  ├─ Connection authentication
  ├─ Access Authority
  ├─ Session and Interaction authority
  └─ Runtime execution under an Owner-controlled policy

A connectivity provider such as iroh or libp2p is replaceable. Replacing it must not require migrating Host identity, users, Share Grants, or Sessions.

Identity model

The system distinguishes:

Identity	Meaning
Host ID	Stable Maka-owned identity of one Host installation
Root ID	Identity of the durable State Root
Subject ID	Host-local identity of a person or member
Device ID	Cryptographic identity of one device acting for a subject
Provider address	Replaceable iroh Endpoint ID, libp2p Peer ID, relay address, URL, or SSH target

Host ID must not be defined by an iroh Endpoint ID or libp2p Peer ID. A provider identity may reuse or be cryptographically bound to the Maka Host key, but it does not become the application identity.

A profile identifies a logical Host target, not one route:

Host target:
  Host ID
  Root ID
  display name
  membership reference

Connectivity state:
  provider
  route hints
  current direct/relay path
  latency and readiness

Route state is ephemeral. A network change or provider migration does not create a new Host profile or invalidate a Share Grant.

Connectivity boundary

Peer connectivity provides one narrow capability: an authenticated, encrypted, bidirectional stream to the expected Host.

It owns:

• rendezvous and discovery;
• direct connection attempts;
• NAT traversal;
• relay fallback;
• path healing or reconnect;
• bounded route diagnostics.

It does not own:

• Runtime Host credentials;
• users or membership;
• Session visibility;
• Share Grants;
• Owner approvals;
• Runtime permissions.

The preferred product behavior is relay-first: establish a usable encrypted path immediately, discover a better direct path in the background, and fall back to relay if direct connectivity fails.

Rendezvous and relay infrastructure must not receive Host ACLs, Session IDs, Runtime credentials, prompts, or plaintext application traffic.

The initial implementation may tunnel the existing authenticated Runtime Host WebSocket over the peer stream. A second Runtime Host protocol or recovery model is not introduced.

Pairing and sharing are different operations

Two invitation purposes are required:

Owner pairing

• establishes another Owner device;
• requires local operator authority or confirmation by an existing Owner;
• may administer Host lifecycle, access, and sharing;
• cannot be obtained through a normal sharing invitation.

Share invitation

• identifies an intended subject;
• carries explicit Session scope, role, expiry, and approval policy;
• uses a short-lived, one-time secret;
• issues a restricted device credential after acceptance;
• never contains a durable bearer credential.

Completing peer connectivity alone grants no Runtime Host authority.

Resource authorization

Existing operation grants remain useful as a coarse protocol boundary, but they cannot express “this principal may access Sessions A and B only.”

A Share Grant is Host-owned durable state containing:

grant identity
subject identity
explicit Session scope
allowed actions
decision policy
execution policy reference
revision, status, and optional expiry

Initial sharing uses explicit Session IDs. Project-wide selectors, groups, teams, and “all future Sessions” are deferred until a concrete product need exists.

User-facing roles are presets over explicit actions:

Role	Default authority
Viewer	Observe an allowed Session
Contributor	Observe and propose messages; Owner approval required by default
Collaborator	Submit messages under a bounded Owner-controlled execution policy
Session manager	Manage sharing for that Session
Host Owner	Host administration; not granted by Session sharing

Internally, actions remain distinct, for example:

• view Session transcript and live state;
• submit a message intent;
• interrupt or stop active work;
• answer a question;
• resolve a permission interaction;
• manage Session sharing.

Each sensitive action resolves to deny, ask_owner, or allow.

“Write access” is not one permission. Submitting a message may trigger tools, filesystem access, credential use, model cost, or external effects.

Execution policy

A shared principal cannot select arbitrary Host permissions merely because it may submit a message.

Every accepted Guest intent executes under an Owner-controlled policy defining the relevant boundaries, such as:

• allowed Project or workspace;
• filesystem permission mode;
• available tools and Client capabilities;
• model and usage limits;
• credential availability;
• interactions that still require Owner approval.

Host settings, provider credentials, Project paths, and unrelated tools are never projected to a shared principal unless a future explicit grant introduces that capability.

Durable approval

Owner approval is authoritative Host state, not a transient Desktop dialog.

When an action requires approval:

1. Host persists a pending Access Request containing the exact intent and a safe preview.
2. Owner Desktop, CLI, and TUI Clients receive its projection.
3. The requesting Client observes a pending state.
4. One Owner resolves it atomically.
5. Only after approval does Host admit the exact intent into the Session.
6. The decision and actor attribution are recorded.

The request survives Client disconnects, Desktop reloads, and Host recovery. Concurrent Owner responses converge on one result.

Approving one request does not create ambient future permission unless the Owner explicitly selects a broader policy.

Projection and revocation

Authorization is enforced before Host projection. A Guest never receives a complete catalog and relies on Desktop filtering.

Unauthorized principals must not learn:

• unrelated Session IDs, titles, or counts;
• Projects or Host paths;
• settings or provider configuration;
• credentials;
• unrelated interactions, usage, or diagnostics.

Unknown and unauthorized resources should normally have the same external result.

Connection authentication fixes principal and device identity. Resource authorization is evaluated dynamically for every request, subscription, and canonical rebuild.

Grant changes and revocation take effect without reconnecting:

• inaccessible subscriptions stop;
• future operations are rejected;
• pending intents are cancelled or re-evaluated;
• already committed canonical facts remain correctly attributed.

Ownership boundaries

Layer	Authority
Connectivity provider	Secure reachability and route lifecycle
Runtime Host Kernel	Connection authentication, limits, routing, operation lifecycle
Access Authority	Subjects, devices, grants, revocation, and Access Requests
Session/Interaction domains	Resource state and authorized semantic transitions
Runtime	Execution of already admitted intents
Client	Presentation, drafts, and submission of intent
Relay/rendezvous	No application authority

Share Grants and durable approval state belong to the Host State Root. Host installation identity remains separate so copying a State Root cannot silently impersonate the previous machine.

Delivery plan

Phase 1: Separate target identity from route

• Replace endpoint-defined profile identity with stable Host target identity.
• Preserve TLS, SSH, and acknowledged plaintext as route adapters.
• Keep existing user behavior unchanged.
• Define the provider-neutral secure-stream boundary.

Phase 2: Establish peer identity and owner connectivity

• Add Maka-owned Host and Client device keys.
• Implement purpose-bound Owner pairing.
• Select a connectivity provider through measured iroh/libp2p prototypes.
• Deliver relay-first connectivity, direct upgrade, reconnect, and diagnostics.
• Keep the existing Runtime Host protocol above the stream.

Phase 3: Introduce resource-scoped access

• Add subject and device membership.
• Add dynamically evaluated Session grants and immediate revocation.
• Filter catalog, snapshots, subscriptions, and diagnostics at the Host.
• Deliver read-only Session sharing first.

Phase 4: Add controlled participation

• Persist pending Access Requests.
• Add Owner approval across Desktop, CLI, and TUI.
• Admit only the exact approved intent.
• Record actor and approval attribution.

Phase 5: Add bounded collaboration

• Introduce Owner-controlled Guest execution policies.
• Support direct contribution within policy.
• Add device management, expiry, audit, rate limits, and recovery hardening.

Acceptance criteria

• A Host behind NAT is reachable without opening an inbound port.
• Relay failure and direct-path changes do not alter Runtime Host semantics.
• Replacing iroh with libp2p, or the reverse, does not migrate grants or Sessions.
• Peer connectivity never implies Owner authority.
• A shared user sees only explicitly granted Sessions.
• Read-only users cannot submit or control Runtime work.
• Approval remains pending while the Owner is offline and survives restart.
• Concurrent Owner decisions produce one canonical result.
• Revocation removes access without requiring a new profile or application restart.
• Guest execution cannot expand beyond its Owner-selected policy.
• Desktop, CLI, and TUI observe the same canonical grants and requests.
• Existing Local, TLS, SSH, and acknowledged plaintext use cases continue to work.

Concepts to delete

• Connection method or endpoint as logical Host identity
• “Paired peer means remote owner”
• Provider Peer ID as Maka user or Host identity
• Host-wide bearer credentials for shared users
• One read/write boolean for Session collaboration
• Client-side filtering of an over-broad Host projection
• Transient UI dialogs as approval authority
• Resource grants frozen into a connection for its full lifetime
• Direct-only P2P without relay fallback

Non-goals

• A federated Runtime Host or cross-Host durable database
• Cross-Host Session migration
• Public discovery of arbitrary Hosts
• A global DHT as a product requirement
• Sharing the Host filesystem, settings, or credentials
• A generic policy language in the first implementation
• Teams, organizations, groups, or Project-wide sharing in the first milestone
• Choosing iroh or libp2p before cross-platform evidence exists
• Replacing the existing Runtime Host protocol or execution authority

简体中文

问题

当前 Runtime Host 远程访问假设 Client 可以直接连接一个配置好的 endpoint，并且经过认证的远程 Client 具有接近 Owner 的权限。

这无法满足两个新的产品目标：

1. 用户无需暴露公网 endpoint、配置端口转发或依赖网络直接可达，就能连接自己的 Host。
2. Host Owner 可以把选定 Sessions 分享给其他人，同时不暴露其余 Sessions、Projects、设置、credentials 或文件系统。

不能通过增加一个 p2p transport kind，或把所有完成配对的 peer 当成 remote owner 来实现这些目标。

当前 profile 还把连接方式和 endpoint 当成 Host target 的一部分；而自适应连接可能在 LAN、直连、NAT 穿透、Relay、TLS 与 SSH 之间变化，逻辑 Host 并没有改变。

本 issue 有意识地开启 #2522 完成后的下一阶段：引入多主体和资源级权限，而不是继续扩展 remote owner。

关联：

• [Tracking] Runtime Host remote access and production hardening #2522
• Runtime Host 中文架构文档

期望结果

Runtime Host 成为一个可私密连接的执行节点：

• Host 身份独立于当前网络地址和连接实现；
• 自动通过 direct 或 Relay 连接；
• 支持多个独立认证的用户和设备；
• Owner 可以用有界权限分享明确的 Sessions；
• 所有授权、审批、执行和投影决策都由 Host 完成；
• 保留现有 Runtime Host protocol、canonical state、恢复和单写入 authority。

“Share your Host”只是产品入口，并不表示获得整台 Host 的权限；真实 authority 始终来自明确的资源 grant。

架构主张

Connectivity 回答：Client 如何到达 Host。

Authentication 回答：哪个用户的哪台设备建立了连接。

Authorization 回答：这个用户可以观察或改变哪些资源。

Execution policy 回答：被接受的意图可以触发哪些 Runtime 工作。

四层必须独立：

用户
  └─ 设备
       │ 认证
       ▼
Peer Connectivity
  LAN / Direct / Hole Punching / Relay
       │ 安全连接
       ▼
Runtime Host
  ├─ Connection authentication
  ├─ Access Authority
  ├─ Session 与 Interaction authority
  └─ 在 Owner 控制的策略下执行 Runtime 工作

iroh 或 libp2p 等连接实现必须可替换。替换 provider 不应迁移 Host identity、用户、Share Grant 或 Sessions。

身份模型

系统区分：

身份	含义
Host ID	由 Maka 持有的稳定 Host 安装实例身份
Root ID	持久 State Root 身份
Subject ID	Host 内部的一名用户或成员
Device ID	代表该用户连接的一台设备的加密身份
Provider address	可替换的 iroh Endpoint ID、libp2p Peer ID、Relay 地址、URL 或 SSH target

Host ID 不能由 iroh Endpoint ID 或 libp2p Peer ID 定义。Provider identity 可以复用 Maka Host key，或与其建立加密绑定，但不能成为应用层身份。

Profile 标识逻辑 Host，而不是某条连接路径：

Host target:
  Host ID
  Root ID
  显示名称
  membership reference

Connectivity state:
  provider
  route hints
  当前 direct/relay 路径
  延迟与 readiness

Route state 是临时状态。网络变化或 provider 迁移不会创建新 Profile，也不会让 Share Grant 失效。

Connectivity 边界

Peer connectivity 只提供一个能力：建立到预期 Host 的、经过认证和加密的双向连接。

它负责：

• rendezvous 与 discovery；
• direct connection；
• NAT traversal；
• Relay fallback；
• path healing 或 reconnect；
• 有界连接诊断。

它不负责：

• Runtime Host credentials；
• 用户或成员关系；
• Session visibility；
• Share Grant；
• Owner approval；
• Runtime permission。

产品默认应采用 Relay-first：先快速得到一条可用的加密路径，后台寻找更好的 direct path；direct 失败时退回 Relay。

Rendezvous 与 Relay 不接收 Host ACL、Session ID、Runtime credential、prompt 或明文应用数据。

第一版可以在 peer stream 上承载现有 authenticated Runtime Host WebSocket，不引入第二套 Runtime Host protocol 或恢复模型。

Owner 配对与分享是不同操作

需要两种用途严格不同的邀请：

Owner pairing

• 添加另一个 Owner device；
• 需要本机 operator authority 或已有 Owner 确认；
• 可以管理 Host lifecycle、access 与 sharing；
• 普通 share invitation 不能获得 Owner authority。

Share invitation

• 指定分享对象；
• 带有明确 Session scope、role、有效期和 approval policy；
• 使用短期、一次性 secret；
• 接受后签发受限 device credential；
• 不包含长期 bearer credential。

仅仅建立 P2P connectivity 不授予任何 Runtime Host authority。

资源授权

现有 operation grant 可以继续作为粗粒度 protocol boundary，但无法表达“该主体只能访问 Session A 和 B”。

Share Grant 是 Host 持有的 durable state，包含：

grant identity
subject identity
明确的 Session scope
允许的 actions
decision policy
execution policy reference
revision、status 与可选 expiry

第一阶段只支持明确 Session ID。Project selector、group、team 和“所有未来 Sessions”在出现明确需求前不实现。

用户可见 role 是一组明确 actions 的 preset：

角色	默认权限
Viewer	观察允许访问的 Session
Contributor	观察并提交消息意图；默认需要 Owner 批准
Collaborator	在 Owner 设定的有界 execution policy 中提交消息
Session manager	管理该 Session 的分享
Host Owner	管理 Host；不能通过 Session sharing 获得

内部 action 仍然分开，例如：

• 查看 Session transcript 和实时状态；
• 提交消息意图；
• interrupt 或 stop；
• 回答 question；
• resolve permission interaction；
• 管理 Session sharing。

每个敏感 action 的结果是 deny、ask_owner 或 allow。

“写权限”不是一个权限。提交消息可能触发工具、文件系统访问、credential 使用、模型费用或 external effect。

Execution policy

共享用户即使可以提交消息，也不能自行选择任意 Host permission。

每个 Guest intent 都在 Owner 控制的策略下执行，约束包括：

• 允许访问的 Project 或 workspace；
• filesystem permission mode；
• 可用 tools 与 Client capabilities；
• 模型和用量限制；
• credential 是否可用；
• 哪些 interaction 仍然必须询问 Owner。

除非未来增加明确 grant，否则共享用户永远不能看到 Host settings、provider credentials、Project path 或无关 tools。

持久审批

Owner approval 是 Host 的权威状态，而不是 Desktop 临时弹窗。

当某个 action 需要批准时：

1. Host 持久创建 Access Request，记录精确 intent 和安全预览。
2. Owner Desktop、CLI 与 TUI 收到投影。
3. 请求方看到 pending 状态。
4. 某个 Owner 原子 resolve。
5. 只有批准后，Host 才把精确 intent admitted 到 Session。
6. 记录决策和 actor attribution。

请求在 Client 断线、Desktop reload 和 Host recovery 后继续存在。多个 Owner 同时回答时只产生一个 canonical result。

批准一次请求不会自动授予未来权限，除非 Owner 明确选择更宽的 policy。

投影与撤销

Host 必须在 projection 前完成授权，不能把完整 catalog 发给 Guest 后依赖 Desktop 隐藏。

未授权用户不能知道：

• 其他 Session 的 ID、标题或数量；
• Project 与 Host path；
• settings 或 provider config；
• credentials；
• 无关 interactions、usage 或 diagnostics。

外部通常不应区分资源不存在和无权访问。

连接认证固定 principal 与 device identity；资源授权则对每个 request、subscription 和 canonical rebuild 动态检查。

Grant 修改和 revoke 无需重连即可生效：

• 停止无权访问的 subscriptions；
• 拒绝后续 operations；
• 取消或重新判断 pending intents；
• 已提交的 canonical facts 保留正确 attribution。

Authority 边界

层	Authority
Connectivity provider	安全可达性与 route lifecycle
Runtime Host Kernel	连接认证、限制、路由和 operation lifecycle
Access Authority	Subject、Device、Grant、撤销和 Access Request
Session/Interaction domains	资源状态与经过授权的语义迁移
Runtime	执行已经 admitted 的 intent
Client	展示、draft 和提交 intent
Relay/rendezvous	不具有应用层 authority

Share Grant 与持久 approval state 属于 Host State Root。Host 安装身份保持独立，因此复制 State Root 不会静默冒充原机器。

实施阶段

Phase 1：分离 target identity 与 route

• 用稳定 Host target 取代 endpoint-defined profile identity。
• TLS、SSH 与明确确认风险的 plaintext 保留为 route adapter。
• 不改变现有用户行为。
• 定义 provider-neutral secure-stream boundary。

Phase 2：建立 peer identity 与 Owner connectivity

• 增加 Maka 持有的 Host 与 Client device keys。
• 实现 purpose-bound Owner pairing。
• 通过可度量的 iroh/libp2p prototype 选择 provider。
• 交付 Relay-first、direct upgrade、reconnect 和 diagnostics。
• 在连接之上继续使用现有 Runtime Host protocol。

Phase 3：资源级授权

• 增加 subject/device membership。
• 增加动态计算的 Session grant 和立即 revoke。
• 在 Host 端过滤 catalog、snapshot、subscription 和 diagnostics。
• 优先交付 read-only Session sharing。

Phase 4：受控参与

• 持久化 pending Access Request。
• 在 Desktop、CLI 与 TUI 提供 Owner approval。
• 只 admitted 被精确批准的 intent。
• 记录 actor 与 approval attribution。

Phase 5：有界协作

• 增加 Owner 控制的 Guest execution policy。
• 支持 policy 范围内直接参与。
• 增加 device management、expiry、audit、rate limit 与 recovery hardening。

验收标准

• NAT 后的 Host 无需开放 inbound port 即可访问。
• Relay failure 和 direct path 变化不改变 Runtime Host semantics。
• iroh 与 libp2p 互换不需要迁移 Grant 或 Sessions。
• P2P connectivity 永远不隐式获得 Owner authority。
• 共享用户只能看到明确授权的 Sessions。
• Read-only 用户不能提交或控制 Runtime 工作。
• Owner 离线时 approval 保持 pending，并在重启后恢复。
• 多个 Owner 的并发决策产生一个 canonical result。
• Revoke 无需创建新 Profile 或重启应用即可生效。
• Guest execution 不能超出 Owner 设定的 policy。
• Desktop、CLI 与 TUI 观察同一份 canonical Grant 和 Access Request。
• 现有 Local、TLS、SSH 与 acknowledged plaintext 场景继续工作。

应删除的概念

• 把 connection method 或 endpoint 当作逻辑 Host identity
• “完成 peer pairing 就是 remote owner”
• 把 provider Peer ID 当作 Maka User 或 Host identity
• 给共享用户发放 Host-wide bearer credential
• 用一个 read/write boolean 表示 Session collaboration
• Client 过滤过宽的 Host projection
• 把临时 UI dialog 当作 approval authority
• 在整个 connection lifetime 冻结 resource grant
• 没有 Relay fallback 的 direct-only P2P

非目标

• Federated Runtime Host 或跨 Host durable database
• 跨 Host Session migration
• 公开发现任意 Host
• 把全局 DHT 作为产品要求
• 分享 Host filesystem、settings 或 credentials
• 第一版实现通用 policy language
• 第一阶段支持 team、organization、group 或 Project-wide sharing
• 在获得跨平台证据前决定 iroh 或 libp2p
• 替换现有 Runtime Host protocol 或 execution authority

[M4n5ter]

English

Clarification on how the phases should be classified:

• Phase 1 is an architecture refactor: it separates logical Host identity from connection routes without adding a new user-visible capability.
• The identity and provider-neutral connectivity boundary in Phase 2 is also enabling refactor work. The point where Phase 2 actually delivers relay-backed or direct peer connectivity is feature work because it makes previously unreachable Hosts reachable.
• Phases 3–5 are product features: scoped sharing, durable approval, and bounded collaboration.

The sharing and collaboration feature plan in Phases 3–5 will be moved into a GitHub Discussion later, where product behavior, permission presets, and UX can be resolved before implementation. This issue can continue to hold the architecture boundary and the prerequisite refactoring work.

简体中文

补充说明各阶段的性质：

• Phase 1 属于架构重构：它把逻辑 Host identity 与连接路径分离，不增加新的用户可见能力。
• Phase 2 中的身份基础和 provider-neutral connectivity 边界同样属于前置重构；当 Phase 2 真正交付基于 Relay 或 direct 的 peer connectivity，使原本不可达的 Host 变得可达时，这部分已经属于 feature。
• Phase 3–5 属于产品功能：资源级分享、持久审批和有界协作。

Phase 3–5 的分享与协作功能计划稍后会转入 GitHub Discussion，在实施前充分讨论产品行为、权限 preset 和 UX。本 issue 可以继续承载架构边界与前置重构工作。

[M4n5ter]

English

This tracker combined two independent architecture boundaries: connectivity and resource authorization. The intended work now continues in:

• [Tracking] Application-scoped peer mesh for Runtime Hosts #3842 — Trusted Mesh connectivity for Runtime Hosts
• [Tracking] Resource-scoped Runtime Host sharing and collaboration #3843 — Resource-scoped Runtime Host sharing and collaboration

The replacement also removes assumptions that no longer hold, including a new provider-neutral Host ID, Relay-first as a release requirement, and sharing roles being part of the connectivity contract. Closing this issue as superseded rather than cancelling either goal.

简体中文

本 tracker 混合了两个独立的架构边界：connectivity 与资源授权。相关工作现在分别由以下 issue 继续跟踪：

• [Tracking] Application-scoped peer mesh for Runtime Hosts #3842 — Runtime Host Trusted Mesh connectivity
• [Tracking] Resource-scoped Runtime Host sharing and collaboration #3843 — 资源级 Runtime Host sharing 与 collaboration

替代方案同时删除了已经不再成立的假设，包括新增 provider-neutral Host ID、把 Relay-first 作为发布要求，以及把 sharing roles 纳入 connectivity 契约。关闭本 issue 表示它已被替代，而不是取消其中任一目标。