dsh-qr-share 0.1.0

package/src/client/index.tsx

@@ -0,0 +1,107 @@
+/**
+ * dsh-qr-share client half.
+ *
+ * Registers a single `sidebar.footer.action` slot occupant that renders
+ * the QR-code button. The button stays mounted but hidden until the host
+ * half's `/_qr/share` returns `ready: true` — that happens exactly when
+ *   (a) the request passed `connection.requestRejection` (Host/Origin
+ *       trusted AND browser cookie valid), AND
+ *   (b) a non-empty launch token was minted.
+ * Both conditions jointly mean "the desktop has already completed the
+ * token-exchange redirect and now lives on /, not on /?token=…".
+ */
+import { Fragment, createElement, useEffect, useState } from 'react'
+import type { ReactNode } from 'react'
+import { QrButton } from './QrButton.tsx'
+import { fetchShareInfo, type ShareInfo } from './api.ts'
+import { LOCALE_NS, zh, en } from './locales.ts'
+
+// Ambient module augmentations — the host runtime supplies the real
+// service shapes via type-only declarations in its `@deepseek-ai/*`
+// packages. We declare just enough for our apply() to type-check.
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    locale: {
+      register(ns: string, dict: { zh: unknown; en: unknown }): () => void
+      bind(ns: string): (k: string) => string
+    }
+    slots: {
+      inject(slot: string, factory: () => unknown): void
+      register(opts: {
+        name: string
+        id: string
+        order: number
+        locale: string
+      }, component: (owner: SidebarFooterActionOwnerPropsLike) => ReactNode): () => void
+    }
+    /** Empty marker: this entry only needs slots + locale. */
+  }
+}
+
+interface SidebarFooterActionOwnerPropsLike {
+  wide: boolean
+}
+
+/** Services required before this entry activates. */
+export const inject = ['slots', 'locale', 'connection'] as const
+
+/**
+ * The footer-action component. Mounted by the slot registry; receives the
+ * sidebar's wide/rail state via the slot owner props.
+ * @param owner - slot owner props from the sidebar shell.
+ * @param t - locale reader bound by the apply function below.
+ */
+function FooterAction(
+  owner: SidebarFooterActionOwnerPropsLike,
+  t: (k: keyof typeof zh) => string,
+): ReactNode {
+  const [info, setInfo] = useState<ShareInfo | null>(null)
+
+  useEffect(() => {
+    // Probe on mount; refresh on window focus (a fresh login in another
+    // tab + focus-back should immediately enable the button).
+    let cancelled = false
+    const refresh = (): void => {
+      void fetchShareInfo().then((next) => {
+        if (!cancelled) setInfo(next)
+      })
+    }
+    refresh()
+    window.addEventListener('focus', refresh)
+    return () => {
+      cancelled = true
+      window.removeEventListener('focus', refresh)
+    }
+  }, [])
+
+  // Two-stage gate: null = still probing (no flicker); !ready = server
+  // says "no" (button hidden); ready = render.
+  if (info === null) return null
+  if (!info.ready) return null
+
+  return createElement(QrButton, { info, wide: owner.wide, t })
+}
+
+/**
+ * Register dictionaries and the slot occupant.
+ * @param ctx - client root context (slots + locale + connection injected).
+ */
+export function apply(ctx: import('@deepseek-ai/cordis').Context): void {
+  // Locale registration is a side-effect on the locale service; the slot
+  // rendering reads through the bound `t` thunk the apply captures here.
+  ctx.effect(() => ctx.locale.register(LOCALE_NS, { zh, en }), 'qr-share: dictionaries')
+  const t = ctx.locale.bind(LOCALE_NS) as (k: keyof typeof zh) => string
+
+  ctx.slots.inject('sidebar.footer.action', () =>
+    ctx.slots.register({
+      name: 'sidebar.footer.action',
+      id: 'qr-share',
+      order: 100, // after the Settings icon (which is order 0/10)
+      locale: LOCALE_NS,
+    }, (owner: SidebarFooterActionOwnerPropsLike) => FooterAction(owner, t)),
+  )
+}
+
+// Suppress unused warning for Fragment; we keep the import so future
+// expansions (toast messages, multi-button groups) don't churn imports.
+void Fragment

package/src/client/locales.ts

