dsh-qr-share 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to **dsh-qr-share** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-08-29
+
+### Added
+
+- **Host half** (`lib/index.js`) — registers `/_qr/share` HTTP route via
+  `ctx.webServer.register`. The route is gated by `connection.requestRejection`
+  (same trust fence as `/api`): 403 if Host is not in `trustedHosts`,
+  401 if the browser cookie is missing/expired, 200 only when both pass.
+  On success it returns `{ ready, token, tokenTtlMs }` so the client can
+  compose `${window.location.origin}/?token=${token}` without any
+  environment variable coupling.
+- **Client half** (`lib/client.js` + `lib/client-registry.js`) — registers a
+  `sidebar.footer.action` slot occupant. The button stays mounted but
+  hidden until the host reports `ready: true`; clicking it opens a dialog
+  showing the QR code (`qrcode` lib) and the resolved URL as plain text
+  fallback.
+- **Locale dictionaries** — `betterSidebar` namespace, `zh` and `en` translations
+  for button title and dialog copy.
+- **Two client bundles** — official profile channel (`lib/client.js`,
+  id `dsh-qr-share`) and plugin-registry channel (`lib/client-registry.js`,
+  id `dsh-external/dsh-qr-share`); both ship the same source compiled with
+  only the registered id and output filename differing.
+- **Type-only `Context` augmentations** — `declare module '@deepseek-ai/cordis'`
+  carries the minimal slices (`locale`, `slots`, `connection`, `webServer`)
+  we use; no runtime value import of cordis, the runtime instance is
+  supplied by the DSH core.
+- **`cordis.patch.yml`** — single `insert` row that the official
+  `dsh plugin --profile <name> add dsh-qr-share@<version>` reconciles
+  into `dsh.profile.bundles` automatically.
+
+### Security
+
+- The `/_qr/share` route only returns the launch token after passing the
+  same `connection.requestRejection` gate as `/api` — identical 401/403
+  status codes, identical minimal text body shape, no JSON leak about
+  which check tripped.
+- The launch token is process-stable (one per `dsh web` activation) and
+  becomes useless after the first exchange (the cookie is bound to the
+  authority and HttpOnly + SameSite=Strict).
+- The client uses `credentials: 'same-origin'` and `cache: 'no-store'`,
+  preventing cross-site frames from reaching the route and stopping
+  intermediary caches from storing the token.
+
+[Unreleased]: https://github.com/xiaoguomeiyitian/dsh-qr-share/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/xiaoguomeiyitian/dsh-qr-share/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xiaoguomeiyitian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# dsh-qr-share
+
+English | [中文](README.zh.md)
+
+> DSH web plugin: a sidebar-footer QR-code button that lets a phone scan
+> and re-issue the current browser's authenticated launch URL, reusing the
+> same `?token=…` exchange the desktop just completed.
+
+[![license](https://img.shields.io/github/license/xiaoguomeiyitian/dsh-qr-share)](LICENSE)
+[![version](https://img.shields.io/github/v/release/xiaoguomeiyitian/dsh-qr-share)](https://github.com/xiaoguomeiyitian/dsh-qr-share/releases)
+[![stars](https://img.shields.io/github/stars/xiaoguomeiyitian/dsh-qr-share?style=social)](https://github.com/xiaoguomeiyitian/dsh-qr-share/stargazers)
+[![dsh.so](https://www.dsh.so/badge/dsh-qr-share.svg)](https://www.dsh.so/artifact/dsh-qr-share)
+![dsh](https://img.shields.io/badge/DSH-0.1.0--rc.8%20%7C%200.1.2--alpha.1-8257D0)
+
+## Screenshots
+
+> Placeholder — add a screenshot of the sidebar footer button + dialog to
+> `docs/screenshot.png` and uncomment the line below. Recommended size:
+> 640×400, capturing the bottom of the sidebar and the QR dialog.
+
+<!-- ![QR button + dialog](docs/screenshot.png) -->
+
+## What it does
+
+1. After login, a QR-code icon appears in the sidebar footer (next to
+   the Settings trigger).
+2. Click → a dialog opens showing a QR code and the resolved URL as
+   plain text (fallback for failed scans).
+3. Scan with a phone → the phone opens the URL → the server's
+   `BrowserAuth` exchanges the token for a cookie (303 → `/`) and the
+   phone lands on the same session.
+
+The QR URL is composed from `window.location.origin` so it automatically
+matches whatever authority the desktop actually used (LAN IP, public
+domain, reverse-proxied sub-path). **No environment variable is needed
+for the QR to point at the right host** — the `DSH_PUBLIC_HOST` already
+in `web-external.patch.yml` still gates the route via the trust fence.
+
+## Security model
+
+- The `/_qr/share` route is gated by `connection.requestRejection` —
+  identical to `/api`'s gate. 403 if Host isn't trusted; 401 if the
+  browser cookie isn't valid. The token is only returned on 200.
+- The launch token is process-stable (one per `dsh web` activation) and
+  becomes useless after the first exchange (the cookie is bound to the
+  authority and HttpOnly + SameSite=Strict).
+- `SameSite=Strict` + same-origin `fetch` mean the route is unreachable
+  from any cross-site frame.
+
+## Install
+
+### Via the DSH plugin CLI (recommended for production)
+
+```bash
+dsh plugin --profile <name> add dsh-qr-share@latest
+```
+
+This adds the bundle declaration to your profile and reuses the
+`cordis.patch.yml` shipped in the package — no manual patch overlay
+edits needed.
+
+### Via plain `npm install`
+
+```bash
+# in a project that owns a DSH profile directory
+npm install dsh-qr-share
+# or with pnpm
+pnpm add dsh-qr-share
+```
+
+Then add the row from `cordis.patch.yml` (shipped with the package) to
+your profile's patch overlay, and ensure the package is reachable from
+the profile's `node_modules` (pnpm/npm flat layout works; pnpm strict
+layout needs a symlink — see `manual` install below).
+
+### Manual install (e.g. inside the docker-build image)
+
+1. Place the package at `/app/dsh-qr-share/`.
+2. Symlink it into `$DSH_HOME/profiles/node_modules/dsh-qr-share` (the
+   entrypoint does this for you; see `docker-build/docker-scripts/entrypoint.sh`).
+3. Add the row from `cordis.patch.yml` to your patch overlay:
+
+   ```yaml
+   - insert:
+       - id: qr-share
+         name: 'dsh-qr-share'
+   ```
+
+## Configuration (patch overlay)
+
+```yaml
+- insert:
+    - id: qr-share
+      name: 'dsh-qr-share'
+      config:
+        enabled: true   # default true; set false to short-circuit the route to 404
+```
+
+## Build
+
+```bash
+pnpm install
+pnpm build       # tsc declarations + tsdown bundles
+pnpm typecheck   # strict check
+pnpm pack        # produce dsh-qr-share-<version>.tgz (used by the install commands above)
+```
+
+Outputs:
+
+- `lib/index.js` — Node host half (the `/_qr/share` route)
+- `lib/invariant.js` — runtime guard
+- `lib/client.js` — official profile channel bundle (id `dsh-qr-share`)
+- `lib/client-registry.js` — plugin-registry channel bundle (id `dsh-external/dsh-qr-share`)
+- `lib/types/**` — TypeScript declarations
+
+## Compatibility
+
+- Node `>=20`
+- DSH (DeepSeek Harness) core `>=0.1.0-rc.8` (tested against
+  `0.1.1-rc.2` and `0.1.2-alpha.1`)
+- React `^18 || ^19` (peer, optional — the host half doesn't need React)
+
+The host half uses `@deepseek-ai/cordis` **types only** (declaration
+merging + `Context` re-export); the runtime cordis instance is supplied
+by the DSH core at plugin mount time. This is why the peer dependency
+on `@deepseek-ai/cordis` is intentionally absent — it would be rejected
+by the DSH market manifest gate, and is not required at runtime.
+
+## Publishing
+
+For maintainers — see [RELEASE-CHECKLIST.md](RELEASE-CHECKLIST.md) for
+the step-by-step `npm publish` flow.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Acknowledgements
+
+- [`dsh-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar) — the
+  slot injection and dual client bundle (official / plugin-registry) pattern
+  is inspired by its `tsdown.config.ts`.
+- [`qrcode`](https://www.npmjs.com/package/qrcode) — the QR code renderer.
+- DSH community — for the `dsh.community` plugin manifest spec
+  (`0.15`) and the verification / discovery surface at
+  [dsh.so](https://www.dsh.so).

package/README.zh.md

@@ -0,0 +1,109 @@
+# dsh-qr-share
+
+[English](README.md) | 中文
+
+> DeepSeek Harness 侧边栏底部 QR 码按钮插件。手机扫码即获取当前浏览器已登录的 launch URL，复用桌面已完成的 `?token=` 换 cookie 流程。
+
+![license](https://img.shields.io/github/license/xiaoguomeiyitian/dsh-qr-share)
+![version](https://img.shields.io/github/v/release/xiaoguomeiyitian/dsh-qr-share)
+![stars](https://img.shields.io/github/stars/xiaoguomeiyitian/dsh-qr-share?style=social)
+![dsh-so](https://www.dsh.so/badge/dsh-qr-share.svg)
+![dsh](https://img.shields.io/badge/DSH-0.1.0--rc.8%20%7C%200.1.2--alpha.1-8257D0)
+
+## 这是什么
+
+DSH 运行起来后，扫码登录很烦——你用手机拍屏幕上的 `127.0.0.1:3080` 没用。`dsh-qr-share` 在侧边栏底部加一个 QR 码按钮：
+
+1. 登录后，QR 码图标出现在侧边栏底部（设置按钮旁）。
+2. 点击 → 弹窗显示 QR 码 + URL 明文（扫码失败时手动复制）。
+3. 手机扫码 → 浏览器打开 URL → 服务端 `BrowserAuth` 拿 token 换 cookie（303 → `/）→ 手机落到同一会话。
+
+QR 内容用 `window.location.origin` 拼接，所以**自动跟随**桌面实际使用的 host（局域网 IP、公网域名、反向代理子路径）——**不需要任何环境变量**告诉它指向哪个 host。`web-external.patch.yml` 里那个 `DSH_PUBLIC_HOST` 只负责打开 `/_qr/share` 路由的信任围栏，不参与 URL 拼接。
+
+## 安全模型
+
+- `/_qr/share` 走与 `/api` 相同的 `connection.requestRejection` 围栏：
+  - 403 — Host 不在 `trustedHosts`；
+  - 401 — 浏览器 cookie 缺失/过期；
+  - 200 — 仅在两条都通过时返回 token。
+- 启动 token 每个 `dsh web` 进程一份（`process-stable`），第一次换 cookie 后即作废（cookie 绑定到 authority，HttpOnly + SameSite=Strict）。
+- 客户端用 `credentials: 'same-origin'` + `cache: 'no-store'`，跨站 frame 无法访问该路由。
+
+## 安装
+
+### 通过 DSH CLI（推荐）
+
+```bash
+dsh plugin --profile <name> add dsh-qr-share@latest
+```
+
+CLI 会自动把本包声明的 `cordis.patch.yml` 加进 `dsh.profile.bundles`，不需要手改 profile。
+
+### 通过 `npm install`
+
+```bash
+# 在拥有 DSH profile 目录的项目里
+npm install dsh-qr-share
+# 或
+pnpm add dsh-qr-share
+```
+
+然后把 `cordis.patch.yml`（包内自带）的一行加到 profile 的 patch overlay 里，并确保 profile 的 `node_modules` 能解析到这个包。
+
+### 手动安装（如 docker-build 镜像）
+
+1. 把包放到 `/app/dsh-qr-share/`。
+2. 用 symlink 链到 `$DSH_HOME/profiles/node_modules/dsh-qr-share`（`docker-build/docker-scripts/entrypoint.sh` 已自动做）。
+3. 在 patch overlay 加：
+   ```yaml
+   - insert:
+       - id: qr-share
+         name: 'dsh-qr-share'
+   ```
+
+## 配置（patch overlay）
+
+```yaml
+- insert:
+    - id: qr-share
+      name: 'dsh-qr-share'
+      config:
+        enabled: true   # 默认 true；设为 false 时路由 short-circuit 到 404
+```
+
+## 构建
+
+```bash
+pnpm install
+pnpm build       # tsc 声明 + tsdown bundle
+pnpm typecheck   # 严格检查
+pnpm pack        # 产出 dsh-qr-share-<version>.tgz
+```
+
+产物：
+
+- `lib/index.js` — Node 宿主半（`/_qr/share` 路由）
+- `lib/invariant.js` — 运行时守卫
+- `lib/client.js` — 官方 profile 通道 bundle（id `dsh-qr-share`）
+- `lib/client-registry.js` — plugin-registry 通道 bundle（id `dsh-external/dsh-qr-share`）
+- `lib/types/**` — TypeScript 声明
+
+## 兼容性
+
+- Node `>=20`
+- DSH core `>=0.1.0-rc.8`（已在 `0.1.1-rc.2` 与 `0.1.2-alpha.1` 实测）
+- React `^18 || ^19`（peer，可选；宿主半不依赖 React）
+
+宿主半只**类型层面**使用 `@deepseek-ai/cordis`（声明合并 + `Context` re-export），运行时 cordis 实例由 DSH core 在挂载时注入——所以 `peerDependencies` 里**故意没有** `@deepseek-ai/cordis`：它会被 DSH 市场 manifest 闸门按名硬拒，运行时也不需要。
+
+## 发布
+
+维护者请参考 [RELEASE-CHECKLIST.md](RELEASE-CHECKLIST.md) 走 `npm publish` 流程。
+
+## 许可证
+
+MIT — 见 [LICENSE](LICENSE)。
+
+## 致谢
+
+`[dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)` 启发了本插件的 slot 注入与多 bundle 双通道模式；`qrcode` 库提供 QR 渲染。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,38 @@
+# Third-Party Notices
+
+This project includes or depends on the following third-party software.
+The full corresponding license texts are reproduced below per their
+respective terms.
+
+---
+
+## `qrcode` — MIT
+
+> Copyright (c) 2012 Ryan Day
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+---
+
+## `react-icons` — MIT / CC0 (icon glyphs)
+
+`react-icons` redistributes icon glyphs from multiple upstream icon sets
+(Heroicons, VS Code Icons, etc.) under MIT for the wrapper code and
+CC0 1.0 Universal for the glyphs themselves. See
+<https://github.com/react-icons/react-icons#license> for the full breakdown.

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# dsh-qr-share bundle patch.
+#
+# When the plugin is installed through the official CLI:
+#
+#   dsh plugin --profile <name> add dsh-qr-share@<version>
+#
+# — this declaration makes the profile reconcile `dsh.profile.bundles`
+# against installed packages and append `dsh-qr-share` to the bundle
+# stack automatically. The profile boot then merges THIS patch (a single
+# `insert` of the plugin row) exactly like a manual cordis.patch.yml
+# mount line.
+#
+# `name` MUST be the package specifier, not a file path: dsh-client-
+# modules resolves `<name>/package.json` from the profile dir to
+# discover the client half and compose window.__DSH_BOOT__.
+#
+# To disable the plugin without uninstalling, swap this row's `name`
+# to a `!!js` expression returning a disabled placeholder (see
+# dsh-better-sidebar's cordis.patch.yml for the pattern).
+- insert:
+    - id: qr-share
+      name: 'dsh-qr-share'

package/dsh.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "dsh-external/dsh-qr-share",
+  "version": "0.1.0",
+  "main": "./lib/index.js",
+  "description": "Sidebar footer QR-code button: lets a phone scan and re-issue the current browser's authenticated launch URL, reusing the same ?token exchange the desktop just completed.",
+  "engines": {
+    "dsh": ">=0.0.1"
+  },
+  "contributes": {
+    "tools": [],
+    "skills": []
+  },
+  "client": {
+    "main": "./lib/client-registry.js"
+  }
+}