Skip to content

Service Surface And Bootstrap

This content is not available in your language yet.

0. 规范语言

本文中的规范关键字按 normative-language.md 解释。字段级请求、响应、认证和错误合同以 service-http-binding.md 与 canonical operation registry 为准；本文只定义服务角色和跨 surface 不变量。

1. 目标（Goals）

Arkret v1 定义可互操作的 identity、authority commit、account sync、snapshot、Directory、Blob 与 invite surface。producer-signed Event 只有在其所属 Realm/Circle/Sidecar stream 的当前治理 Station签发 RealmCommit 后才成为共享 accepted 事实。

Realm、每个 Circle、每个 Sidecar 各有独立 stream；不存在 Realm 总链或跨 stream position。Account-private 数据、DeviceMessage、Signal 和 Blob bytes 不进入这些 stream。

2. 基本原则

2.1 DID Document 只做发现，不直接承载全部状态

DID method state 用于解析稳定 did_core_id、service identity、verification method 与 HTTPS endpoint。Realm current state、member、capability、MLS epoch、通知或 inbox 不写入 DID Document。

2.2 治理 Station 是每条 Realm stream 的唯一提交权威

  • producer Event 是内容与用户意图的真实性来源；
  • 当前治理 Station 是 admission、顺序、finality、复制和 current projection 的唯一权威；
  • RealmCommit 绑定 exact Event、stream、position 和同 stream predecessor；
  • 消费 Station验证 producer proof 自身一致、authority chain、commit signature 与逐 stream 连续性；外站 human 设备的授权以治理 Station 的 RealmCommit 为准（federation.md §3），本站托管账号的 producer 仍按本地 PCR 验签；
  • Directory、invite、cache 和 mirror 只提供 locator，不能产生或替代 authority。

治理 Station可能审查、扣留或停止写入，因此 v1 明确接受单权威的可用性与治理信任代价。协议不再要求客户端交叉验证 authority-commit、RealmCommit、typed current result root、actor chain 或 fixed reducer semantics。

2.3 接口必须天然支持幂等重试

同一 Event canonical bytes 以 event_id 幂等；同一 committed 结果以 commit_id 幂等。相同 Event ID 对应不同 bytes、相同 stream position 对应不同有效 Commit，均为安全故障并 fail closed。网络失败后 caller 重放 exact request，不重新签 Event。

2.4 服务必须公布自己的实现 profile

ServiceDescribe 公布 protocol_version、supported operation bundles、features、schema profiles、limits 与 transport。固定 v1 reducer/digest 语义不是 Realm 可选择 profile；服务只能广告 operation registry 中当前存在的操作。

2.5 核心角色、Station capability 与可选服务

角色职责
Account Station认证本地账号，保存 signed draft，转发到 current authority，向自己的客户端提供 trusted current/sync。
Realm governance Station对 Realm、每个 Circle、每个 Sidecar 的独立 stream 分配 position、签 RealmCommit、执行 typed reducer、生成 snapshot 与复制 outbox。
Consumer Station验证 authority chain/Commit 连续性并向本地成员提供获准结果。
Directory返回 discovery projection 与 authority locator；不执行 join，不选择 authority。
Blob/Media/Push 等仅在各自委托边界工作，不取得 Realm commit authority。

一个 Station 可以同时承担多个角色，但每个请求的 service identity、Realm authority generation 和 operation contract必须明确。

2.5.1 Account Authority 与认证方法发现

Account Authority 是 Station 的账号准入逻辑入口，不是独立 Realm authority。Passkey、OIDC、SSO 等 provider 只提供认证输入；它们不能签 RealmCommit。账号恢复、session、device 与本地 draft queue 不改变 Realm 的 current governance Station。

2.6 Service DID 权威入口与路由解析（normative）

服务调用方 MUST 验证 did_core_id 对应的 method-native 当前状态、唯一 ArkretService entry、serviceKind 和 canonical HTTPS endpoint。缓存、邀请和 Directory 行都是 locator。

Realm authority 还必须验证 genesis 的 generation-0 service、连续 old→new handoff chain、已观察最高 generation 的防回滚约束，以及目标 service 对 caller nonce 的短期 current_assertion。只有这一 bundle 验证成功后，endpoint 才可作为 current governance Station。