@@ -0,0 +1,38 @@
+/**
+ * dsh-qr-share dictionaries: zh-Hans + en. The shell's locale service
+ * drives the active language; the footer action reads via `ctx.locale.bind`.
+ */
+
+export const LOCALE_NS = 'qr-share' as const
+
+export interface QrShareKey {
+  'button.label': string
+  'button.tooltip': string
+  'dialog.title': string
+  'dialog.hint': string
+  'dialog.urlLabel': string
+  'dialog.close': string
+  'dialog.error': string
+}
+
+export const zh: QrShareKey = {
+  'button.label': '扫码登录',
+  'button.tooltip': '用手机扫码以同一账号登录',
+  'dialog.title': '用手机扫码登录',
+  'dialog.hint':
+    '用手机相机扫描下方二维码。手机打开后会自动以当前账号登录，token 与浏览器 cookie 同寿命。',
+  'dialog.urlLabel': '链接',
+  'dialog.close': '关闭',
+  'dialog.error': '二维码生成失败',
+}
+
+export const en: QrShareKey = {
+  'button.label': 'Mobile Login',
+  'button.tooltip': 'Scan with a phone to log in to this session',
+  'dialog.title': 'Scan to log in on mobile',
+  'dialog.hint':
+    'Scan the QR code below with your phone camera. The phone will log in to this session; the token lives as long as the browser cookie.',
+  'dialog.urlLabel': 'URL',
+  'dialog.close': 'Close',
+  'dialog.error': 'Failed to render QR code',
+}

package/src/client/styles.module.css

