dsh-deeppilot 0.3.0 → 0.5.0

package/COMPATIBILITY.md

@@ -1,36 +1,39 @@
 # Compatibility
 
-This file separates tested evidence from intended fallback behavior. Passing
-unit tests does not prove every DSH build, network, Mac, or iPhone combination.
+This file separates tested evidence from intended behavior. Passing unit tests does not prove every DSH build, network, Mac, or iPhone combination.
 
 ## Public-beta baseline
 
 | Component | Baseline | Evidence |
 |---|---|---|
 | Node.js | 22 or newer | package engine and CI |
-| DSH packages | `0.1.1-rc.2` peer family | build/type contracts and isolated host smoke tests |
+| DSH Host API | 0.1.2 controller family | source-built 0.1.2 Host, paired iOS client, new- and legacy-session history, and `/phone` protocol tests |
 | Host OS | macOS on Apple silicon | embedded helper artifact and local integration testing |
-| Remote access | Tailscale Funnel, ports 443/8443/10000 | helper and supervisor tests; real-tailnet acceptance remains release-specific |
-| iOS | native DeepPilot client, protocol v1 | simulator build and bridge pairing evidence |
-
-## Expected degradation
-
-- Without a compatible embedded helper, the core bridge and trusted-LAN mode
-  can still run; remote Funnel reports `unavailable`.
-- If a DSH host API is missing, only the dependent capability should be
-  disabled. The plugin must not crash the host.
-- Query-string token authentication is legacy compatibility only. Current
-  clients use Bearer or first-frame authentication.
+| Remote access | Tailscale Funnel, ports 443/8443/10000 | helper and supervisor tests |
+| iOS | native DeepPilot client, protocol v2 | simulator build and v2 pairing/challenge evidence |
+
+## Protocol boundary
+
+- Protocol v2 is the only supported wire version. Existing protocol-v1 devices must pair again after upgrading.
+- Bearer authentication, URL credentials, and first-frame shared tokens are rejected. A supported client registers a P-256 public key through `/phone/pair` and signs each WebSocket challenge.
+- Without a compatible embedded helper, the core bridge and trusted-LAN mode can still run; remote Funnel reports `unavailable`.
+- If a DSH Host API is missing, only the dependent capability should be disabled. The plugin must not crash the Host.
+- On the tested 0.1.2 Host, the compatibility facade converts the
+  current Session controller's raw event arrays into the stable wrapped
+  history entries consumed by the phone bridge. Sessions persisted by earlier
+  Hosts can therefore be listed and opened when the 0.1.2 Host's own
+  persistence reader accepts their log vocabulary. Unsupported persisted
+  formats still fail closed in the Host without modifying the original log.
 
 ## Not yet claimed
 
 - Intel macOS support for the embedded helper;
 - signed/notarized helper distribution;
 - Windows or Linux host validation;
+- repair or migration of persisted history rejected by the `0.1.2`
+  Host's own session reader;
 - every DSH developer-preview revision;
 - physical-device performance and every carrier/network combination;
 - production APNs delivery without a real provider credential and device.
 
-When reporting an issue, include `node --version`, the exact DSH package
-version, plugin commit/tag, macOS version and architecture, connection mode,
-and sanitized status output. Never include bearer tokens or message content.
+When reporting an issue, include `node --version`, the exact DSH package version, plugin commit/tag, macOS version and architecture, connection mode, and sanitized status output. Never include pairing codes, key material, APNs tokens, or message content.

package/PRIVACY.md

@@ -1,64 +1,36 @@
 # Privacy and data flow
 
-DeepPilot is designed around a direct connection to the DSH Host controlled by
-the user. The plugin does not upload complete conversations to a DeepPilot
-application server.
+DeepPilot connects directly to the DSH Host controlled by the user. The plugin does not upload complete conversations to a DeepPilot application server.
 
 ## Data stored on the Mac
 
 By default, runtime state is stored under `$DSH_HOME/deeppilot/`:
 
