dsh-qr-share 0.1.0

package/lib/index.js

@@ -0,0 +1,78 @@
+import { assertNodeContext } from "./invariant.js";
+//#region src/config.ts
+const DEFAULTS = { 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.
+*/
+function resolveConfig(raw) {
+	if (raw === null || typeof raw !== "object") return DEFAULTS;
+	if (raw.enabled === false) return { enabled: false };
+	return DEFAULTS;
+}
+//#endregion
+//#region src/index.ts
+const name = "dsh-qr-share";
+/** Required services from the cordis fiber. */
+const inject = ["connection", "webServer"];
+/**
+* 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 = 864e5;
+/** Resolve the launch token from the live BrowserAuth, given a request. */
+function resolveToken(ctx, hostHeader) {
+	const baseUrl = `http://${hostHeader}`;
+	const launchUrl = ctx.connection.authenticatedUrl(baseUrl);
+	return new URL(launchUrl).searchParams.get("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).
+*/
+function apply(ctx, rawConfig) {
+	assertNodeContext();
+	if (!resolveConfig(rawConfig).enabled) return;
+	const connection = ctx.connection;
+	ctx.webServer.register({
+		kind: "exact",
+		path: ROUTE_PATH,
+		handler: (req, res) => {
+			const rejection = connection.requestRejection(req);
+			if (rejection !== void 0) {
+				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;
+			}
+			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 body = JSON.stringify({
+				ready: token !== "",
+				token,
+				tokenTtlMs: ADVISORY_TOKEN_TTL_MS
+			});
+			res.writeHead(200, {
+				"content-type": "application/json; charset=utf-8",
+				"cache-control": "no-store"
+			});
+			res.end(body);
+		}
+	});
+}
+//#endregion
+export { apply, inject, name, resolveConfig };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+import { createRequire } from "node:module";
+//#region src/invariant.ts
+/**
+* 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.
+*/
+const require = createRequire(import.meta.url);
+/** Throws when the import-time guard fails; never returns. */
+function assert(condition, message) {
+	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.
+*/
+function assertNodeContext() {
+	require("node:fs");
+}
+//#endregion
+export { assert, assertNodeContext };

package/lib/types/client/QrButton.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+export interface QrButtonProps {
+    /** Authoritative payload from the host half. */
+    info: {
+        token: string;
+        tokenTtlMs: number;
+    };
+    /** Sidebar column state: true = wide (icon + label), false = rail (icon only). */
+    wide: boolean;
+    /** Locale reader from ctx.locale.bind(LOCALE_NS). */
+    t: (key: keyof typeof import('./locales.ts').zh) => string;
+}
+export declare function QrButton({ info, wide, t }: QrButtonProps): ReactNode;

package/lib/types/client/QrDialog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * QR-code modal: a fixed-position overlay with a canvas, the resolved URL
+ * as plain text (so the user can type it manually if scanning fails), and
+ * a Close button. The URL is composed from `window.location.origin` —
+ * not from the host — so it always matches whatever authority the
+ * desktop just used to reach this page.
+ *
+ * Server-side constraint: BrowserAuth.authorizeIndex only accepts token
+ * exchanges on path `/` (see browser-auth.ts). We enforce that here so a
+ * future reverse-proxy sub-path does NOT silently produce a 401 on the
+ * phone.
+ */
+import { type ReactNode } from 'react';
+export interface QrDialogProps {
+    token: string;
+    tokenTtlMs: number;
+    t: (key: keyof typeof import('./locales.ts').zh) => string;
+    onClose: () => void;
+}
+export declare function QrDialog({ token, tokenTtlMs, t, onClose }: QrDialogProps): ReactNode;

package/lib/types/client/api.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Client-side wrapper around the host half's `/_qr/share` route. A single
+ * GET; the browser's cookie is carried automatically (SameSite=Strict,
+ * set by BrowserAuth at the same authority).
+ *
+ * Returns null on any non-2xx or network failure so the caller can treat
+ * "not ready" and "still probing" identically.
+ */
+export interface ShareInfo {
+    /** True when the server saw an authenticated browser AND produced a token. */
+    ready: boolean;
+    /** Fresh launch token (process-stable; cookie-bound by Host once consumed). */
+    token: string;
+    /** Advisory TTL displayed in the dialog — not enforced server-side. */
+    tokenTtlMs: number;
+}
+export declare function fetchShareInfo(signal?: AbortSignal): Promise<ShareInfo | null>;

package/lib/types/client/index.d.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+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;
+        };
+    }
+}
+interface SidebarFooterActionOwnerPropsLike {
+    wide: boolean;
+}
+/** Services required before this entry activates. */
+export declare const inject: readonly ["slots", "locale", "connection"];
+/**
+ * Register dictionaries and the slot occupant.
+ * @param ctx - client root context (slots + locale + connection injected).
+ */
+export declare function apply(ctx: import('@deepseek-ai/cordis').Context): void;
+export {};