@@ -0,0 +1,158 @@
+/**
+ * dsh-qr-share styles. Two pieces:
+ *
+ *  1. The sidebar footer action button — same row layout as the official
+ *     Settings trigger (`sidebar.settings` occupant). The shell handles
+ *     wide vs rail sizing; we only style the inner button + icon.
+ *
+ *  2. The dialog — a centered overlay with backdrop, mimicking the visual
+ *     tone of the existing Settings panel without depending on its CSS
+ *     variables (plugins can't reach the shell's CSS module surface).
+ *
+ * Colors are kept neutral so the plugin inherits whichever theme the
+ * user has active (light/dark) via `color-scheme` + native inheritance.
+ */
+
+.button {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 8px 10px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+  text-align: left;
+}
+
+.button:hover {
+  background: color-mix(in srgb, currentColor 8%, transparent);
+}
+
+.button:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: -2px;
+}
+
+.buttonLabel {
+  font-size: 13px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.backdrop {
+  position: fixed;
+  inset: 0;
+  background: color-mix(in srgb, black 45%, transparent);
+  display: grid;
+  place-items: center;
+  z-index: 9999;
+  animation: dsh-qr-share-fade-in 120ms ease-out;
+}
+
+.dialog {
+  background: var(--dsh-qr-share-dialog-bg, #ffffff);
+  color: var(--dsh-qr-share-dialog-fg, #111111);
+  border-radius: 12px;
+  padding: 24px;
+  min-width: 320px;
+  max-width: 420px;
+  box-shadow: 0 12px 32px color-mix(in srgb, black 25%, transparent);
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  align-items: center;
+  animation: dsh-qr-share-pop-in 160ms cubic-bezier(0.2, 0.9, 0.3, 1.2);
+}
+
+@media (prefers-color-scheme: dark) {
+  .dialog {
+    background: var(--dsh-qr-share-dialog-bg, #1c1c1f);
+    color: var(--dsh-qr-share-dialog-fg, #f0f0f0);
+  }
+}
+
+.title {
+  font-size: 16px;
+  font-weight: 600;
+  margin: 0;
+}
+
+.canvas {
+  display: block;
+  image-rendering: pixelated;
+  border-radius: 8px;
+}
+
+.err {
+  color: #d23f3f;
+  font-size: 13px;
+  margin: 0;
+}
+
+.urlBlock {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  width: 100%;
+  align-items: center;
+}
+
+.urlLabel {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  opacity: 0.6;
+}
+
+.url {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 11px;
+  word-break: break-all;
+  background: color-mix(in srgb, currentColor 6%, transparent);
+  padding: 6px 8px;
+  border-radius: 4px;
+  max-width: 100%;
+  text-align: center;
+}
+
+.hint {
+  font-size: 12px;
+  opacity: 0.7;
+  text-align: center;
+  margin: 0;
+}
+
+.close {
+  margin-top: 4px;
+  padding: 8px 16px;
+  border: 1px solid color-mix(in srgb, currentColor 20%, transparent);
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  border-radius: 6px;
+  cursor: pointer;
+}
+
+.close:hover {
+  background: color-mix(in srgb, currentColor 8%, transparent);
+}
+
+.close:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: -2px;
+}
+
+@keyframes dsh-qr-share-fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes dsh-qr-share-pop-in {
+  from { opacity: 0; transform: scale(0.92); }
+  to { opacity: 1; transform: scale(1); }
+}

package/src/config.ts

@@ -0,0 +1,37 @@
+/**
+ * dsh-qr-share Config schema. The host half is mounted as a cordis
+ * `insert` row; the `config` field in the patch is fed here. Defaults
+ * match a "just works" deployment with no patch config.
+ *
+ * Note: we DO NOT read DSH_PUBLIC_HOST here — the QR URL is composed
+ * by the browser from `window.location.origin`, so no configuration is
+ * required for the QR to point at the right host. The web-app
+ * trustedHosts patch (set elsewhere) still gates the /_qr/share route
+ * via the same trust fence that gates /api.
+ *
+ * We intentionally avoid @deepseek-ai/schemastery / zod — the patch
+ * overlay can only feed plain JS values, so a hand-rolled validator
+ * keeps the host bundle dependency-free.
+ */
+
+/** Wire shape (defaults applied). */
+export interface ResolvedConfig {
+  /** Master switch: false short-circuits the route to 404. */
+  enabled: boolean
+}
+
+const DEFAULTS: ResolvedConfig = { enabled: true }
+
+/**
+ * Apply defaults + permissive coercion. Patch-time `config:` maps are
+ * untyped JS objects; anything truthy that isn't explicitly `false`
+ * counts as enabled.
+ * @param raw - patch-time config object (or undefined).
+ * @returns resolved config.
+ */
+export function resolveConfig(raw: unknown): ResolvedConfig {
+  if (raw === null || typeof raw !== 'object') return DEFAULTS
+  const value = (raw as { enabled?: unknown }).enabled
+  if (value === false) return { enabled: false }
+  return DEFAULTS
+}

package/src/context-types.ts

@@ -0,0 +1,39 @@
+/**
+ * dsh-qr-share host context types. Declares the cordis Context services
+ * the host half consumes as ambient module augmentations. The actual
+ * services come from the loaded Connection + WebServer plugins; we
+ * declare the slices we use and rely on the module loader to supply
+ * the real implementations.
+ *
+ * Runtime: zero import from monorepo; type-only augmentations are
+ * stripped by tsdown.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+/** Minimal slice of `connection.requestRejection` we consume. */
+export interface ConnectionRejectionLike {
+  /** 401 when cookie missing/expired; 403 when Host/Origin not trusted. */
+  requestRejection(req: IncomingMessage): number | undefined
+  /** Add the fresh process token to a clean URL. */
+  authenticatedUrl(baseUrl: string): string
+}
+
+/** Minimal slice of `webServer.register` we consume. */
+export interface WebServerLike {
+  register(route: {
+    kind: 'exact'
+    path: string
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+  }): () => void
+}
+
+declare module '@deepseek-ai/cordis' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface Context {
+    connection: ConnectionRejectionLike
+    webServer: WebServerLike
+  }
+}
+
+/** Re-export for ergonomic imports. */
+export type Context = import('@deepseek-ai/cordis').Context

package/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ * dsh-qr-share host half.
+ *
+ * Exposes `/_qr/share` (exact HTTP route) to authenticated browsers. The
+ * response carries the fresh process launch token; the browser then
+ * composes the final URL as `${window.location.origin}/?token=${token}`
+ * so the QR code automatically follows whatever authority the desktop
+ * actually used (LAN IP, public domain, reverse-proxied sub-path on a
+ * port-80 host, etc.) — no DSH_PUBLIC_HOST coupling.
+ *
+ * Security: every request passes through `connection.requestRejection`,
+ * which applies the same trust fence as the /api gateway:
+ *   - 403 if Host is not in `trustedHosts` (LAN literals + --trusted-host)
+ *   - 401 if the browser cookie is missing/expired (i.e. not yet logged in)
+ * The token is only returned when both checks pass; the same code path
+ * also drives the client-side `ready` flag so the button is hidden until
+ * the user is actually authenticated.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { assertNodeContext } from './invariant.ts'
+import { resolveConfig, type ResolvedConfig } from './config.ts'
+import type { Context } from './context-types.ts'
+
+export const name = 'dsh-qr-share'
+export { resolveConfig }
+export type { ResolvedConfig } from './config.ts'
+
+/** Required services from the cordis fiber. */
+export const inject = ['connection', 'webServer'] as const
+
+/**
+ * The exact HTTP route name. Hard-coded so the plugin self-documents and
+ * a misconfigured patch never silently mounts under a wrong path.
+ */
+const ROUTE_PATH = '/_qr/share'
+
+/** Wall-clock approximate TTL of the browser cookie — purely advisory. */
+const ADVISORY_TOKEN_TTL_MS = 24 * 60 * 60 * 1000
+
+/** Resolve the launch token from the live BrowserAuth, given a request. */
+function resolveToken(ctx: Context, hostHeader: string): string {
+  const baseUrl = `http://${hostHeader}`
+  const launchUrl = ctx.connection.authenticatedUrl(baseUrl)
+  const token = new URL(launchUrl).searchParams.get('token')
+  return token ?? ''
+}
+
+/**
+ * Mount the route and return the disposer. Plugin fiber disposal removes
+ * it via the webServer's own bookkeeping.
+ * @param ctx - host cordis context (connection + webServer injected).
+ * @param rawConfig - patch-time config (validated by resolveConfig).
+ */
+export function apply(ctx: Context, rawConfig: unknown): void {
+  assertNodeContext()
+  const config = resolveConfig(rawConfig)
+  if (!config.enabled) return
+
+  const connection = ctx.connection
+  const webServer = ctx.webServer
+
+  webServer.register({
+    kind: 'exact',
+    path: ROUTE_PATH,
+    handler: (req: IncomingMessage, res: ServerResponse): void => {
+      // Trust + auth gate. Returns the rejection status (401/403) or undefined.
+      const rejection = connection.requestRejection(req)
+      if (rejection !== undefined) {
+        // Match /api's minimal response shape: status + plain text body.
+        // No JSON leak about which check tripped.
+        res.writeHead(rejection, {
+          'content-type': 'text/plain; charset=utf-8',
+          'cache-control': 'no-store',
+        })
+        res.end(
+          rejection === 401
+            ? 'qr-share: authentication required\n'
+            : 'qr-share: forbidden\n',
+        )
+        return
+      }
+
+      // Use req.headers.host (the authority the browser actually used).
+      // Trust fence has just approved it, so we don't risk SSRF here.
+      const hostHeader = req.headers.host
+      if (typeof hostHeader !== 'string' || hostHeader === '') {
+        res.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' })
+        res.end('qr-share: missing Host header\n')
+        return
+      }
+
+      const token = resolveToken(ctx, hostHeader)
+      const ready = token !== ''
+
+      const body = JSON.stringify({
+        ready,
+        token,
+        tokenTtlMs: ADVISORY_TOKEN_TTL_MS,
+      })
+      res.writeHead(200, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+      })
+      res.end(body)
+    },
+  })
+}

package/src/invariant.ts

@@ -0,0 +1,27 @@
+/**
+ * dsh-qr-share invariant — fails fast when the host half is loaded without
+ * the services it declares in `inject`. Mirrors the official DSH plugin
+ * invariant pattern (used by every bundle in the monorepo) so a misconfigured
+ * mount surfaces a precise error rather than a runtime undefined access.
+ */
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+/** Throws when the import-time guard fails; never returns. */
+export function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) {
+    throw new Error(`dsh-qr-share: ${message}`)
+  }
+}
+
+/**
+ * Guard `require` to the official Node context — the host half MUST NOT
+ * be loaded through the browser module table. The bundler's purity gate
+ * already blocks Node-builtin imports in the client bundles; this is the
+ * defense-in-depth runtime check.
+ */
+export function assertNodeContext(): void {
+  // Trigger a Node-only import to fail-fast in any non-Node runtime.
+  require('node:fs')
+}