WebRTC v1 与受限 RPC

远程 APP 先按云端协议完成身份签名、PIN配对和所有者批准，再建立只含数据通道的WebRTC直连。云信令成功不能替代实际DTLS连接，也不能把未核实的SDP直接交给浏览器。不得配置TURN或relay候选，不允许直连失败后自动经ApuConnect传文件。

NAS所有者侧配置接口

这些接口使用正常NAS Bearer、原backup/files能力和当前密码确认，供设备端设置界面使用，不是APP拿云Bearer就能调用的授权捷径。云端运营者先允许该NAS使用sync；设备端状态中的online表示云信令连接，不是APP已经获得文件访问权。

方法与路径	精确正文	用途
GET /api/v1/apusync/direct	无	当前enabled、online、error、deviceId、discoveryUrl、directOnly、fileRelay、旧maxFileBytes、grants和connections
POST /api/v1/apusync/direct/settings	enabled、currentPassword、confirm:true	明确启用或禁用；不自动给任意APP授权
POST /api/v1/apusync/direct/invitations	root、path、currentPassword、confirm:true	创建本地一小时以内grant与云五分钟PIN，返回deviceId、grantId、sessionId、pin、expiresAt
POST /api/v1/apusync/direct/sessions/{id}/approve	expectedClientId、clientPublicKey、currentPassword、confirm:true	核对待批准APP原签名claim与精确公钥后批准
POST /api/v1/apusync/direct/sessions/{id}/revoke	currentPassword、confirm:true	撤销自己的对应会话；返回revoked、cloudNotified

创建邀请前root/path必须存在并通过文件身份代理检查。批准时不能只输入设备显示名称或猜测clientId；clientId必须由传入公钥派生并与原签名claim一致。currentPassword只用于本次明确确认，不写入普通偏好或任务库。

NAS状态grants条目包含id、sessionId、root、path、expiresAt、revoked、approved、clientId、clientPublicKey与可选pending信息。云端和本地直接授权期限用Unix秒，connections中的调试状态不能冒充任务已完成。撤销返回cloudNotified:false仍表示本地已撤销，不能因云暂时离线而继续写文件。

通道、hello与NAS登录

APP创建两个可靠、有序DataChannel：apusync.control.v1传UTF-8 JSON，apusync.data.v1传旧单文件二进制帧。必须核验已签名SDP中的指纹与实际对端身份，NAS也会核验APP的签名与实际DTLS证书。两个通道打开后，NAS发hello，保留旧字段：

{"v":1,"type":"hello","sessionId":"<32hex>","deviceId":"<32hex>","chunkSize":16384,"maxFileBytes":67108864,"authRequired":true,"directOnly":true}

旧chunkSize/maxFileBytes描述旧begin/data/commit通道，不是新版持久上传的能力上限。新APP在hello之后登录，再调用capabilities探测新操作。服务器可能增加能力字段，应保留兼容；客户端不能通过猜测字段存在跳过批准。

APP仅在签名与直连身份都通过后发送：

{"v":1,"type":"login","username":"<NAS账号>","password":"<NAS密码>"}

NAS使用固定本机认证入口核验，要求账号匹配本地批准者、原能力和目标目录ACL。响应为 {v:1,type:authenticated,username,destination:{root,path}}。NAS会话留在NAS内，不返回到云信令，客户端不上传NAS密码到mailbox。超时、撤销或断线后需重新建立有效授权和登录。

新版RPC封装

{"v":1,"type":"rpc","requestId":"op_0001","operation":"capabilities","params":{}}

requestId是本次RPC关联ID，1–64字符，仅字母数字、短横线与下划线；它与uploads.create内持久化的32hex requestId不是同一字段。RPC JSON最大32768字节，拒绝未知外层字段，params为对象。旧单文件仍有active传输时不能混入RPC任务。

成功响应：

{"v":1,"type":"rpc-result","requestId":"op_0001","status":200,"data":{}}

失败响应保留同一requestId与status，使用error稳定码而不是data。某些认证或协议层错误为 {v:1,type:error,error:<code>}，不会保证带requestId；APP必须让当前在途操作进入待确认状态，不能忽略错误后继续发送。

