@awiki/dsh-plugin 0.3.10 → 0.3.11-rc.2

package/README.md

@@ -11,7 +11,9 @@ General DID documents and private keys are managed by the independent
 Identity-entry failures preserve the currently mounted form and local pending identity material. The
 phone and OTP never enter browser persistence, controller snapshots, or public
 Remote results. Closed registration, unavailable verification state, and commit conflicts each give
-a safe next action without exposing remote response details.
+a safe next action without exposing remote response details. The exact Node error
+`short_handle_invite_required` returns registration to the editable identity form and shows the fixed
+invitation notice; neither Handle length nor remote error text selects that UI.
 
 The two plugins deliberately own different state. ANP Identity owns the multi-DID Store, DID
 documents, private keys, and publication transactions. AWiki IM Core owns Handle/account bindings,
@@ -21,7 +23,7 @@ tools, or model APIs.
 
 ## Features
 
-- Enter a Handle and phone through one Web UI flow and always request a registration OTP. A new Handle creates the deployment identity; an existing Handle offers ordinary Device Join first, with Recovery V4 as an explicit destructive alternative that requests a second purpose-scoped OTP.
+- Enter a Handle and phone through one Web UI flow and always request a registration OTP. A new Handle creates the deployment identity; an existing Handle offers ordinary Device Join first. Choosing Recovery V4 opens a separate destructive-impact page without cancelling Join or sending an OTP; only its second explicit “replace DID” action cancels the pending choice and requests a purpose-scoped recovery OTP.
 - DSH can join an existing Handle as an independent member device. When DSH created or recovered the Handle and is the current ready-admin, the foreground Devices tab can list devices, verify an incoming request with SAS, approve one member, reject it, or revoke another device. These mutations are not Agent tools and require explicit `APPROVE` / `REVOKE` confirmation.
 - A local Darwin x64 ready-admin can prepare Root Transfer for one exact active member and use native system authentication before sending management capability. Authorization handles and Root material remain Host/Core-only; unsupported or headless Hosts fail closed. A recovered old device uses the same native-authentication seam to re-Join only as a member.
 - Open the top-left AWiki account menu to sign out locally without deleting the encrypted identity or message database; **Resume local identity** restores the same DID and Handle, including across DSH restarts. The signed-out screen reveals phone recovery only after local resume fails. Switching identities requires an explicit confirmation that permanently clears local AWiki data first.
@@ -31,7 +33,8 @@ tools, or model APIs.
 - Text messages plus one attachment per message, with Enter-to-send, Shift+Enter line breaks, optimistic sending bubbles reconciled by an exact client message ID, image previews, and SHA verification. Verified image bytes use three bounded layers: a browser-runtime LRU makes conversation remounts immediate, identity-scoped IndexedDB survives full page reloads without a Host call, and the private Host disk cache survives browser-storage loss and Harness restarts. Clear Local Data removes all three layers and selectively removes every AWiki Mail list/folder localStorage projection while preserving unrelated origin storage.
 - A draggable circular launcher that defaults to the lower-left sidebar area, adaptive popup placement, dark mode, and remembered active conversation.
 - User-triggered AI summaries for up to 50 recent or unread messages, kept only in runtime memory with explicit stale, retry, copy, and source-navigation states.
-- OTP identity access keeps the verification form visible and disables resend with a visible server-directed cooldown countdown. Handle classification happens before OTP delivery, so each attempt sends exactly one purpose-correct registration or recovery code.
+- New one- through four-character Handles require an invitation code; self-service registration is currently unavailable. The server enforces this only when creating an account. The Browser and Host send OTP and registration requests without a Handle-availability preflight, so existing short Handles retain the Join/recovery flow.
+- OTP identity access keeps the verification form visible and disables resend with a visible server-directed cooldown countdown. A non-secret Recovery retry deadline is retained per tenant and operation so a late successful request cannot enable duplicate sending after a tenant round trip; phone, Handle, and OTP factors remain memory-only. The server selects registration or existing-account continuation; an explicitly resumed Recovery operation retains its own scoped OTP flow.
 - When the user continues into the recovered identity after Recovery V4 reaches `applied`, the Host resolves the recovered Handle's original mailbox under the current DID. Inbox and sent views remount for that identity; sent history is read from the Mail Service with `mail.list(direction=outbound)`, never from the removed Host-local sent store. The optional Model Proxy package independently authenticates that current DID and sends only strict `{}` to the Model endpoint; it never requests or carries a User Service recovery credential, DID path, proof, assurance, or ledger owner. It consumes only the actual outcome-only Model response (`restored`, `already_current`, or `not_applicable`); transition assurance remains a Model server-side operation/audit/DB oracle and is not inferred by DSH.
 - Recovery E2E receipt collection uses a run-ID-first `0600` file handshake with separately operated Model/Mail producers; DSH verifies producer, target, source candidate, measurement window, receipt path, and shared operation fingerprints but never launches those external producers. The current Mail send API is text-only, so outbound attachment-preservation evidence remains blocked until DSH/Core expose an independently reviewed attachment-send seam.
 - When the separate `@awiki/dsh-model-proxy` package is installed, an AWiki-hosted DeepSeek choice appears before the official API-key onboarding step only when Harness has no usable model provider, with an explicit opt-in and an unchanged API-key escape path. New sessions do not show AWiki model or payment prompts after the official or another provider is usable.