current_assertion.signature 使用 ak.realm_authority_current_assertion_signature.v1。其 unsigned projection 是从 closed current_assertion 删除 signature 后的全部实际存在成员，包括 nonce、expires_at，以及允许为 null 的 last_handoff_ref；缺席成员不得补 null。验证方对该投影作 RFC 8785 JCS 与 SHA-256，比较载荷内 signed_digest， 再验证 UTF8(context + "\n") 与五成员 signature envelope JCS 串接后的 Ed25519 签名。authority basis 必须证明 current_generation/current_service_id 与已验证 genesis→handoff chain 得出的 current governance Station 完全相同， 并证明 verification_method 是该 Station 的 service signing key；自报 method 不能自行授权。

2.7 Device-pairing 分离部署边界（normative）

device-pairing 的 client-visible origin 固定为 Station。Account Authority 是 Station 内部职责，不取得独立 service_kind 或 Service DID；分离部署时，Station 按 service-http-binding.md §2.2.3 的部署内私有通道，把 ak.open.device_pairing.command.stage.v1、ak.open.device_pairing.read.resolve.v1、 ak.open.device_pairing.read.status.v1 三项 open operation 以及 ak.gate.account.command.finalize_device_pairing.v1、 ak.gate.account.read.claim_device_pairing_code.v1 两项 gate operation 的已登记 canonical DTO 原样代理给 Account Authority。该通道不登记任何 operation，代理范围只限这五项 operation 的请求与响应转交，不扩大 Station 的写入职责。 finalize_device_pairing 与 claim_device_pairing_code 由 Account Authority 作唯一业务裁决和耐久写入；承载这两个 gate 路由的 Station 角色 endpoint 只能在实际挂载并代理到该 Authority 时广告 ak.operation_bundle.station.account_gate_pairing.v1。其它 Station endpoint 不得仅凭共同 Station 身份广告此 bundle。 Account Authority 是 pending、abuse、admission fence 与 terminal outcome 的唯一 durable owner；Station 不拥有 pairing 业务状态，不得维护第二份可写 ledger、从 proxy response 推导另一份状态，或让客户端改打 internal origin。

pair_device 的 ak.device.authorize 仍由 producer 签署，由 owning Station 在自己的 Event／RealmCommit 事务中接纳。 该事务与 Account Authority terminal 之间的连接与恢复属于实现私有机制，规范不得以共享数据库或跨库单事务作为隐含前提； 对外只要求公开 operation 边界上的结果：成功的 Event、唯一 RealmCommit 与 terminal outcome 可 exact replay， 内部状态未知或不确定时 fail closed，不扩大公开信息。

3. 通用服务描述接口

所有可发现服务提供 GET /_arkret/describe。响应只广告 registry 中存在且本部署真实实现的 operation bundle。HTTP/JSON 是 v1 core binding；其它 transport 必须逐 operation 等价映射认证、授权、幂等、分页、错误和流控。

3.0 Describe response claim levels

描述信息分为协议固定能力、部署声明能力和运行时可用性。Describe 不能证明某服务是某 Realm 的 current authority；authority 身份只能由 RealmAuthorityBundle 证明。

响应形状由 service-describe.schema.json 封闭定义， 其中三个字段承载不同强度的断言，实现与下游 MUST 明确区分，MUST NOT 互相替代：

  • supported_operation_bundles 只表示 wire 可达性：展开后的 (operation_id, binding_kind) union 是唯一 可达性真源。它不构成任何 profile claim。surface_class 的 core/extension/deployment_local 等 tier 只用于文档与 lint，不隐含任何 operation 可达；endpoint 必须实际实现其广告 bundle 的全部成员。
  • supported_features 表示服务有实现代码，但不一定通过 conformance verification。构建 conformance matrix 的工具 MUST 把它视为严格弱于 supported_profiles。
  • supported_profiles 是当前构建与本角色 endpoint 唯一的完整 profile 自声明集合。每一项 MUST 满足该 profile 的全部适用要求；只实现了一部分时 MUST 只在 supported_features 中声明。profile activation、前置 依赖与自声明 badge MUST 只从此集合求值。

verified_profiles 只补充独立验证证据，不单独激活任何 profile：其每个 profile_id MUST 唯一，且 MUST 属于 supported_profiles；不满足时接收方 MUST 拒绝该 Describe。每项 MUST 携带独立验证证据（verification run 标识、artifact digest 与获取位置、verifier identity、签名与时间戳）。缺少验证证据 MUST NOT 被解读为 “部分实现”，实现也 MUST NOT 保留一份平行的 claimed 数组。service_kind 只选择 role overlay，不自动 产生任何 profile claim。