package/lib/types/client/locales.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare const LOCALE_NS: "qr-share";
+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 declare const zh: QrShareKey;
+export declare const en: QrShareKey;

package/lib/types/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function resolveConfig(raw: unknown): ResolvedConfig;

package/lib/types/context-types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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' {
+    interface Context {
+        connection: ConnectionRejectionLike;
+        webServer: WebServerLike;
+    }
+}
+/** Re-export for ergonomic imports. */
+export type Context = import('@deepseek-ai/cordis').Context;

package/lib/types/index.d.ts

@@ -0,0 +1,14 @@
+import { resolveConfig } from './config.ts';
+import type { Context } from './context-types.ts';
+export declare const name = "dsh-qr-share";
+export { resolveConfig };
+export type { ResolvedConfig } from './config.ts';
+/** Required services from the cordis fiber. */
+export declare const inject: readonly ["connection", "webServer"];
+/**
+ * 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 declare function apply(ctx: Context, rawConfig: unknown): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,9 @@
+/** Throws when the import-time guard fails; never returns. */
+export declare function assert(condition: unknown, message: string): asserts condition;
+/**
+ * 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 declare function assertNodeContext(): void;

package/package.json

@@ -0,0 +1,135 @@
+{
+  "name": "dsh-qr-share",
+  "version": "0.1.0",
+  "description": "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.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xiaoguomeiyitian/dsh-qr-share.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xiaoguomeiyitian/dsh-qr-share/issues"
+  },
+  "homepage": "https://github.com/xiaoguomeiyitian/dsh-qr-share#readme",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "qr-code",
+    "web-plugin"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./client/service": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./client/api": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/client-registry.js",
+    "lib/types/**/*.d.ts",
+    "src",
+    "cordis.patch.yml",
+    "dsh.plugin.json",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsdown",
+    "typecheck": "tsc --noEmit",
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "pack:tarball": "pnpm build && pnpm pack"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "xiaoguomeiyitian",
+    "url": "https://github.com/xiaoguomeiyitian"
+  },
+  "contributors": [
+    {
+      "name": "xiaoguomeiyitian",
+      "url": "https://github.com/xiaoguomeiyitian"
+    }
+  ],
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/xiaoguomeiyitian"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@types/node": "^22.0.0",
+    "@types/qrcode": "^1.5.5",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "lightningcss": "^1.27.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "react-icons": "^5.4.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/client/QrButton.tsx

@@ -0,0 +1,49 @@
+/**
+ * Sidebar footer action: a QR-code icon button. Clicking opens the
+ * `QrDialog`. The button renders only when the server reports `ready`
+ * (i.e. the browser is past the launch-token exchange AND a token is
+ * available); otherwise it stays mounted-but-empty so the slot ledger
+ * remains stable across the login → main transition.
+ */
+import { Fragment, createElement, useState } from 'react'
+import type { ReactNode } from 'react'
+import { HiOutlineQrCode } from 'react-icons/hi2'
+import { QrDialog } from './QrDialog.tsx'
+import { LOCALE_NS } from './locales.ts'
+
+export interface QrButtonProps {
+  /** Authoritative payload from the host half. */
+  info: { token: string; tokenTtlMs: number }
+  /** Sidebar column state: true = wide (icon + label), false = rail (icon only). */
+  wide: boolean
+  /** Locale reader from ctx.locale.bind(LOCALE_NS). */
+  t: (key: keyof typeof import('./locales.ts').zh) => string
+}
+
+export function QrButton({ info, wide, t }: QrButtonProps): ReactNode {
+  const [open, setOpen] = useState(false)
+  return createElement(Fragment, null,
+    createElement('button', {
+      type: 'button',
+      className: 'dsh-qr-share-button',
+      'aria-label': t('button.label'),
+      title: t('button.tooltip'),
+      onClick: () => { setOpen(true) },
+    },
+      createElement(HiOutlineQrCode, { size: wide ? 18 : 20 }),
+      wide
+        ? createElement('span', { className: 'dsh-qr-share-button-label' }, t('button.label'))
+        : null,
+    ),
+    open
+      ? createElement(QrDialog, {
+          token: info.token,
+          tokenTtlMs: info.tokenTtlMs,
+          t,
+          onClose: () => { setOpen(false) },
+        })
+      : null,
+  )
+}
+
+void LOCALE_NS

package/src/client/QrDialog.tsx