@@ -50,6 +53,12 @@ tools, or model APIs.
 
 ### Mail
 
+Browser-selected attachments use Host-authenticated HTTP (`mail.send` / `mail.getAttachment` on `/mail/rpc`), with no new IM Core attachment API. Up to 10 files can be selected. The current signing API accepts at most 4 MiB per request: the effective decoded upload limit is 2.625 MiB per file and in total (or a lower configured limit), reserving room for Base64 and JSON metadata. Downloads support up to 10 MiB per file. The UI obtains these limits from Host. Send confirmation lists filenames and sizes; attachment sends are never automatically replayed, including authentication retries.
+
+Download responses are bounded before JSON parsing and validated against attachment index, safe filename, MIME type, canonical Base64 and decoded size; Browser also verifies the Host SHA-256 against the selected metadata. Inbox and sent downloads use the authoritative service message ID. Pending operations are fenced on identity or tenant changes. File selections remain only in owner/tenant-scoped process memory across drawer remounts, never in persistent browser storage. Agent tools remain plain-text-only.
+
+Host options `mailAttachmentMaxCount`, `mailAttachmentMaxBytes` and `mailAttachmentTotalMaxBytes` may lower the service limits; the effective upload budget is additionally clamped to the signing transport limit. `mailAttachmentMaxBytes` also bounds downloads.
+
 ![AWiki mailbox in DeepSeek Harness](./assets/screenshots/awiki-mail.jpg)
 
 The first release does not implement end-to-end encryption, multiple identities,
@@ -62,7 +71,7 @@ the existing Core inbound query; sent uses a fixed Host-only, current-identity-a
 `mail.list(direction=outbound)` query. The identity-scoped browser cache may keep the last visible
 page during an explicit refresh error, but it is never sent-history authority. A successful send is
 attempted once and triggers one server-backed sent refresh in the browser. Mail does not wake an Agent
-for new mail, render or send HTML, transfer mail attachments, or implement reply, forward, and
+for new mail, render or send HTML, or implement reply, forward, and
 threading. Mail subject, addresses, preview, body, timestamps, and attachment metadata are
 untrusted external data, never Agent instructions. `awiki_mail_mark_read` and `awiki_mail_send`
 require execution approval. Mail send is attempted once without automatic retry; a timeout or
@@ -94,7 +103,7 @@ dsh plugin --profile web add @awiki/dsh-model-proxy@latest
 The profile installer both adds the package and activates its bundle layer. A
 plain `npm i @awiki/dsh-plugin` in a DSH project only installs the package; it
 does not activate the bundle, so the profile command remains the recommended
-installation path. This release line targets the `0.1.1-rc.2` package family
+installation path. This release line targets the `0.1.5-rc.1` package family
 and pins every direct Host peer exactly, preventing npm from mixing prerelease
 families in a DSH root dependency tree.
 

package/README.zh.md

@@ -11,17 +11,18 @@ Host-only Provider lease 不会进入 Browser、Remote、Agent tools 或模型 A
 
 ## 功能
 
-- 在 Web UI 的统一入口输入 Handle 和手机号，先查找该 Handle 的未完成恢复；命中则继续原操作，否则发送注册验证码。新 Handle 创建部署级身份；已有 Handle 优先进入普通 Device Join，Recovery V4 仅作为显式危险替代项，并重新发送用途隔离的恢复验证码；根 Agent 与子 Agent 共用最终身份。
+- 在 Web UI 的统一入口输入 Handle 和手机号，先查找该 Handle 的未完成恢复；命中则继续原操作，否则发送注册验证码。新 Handle 创建部署级身份；已有 Handle 优先进入普通 Device Join。首次选择 Recovery V4 只打开独立的替换 DID 风险确认页，不取消 Join、不创建 Recovery operation、也不发送 OTP；只有第二次明确点击“发送恢复验证码并替换 DID”才取消待处理 Join 并发送用途隔离的恢复验证码。根 Agent 与子 Agent 共用最终身份。
 - DSH 可以作为独立 member 设备加入已有 Handle；当 DSH 创建或恢复 Handle、当前设备为 ready-admin 时，前台“设备”页可列出设备、通过 SAS 验证并批准 member、拒绝请求或撤销其他设备。管理动作不进入 Agent 工具，并要求显式输入 `APPROVE` / `REVOKE`。
 - 本机 Darwin x64 ready-admin 可在“设备”页准备 Root Transfer，并经系统级用户认证把管理能力发送给一个精确的 active member；authorization handle 和 Root material 不进入 Browser。Linux、远程无头或系统认证不可用时失败关闭。Recovery 后旧设备 re-Join 复用同一认证端口，但仍只恢复为 member。
 - 点击 AWiki 面板左上角图标可打开账户菜单；普通退出只锁定本机会话，不删除加密身份或消息数据库，重新进入及重启 DSH 后仍恢复同一个 DID 和 Handle。退出页默认只提供重新进入本机身份和使用其他身份；只有本机重新进入失败后才显示手机号恢复入口。改用其他身份必须先确认永久清除本地 AWiki 数据。