日历 profile 的可执行前提（normative）：服务声明 ak.profile.calendar_event.v1 或 ak.profile.calendar_notification_dispatch.v1 中任一项时，describe 的 calendar_tzdb_versions MUST 非空， 且其每一项 MUST 是已登记的 IANA TZDB release tag，代表该服务确实能执行的 release。签名 schedule 的 tzdb_version 不在该集合中时，服务 MUST 以 calendar_tzdb_mismatch fail closed 或把该 instant 投影为 unresolved，MUST NOT 回退到相邻或更新的 release。空集合或无法执行的 tag 使该 profile 声明非法。

3.0.1 Bundle 展开与 transport 求交

实现先展开 canonical operation bundle，再与调用方和服务共同支持的 transport 求交。求交为空即不支持，不得静默替换另一个 operation。

3.1 Identity Resolution Surface

Identity surface 处理 method-native DID 状态，不处理 Realm Event finality。

3.1.1 描述 registry

返回 method、proof suite、历史能力与大小限制。

3.1.2 获取当前 DID Document

必须返回可独立验证的当前 method state；携带的旧文档或 TLS 可达性不构成 freshness。

3.1.3 获取 DID 日志

有历史的方法返回从已知 head 到目标 head 的连续原生日志；无历史的方法必须显式声明其信任限制。

3.1.4 提交 DID 更新

DID operation 的 admission、receipt 和 witness 语义属于 DID method，不产生 RealmCommit。

3.1.5 获取 receipt / witness 证明

Receipt 仅证明 identity registry/witness 对 method operation 的观察，不证明 Realm admission。

3.1.6 写入确认建议

高保证部署可以要求 method 自身的多 witness 策略；这不恢复 Realm 的分布式共识。

4. Events API

Events API 接收 producer-signed Event，并返回 authority commit 状态。queued / forwarding 只是本地队列状态；只有有效 RealmCommit 才是共享 committed。

4.1 描述 Events API

Describe 至少声明 self submit/read/subscribe 能力；承担 federation 的 Station另声明 peer submit、per-stream scan 和 committed exact resolve。每个 stream selector 都是 closed stream_ref，Circle/Sidecar position 不得通过 Realm stream 暴露。

4.2 提交 Event

ak.self.events.command.submit.v1 使用 endpoint-specific closed union：普通 EventAdmissionSubmission 与 MLS Commit 是单提交；Direct Conversation founding 是四 Event 原子 unit；membership compensation 是带 closed transport-only evidence 与 single-use CAS 的单 Event 原子 unit。Account Station 验证本地 session 与 producer proof，随后把 exact bytes 交给已验证 current authority；未取得 authority-signed RealmCommit 不得自行报告 committed。founding success 只返回四个连续 source Commit；第四个 Commit 的 committed_at 是唯一接受时间， 不返回第二张 receipt 或虚构的逐项 partial。

ak.peer.events.command.submit.v1 是同一路径上的三分支 closed union：authority_forward 只把普通 Event／MLS 提交交给 current governance Station 首次接纳，跨站 human 设备 producer 由本分支的 producer_device_evidence 承载设备证据（../crypto-media/device-lifecycle.md §8.2.2），转发 ak.mls.genesis 另携 mls_genesis_material；committed_replication 携完整 source Event、source RealmCommit，ak.mls.commit 另携目标 service 托管 recipient 的 welcomes[]，接收方从自己的已验证 committed history 求值接收资格，并以 stored|duplicate|rejected 同序逐项保存副本；wire 不携 membership witness、per-item mode、destination、 输入 index 或 source-coordinate echo； registered_atomic_unit 只接纳已登记的 DC founding 或 membership compensation，并整组 materialize 或零写。 后两支不签新 Commit、不产生第二轮 fanout；ordinary forward success 返回 schema 中的 Commit，不额外返回 Event。

4.3 获取单个 Event

ak.self.committed_event.resource.get.v1 返回调用方可见的 committed Event 及其 Commit 坐标。不可见与不存在保持不可区分。

4.4 批量获取 Event

4.5 列出 / 回填 Event

ak.self.committed_event.read.scan.v1 与 ak.peer.committed_event.read.scan.v1 按单个获准 stream的连续 position 分页。每页不得把多个 Circle/Sidecar 拼成 Realm 总序，也不得用隐藏 stream 的 position gap 暗示其活动。历史可见性、membership join floor 和 retention 可以裁剪可读起点。

4.6 获取 stream head

每条获准 stream 以 {head_commit_ref, next_position} 表示当前进度。公开 authority bundle只披露 Realm stream head；私有 Circle/Sidecar heads 只进入获权 snapshot 或 handoff manifest。

5. Account Aggregate / Snapshot Surface

