@qzsy/dsh-bridge 0.0.0-stage → 3.0.0

package/client/index.js

@@ -0,0 +1,297 @@
+// DSH 远程隧道云 · 官方客户端（设置页面板）
+//
+// 仅包含 SaaS 隧道需要的最小 UI：状态、网关、设备码绑定/解绑、公网地址复制与二维码、
+// 在线态与最近错误。所有网络操作走 Host 侧 RPC（同一 profile 的本地回环）。
+import { PLUGIN_ID, PACKAGE_NAME, RPC_CHANNEL, RPC_ENDPOINTS } from '../lib/identity.js';
+import { createTranslator } from './locales.mjs';
+
+export const name = PLUGIN_ID;
+export const inject = ['slots', 'connection'];
+
+const h = (type, props, ...children) => React.createElement(type, props, ...children);
+
+const styles = {
+  wrap: { padding: '4px 0', maxWidth: 720, fontFamily: 'inherit' },
+  card: { border: '1px solid var(--dsw-alias-border-secondary, #e5e7eb)', borderRadius: 12, padding: 16, marginBottom: 12 },
+  row: { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' },
+  label: { fontSize: 12, color: 'var(--dsw-alias-label-secondary, #6b7280)', marginBottom: 6, display: 'block' },
+  value: { fontSize: 13, lineHeight: 1.6, wordBreak: 'break-all' },
+  input: { flex: '1 1 320px', minWidth: 0, padding: '8px 10px', borderRadius: 8, border: '1px solid var(--dsw-alias-border-secondary, #d1d5db)', font: 'inherit', fontSize: 13 },
+  btn: { padding: '7px 14px', borderRadius: 8, border: '1px solid var(--dsw-alias-border-secondary, #d1d5db)', background: 'transparent', color: 'inherit', cursor: 'pointer', fontSize: 13 },
+  btnPrimary: { padding: '7px 14px', borderRadius: 8, border: 'none', background: 'var(--dsw-alias-brand-primary, #4f6ef7)', color: '#fff', cursor: 'pointer', fontSize: 13, fontWeight: 600 },
+  badge: { display: 'inline-block', fontSize: 12, padding: '2px 8px', borderRadius: 999, border: '1px solid var(--dsw-alias-border-secondary, #d1d5db)' },
+  code: { fontSize: 28, fontWeight: 700, letterSpacing: 4, fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace', margin: '8px 0' },
+  error: { color: 'var(--dsw-alias-state-error-primary, #dc2626)', fontSize: 12, lineHeight: 1.6, wordBreak: 'break-all' },
+  muted: { color: 'var(--dsw-alias-label-secondary, #6b7280)', fontSize: 12, lineHeight: 1.6 },
+  qr: { width: 168, height: 168, borderRadius: 8, background: '#fff', padding: 6 },
+};
+
+function CopyButton({ value, t }) {
+  const [copied, setCopied] = React.useState(false);
+  const copy = React.useCallback(async () => {
+    if (!value) return;
+    try {
+      await navigator.clipboard.writeText(value);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch {}
+  }, [value]);
+  return h('button', { style: styles.btn, onClick: copy, disabled: !value }, copied ? t('copied') : t('copy'));
+}
+
+function UrlRow({ label, url, t }) {
+  if (!url) return null;
+  return h('div', { style: { marginTop: 10 } },
+    h('span', { style: styles.label }, label),
+    h('div', { style: styles.row },
+      h('input', { style: styles.input, readOnly: true, value: url, onFocus: (e) => e.currentTarget.select() }),
+      h(CopyButton, { value: url, t }),
+    ),
+  );
+}
+
+function BridgePanel() {
+  const t = createTranslator({});
+  // 注意：adminToken 必须先声明——后面 useCallback 的依赖数组会在 Hook 调用时立即求值，
+  // 若 state 声明在其后，会在渲染时触发 TDZ（Cannot access before initialization）导致整页白屏。
+  const [adminToken, setAdminToken] = React.useState('');
+  const rpc = React.useCallback((endpoint, payload, signal) =>
+    ctxRpc(endpoint, { ...(payload ?? {}), ...(adminToken ? { adminToken } : {}) }, signal), [adminToken]);
+  const [status, setStatus] = React.useState(null);
+  const [gatewayDraft, setGatewayDraft] = React.useState('');
+  const [codeDraft, setCodeDraft] = React.useState('');
+  const [busy, setBusy] = React.useState('');
+  const [error, setError] = React.useState('');
+  const [notice, setNotice] = React.useState('');
+  const [confirmUnbind, setConfirmUnbind] = React.useState(false);
+  const [accessUrl, setAccessUrl] = React.useState('');
+  const [qrDataUrl, setQrDataUrl] = React.useState('');
+  const [passwordDraft, setPasswordDraft] = React.useState('');
+
+  const loadAdminToken = React.useCallback(async (port) => {
+    if (!port) return;
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/__qzsy_bridge__/loopback-token`, { cache: 'no-store' });
+      const data = await res.json();
+      if (data?.adminToken) setAdminToken(data.adminToken);
+    } catch { /* 非物理本机（如远端浏览器）无法领取，面板保持只读 */ }
+  }, []);
+
+  const refresh = React.useCallback(async () => {
+    const res = await rpc(RPC_ENDPOINTS.getStatus);
+    if (res?.ok && res.value) {
+      setStatus(res.value);
+      setGatewayDraft((current) => current || res.value.gatewayUrl || '');
+      setError(res.value.lastError || '');
+      if (!adminToken) await loadAdminToken(res.value.proxy?.port);
+    } else if (res && res.ok === false) {
+      setError(res.error?.message ?? t('loadFailed'));
+    }
+  }, [t, adminToken, loadAdminToken]);
+
+  React.useEffect(() => {
+    refresh().catch(() => {});
+    const timer = setInterval(() => { refresh().catch(() => {}); }, 3000);
+    return () => clearInterval(timer);
+  }, [refresh]);
+
+  React.useEffect(() => {
+    if (!adminToken || !status?.publicUrl) {
+      setAccessUrl('');
+      setQrDataUrl('');
+      return;
+    }
+    let cancelled = false;
+    rpc(RPC_ENDPOINTS.getAccessUrl).then((res) => {
+      if (cancelled || !res?.ok) return;
+      setAccessUrl(res.value?.url ?? '');
+      setQrDataUrl(res.value?.qrDataUrl ?? '');
+    }).catch(() => {});
+    return () => { cancelled = true; };
+  }, [adminToken, status?.publicUrl, rpc]);
+
+  const run = React.useCallback(async (key, fn) => {
+    setBusy(key);
+    setError('');
+    setNotice('');
+    try {
+      const res = await fn();
+      if (res && res.ok === false) throw new Error(res.error?.message ?? 'RPC failed');
+      await refresh();
+      return res?.value;
+    } catch (err) {
+      setError(err?.message ?? String(err));
+      return null;
+    } finally {
+      setBusy('');
+    }
+  }, [refresh]);
+
+  const saveGateway = () => run('gateway', () => rpc(RPC_ENDPOINTS.saveGateway, { gatewayUrl: gatewayDraft })).then(() => setNotice(t('saved')));
+  const requestCode = () => run('code', () => rpc(RPC_ENDPOINTS.requestDeviceCode));
+  const bindCode = () => run('bind', () => rpc(RPC_ENDPOINTS.bindDevice, { code: codeDraft })).then((value) => { if (value) setCodeDraft(''); });
+  const startTunnel = () => run('start', () => rpc(RPC_ENDPOINTS.startTunnel, { autoStart: true }));
+  const stopTunnel = () => run('stop', () => rpc(RPC_ENDPOINTS.stopTunnel));
+  const unbind = () => run('unbind', () => rpc(RPC_ENDPOINTS.unbindDevice)).then(() => setConfirmUnbind(false));
+  const savePassword = () => run('password', () => rpc(RPC_ENDPOINTS.setAccessPassword, { password: passwordDraft })).then((value) => {
+    if (value) { setPasswordDraft(''); setNotice(t('passwordSet')); }
+  });
+
+  const bound = Boolean(status?.device?.bound);
+  const connected = Boolean(status?.connected);
+  const phase = status?.phase ?? 'idle';
+  const publicUrl = status?.publicUrl ?? '';
+  const pairing = status?.pairing;
+  const passwordSet = Boolean(status?.access?.passwordSet);
+  const stateText = connected ? t('ready') : (phase === 'connecting' || phase === 'reconnecting' ? t('connecting') : t('offline'));
+
+  return h('div', { style: styles.wrap },
+    h('div', { style: { marginBottom: 12 } },
+      h('div', { style: { fontSize: 15, fontWeight: 700 } }, t('subtitle')),
+      h('div', { style: styles.muted, marginTop: 4 }, `${PACKAGE_NAME} · v${status?.version ?? '—'}`),
+    ),
+
+    h('div', { style: styles.card },
+      h('div', { style: styles.row },
+        h('span', { style: styles.badge }, `${t('status')}: ${stateText}`),
+        h('span', { style: styles.badge }, bound ? `${t('device')}: ${status?.device?.idMasked ?? ''}` : t('notBound')),
+        status?.protocol ? h('span', { style: styles.badge }, `protocol v${status.protocol}`) : null,
+      ),
+      h('div', { style: { marginTop: 10 } },
+        h('span', { style: styles.label }, t('gateway')),
+        h('div', { style: styles.row },
+          h('input', {
+            style: styles.input,
+            value: gatewayDraft,
+            placeholder: 'wss://dsh.b.nps.qzsyzn.com/_gw/connect',
+            onChange: (e) => setGatewayDraft(e.target.value),
+          }),
+          h('button', { style: styles.btnPrimary, disabled: busy === 'gateway' || !gatewayDraft, onClick: saveGateway }, t('save')),
+        ),
+      ),
+      !adminToken ? h('div', { style: { ...styles.muted, marginTop: 8 } }, t('adminLocalOnly')) : null,
+      error ? h('div', { style: { ...styles.error, marginTop: 10 } }, `${t('lastError')}: ${error}`) : null,
+      notice ? h('div', { style: { ...styles.muted, marginTop: 8 } }, notice) : null,
+    ),
+
+    h('div', { style: styles.card },
+      h('div', { style: styles.row },
+        h('div', { style: { flex: 1, minWidth: 260 } },
+          h('div', { style: { fontSize: 13, fontWeight: 600 } }, t('device')),
+          h('div', { style: styles.muted },
+            bound
+              ? `${status?.device?.tunnel?.name || 'DSH'} · ${status?.device?.tunnel?.publicId || ''}`
+              : t('notBound'),
+          ),
+        ),
+        !bound && h('button', { style: styles.btnPrimary, disabled: Boolean(busy), onClick: requestCode }, t('getCode')),
+        bound && h('button', {
+          style: styles.btn,
+          disabled: Boolean(busy),
+          onClick: () => setConfirmUnbind(true),
+        }, t('unbind')),
+      ),
+      pairing && pairing.status === 'pending' ? h('div', { style: { marginTop: 12 } },
+        h('div', { style: styles.muted }, t('codeTitle')),
+        h('div', { style: styles.code }, pairing.code),
+        h('div', { style: styles.muted }, t('codeExpires')),
+        pairing.verificationUrl ? h('a', { href: pairing.verificationUrl, target: '_blank', rel: 'noreferrer', style: { fontSize: 12 } }, t('openConsole')) : null,
+      ) : null,
+      !bound ? h('div', { style: { marginTop: 12 } },
+        h('span', { style: styles.label }, t('bindManual')),
+        h('div', { style: styles.row },
+          h('input', { style: styles.input, value: codeDraft, onChange: (e) => setCodeDraft(e.target.value), placeholder: 'ABCD-1234' }),
+          h('button', { style: styles.btn, disabled: busy === 'bind' || !codeDraft, onClick: bindCode }, t('bind')),
+        ),
+      ) : null,
+      confirmUnbind ? h('div', { style: { marginTop: 12 } },
+        h('div', { style: { ...styles.muted, marginBottom: 8 } }, t('unbindConfirm')),
+        h('div', { style: styles.row },
+          h('button', { style: styles.btnPrimary, disabled: busy === 'unbind', onClick: unbind }, t('unbind')),
+          h('button', { style: styles.btn, onClick: () => setConfirmUnbind(false) }, t('cancel')),
+        ),
+      ) : null,
+    ),
+
+    h('div', { style: styles.card },
+      h('div', { style: { fontSize: 13, fontWeight: 600 } }, t('password')),
+      h('div', { style: styles.muted }, passwordSet ? t('passwordSet') : t('passwordHint')),
+      h('div', { style: { ...styles.row, marginTop: 8 } },
+        h('input', {
+          style: styles.input,
+          type: 'password',
+          value: passwordDraft,
+          onChange: (e) => setPasswordDraft(e.target.value),
+          placeholder: t('passwordPlaceholder'),
+        }),
+        h('button', { style: styles.btnPrimary, disabled: busy === 'password' || passwordDraft.length < 6, onClick: savePassword }, t('savePassword')),
+      ),
+    ),
+
+    h('div', { style: styles.card },
+      h('div', { style: styles.row },
+        h('div', { style: { flex: 1, minWidth: 200 } },
+          h('div', { style: { fontSize: 13, fontWeight: 600 } }, t('tunnel')),
+          h('div', { style: styles.muted }, connected ? publicUrl : t('noPublicUrl')),
+        ),
+        connected
+          ? h('button', { style: styles.btn, disabled: Boolean(busy), onClick: stopTunnel }, t('stop'))
+          : h('button', { style: styles.btnPrimary, disabled: Boolean(busy) || !bound || !passwordSet, onClick: startTunnel }, t('start')),
+      ),
+      publicUrl ? h('div', { style: { display: 'flex', gap: 16, marginTop: 12, flexWrap: 'wrap', alignItems: 'flex-start' } },
+        h('div', { style: { flex: '1 1 320px', minWidth: 260 } },
+          h(UrlRow, { label: t('publicUrl'), url: publicUrl, t }),
+          h(UrlRow, { label: t('accessUrl'), url: accessUrl, t }),
+        ),
+        qrDataUrl ? h('div', null,
+          h('div', { style: styles.label }, t('qr')),
+          h('img', { src: qrDataUrl, alt: t('qr'), style: styles.qr }),
+        ) : null,
+      ) : null,
+    ),
+  );
+}
+
+let ctxRpc = async () => ({ ok: false, error: { code: 'no-context', message: 'RPC not ready' } });
+let serviceControl = null;
+
+export function apply(ctx) {
+  ctxRpc = (endpoint, payload, signal) => ctx.connection.rpc.call(RPC_CHANNEL, endpoint, payload, signal);
+  const panel = (props = {}) => h(BridgePanel, { ...props, key: 'qzsy-dsh-bridge-panel' });
+  let visible = true;
+  let registration = null;
+  const register = () => {
+    if (!visible || registration) return;
+    try {
+      registration = ctx.slots.register({
+        name: 'settings.section',
+        id: PLUGIN_ID,
+        order: 10,
+        label: () => createTranslator(ctx)('title'),
+      }, panel);
+    } catch {}
+  };
+  const unregister = () => {
+    if (!registration) return;
+    try {
+      if (typeof registration === 'function') registration();
+      else registration.dispose?.();
+    } catch {}
+    registration = null;
+  };
+  try { ctx.slots.inject('settings.section', () => { if (visible) register(); }); } catch { register(); }
+
+  serviceControl = {
+    version: 1,
+    render: (props = {}) => h(BridgePanel, props),
+    setSettingsVisible: (next) => {
+      visible = Boolean(next);
+      if (visible) register();
+      else unregister();
+    },
+    settingsVisible: () => visible,
+  };
+  if (typeof ctx.provide === 'function') ctx.provide(PLUGIN_ID, serviceControl);
+}
+
+export { BridgePanel };

package/client/locales.mjs

@@ -0,0 +1,108 @@
+// 面板中英文词典（跟随 DSH <html lang>；ctx.locale 可用时优先用宿主语言服务）
+export const zh = {
+  title: '远程访问',
+  subtitle: 'DSH 远程隧道云 · 官方客户端',
+  gateway: 'SaaS 网关地址',
+  save: '保存网关',
+  saved: '已保存',
+  device: '设备',
+  notBound: '未绑定',
+  bound: '已绑定',
+  getCode: '获取设备码',
+  codeTitle: '在控制台添加设备并输入此设备码',
+  codeExpires: '设备码 10 分钟内有效，绑定后自动消失。',
+  openConsole: '打开控制台',
+  bindManual: '已有设备码？直接绑定',
+  bind: '绑定',
+  unbind: '解绑设备',
+  unbindConfirm: '确认解绑？',
+  cancel: '取消',
+  tunnel: '隧道',
+  start: '开启隧道',
+  stop: '关闭隧道',
+  connecting: '连接中…',
+  ready: '在线',
+  offline: '离线',
+  publicUrl: '公网地址',
+  copy: '复制',
+  copied: '已复制',
+  accessUrl: '带访问令牌的链接（首次打开后写入会话）',
+  qr: '扫码打开',
+  lastError: '最近错误',
+  password: '访问口令',
+  passwordHint: '首次使用必须先设置访问口令；远程/局域网访客需凭此口令通过本地门禁。',
+  passwordSet: '已设置访问口令（可在此修改）。',
+  passwordPlaceholder: '至少 6 位',
+  savePassword: '保存口令',
+  adminLocalOnly: '当前不是物理本机打开：面板只读，请在运行 DSH 的电脑上操作。',
+  noPublicUrl: '尚未获取公网地址（先开启隧道）',
+  autoStart: '随 DSH 启动自动开启',
+  status: '状态',
+  version: '版本',
+  loadFailed: '无法连接插件 RPC',
+};
+
+export const en = {
+  title: 'Remote Access',
+  subtitle: 'DSH Remote Tunnel Cloud · Official Client',
+  gateway: 'SaaS gateway URL',
+  save: 'Save gateway',
+  saved: 'Saved',
+  device: 'Device',
+  notBound: 'Not bound',
+  bound: 'Bound',
+  getCode: 'Get device code',
+  codeTitle: 'Add the device in the console and enter this code',
+  codeExpires: 'The code is valid for 10 minutes and disappears after binding.',
+  openConsole: 'Open console',
+  bindManual: 'Already have a code? Bind it',
+  bind: 'Bind',
+  unbind: 'Unbind device',
+  unbindConfirm: 'Confirm unbind?',
+  cancel: 'Cancel',
+  tunnel: 'Tunnel',
+  start: 'Start tunnel',
+  stop: 'Stop tunnel',
+  connecting: 'Connecting…',
+  ready: 'Online',
+  offline: 'Offline',
+  publicUrl: 'Public URL',
+  copy: 'Copy',
+  copied: 'Copied',
+  accessUrl: 'Access-token URL (writes a session cookie on first open)',
+  qr: 'Scan to open',
+  lastError: 'Last error',
+  password: 'Access password',
+  passwordHint: 'Set an access password before first use; remote/LAN visitors must pass the local gate with it.',
+  passwordSet: 'Access password is set (you can change it here).',
+  passwordPlaceholder: 'At least 6 characters',
+  savePassword: 'Save password',
+  adminLocalOnly: 'Opened outside the physical host: panel is read-only. Use the DSH machine to manage.',
+  noPublicUrl: 'No public URL yet (start the tunnel first)',
+  autoStart: 'Auto-start with DSH',
+  status: 'Status',
+  version: 'Version',
+  loadFailed: 'Cannot reach plugin RPC',
+};
+
+export function detectLang(host = {}) {
+  try {
+    const fromHost = host?.locale?.current?.();
+    if (fromHost === 'en' || fromHost === 'zh') return fromHost;
+  } catch {}
+  try {
+    const documentLang = globalThis.document?.documentElement?.getAttribute?.('lang');
+    if (documentLang) return String(documentLang).toLowerCase().startsWith('zh') ? 'zh' : 'en';
+  } catch {}
+  return 'zh';
+}
+
+export function createTranslator(host = {}) {
+  const lang = detectLang(host);
+  const dict = lang === 'en' ? en : zh;
+  return (key, vars = {}) => {
+    let text = dict[key] ?? zh[key] ?? key;
+    for (const [name, value] of Object.entries(vars ?? {})) text = text.replaceAll(`\${${name}}`, String(value));
+    return text;
+  };
+}

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# @qzsy/dsh-bridge bundle patch
+# 本包是 DSH 远程隧道云的官方客户端插件（独立实现）。
+# id 使用插件自己的命名空间，与 DSH profile 中其它插件互不覆盖。
+- insert:
+    - id: qzsy-dsh-bridge
+      name: '@qzsy/dsh-bridge'

package/lib/config.js

@@ -0,0 +1,93 @@
+// 配置读写：~/.dsh/qzsy-dsh-bridge/config.json，权限固定 0600。
+// 配置里含设备密钥与会话签名密钥，视同机器凭据：绝不外传日志，绝不放宽权限。
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+import { dirname } from 'node:path';
+import { resolveConfigPath } from './data-dir.js';
+import { DEFAULT_GATEWAY_URL, DEFAULT_PORT } from './identity.js';
+
+export const CONFIG_FILE_MODE = 0o600;
+const SCRYPT_KEYLEN = 32;
+
+export function createSecret(bytes = 32) {
+  return randomBytes(bytes).toString('base64url');
+}
+
+export function hashPassword(password, salt = randomBytes(16).toString('hex')) {
+  const hash = scryptSync(String(password), salt, SCRYPT_KEYLEN).toString('hex');
+  return { passwordHash: hash, passwordSalt: salt };
+}
+
+export function verifyPassword(password, { passwordHash = '', passwordSalt = '' } = {}) {
+  if (!passwordHash || !passwordSalt || typeof password !== 'string' || password === '') return false;
+  try {
+    const expected = Buffer.from(passwordHash, 'hex');
+    const actual = scryptSync(password, passwordSalt, expected.length);
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+  } catch {
+    return false;
+  }
+}
+
+/** 归一化 + 补默认值；不写盘（由 ensureConfigSecrets 决定是否需要持久化新密钥）。 */
+export function normalizeConfig(raw = {}) {
+  const input = raw && typeof raw === 'object' ? raw : {};
+  const access = input.access && typeof input.access === 'object' ? input.access : {};
+  const port = Number(input.port);
+  return {
+    port: Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_PORT,
+    gatewayUrl: typeof input.gatewayUrl === 'string' && input.gatewayUrl.trim()
+      ? input.gatewayUrl.trim()
+      : DEFAULT_GATEWAY_URL,
+    autoStart: input.autoStart === true,
+    deviceId: typeof input.deviceId === 'string' ? input.deviceId : '',
+    deviceSecret: typeof input.deviceSecret === 'string' ? input.deviceSecret : '',
+    tunnel: input.tunnel && typeof input.tunnel === 'object'
+      ? { publicId: String(input.tunnel.publicId ?? ''), name: String(input.tunnel.name ?? '') }
+      : null,
+    access: {
+      passwordHash: typeof access.passwordHash === 'string' ? access.passwordHash : '',
+      passwordSalt: typeof access.passwordSalt === 'string' ? access.passwordSalt : '',
+      token: typeof access.token === 'string' && access.token ? access.token : '',
+      sessionSecret: typeof access.sessionSecret === 'string' && access.sessionSecret ? access.sessionSecret : '',
+    },
+  };
+}
+
+/** 读取配置；文件缺失/损坏一律降级为默认值（首次安装等价）。 */
+export function loadConfig(filePath = resolveConfigPath()) {
+  try {
+    return normalizeConfig(JSON.parse(readFileSync(filePath, 'utf8')));
+  } catch {
+    return normalizeConfig({});
+  }
+}
+
+export function saveConfig(config, filePath = resolveConfigPath()) {
+  const normalized = normalizeConfig(config);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(normalized, null, 2), { mode: CONFIG_FILE_MODE, encoding: 'utf8' });
+  try { chmodSync(filePath, CONFIG_FILE_MODE); } catch { /* Windows 不实现 POSIX 权限位 */ }
+  return normalized;
+}
+
+/** 首次启动补上访问令牌 / 会话密钥（缺失才补，已有值不变），返回是否发生变更。 */
+export function ensureConfigSecrets(config) {
+  let changed = false;
+  if (!config.access.token) {
+    config.access.token = createSecret(24);
+    changed = true;
+  }
+  if (!config.access.sessionSecret) {
+    config.access.sessionSecret = createSecret(32);
+    changed = true;
+  }
+  return changed;
+}
+
+export function maskSecret(value, tail = 4) {
+  const text = String(value ?? '');
+  if (!text) return '';
+  if (text.length <= tail) return '•'.repeat(text.length);
+  return '•'.repeat(Math.min(8, text.length - tail)) + text.slice(-tail);
+}

package/lib/data-dir.js

@@ -0,0 +1,16 @@
+// 数据目录解析（Host 侧；依赖 node:os / node:path，client 不得 import）
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { DATA_DIR } from './identity.js';
+
+export function resolveDshHome(env = process.env) {
+  return env?.DSH_HOME || join(homedir(), '.dsh');
+}
+
+export function resolveDataDir(env = process.env) {
+  return join(resolveDshHome(env), DATA_DIR);
+}
+
+export function resolveConfigPath(env = process.env) {
+  return join(resolveDataDir(env), 'config.json');
+}

package/lib/dsh-cookie.js

@@ -0,0 +1,111 @@
+// 为 DSH 反转代理生成"本机回环"会话凭据的工具。
+//
+// 背景：DSH 的浏览器会话凭据绑定在 <host>:<port> 这个 authority 上，而本插件
+// 对外监听的端口与 DSH 自身端口不同；转发时必须替浏览器补一枚面向 DSH 端口的
+// 合法凭据，否则 DSH 会把所有经代理的请求当作未登录。
+//
+// 对外契约（由 DSH 宿主的浏览器鉴权实现决定，属外部协议常量）：
+//   cookie 名 = "dsh-auth-" + urlsafeBase64(sha256("127.0.0.1:<port>"))
+//   cookie 值 = "v1." + urlsafeBase64(JSON{v,authority,issuedAt,expiresAt}) + "." + urlsafeBase64(hmacSha256(body))
+// 签名密钥存放于 <DSH_HOME>/.credentials.yaml 的 client-connection/browser-session 记录。
+//
+// 本文件为独立实现，仅依赖 node 内置模块；不包含任何第三方项目代码。
+import { createHash, createHmac } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveDshHome } from './data-dir.js';
+
+const COOKIE_SPEC = { prefix: 'dsh-auth-', version: 1, ttlMs: 2592000000 };
+export const DSH_AUTH_COOKIE_PREFIX = COOKIE_SPEC.prefix;
+export const DSH_AUTH_COOKIE_VERSION = COOKIE_SPEC.version;
+export const DSH_AUTH_COOKIE_MAX_AGE_MS = COOKIE_SPEC.ttlMs;
+
+const base64url = (value) => Buffer.from(value).toString('base64url');
+const authorityOf = (host, port) => host + ':' + port;
+
+/** 会话 cookie 名由 authority 的哈希决定，不同端口互不覆盖。 */
+export function dshCookieNameFor(targetPort, host = '127.0.0.1') {
+  const digest = createHash('sha256').update(authorityOf(host, targetPort)).digest();
+  return DSH_AUTH_COOKIE_PREFIX + base64url(digest);
+}
+
+/**
+ * 从 .credentials.yaml 文本里定位 browser-session 记录的 secret。
+ * 逐行扫描而非整文件正则，避免误取模型 API key 等其它 secret 字段。
+ */
+export function extractBrowserSessionKey(content) {
+  const text = typeof content === 'string' ? content : '';
+  if (text.length === 0) return '';
+  const target = 'client-connection/browser-session:';
+  let recordIndent = -1;
+  let reading = false;
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.replace(/\t/g, '  ');
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith('#')) continue;
+    const indent = line.length - line.replace(/^\s+/, '').length;
+    if (trimmed === target) {
+      reading = true;
+      recordIndent = indent;
+      continue;
+    }
+    if (!reading) continue;
+    if (indent <= recordIndent) break;
+    const match = /^secret:\s*([A-Za-z0-9_-]+)$/.exec(trimmed);
+    if (match) return match[1];
+  }
+  // 兼容非标准缩进/单行写法：只在记录键之后有限范围内兜底查找。
+  const fallback = /client-connection\/browser-session[\s\S]{0,256}?secret:\s*([A-Za-z0-9_-]+)/.exec(text);
+  return fallback?.[1] ?? '';
+}
+
+/**
+ * 生成面向 <host>:<targetPort> 的 DSH 会话 cookie。
+ * @returns {string} "name=value"；参数不全时返回空串。
+ */
+export function mintDshAuthCookie({
+  targetPort,
+  secret,
+  host = '127.0.0.1',
+  now = Date.now(),
+  ttlMs = DSH_AUTH_COOKIE_MAX_AGE_MS,
+} = {}) {
+  if (!targetPort || !secret) return '';
+  const payload = {
+    version: COOKIE_SPEC.version,
+    authority: authorityOf(host, targetPort),
+    issuedAt: now - 1000,
+    expiresAt: now - 1000 + ttlMs,
+  };
+  const body = base64url(JSON.stringify(payload));
+  const mac = createHmac('sha256', Buffer.from(secret, 'base64url'));
+  const signature = base64url(mac.update(body).digest());
+  return dshCookieNameFor(targetPort, host) + '=v' + DSH_AUTH_COOKIE_VERSION + '.' + body + '.' + signature;
+}
+
+/** 读取本机凭据并生成 cookie；任何失败都返回空串。 */
+export function getDshAuthCookie(targetPort, options = {}) {
+  const env = options.env ?? process.env;
+  const read = options.readFileSync ?? readFileSync;
+  const exists = options.existsSync ?? existsSync;
+  try {
+    const home = options.dshHome ?? resolveDshHome(env);
+    const credentials = join(home, '.credentials.yaml');
+    if (!exists(credentials)) return '';
+    const secret = extractBrowserSessionKey(read(credentials, 'utf8'));
+    if (secret.length === 0) return '';
+    return mintDshAuthCookie({ targetPort, secret, now: options.now });
+  } catch {
+    return '';
+  }
+}
+
+/** 合并 Cookie 头：移除已有 DSH 会话（同 authority 只保留一枚），再追加新值。 */
+export function mergeCookieHeader(existing, cookie) {
+  const parts = String(existing ?? '')
+    .split(';')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0 && !part.startsWith(DSH_AUTH_COOKIE_PREFIX));
+  if (cookie) parts.push(cookie);
+  return parts.join('; ');
+}