-- 身份入口失败时保留当前挂载表单中的手机号、Handle 和验证码，以便修正后重试；手机号和验证码不进入 Browser 持久化状态、controller snapshot 或公开 Remote 结果。仅恢复操作编号可用于崩溃续跑。注册未开放、验证码状态失效和提交冲突会给出对应的安全处理提示。
+- 一般身份入口失败时保留当前挂载表单中的手机号、Handle 和验证码，以便修正后重试。例外是 Node 返回精确错误码 `short_handle_invite_required`：注册会清空验证码并返回可编辑的 Handle／手机号表单，显示“注册少于5位的handle需要使用邀请码，目前暂不支持自主注册。”；该提示在关闭重开面板后保留，修改 Handle 后清除。界面不根据 Handle 长度或远端错误文案推断该错误。手机号和验证码不进入 Browser 持久化状态、controller snapshot 或公开 Remote 结果。恢复操作编号以及按租户和操作隔离的非敏感重发截止时间可用于崩溃续跑；后者只恢复服务端冷却，不包含手机号、Handle 或验证码。注册未开放、验证码状态失效和提交冲突会给出对应的安全处理提示。
 - 私聊和已有群聊列表、未读角标、最新消息预览、时间更新与昵称持久化。Core SQLite 是持久化真相源：Host 将持久化的对端资料合并进私聊列表，浏览器再按当前身份保留最后一次可信的私聊资料和群名，稀疏轮询中的 Handle、DID 或 Group DID 占位不会覆盖真实名称。恢复已有 Handle 后，Host 会先同步账号投影，再让 Core 自动恢复旧群聊成员身份；未完成或受阻的群聊会显示可重试状态，但不影响私聊和其他群聊。打开会话时先显示 Core 已提交的本地时间线，并从 Core 显示资料缓存补齐群消息发送者名称，再在后台补齐远端历史和私聊资料；刷新失败不会清空本地消息。后台会话轮询失败也不会用全局红条打断仍可用的本地页面，用户主动加载失败仍会正常提示。当前 local-first 只覆盖本地最新一页，“加载更早消息”仍需访问远端 history。向上阅读时显示下滑箭头，新消息到达后在同一控件中累计数量且不打断阅读位置。只有最新一条已渲染消息到达可视区域底部后，当前会话才会自动标记为已读。
 - 可从 Web UI 输入群名和 1–50 个 Handle 或 DID 发起私有发现、开放加入、传输保护的群聊。建群成功后立即进入新会话；个别成员添加失败会单独提示，不会隐藏已经创建的群。
 - 文本和单附件消息；Enter 发送、Shift+Enter 换行，发送中立即显示带 loading 动画的乐观气泡，并通过精确的客户端消息 ID 与已提交消息对账，避免同一条消息显示两个气泡；同时支持图片预览、附件说明与 SHA 校验。校验通过的图片字节使用三层有界缓存：浏览器运行期 LRU 让会话重新挂载时立即出图，按身份隔离的 IndexedDB 在整页刷新后无需访问 Host，Host 私有磁盘缓存则应对浏览器缓存丢失并跨 Harness 重启复用；“清除本地数据”会删除三层缓存，并精确删除全部 AWiki Mail list/folder localStorage 投影而保留无关 origin storage。
 - 圆形可拖动入口、自适应四角弹窗、深色模式和当前会话记忆。
 - 用户点击后才生成的 AI 对话总结：最多处理 50 条最近或未读消息，按会话保留本次运行期缓存，并支持过期提示、重试、复制与跳转原消息。