-- `auth-token`: the pairing bearer token, mode `0600`;
-- `devices.json`: paired-device identifiers, names, app versions, last-seen
-  timestamps, notification preferences, and APNs registrations;
-- `tailscale/`: local state for the optional embedded `tsnet` node.
+- `host-id`: a random, non-secret stable audience identifier;
+- `devices-v2.json`: paired public keys, fingerprints, scopes, device metadata, revocation/last-seen timestamps, notification preferences, and APNs registrations;
+- `tailscale/`: local state for the optional embedded tsnet node.
 
-The pairing token and full APNs tokens are not rendered in routine logs. The
-settings report exposes only token readiness and masked/fingerprint values
-needed for diagnostics.
+The directory is owner-only mode `0700`. The Mac never receives or stores iPhone private signing keys. Pairing codes exist only in plugin memory for up to five minutes and are not written to disk.
+
+The settings report exposes public-key fingerprints, scopes, revocation state, and masked notification diagnostics. It does not expose full APNs tokens, pairing codes, or message bodies.
 
 ## Direct session connection
 
-Projects, session lists, conversation history, prompts, streaming events,
-approvals, questions, and model changes travel over the authenticated
-connection between the iPhone and the user's DSH Host.
+Projects, history, prompts, streaming events, approvals, questions, and model changes travel over the authenticated connection between the iPhone and the user's DSH Host.
 
-- In LAN mode this is direct HTTP/WebSocket traffic and is not encrypted by the
-  plugin. Use a trusted network.
-- In Funnel mode the phone uses HTTPS/WSS through Tailscale Funnel. The helper
-  forwards only `/phone` and `/phone/health` to the local DSH origin.
+- LAN mode is direct HTTP/WebSocket traffic and is not encrypted by the plugin. Use a trusted network.
+- Funnel mode uses HTTPS/WSS. The helper forwards only `/phone`, `/phone/pair`, and `/phone/health`.
 
 ## Optional offline push
 
-Offline push is optional.
-
-### Direct APNs mode
-
-When `provider: apns` is configured, the user's Mac sends the APNs device token
-and notification payload directly to Apple. The user supplies and controls the
-Apple provider credentials.
-
-### DeepPilot relay mode
-
-When `provider: relay` is active, the plugin sends the following over HTTPS to
-the configured relay:
+Direct APNs mode sends the device token and notification payload to Apple using user-controlled credentials. Relay mode sends over HTTPS:
 
 - a per-bridge relay authorization token;
-- target APNs device token and sandbox/production environment;
-- notification identifier, category, session identifier, title, and a short,
-  truncated notification body.
-
-The body may contain a short assistant reply, session title, approval summary,
-or question text. The relay does not receive complete history, attachments,
-live token streams, prompts that are unrelated to the notification, the local
-pairing token, or the Tailscale node state.
+- target APNs device token and environment;
+- notification identifier, category, session identifier, title, and a short, truncated body.
 
-Apple receives the normal APNs alert payload in both modes. Users who do not
-want this disclosure can disable offline push; live WebSocket operation remains
-available.
+The relay does not receive complete history, attachments, live token streams, unrelated prompts, pairing codes, device keys, the device registry, or Tailscale state. Disabling offline push removes this path.
 
 ## Logs
 
-Routine logs contain lifecycle state, delivery outcomes, and masked token
-prefixes. They are designed not to contain pairing tokens or message bodies.
-Frame-level diagnostics are emitted only when `debug` is enabled.
+Routine logs contain lifecycle state, delivery outcomes, and process-local salted hashes for source/device identifiers. Logs are designed not to contain pairing codes, key material, APNs tokens, or message bodies. Frame diagnostics appear only with `debug`.

package/README.md

@@ -20,7 +20,8 @@ Host on your own Mac and does not replace or modify the DSH Web UI.
 
 - Browse projects, sessions, history, and live agent output from iPhone.
 - Send prompts, switch models, create sessions, and answer approvals/questions.
-- Pair through a QR code with the secret stored on the Mac and in iOS Keychain.
+- Pair with a five-minute single-use code and a per-device P-256 key; physical
+  iPhones keep the private key in Secure Enclave.
 - Connect over a trusted LAN or the optional embedded Tailscale Funnel.
 - Receive live notifications and optional APNs notifications while offline.
 - Self-update hint: the settings page footer shows the installed plugin
