dsh-qr-share

English | 中文

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.

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.

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)

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

# 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:

   - insert:
       - id: qr-share
         name: 'dsh-qr-share'
   

Configuration (patch overlay)

- insert:
    - id: qr-share
      name: 'dsh-qr-share'
      config:
        enabled: true   # default true; set false to short-circuit the route to 404

Build

# Recommended: pnpm (matches the project lockfile-less layout)
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)

# Also supported: npm (any Node >= 20, no extra install)
npm install
npm run build    # same tsc + tsdown pipeline
npm run typecheck
npm pack

For npm publishing we ship ./npm_publish.sh — a single-file mirror of the core_ts release flow (npm login → npm install → npm run build → npm pack --dry-run review → npm publish --access public).

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 for the step-by-step npm publish flow.

License

MIT — see LICENSE.

Acknowledgements

• dsh-better-sidebar — the slot injection and dual client bundle (official / plugin-registry) pattern is inspired by its tsdown.config.ts.
• qrcode — the QR code renderer.
• DSH community — for the dsh.community plugin manifest spec (0.15) and the verification / discovery surface at dsh.so.