dsh-cindy-host 0.1.20

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "dsh-cindy-host",
+  "version": "0.1.20",
+  "private": false,
+  "description": "Cindy 手机客户端连接 DSH 的 Host 侧插件：会话/消息/审批/todo/goal 的手机通道，以及配套的设置卡片",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chanyuenpang/dsh-cindy-host.git"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "cindy",
+    "device-link"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "//files": "白名单，而非整个目录：.sandbox/（含凭据与会话）、.claw/runtime、验收日志、开发记录都不进包。见 doc/publishing.md §3。",
+  "files": [
+    "src",
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "doc"
+  ],
+  "type": "module",
+  "main": "./src/dsh-plugin.js",
+  "exports": {
+    ".": "./src/dsh-plugin.js",
+    "./client": "./lib/client.js",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "acceptance": "node tools/acceptance.mjs",
+    "acceptance:sandbox": "node tools/acceptance.mjs --base http://127.0.0.1:3081",
+    "sandbox": "node tools/sandbox.mjs start",
+    "sandbox:stop": "node tools/sandbox.mjs stop",
+    "restart": "node tools/restart-host.mjs",
+    "restart:apply": "node tools/restart-host.mjs --apply",
+    "audit:channels": "node tools/channel-audit.mjs",
+    "verify": "npm test && npm run audit:channels && npm run acceptance",
+    "demo": "node src/demo.js",
+    "login": "node src/login.js",
+    "logout": "node src/logout.js",
+    "host": "node src/host.js",
+    "host:demo": "node src/host-demo.js",
+    "test": "node --test",
+    "test:file-peer": "node --test test/file-peer-rtc.test.js test/host-file-peer.test.js test/host-file-ice.test.js test/host-media-fetch.test.js test/file-peer-integration.test.js",
+    "smoke:file-peer": "node tools/file-peer-rtc-smoke.mjs --manager"
+  },
+  "//dependencies": "只放宿主不提供的库。DSH 自己的包一律不进 dependencies —— 见下面 peerDependencies 的说明。`keytar` 放 optionalDependencies：它是**原生**模块，没有 C++ 工具链的机器上必然编译失败，而 pnpm 会把普通 dependency 的构建失败当成安装失败（exit 1）—— DSH 随后就不会把这个 bundle 写进 `dsh.profile.bundles`，行也就永远不会出现。可选依赖的构建失败是允许的，与我们本来就有的惰性 require + 降级（凭据能力不可用，插件照常 mount）语义一致。",
+  "dependencies": {
+    "werift": "0.24.4",
+    "ws": "^8.21.3"
+  },
+  "optionalDependencies": {
+    "keytar": "^7.9.0"
+  },
+  "//peerDependencies": "DSH 自己的包必须由宿主提供，绝不能声明成 dependency/optionalDependency：pnpm 会把它们**连同整代依赖图**装进 profile，宿主再组合这个混合体就起不来（实测：`^0.1.1-rc.2` 会把 28 个 0.1.1-rc.2 的包装进一个 0.1.5-rc.2 的宿主，profile 启动失败于 dsh-client-file-upload / dsh-session）。区间必须覆盖宿主那一代（semver 的预发布规则：`^0.1.1-rc.2` 匹配不到 `0.1.5-rc.2`），与生态里 dsh-codex / dsh-cost-meter 的写法一致；`0.2.0-rc.2` 需要 `>=0.2.0-rc.1 <0.3.0-0`。",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2 || ^0.1.5-rc.2 || >=0.2.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2 || ^0.1.5-rc.2 || >=0.2.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "//peerDependenciesMeta": "**故意没有这个字段。** `@deepseek-ai/dsh-host-apiproxy` 曾经在这里标 optional，但 0.2 已经删掉了这个包，而 `evaluatePluginCompatibility` 会遍历 `peerDependencies` 的**每一个键且不查 `peerDependenciesMeta`**，所以只要它出现在 peers 里，`dsh plugin add` 就会直接拒绝安装（`installation rejected`），启动时 bundle 也会被静默跳过、`dsh-cindy-host` 行根本不会出现。该适配器本来就走惰性 `require` + 失败降级（见 src/dsh-plugin.js 的 apiProxy 分支），从 peers 里移除不改变任何运行时行为，只是让两道门禁都能正确判定。",
+  "devDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  }
+}

package/src/auth-session.js