-- OTP 身份入口会保留验证码输入表单，并按服务端返回的冷却时间显示重发倒计时、禁用提前重发；已有 Handle 在消费 registration OTP 后再选择 Join 或 Recovery，Recovery 不复用 registration grant。
+- 新注册少于5位的handle需要使用邀请码，目前暂不支持自主注册。限制由服务端仅在新建账户时校验。前端和 Host 不再按长度或 Handle 可用性拦截验证码与注册请求，已有短 Handle 保留 Join／恢复流程。
+- OTP 身份入口会保留验证码输入表单，并按服务端返回的冷却时间显示重发倒计时、禁用提前重发；已有 Handle 在消费 registration OTP 后再选择 Join 或 Recovery，Recovery 不复用 registration grant。Join 来源 Recovery 的第二次确认会重新检查当前 phone capability；若已关闭则回到普通 Join，且不取消 Join、不发送 Recovery OTP。已存在的 Core Recovery operation 与真实 `recovery-required` 会话仍可继续查询或进入恢复，不由瞬时 capability discovery 失败隐藏。
 - Recovery V4 进入 `applied` 且用户继续进入恢复后的身份时，Host 会用 current DID 解析已恢复 Handle 的原邮箱，并为该身份重新挂载收件箱与发件箱；发件历史固定来自 Mail Service 的 `mail.list(direction=outbound)`，不再读取已删除的 Host 本地 sent store。可选 Model Proxy 包会独立使用 current DID 认证，并且只向现有 Model endpoint 发送严格 `{}`。它不请求或携带 User Service 恢复凭证、DID path、proof、assurance 或账本 owner，只消费 Model 实际的 outcome-only 响应（`restored`、`already_current` 或 `not_applicable`）；transition assurance 由 Model 服务端 operation/audit/DB oracle 验证，DSH 不从公开响应推断。
 - 安装独立的 `@awiki/dsh-model-proxy` 后，仅在 Harness 没有任何可用模型时，首次引导才会在官方 API Key 步骤前提供 AWiki 托管模型选项；用户可以明确启用，也可以跳过并继续原版 API Key 流程。已经配置官方或其他 Provider 时，新会话不会显示 AWiki 模型或支付提示。
 - 可选 Model Proxy 包独占 Host 内部短期 Token 和全部模型托管界面：首次引导，以及“设置 → 快速充值”中的“账户与充值”“用量明细”。它提供 `deepseek-v4-flash` 和 `deepseek-v4-pro`，默认推荐 Flash；Token 不进入 Browser。
@@ -39,6 +40,12 @@ Host-only Provider lease 不会进入 Browser、Remote、Agent tools 或模型 A
 
 ### 邮件
 
+浏览器选取的附件通过 Host 鉴权 HTTP 调用 `/mail/rpc` 的 `mail.send` 和 `mail.getAttachment`，不新增 IM Core 附件接口。最多选择 10 个附件。当前签名接口的请求体上限为 4 MiB，扣除 Base64 和 JSON 元数据开销后，实际上传上限为单文件及总计 2.625 MiB（配置可进一步降低）；下载支持单文件 10 MiB。界面从 Host 获取准确限制，发送前确认文件名和大小；附件发送包括鉴权失败在内均不自动重放。
+
+下载响应在 JSON 解析前限制大小，并校验附件索引、安全文件名、MIME、标准 Base64 和字节数，浏览器再核对所选元数据与 Host 提供的 SHA-256。收件箱和发件箱均使用服务端邮件 ID。身份或租户切换后，旧操作结果不能进入新会话。关闭重开抽屉可保留按租户和身份隔离的内存附件草稿，文件不会写入浏览器持久存储。Agent 工具继续仅发送纯文本。
+
+Host 的 `mailAttachmentMaxCount`、`mailAttachmentMaxBytes`、`mailAttachmentTotalMaxBytes` 可降低服务上限；上传还会按鉴权传输预算限制，`mailAttachmentMaxBytes` 同时约束下载。
+
 ![DeepSeek Harness 中的 AWiki 邮箱界面](./assets/screenshots/awiki-mail.jpg)
 
 首版不包含端到端加密、多身份、建群后的成员或群设置管理和单消息多附件。Agent listener 只接受明文私聊文本；
@@ -48,7 +55,7 @@ Host-only Provider lease 不会进入 Browser、Remote、Agent tools 或模型 A
 发件箱通过固定、仅 Host 可用且绑定 current identity 的 `mail.list(direction=outbound)` 查询。
 身份隔离的浏览器 cache 可以在显式刷新失败时保留最近可见页面，但绝不是发件历史权威；发送
 成功后浏览器只触发一次服务端发件箱刷新。邮件不会以新邮件唤醒 Agent；不渲染或发送 HTML，
-不传输邮件附件，也不支持回复、转发和会话串联。邮件主题、地址、预览、正文、
+不支持回复、转发和会话串联。邮件主题、地址、预览、正文、
 时间戳和附件元数据都是不可信外部数据，不能作为 Agent 指令。`awiki_mail_mark_read` 和
 `awiki_mail_send` 每次执行都需要审批。邮件发送只尝试一次且不自动重试；超时或传输中断返回
 `delivery-unknown`，再次审批发送前应先检查邮箱。