建议先采用一个在途RPC，收到对应响应再推进，遵守DataChannel bufferedAmount背压。16KiB分片base64后会超过21KiB，必须将UTF-8完整JSON长度计入32768边界。不要按字符数估算编码后的字节长度，不把2MiB base64塞入控制帧。

目录范围与上下文

允许操作由capabilities.operations给出：capabilities、files.roots、files.list、files.mkdir、files.read-chunk，以及uploads的显式操作（含forget）。没有任意REST代理、shell、全盘备份jobs或可指定URL的请求。

远程files.list、files.mkdir、files.read-chunk和uploads.create的path始终是相对于所有者批准目录的路径。root可省略并由NAS强制为grant.root；若提供不同root会拒绝。不能用../、share、绝对路径或publicationTicket扩大范围。服务器把相对路径拼到grant目录，再交给现有UID/ACL代理。

files.roots在远程只返回批准根与范围，不暴露完整NAS所有根。部分响应中的path可能为NAS根下实际路径，而不是APP输入的grant相对路径；客户端应保存自己的相对层级，不将响应路径原样再次拼接。新增目录或新文件不自动扩大授权范围。

持久上传上下文由NAS生成，绑定已批准clientId与规范化root/path的摘要，不使用短期sessionId。因此相同账号、相同客户端公钥和相同目录重新批准后可以恢复原范围任务；换公钥、账号或范围时不可读取其他上下文。HTTP固定nas-app，与远程上下文不同；不要假设同owner在HTTP和直连列出同一任务集合。

文件RPC字段

operation	params	结果与限制
capabilities	空对象	apiVersion、操作与大小限制、transport与scope
files.roots	空对象	仅批准根与grantPath，scoped:true
files.list	root可选、path可省略为空、offset默认0	entries最多32项，可含nextOffset，readOnly
files.mkdir	root可选、path可省略、name必填	创建一级目录，返回实际path
files.read-chunk	root可选、path必填、offset默认0、ifModified可选	原文件最多16KiB的base64及断点信息

read-chunk返回data（base64字符串）、offset、nextOffset、totalBytes、complete、lastModified、contentRange、stableSnapshot:false。第一次从0开始保存lastModified；之后把同一HTTP日期放到params.ifModified，每次仅在确认nextOffset和解码长度匹配后追加。源改变返回409 sync_download_source_changed，重新开始或让用户决定，不继续拼接。其底层是可变原文件，非强hash快照；零字节文件从offset:0读取时返回data为空、nextOffset:0、totalBytes:0、complete:true、contentRange:null，APP据实际响应创建空文件。

一次普通下载请求不支持自定读取块大小、任意Range头、上游URL、共享标识或代理头。大文件下载会有大量16KiB请求，性能须在目标网络验收，不能只因协议支持就声称达到局域网满速。

持久上传流程

用uploads.create绑定目标和完整hash；将每个2MiB块切成最多16KiB的uploads.segment，等待响应并区分received与fragmentReceived。最后uploads.commit，轮询校验状态并再次提交，直到committed且receipt匹配。详细字段与错误见持久上传。

NAS在最终发布时重新验证实时grant、账号、权限和目录，内部一次性publication ticket不由APP获取或传入。撤销可能等待已进入有界发布的操作结算；已经写入的文件不因撤销自动删除。连接关闭或授权过期会终止继续操作，但不能将已经持久的任务误当临时16KiB内存片段清除。

旧单文件通道兼容

旧模式begin含v、type、transferId（32小写hex）、name、size、sha256、chunkSize:16384；NAS发ready（nextOffset:0、nextSeq:0）。二进制每帧为u32BE seq + u64BE offset + 1–16384字节，最多8个未ACK块，顺序偏移连续。NAS发ack后继续，最后commit带transferId、size、sha256；只有complete且长度/摘要吻合才成功。

旧模式上限64MiB，中断从0开始，不具备新manifest的持久断点与receipt。两个模式不能共用任务ID、进度或成功判定。旧协议仍保留并不意味着新版APP必须走旧路径；请根据capabilities决定，老NAS没有新能力时明确显示限制而不是假装续传。