@@ -0,0 +1,189 @@
+/**
+ * Session lifecycle for the Cindy Host.
+ *
+ * Two callers with different needs share this module:
+ *  - the Web settings card needs a non-interactive restore (`restoreSession`),
+ *    because a host with no TTY can never answer a readline prompt;
+ *  - the `npm run host` CLI keeps the interactive fallback that asks for a
+ *    phone number and a verification code on the terminal.
+ *
+ * Tokens only ever travel between the OS credential store and the relay
+ * handshake; neither path prints them.
+ */
+import { randomUUID } from 'node:crypto';
+import { loginWithPhone } from './cindy-login.js';
+import { refreshStoredSession } from './cindy-login-flow.js';
+import { loadSession, saveSession, credentialStoreAvailable, clearSession as clearStoredSession } from './credential-store.js';
+
+// One in-process writer for login/logout and guarded refresh commits. This is
+// deliberately not a cross-process credential-store CAS.
+let credentialRevision = 0;
+let writes = Promise.resolve();
+function serializeWrite(action) {
+  const pending = writes.then(action);
+  writes = pending.catch(() => {});
+  return pending;
+}
+function sameCredential(a, b) {
+  return a != null && b != null && ['deviceId', 'authBaseUrl', 'accessToken', 'refreshToken']
+    .every((key) => a[key] === b[key]);
+}
+const superseded = () => ({ ok: false, reason: 'OWNER_UNVERIFIED', message: 'Cindy 登录归属已变化，未采用旧操作结果' });
+
+/** Refresh only a captured authenticated lease, never import another stored identity. */
+export async function refreshOwnedCredential(captured, ports = {}) {
+  const load = ports.loadSession ?? loadSession;
+  const save = ports.saveSession ?? saveSession;
+  const refresh = ports.refreshStoredSession ?? refreshStoredSession;
+  const current = ports.isCurrent ?? (() => false);
+  const revision = credentialRevision;
+  const snapshot = Object.freeze({ ...captured });
+  const stored = await load();
+  if (revision !== credentialRevision || !current() || !sameCredential(snapshot, stored)) return superseded();
+  const timeoutMs = Number.isSafeInteger(ports.timeoutMs) && ports.timeoutMs > 0 ? Math.min(ports.timeoutMs, 30_000) : 30_000;
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  ports.signal?.addEventListener('abort', abort, { once: true });
+  if (ports.signal?.aborted) abort();
+  const timer = setTimeout(abort, timeoutMs);
+  let aborted;
+  let refreshed;
+  try {
+    const cancelled = new Promise((resolve) => {
+      aborted = () => resolve({ ok: false });
+      controller.signal.addEventListener('abort', aborted, { once: true });
+      if (controller.signal.aborted) aborted();
+    });
+    refreshed = await Promise.race([
+      Promise.resolve().then(() => {
+        controller.signal.throwIfAborted();
+        return refresh(snapshot, { signal: controller.signal });
+      }), cancelled,
+    ]);
+  } catch { refreshed = { ok: false }; }
+  finally {
+    clearTimeout(timer);
+    ports.signal?.removeEventListener('abort', abort);
+    controller.signal.removeEventListener('abort', aborted);
+  }
+  if (!refreshed?.ok) return { ok: false, reason: 'AUTH_FAILED', message: 'Cindy 登录续期失败' };
+  const session = { ...snapshot, ...refreshed.session };
+  if (session.deviceId !== snapshot.deviceId || session.authBaseUrl !== snapshot.authBaseUrl
+      || typeof session.accessToken !== 'string' || !session.accessToken
+      || typeof session.refreshToken !== 'string' || !session.refreshToken) return superseded();
+  return serializeWrite(async () => {
+    const stored = await load();
+    if (revision !== credentialRevision || !current() || !sameCredential(snapshot, stored)) return superseded();
+    await save(session);
+    if (revision !== credentialRevision || !current()) return superseded();
+    credentialRevision += 1;
+    return { ok: true, session };
+  });
+}
+
+/**
+ * Load the stored session and refresh it.
+ *
+ * The credential ports are injectable so the **deletion rule** can be tested
+ * directly: it is the one behaviour here that is destructive, and it already cost
+ * a real login once.
+ * @param ports - optional overrides for the credential store and the refresher.
+ * @returns `{ ok: true, session }` when a usable session stands, else the reason none does.
+ */
+export async function restoreSession(ports = {}) {
+  const load = ports.loadSession ?? loadSession;
+  // A missing native dependency says nothing about whether the OS holds a login.
+  // Injected stores do not depend on this machine's keytar unless they opt in.
+  const available = ports.credentialStoreAvailable ?? (load === loadSession ? credentialStoreAvailable : undefined);
+  if (available && !available()) {
+    return {
+      ok: false,
+      reason: 'CREDENTIAL_STORE_UNAVAILABLE',
+      message: '本机 Cindy 凭据存储不可用，无法读取已有登录态。请修复当前 DSH 配置中的 keytar 原生模块（允许安装构建脚本或重新构建），然后重启 DSH；请勿因此清除登录态或重复登录。',
+    };
+  }
+  const save = ports.saveSession ?? saveSession;
+  const refresh = ports.refreshStoredSession ?? refreshStoredSession;
+  const revision = credentialRevision;
+  const saved = await load();
+  if (!saved) return { ok: false, reason: 'missing', message: '本机还没有 Cindy 登录态' };
+
+  if (revision !== credentialRevision) return superseded();
+  const refreshed = await refresh(saved);
+  if (revision !== credentialRevision) return superseded();
+  if (refreshed.ok) {
+    const session = { ...saved, ...refreshed.session };
+    return serializeWrite(async () => {
+      const stored = await load();
+      if (revision !== credentialRevision || !sameCredential(saved, stored)) return superseded();
+      await save(session);
+      if (revision !== credentialRevision) return superseded();
+      credentialRevision += 1;
+      return { ok: true, session };
+    });
+  }
+
+  // A service that could not be reached is not evidence about the credential at
+  // all: keep it and try with what is stored. If the access token has also
+  // expired the connection fails visibly, which is recoverable — unlike a
+  // credential that no longer exists.
+  if (refreshed.transient === true) {
+    return { ok: true, session: saved, refreshDeferred: true, message: refreshed.message };
+  }
+
+  // A **refused** session is reported, never deleted.
+  //
+  // This used to `clearSession()` on any failure, and that is what cost a real
+  // login: every Host start refreshes, `refreshStoredSession` used to fold
+  // timeouts and 5xx into "expired", and a second instance sharing the credential
+  // rotates the refresh token out from under the first — so one hiccup permanently
+  // deleted a working credential and forced a fresh login.
+  //
+  // Keeping it is safe, because the card's login form keys off this result
+  // (`resolved.ok`), not off the credential's presence: a rejected session still
+  // shows the form. What the user gets back is the ability to recover — a rotation
+  // that merely raced works again on the next start instead of demanding a new
+  // login. Deleting the credential is now something only an explicit logout does
+  // (`forgetSession`).
+  return { ok: false, reason: 'expired', message: refreshed.message, rejected: refreshed.rejected === true };
+}
+
+/**
+ * Persist a session the card just established.
+ * @param session - the session the login flow returned.
+ * @param ports - optional credential-store override, for tests.
+ */
+export async function adoptSession(session, ports = {}) {
+  const save = ports.saveSession ?? saveSession;
+  const stored = { deviceId: session.deviceId ?? randomUUID(), ...session };
+  credentialRevision += 1; // Fence refreshes immediately, before waiting for an older writer.
+  await serializeWrite(() => save(stored));
+  return stored;
+}
+
+/**
+ * Drop the stored session; the next connect starts from the login form.
+ *
+ * This is the **only** path that deletes the credential. A failed refresh reports
+ * itself instead (see {@link restoreSession}).
+ * @param ports - optional credential-store override, for tests.
+ */
+export async function forgetSession(ports = {}) {
+  const clear = ports.clearSession ?? clearStoredSession;
+  credentialRevision += 1;
+  await serializeWrite(clear);
+}
+
+/**
+ * CLI path: reuse a stored session when possible, otherwise ask on the terminal.
+ * @returns a usable Cindy session.
+ */
+export async function getAuthenticatedSession() {
+  const restored = await restoreSession();
+  if (restored.ok) return restored.session;
+  const session = await loginWithPhone({ clientType: 'desktop' });
+  await adoptSession(session);
+  return session;
+}
+
+export { forgetSession as clearSession };