Account aggregate 是自己的 Station提供的受信投影。它可以聚合多个 Realm，但必须保留每条 Realm/Circle/Sidecar stream 的独立 cursor/position；聚合 cursor 只是 Station-local resume token，不是 RealmCommit predecessor。

5.1 Account 自服务与描述

viewer、profile、account subscribe 与 cursor revoke 只作用于已认证账号。Profile Event若属于 PCR Realm，同样必须由其 current authority commit；Account-private preference 则继续使用自身的 Station-local合同。

5.2 snapshot 入口

ak.self.realm_state_snapshot.read.manifest_head.v1 返回 current governance Station 签署的 closed typed snapshot。其 wire 成员是 snapshot_id、realm_id、governance_generation、每条获准 visible_stream_heads[]、内联 current_state_entries[]、retention_and_history_floor、created_at 与 signature；rows 是 typed current results，必须和 heads/floors 来自同一 durable cut 且只覆盖请求者可见范围。完整 canonical signed body 不得超过 8 MiB；治理 Station 必须按 scalability-constraints.md §4.1 在写入 admission 时预检最大披露投影并拒绝会越界的状态。v1 不存在另一个 sections／chunk_digests、分页、state root 或 reducer replay program 字段。客户端从 current authority 取得 snapshot，再从各自 head 继续拉获准 tail；签名不证明未授权隐藏 stream 的存在或缺席。

Snapshot exact read

ak.self.realm_state_snapshot.read.by_ref.v1 按 exact realm_id 与 snapshot_id 取回先前已向同一认证账号披露的原完整签名对象。响应复用上述 closed schema，两个 ID 必须与请求逐字相等；读取时重新检查该账号当前对 Realm 及 snapshot 中每项 row、head、floor 的披露权限。snapshot ID 不是授权凭据，不得向另一账号转发、按当前状态重造同名对象、重签或以当前 /head 替换。Station 发出非 preview 窗口时，必须从承载窗口的 Account stream cursor 签发起至少保留引用至该 cursor 的 expires_at，并保证同一账号在仍有披露权限时可取回；现有 cursor 合同的 stream TTL 上限为 7 天，不能以 barrier cursor 的 1 小时上限代替。客户端将 cursor 视为 opaque，无需解析过期时刻。不能保证保留与披露时该流只许 preview_only=true。cursor 有效期后允许现有 realm_state_snapshot_unavailable；无权、失效或缺失时沿既有授权／unavailable 错误面失败关闭，客户端不得由本地缓存或 shape-only cursor 猜测前态。

5.3 Event / RealmCommit 状态与确定性 current

Event 状态只区分本地 queued/forwarding 与 authority 的 committed/rejected。领域 current result 由治理 Station 按 commit 顺序执行对应 typed reducer 产生，并带来源 commit_id、stream_ref、stream_position 和领域 revision。客户端不得从 timeline 最后一个同 kind Event 推测 current result。

ak.self.current_results.read.exact.v1 是 authenticated、非枚举的 exact-current 入口。请求只允许 relation {primary_conflict_domain}、moderation_state {target_ref} 与 agent_interaction {agent_account_id} 三种封闭 selector；响应把 realm_id、当前 governance_generation、该 selector 的 effective_stream_head 与同一 durable cut 的 present {entry} 或 never_written {selector} 绑定。entry 必须是正式 relation_result 或 moderation_state_result 或 agent_interaction_result，并携 exact CurrentRevision。Agent mode 的读取 须已有获授权 exact Agent 身份来源，不能用 guessed AccountId 枚举私人参与。权限不足、不可见、外 Realm 与未知 selector 统一返回 not_found，不得用 never_written 泄漏存在性；authority/current basis 暂时不可确认时返回 revision_unavailable。snapshot omission、本地 raw Event 顺序、超时或旧 generation 都不证明 never-written。 never_written 允许 Relation create 据此签 expected_revision=null，或 Agent mode 首写省略 expected_revision／确认默认私人模式；Relation update/tombstone 与 moderation lift 必须取得 present。任何 CAS 冲突都要求重新读取、重新确认并重签，不能静默复用旧 Event bytes。

5.4 明文与服务信任

MLS 未激活的 scope 是明文 scope，治理 Station可见内容；这必须向用户披露。MLS 激活后治理 Station仍可见 sender、scope、时间、大小、routing 和 group churn，但不持有 group secret。Directory、Push 与未授权投影服务不得接收正文。

6. Search / Projection Semantics

搜索、inbox、notification 与 View 默认是 own-Station 或客户端派生结果。任何远端投影都必须标明其来源 committed refs 与可见性边界，且不能成为 authority。