@@ -0,0 +1,105 @@
+/**
+ * QR-code modal: a fixed-position overlay with a canvas, the resolved URL
+ * as plain text (so the user can type it manually if scanning fails), and
+ * a Close button. The URL is composed from `window.location.origin` —
+ * not from the host — so it always matches whatever authority the
+ * desktop just used to reach this page.
+ *
+ * Server-side constraint: BrowserAuth.authorizeIndex only accepts token
+ * exchanges on path `/` (see browser-auth.ts). We enforce that here so a
+ * future reverse-proxy sub-path does NOT silently produce a 401 on the
+ * phone.
+ */
+import { createElement, useEffect, useRef, useState, type MouseEvent, type ReactNode } from 'react'
+import QRCode from 'qrcode'
+import { LOCALE_NS } from './locales.ts'
+
+export interface QrDialogProps {
+  token: string
+  tokenTtlMs: number
+  t: (key: keyof typeof import('./locales.ts').zh) => string
+  onClose: () => void
+}
+
+function composeQrUrl(token: string): string {
+  // URL API handles trailing slashes / port-less origins cleanly; the
+  // resulting href is always of the form `${origin}/?token=...`.
+  const url = new URL('/', window.location.origin)
+  url.searchParams.set('token', token)
+  return url.toString()
+}
+
+export function QrDialog({ token, tokenTtlMs, t, onClose }: QrDialogProps): ReactNode {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null)
+  const [payload, setPayload] = useState<string>('')
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (token === '') return
+    const url = composeQrUrl(token)
+    setPayload(url)
+    const canvas = canvasRef.current
+    if (canvas !== null) {
+      void QRCode.toCanvas(canvas, url, {
+        errorCorrectionLevel: 'M',
+        margin: 1,
+        width: 256,
+        color: { dark: '#000000', light: '#ffffff' },
+      }).catch((reason: unknown) => {
+        setError(reason instanceof Error ? reason.message : String(reason))
+      })
+    }
+  }, [token])
+
+  // Silence unused-var: tokenTtlMs is part of the public surface; the
+  // dialog could render a "expires in Nh" line in the future.
+  void tokenTtlMs
+
+  // Escape + backdrop dismiss. The dialog is rendered above the sidebar
+  // (fixed position) so the user expects the same UX as other DSH modals.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent): void => { if (e.key === 'Escape') onClose() }
+    window.addEventListener('keydown', onKey)
+    return () => { window.removeEventListener('keydown', onKey) }
+  }, [onClose])
+
+  const onBackdropClick = (e: MouseEvent<HTMLDivElement>): void => {
+    if (e.target === e.currentTarget) onClose()
+  }
+
+  return createElement('div', {
+    className: 'dsh-qr-share-backdrop',
+    role: 'presentation',
+    onClick: onBackdropClick,
+  },
+    createElement('div', {
+      className: 'dsh-qr-share-dialog',
+      role: 'dialog',
+      'aria-modal': 'true',
+      'aria-labelledby': 'dsh-qr-share-title',
+    },
+      createElement('h2', { id: 'dsh-qr-share-title', className: 'dsh-qr-share-title' },
+        t('dialog.title')),
+      error !== null
+        ? createElement('p', { className: 'dsh-qr-share-err' }, `${t('dialog.error')}: ${error}`)
+        : createElement('canvas', {
+            ref: canvasRef,
+            className: 'dsh-qr-share-canvas',
+            width: 256,
+            height: 256,
+          }),
+      createElement('div', { className: 'dsh-qr-share-url-block' },
+        createElement('span', { className: 'dsh-qr-share-url-label' }, t('dialog.urlLabel')),
+        createElement('code', { className: 'dsh-qr-share-url' }, payload),
+      ),
+      createElement('p', { className: 'dsh-qr-share-hint' }, t('dialog.hint')),
+      createElement('button', {
+        type: 'button',
+        className: 'dsh-qr-share-close',
+        onClick: onClose,
+      }, t('dialog.close')),
+    ),
+  )
+}
+
+void LOCALE_NS

package/src/client/api.ts

@@ -0,0 +1,41 @@
+/**
+ * Client-side wrapper around the host half's `/_qr/share` route. A single
+ * GET; the browser's cookie is carried automatically (SameSite=Strict,
+ * set by BrowserAuth at the same authority).
+ *
+ * Returns null on any non-2xx or network failure so the caller can treat
+ * "not ready" and "still probing" identically.
+ */
+
+export interface ShareInfo {
+  /** True when the server saw an authenticated browser AND produced a token. */
+  ready: boolean
+  /** Fresh launch token (process-stable; cookie-bound by Host once consumed). */
+  token: string
+  /** Advisory TTL displayed in the dialog — not enforced server-side. */
+  tokenTtlMs: number
+}
+
+const ROUTE_PATH = '/_qr/share'
+
+export async function fetchShareInfo(signal?: AbortSignal): Promise<ShareInfo | null> {
+  try {
+    const res = await fetch(ROUTE_PATH, {
+      method: 'GET',
+      credentials: 'same-origin',
+      cache: 'no-store',
+      headers: { 'accept': 'application/json' },
+      ...(signal === undefined ? {} : { signal }),
+    })
+    if (!res.ok) return null
+    const data = await res.json() as Partial<ShareInfo>
+    if (typeof data.token !== 'string' || typeof data.ready !== 'boolean') return null
+    return {
+      ready: data.ready,
+      token: data.token,
+      tokenTtlMs: typeof data.tokenTtlMs === 'number' ? data.tokenTtlMs : 0,
+    }
+  } catch {
+    return null
+  }
+}