@@ -30,7 +31,7 @@ Host on your own Mac and does not replace or modify the DSH Web UI.
 
 ## Install from npm
 
-Requirements: Node.js 22+, a DSH `web` profile, and macOS. The bundled Funnel
+Requirements: Node.js 22+, DSH 0.1.2 with a `web` profile, and macOS. The bundled Funnel
 helper currently supports Apple silicon; trusted-LAN mode does not require it.
 
 ```sh
@@ -39,7 +40,8 @@ dsh web
 ```
 
 After DSH restarts, open **Settings → DeepPilot**, enable the connection, show
-the pairing QR code, and scan it in the DeepPilot app.
+the pairing QR code, and scan it in the DeepPilot app. The same panel also
+shows a copyable pairing code for Simulator or manual entry.
 
 Package: [npmjs.com/package/dsh-deeppilot](https://www.npmjs.com/package/dsh-deeppilot)
 
@@ -57,13 +59,20 @@ DeepPilot state under `$DSH_HOME/deeppilot/`.
 
 Conversation traffic travels directly between the iPhone and your DSH Host.
 Trusted-LAN `ws://` traffic is unencrypted, so use it only on a network you
-trust. Optional Funnel mode exposes only the authenticated DeepPilot connection
-and health endpoints, not the complete DSH Web UI.
+trust. Optional Funnel mode exposes only the DeepPilot connection, one-time
+pairing, and health endpoints, not the complete DSH Web UI.
+
+The DeepPilot settings page exposes **Connections per public source** under
+the collapsed **Advanced settings** section. It defaults to `8`, accepts
+`1`–`16`, and briefly restarts the Funnel helper when changed, so connected
+remote clients reconnect once.
 
 Offline push is optional. Relay mode sends only the target APNs device token
 and a limited notification payload; full conversation history and live output
 do not pass through the relay. Read [PRIVACY.md](./PRIVACY.md) and
-[SECURITY.md](./SECURITY.md) before enabling remote access or push.
+[SECURITY.md](./SECURITY.md) before enabling remote access or push. Protocol-v2
+implementation status and remaining release validation are tracked in
+[docs/SECURITY_ROADMAP.md](./docs/SECURITY_ROADMAP.md).
 
 ## Screenshots
 
@@ -80,8 +89,9 @@ reporting an issue.
 ## Protocol
 
 [PROTOCOL.md](./PROTOCOL.md) is the normative DeepPilot bridge protocol. Any
-wire change must update that document and `src/protocol.ts` together, preserve
-protocol-v1 compatibility, and be coordinated with the private iOS client.
+wire change must update that document and `src/protocol.ts` together and be
+coordinated with the private iOS client. Protocol v2 is the only supported wire
+version; upgrades from v1 require re-pairing.
 
 ## Development
 

package/README.zh-CN.md

@@ -19,7 +19,8 @@
 
 - 在 iPhone 查看项目、会话、历史记录和 Agent 实时输出；
 - 发送提示词、切换模型、创建会话，并处理审批与提问；
-- 扫描二维码配对，密钥保存在 Mac 与 iOS Keychain；
+- 使用 5 分钟有效的单次配对码与设备级 P-256 密钥；iPhone 真机私钥保存在
+  Secure Enclave；
 - 使用可信局域网，或可选的内嵌 Tailscale Funnel 远程连接；
 - 接收在线通知，以及可选的离线 APNs 推送；
 - 更新提示：设置页底部显示当前插件版本，并在有新版本时附加一个指向
@@ -28,7 +29,7 @@
 
 ## 从 npm 安装
 
-需要 Node.js 22+、DSH `web` profile 与 macOS。内嵌 Funnel helper 目前支持
+需要 Node.js 22+、带 `web` profile 的 DSH 0.1.2 与 macOS。内嵌 Funnel helper 目前支持
 Apple silicon；可信局域网模式不依赖 helper。
 
 ```sh
@@ -37,7 +38,7 @@ dsh web
 ```
 
 DSH 重启后，打开 **设置 → DeepPilot**，启用连接并显示配对二维码，然后在
-DeepPilot App 中扫码。
+DeepPilot App 中扫码。同一面板也会显示可复制的配对码，供模拟器或手动输入使用。
 
 npm 包：[npmjs.com/package/dsh-deeppilot](https://www.npmjs.com/package/dsh-deeppilot)
 
@@ -54,11 +55,16 @@ dsh plugin --profile web remove dsh-deeppilot
 
 完整会话流量由 iPhone 直接连接用户自己的 DSH Host。可信局域网中的 `ws://`
 是明文流量，只应在可信网络使用。可选 Funnel 模式只暴露经过认证的 DeepPilot
-连接与健康检查端点，不会暴露完整 DSH Web UI。
+连接、单次配对与健康检查端点，不会暴露完整 DSH Web UI。
+
+DeepPilot 设置页在默认折叠的“高级设置”中提供“每个公网来源的连接上限”，默认
+`8`，可设置为 `1`–`16`。修改后 Funnel helper 会短暂重启，已连接的远程客户端
+会自动重连一次。
 
 离线推送是可选功能。中继模式只发送目标 APNs 设备 Token 和有限的通知内容；
 完整会话历史与实时输出不会经过中继。启用远程访问或推送前，请阅读
-[PRIVACY.md](./PRIVACY.md) 与 [SECURITY.md](./SECURITY.md)。
+[PRIVACY.md](./PRIVACY.md) 与 [SECURITY.md](./SECURITY.md)。协议 v2 的实现状态与
+剩余发布验证记录在 [docs/SECURITY_ROADMAP.zh-CN.md](./docs/SECURITY_ROADMAP.zh-CN.md)。
 
 ## App 截图
 
@@ -74,8 +80,8 @@ dsh plugin --profile web remove dsh-deeppilot
 ## 协议
 
 [PROTOCOL.md](./PROTOCOL.md) 是 DeepPilot 桥接协议的规范性文档。任何 wire
-变更都必须同步更新该文档与 `src/protocol.ts`，保持协议 v1 向后兼容，并与
-私有 iOS 客户端协调。
+变更都必须同步更新该文档与 `src/protocol.ts`，并与私有 iOS 客户端协调。
+协议 v2 是唯一支持的 wire version；从 v1 升级必须重新配对。
 
 ## 开发
 

package/SECURITY.md

@@ -2,43 +2,41 @@
 
 ## Supported releases
 
-Until the first stable release, only the latest tagged public-beta release is
-supported. DSH itself is a developer preview, so reports must include the exact
-DSH version, plugin commit or tag, operating system, architecture, and whether
-LAN or Funnel mode was used.
+Until the first stable release, only the latest tagged public-beta release is supported. Reports must include the exact DSH version, plugin commit or tag, operating system, architecture, and whether LAN or Funnel mode was used.
 
 ## Reporting a vulnerability
 
-Do not open a public issue containing pairing tokens, APNs device tokens,
-provider keys, relay credentials, private hostnames, conversation content, or
-an unpatched exploit. Use GitHub's private vulnerability reporting for
-`Mars-Sea/dsh-deeppilot` when available. If that channel is unavailable, open a
-minimal public issue requesting a private contact channel without including
-the sensitive details.
-
-## Trust boundaries
-
-- `/phone` and `/phone/health` require the pairing bearer token.
-- New clients authenticate with the `Authorization: Bearer` header or the
-  first WebSocket frame. Query-string tokens exist only for legacy clients.
-- The token is stored with mode `0600` on the Mac and in iOS Keychain.
-- Pairing QR codes contain the bearer secret. Treat screenshots as leaked
-  credentials and rotate the token from the DeepPilot settings page.
-- LAN `ws://` is unencrypted. Use it only on a trusted network.
-- The optional Funnel helper publishes only `/phone` and `/phone/health`, not
-  the complete DSH Web UI.
-- Debug logs may include status and masked identifiers, but must never include
-  pairing tokens or message bodies.
+Do not open a public issue containing pairing codes, APNs device tokens, provider keys, relay credentials, private hostnames, conversation content, or an unpatched exploit. Use GitHub private vulnerability reporting for `Mars-Sea/dsh-deeppilot` when available. Otherwise open a minimal issue asking for a private contact channel without sensitive details.
+
+## Protocol-v2 trust boundaries
+
+- `/phone/pair` accepts only a short-lived, single-use pairing code and a P-256 public key. The code expires after five minutes and is invalidated after one successful registration.
+- `/phone` upgrades anonymously, then sends a fresh 30-second challenge bound to the stable Host audience. The client proves possession of its registered P-256 private key with ECDSA/SHA-256.
+- The iOS app uses a non-exportable Secure Enclave key on physical devices. The Mac stores only public keys and metadata.
+- `GET /phone/health` is intentionally unauthenticated and returns only minimal readiness/version facts.
+- Protocol v1, shared Bearer tokens, query credentials, and `c2s.hello.auth` are not accepted. There is no remote downgrade switch.
+- The server enforces explicit protocol scopes, while the normal settings UI grants the default scope set and exposes only the global connection switch plus per-device deletion. Deleting a device disconnects it immediately.
+- The canonical `$DSH_HOME/deeppilot` directory is repaired to mode `0700`. `host-id` and `devices-v2.json` are owner-only.
+- LAN `ws://` is unencrypted. Use it only on a trusted network. Public access should use Funnel HTTPS/WSS.
+- The Funnel helper publishes only `/phone`, `/phone/pair`, and `/phone/health`, never the complete DSH Web UI.
+- Logs must never include pairing codes, key material, APNs tokens, or message bodies.
+
+## Online attack controls
+
+- The Funnel helper allows at most 60 requests per source per minute and 600 globally. Concurrent WebSockets per public source are configurable from 1 to 16 and default to 8.
+- The Node bridge independently allows at most 12 anonymous authentication or pairing attempts per source per minute, 120 globally, and two concurrent unauthenticated WebSockets per source.
+- Five failures within ten minutes block that source for 15 minutes. A blocked request receives HTTP 429 with `Retry-After`.
+- The bridge ignores caller-supplied forwarding headers on non-loopback sockets.
+- Audit logs use process-local salted hashes, preventing stable source/device correlation across restarts.
+
+If a QR code is exposed before expiry, invalidate it or issue a new one. If a paired device is lost or suspected compromised, delete that device from the settings list; other devices remain valid.
 
 ## Release integrity
 
-The public beta includes a prebuilt macOS Apple-silicon helper. Verify it from
-the repository root with:
+Verify the public-beta helper from the repository root with:
 
 ```bash
 cd bin && shasum -a 256 -c SHA256SUMS
 ```
 
-Developer ID signing and notarization are release gates for broad end-user
-distribution. Until those gates are complete, the helper is a public-beta
-artifact and not a production-readiness claim.
+Developer ID signing and notarization remain release gates for broad end-user distribution.

package/bin/SHA256SUMS

@@ -1,6 +1,6 @@
-6f7caac1655a0d2bce606bcfde2e53a4dde6aea89dff8d99fe2fb3d055d4461f  ./darwin-amd64/dsh-deeppilot-tunnel
-1eaa95742dbe592ab6e5c8bc00715fa63028b975a11876841e221390657535df  ./darwin-arm64/dsh-deeppilot-tunnel
-766c4dfdd70e1b7607b276d4e0cc66cfb6398904c9b841f973641622d9da26ab  ./linux-amd64/dsh-deeppilot-tunnel
-a61bc73b2eca7b6b8358d0c6ff3e6475de8200448d1ac423647d95c37b4d9a2f  ./linux-arm64/dsh-deeppilot-tunnel
-205f598f9c79138f4d8cef372f7a4aa9883f6a70d313bd5277ebac442e46063c  ./windows-amd64/dsh-deeppilot-tunnel.exe
-0282ee0a0a20bb1d220f9a6d4158a5f17d4c4afbbdb2451a22a246f219bbcde5  ./windows-arm64/dsh-deeppilot-tunnel.exe
+1f7f29e139f978a68da0bc80c5755e37aca311de06e5e2a14fb09ccb34647571  ./darwin-amd64/dsh-deeppilot-tunnel
+a7c879a104468c6ab7c782176f4ca4f1c87fbbffef298dc3a1009fa8960a801f  ./darwin-arm64/dsh-deeppilot-tunnel
+210a182ca76f09a244d8439f071b68c606157e5bdd18f383c16b2454b72d117c  ./linux-amd64/dsh-deeppilot-tunnel
+fb7d93a5edb2eeff8b867aa5c745618ef44f425bb7c4cd6aa6289116efef9fb2  ./linux-arm64/dsh-deeppilot-tunnel
+c1a23b917d4fcde70b449574b00cd4e453cd7e13d4777a7f7affaad9e0efbbac  ./windows-amd64/dsh-deeppilot-tunnel.exe
+eff7c91008f5846ccebdd8c7eb51f65ef96455c46f489de7c4d3d6b888a4f3f5  ./windows-arm64/dsh-deeppilot-tunnel.exe

package/docs/SECURITY_ROADMAP.md

@@ -0,0 +1,24 @@
+# Protocol-v2 security status
+
+[简体中文](./SECURITY_ROADMAP.zh-CN.md)
+
+Status: implemented on the development branch. `PROTOCOL.md` is normative. Protocol v1 is not retained; all devices must pair again.
+
+## Implemented
+
+- five-minute, single-use, high-entropy pairing codes;
+- P-256 device identities, Secure Enclave on physical iOS devices with a simulator Keychain fallback;
+- per-connection nonce/audience/timestamp challenge signatures;
+- host-side public-key fingerprints, per-device scopes and immediate revocation;
+- anonymous-endpoint rate limits, source blocking, bounded unauthenticated concurrency, and a bounded registry;
+- minimal unauthenticated health response; no Bearer or URL credentials;
+- privacy-preserving audit identifiers, a global connection switch, and per-device deletion; scopes remain enforced at the protocol layer.
+
+## Remaining release validation
+
+- share fixed canonical/signature vectors between TypeScript and Swift tests;
+- exercise pairing, reconnect/resume, and per-device deletion through both real LAN and Funnel paths;
+- add abuse tests for malformed requests, connection churn, replay, and many-source pressure;
+- document local recovery when `devices-v2.json` is lost;
+- decide whether high-impact approval responses should require fresh local biometric/user-presence confirmation;
+- keep dependency scanning and CodeQL green, then sign and notarize every distributed helper before claiming production readiness.

package/docs/SECURITY_ROADMAP.zh-CN.md

@@ -0,0 +1,24 @@
+# 协议 v2 安全状态
+
+[English](./SECURITY_ROADMAP.md)
+
+状态：已在开发分支实现，`PROTOCOL.md` 为规范来源。不保留协议 v1，所有设备都需要重新配对。
+
+## 已实现
+
+- 5 分钟有效、单次使用的高熵配对码；
+- P-256 设备身份；iOS 真机使用 Secure Enclave，模拟器使用钥匙串回退；
+- 每次连接使用 nonce、audience 和时间戳完成挑战签名；
+- 主机侧公钥指纹、单设备 scope 和即时撤销；
+- 匿名入口限速、来源封禁、未认证连接并发上限和设备表容量上限；
+- 最小化匿名探活响应，不接受 Bearer 或 URL 凭据；
+- 隐私化审计标识、全局连接开关和逐设备删除入口；scope 继续由协议层强制执行。
+
+## 发布前剩余验证
+
+- 在 TypeScript 与 Swift 测试间共享固定的规范化编码/签名向量；
+- 通过真实 LAN 与 Funnel 验证配对、重连/恢复和逐设备删除；
+- 补充畸形请求、连接抖动、重放和多来源压力测试；
+- 记录 `devices-v2.json` 丢失后的本机恢复流程；
+- 决定高影响审批是否要求新的本地生物识别/用户在场确认；
+- 保持依赖扫描与 CodeQL 通过，并在宣称生产可用前签名、公证所有分发 helper。