6.1 结构化查询形状

查询复用 registry 的 closed request/response schema；服务不得增加 caller-controlled state key、reducer 或 authority selector。

6.2 Strand Discussion / Context Projection

Discussion 投影按 typed Strand/Message current 生成；跨 stream 引用不产生跨 stream 顺序。

6.3 Inbox / Notification Projection

通知是提示。客户端收到后仍从 own Station读取对应 Commit/current result。

6.4 全文搜索

搜索范围不得超过 caller 当前可见的 committed plaintext或本地已解密内容。

6.5 明文搜索边界

第三方索引明文需要显式 policy 委托；MLS ciphertext 不得通过搜索 surface 解密。

7. Blob Surface

Blob surface 管理 bytes，不判断 Realm Event accepted。

7.1 上传 blob

上传返回内容摘要引用；引用进入 Event 后仍需 authority commit。

7.2 查询 blob 头信息

metadata 查询遵守引用 Event 的当前访问控制。

7.3 下载 blob

下载授权不授予其它 Event、stream 或历史读取权。

8. Directory Surface

8.1 描述 directory

Describe 公布查询、ingest、anti-enumeration 和 TTL 限制。

8.2 搜索 Realm

搜索结果不是 authority assertion。

8.3 精确解析 Realm

解析可以返回 authority locator；caller 仍必须验证 nonce-bound authority bundle。

8.4 搜索与解析 Organization

Organization 投影不能授权 Realm join 或治理写入。

8.5 搜索 Actor / Handle

结果遵守 visibility 和 anti-enumeration；handle 不替代 AccountId/ActorId。

8.6 私密联系人发现

PSI/OPRF 输出不得泄露未匹配集合或 Realm membership。

9. MIMI Provider Facade Surface（extension profile）

MIMI facade 只映射已注册互操作 operation，不取得 Arkret authority。

10. Capability / Invite Surface

Invite 与 capability 是 typed Event或专用 delivery object。Invite携带的 service 是 locator；join 必须提交给 current authority。无已完成 handoff时，旧 authority永久丢失不会触发自动 takeover。

10.1 Agent Surface

Agent 继续使用自身 producer key、controller authorization 和 Account Station认证。治理 Station不能代签 Agent Event。

11. Realm Bootstrap Strand

新加入者自己的 Station从当前治理 Station取得 nonce-bound authority bundle、签名 typed snapshot 与获准 stream tails。默认不从邀请人 Station、genesis Station或任意 member Station拉全历史。since_join、private Circle 与 retention floor 必须在 snapshot/history floor 中体现。

12. 新鲜度与多服务并存

多个 locator 可以并存，但 carrier MUST 直接使用 ak.schema.realm_join_candidate.v1 的同一个 closed core：1..8 项、按 service_id UTF-8 bytes 严格升序且该 id 语义唯一；同 id 的任何表示冲突令整组 fail closed。locator 不复制 Realm 或时间成员，Directory、invite 与 join intake 分别从 enclosing container 取得 scope/freshness。一个 Realm generation 只有一个 current governance Station。看到更高 generation 后不得回滚；互斥 handoff、相同 generation 不同 cut 或 authority equivocation 必须冻结相关 Realm/stream。

13. 传输安全与密文

所有 service-to-service 请求验证 service identity、TLS、HTTP Message Signature、audience、nonce/expiry 和 replay。Transport protection 不替代 producer proof、RealmCommit 或 MLS。

14. 防滥用与配额机制 (Anti-Spam & Quota)

限速和配额可以拒绝新请求，但不能改写已 committed history。

14.1 存储责任与 Blob Quota

配额按 Station/Realm policy执行；Blob bytes 与 Realm log分别核算。

14.2 写频率控制 (Rate Limiting)

retryable throttle 不产生 pending Realm state；重试必须复用 exact Event。

15. 设计决定

v1 选择单治理 Station、逐 Realm/Circle/Sidecar 独立 authority stream，以实现简单、可判定的顺序、撤销、bootstrap 与 handoff。代价是 authority 的审查权与写可用性单点；Base v1 不提供自动选主或 Byzantine 共识。

16. HTTP/JSON Binding

全部 canonical path、method、schema 与 error mapping 见 service-http-binding.md。

17. 线级互操作要求

实现 MUST 验证 Event/Commit/authority chain；逐 stream 检查 position/predecessor；拒绝跨 stream predecessor；不暴露隐藏 stream gap；只广告 operation registry 的 active operation；并在 snapshot、scan、resolve、handoff 与 MLS transaction 上保持同一 committed 坐标。