package/src/authorization-policy.js

@@ -0,0 +1,59 @@
+/**
+ * Who may control this Host.
+ *
+ * Two facts decide admission, and only two:
+ *  1. the user turned the phone connection on (the settings switch), and
+ *  2. the device has not been explicitly revoked.
+ *
+ * There is deliberately no per-device enrollment step. The relay only ever
+ * routes frames between devices of ONE Cindy account, so a `link-open` that
+ * arrives here is already the same account as the session this Host logged in
+ * with; asking the user to additionally bless each device would be an
+ * enrollment UI the current scope excludes. Revocation stays available and is
+ * honored, which is what makes that omission safe to revisit later.
+ */
+export class AuthorizationPolicy {
+  /** @param settings - resolved `dsh-cindy-host` settings section. */
+  constructor(settings = {}) {
+    this.update(settings);
+  }
+
+  /** Re-resolve from settings; called on every settings change. */
+  update(settings = {}) {
+    // Keep the caller's section verbatim so `revoke` can hand back something
+    // `update` accepts — the internal shape below is not the settings shape.
+    this.raw = settings;
+    this.settings = {
+      // `transportEnabled` is the card's switch. `remoteControlEnabled` is the
+      // legacy/hand-edited spelling of the same intent and is still honored.
+      enabled: settings.transportEnabled === true || settings.remoteControlEnabled === true,
+      controllers: settings.controllers && typeof settings.controllers === 'object' ? settings.controllers : {},
+    };
+  }
+
+  /** Whether this Host is currently willing to be controlled at all. */
+  isEnabled() {
+    return this.settings.enabled;
+  }
+
+  /**
+   * Whether one `link-open`/`invoke` source may be served.
+   * @param deviceId - relay-assigned source device id (`Envelope.src`).
+   */
+  canAccept(deviceId) {
+    if (!this.settings.enabled || typeof deviceId !== 'string' || deviceId === '') return false;
+    return this.settings.controllers[deviceId]?.state !== 'revoked';
+  }
+
+  /** Produce the settings a revocation would write. Pure: the caller persists it. */
+  revoke(deviceId) {
+    const entry = this.settings.controllers[deviceId] ?? {};
+    return {
+      ...this.raw,
+      controllers: {
+        ...this.settings.controllers,
+        [deviceId]: { ...entry, state: 'revoked', revokedAt: new Date().toISOString(), grantRevision: (entry.grantRevision || 0) + 1 },
+      },
+    };
+  }
+}