Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(device-link): add self-hosted relay and one-click server deployment

MagicLizi2ca79792b681
diff --git a/.gitignore b/.gitignore
index 964b8cee9c..38a2a4cd13 100644
--- a/.gitignore
+++ b/.gitignore
@@ -40,6 +40,7 @@ apps/desktop/resources/cc-manager/
apps/desktop/resources/pi-manager/
apps/desktop/resources/anthropic-compat-proxy/
apps/desktop/resources/remote-file-service/
+apps/desktop/resources/device-link-relay/
# Windows 打包时由 prePackage 现场 cargo build 生成并覆盖(forge.config.ts
# buildCindyUpdater);源码在 apps/desktop/cindy-updater/,不入仓避免 4.5MB
# 二进制持续消耗 Git LFS 流量。
diff --git a/AGENTS.md b/AGENTS.md
index 4958bb7700..c731d14cb0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -167,6 +167,9 @@
- 修改本地协议 package、插件分发来源边界或 device-link 协议/relay/隧道
payload/IPC allowlist,或任何改动跨端 wire protocol 前,必须先读
`docs/dev-rules/protocol-compatibility.md`。
+- 修改 Device Link 客户端、协议、relay、设备/媒体接口、能力协商或连接恢复行为前,必须先读
+ `docs/dev-rules/protocol-compatibility.md` 的「自建中转同步维护」:凡影响自建中转的改动,
+ 必须在同一次改动中完成必要的同步适配与互通验证,不得留到后续。
- 修改 package 依赖方向、main 进程模块加载方式,或主界面布局树结构前,必须先读
`docs/dev-rules/architecture-invariants.md`。
- 新增或修改 Settings UI、配置文件、本地偏好、运行时 profile,或 agent/MCP/provider
diff --git a/apps/desktop/forge.config.ts b/apps/desktop/forge.config.ts
index ed78d34718..6b97266c56 100644
--- a/apps/desktop/forge.config.ts
+++ b/apps/desktop/forge.config.ts
@@ -804,6 +804,8 @@ function extraResourcesForTarget(targetPlatform: string): string[] {
'resources/cc-manager',
'resources/anthropic-compat-proxy',
'resources/remote-file-service',
+ // 自建中转单文件:「部署到我的服务器」经 SSH 上传到用户服务器运行。
+ 'resources/device-link-relay',
// .cindy 发布者/审核 Ed25519 公钥信任表(私钥永不进客户端)。
'resources/ghost-trust.json',
// 远端 pi manager bundle(Node 单例 daemon,SSH remote 会话的进程持有器)。
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index fff0d08db8..beaa91d4bd 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -56,6 +56,7 @@
"@cindy/auth-client": "workspace:*",
"@cindy/browser-control-runtime": "workspace:*",
"@cindy/device-link": "workspace:*",
+ "@cindy/device-link-relay": "workspace:*",
"@cindy/embedding-client": "workspace:*",
"@cindy/file-browser-core": "workspace:*",
"@cindy/github-client": "workspace:*",
diff --git a/apps/desktop/scripts/build-remote-bundles.mjs b/apps/desktop/scripts/build-remote-bundles.mjs
index b674f25e05..d75b447412 100644
--- a/apps/desktop/scripts/build-remote-bundles.mjs
+++ b/apps/desktop/scripts/build-remote-bundles.mjs
@@ -49,6 +49,18 @@ const TARGETS = [
destDir: resolve(DESKTOP_ROOT, 'resources', 'remote-file-service'),
destFile: 'file-service.mjs',
},
+ {
+ // 自建中转:部署到用户服务器的同一个中转内核(docs/self-hosted-relay-plan.md)。
+ pkgName: '@cindy/device-link-relay',
+ dependencyDirs: [
+ resolve(MONOREPO_ROOT, 'packages', 'device-link'),
+ resolve(MONOREPO_ROOT, 'packages', 'device-link-protocol'),
+ ],
+ pkgDir: resolve(MONOREPO_ROOT, 'packages', 'device-link-relay'),
+ bundleFile: 'dist/relay.mjs',
+ destDir: resolve(DESKTOP_ROOT, 'resources', 'device-link-relay'),
+ destFile: 'relay.mjs',
+ },
{
pkgName: '@cindy/maker-pi-manager',
pkgDir: resolve(MONOREPO_ROOT, 'packages', 'maker-pi-manager'),
diff --git a/apps/desktop/src/main/bootstrap-electron.ts b/apps/desktop/src/main/bootstrap-electron.ts
index 3fdca3cd43..a317fbbaa1 100644
--- a/apps/desktop/src/main/bootstrap-electron.ts
+++ b/apps/desktop/src/main/bootstrap-electron.ts
@@ -622,6 +622,7 @@ import { closeSharedTasksBeforeLogout } from './device-link/sharedTaskRuntime.js
import { closeSharedTasksBeforeAccountHandover } from './device-link/sharedTaskAccountBoundary.js';
import { registerSharedTaskIpc } from './device-link/sharedTaskIpc.js';
import { registerProviderShareIpc } from './device-link/providerShareRuntime.js';
+import { registerSelfHostedRelayIpc } from './device-link/selfHostedRelayRuntime.js';
import { registerProviderGroupIpc } from './provider-group/ipc.js';
import { registerProviderGroupRemoteHandler } from './provider-group/remoteRegistration.js';
import { providerGroupReshare, registerProviderGroupReshare } from './provider-group/reshareRuntime.js';
@@ -9921,6 +9922,8 @@ app.on('ready', async () => {
);
registerSharedTaskIpc(isSharedTaskAvailable, () => getDeviceLinkStatus() === 'online');
registerProviderShareIpc();
+ // 自建中转服务(docs/self-hosted-relay-plan.md):本机中转与加入别的中转。
+ registerSelfHostedRelayIpc();
registerProviderGroupIpc({ reshare: providerGroupReshare });
registerProviderGroupRemoteHandler({ onGroupChanged: () => providerGroupReshare.kick('group') });
registerProviderGroupReshare();
diff --git a/apps/desktop/src/main/device-link/__tests__/deviceLinkApi.test.ts b/apps/desktop/src/main/device-link/__tests__/deviceLinkApi.test.ts
new file mode 100644
index 0000000000..071175e8b4
--- /dev/null
+++ b/apps/desktop/src/main/device-link/__tests__/deviceLinkApi.test.ts
@@ -0,0 +1,87 @@
+/**
+ * 测试价值
+ * - 生产入口与可观察结果:`deviceLinkApiFetch`(设备列表、媒体预签名、远程桌面 ICE 共用)经真实的
+ * `serverApiFetch` 发出的请求 —— 断言发到哪个地址、带什么 Authorization,以及 401 后是否触发账号刷新/登出。
+ * - Bug/规则依据:docs/self-hosted-relay-plan.md §5.2/§8「Cindy 账号 token 不发往自建中转」「自建中转的 401
+ * 不能让 Cindy 账号登出」;serverApiFetch 对 UNAUTHORIZED 类 401 会 refresh 并 invalidateSession。
+ * - 现有覆盖缺口:serverApiClient.test.ts 只测官方 Bearer 路径;路由逻辑在 deviceLinkApi.ts,需要额外 mock
+ * 中转配置,放进 serverApiClient.test.ts 会让那份文件的所有用例都背上无关 mock,故单独成文件。
+ * - 最小失败输入:自建中转生效时任意 REST 请求;中转回 401 UNAUTHORIZED。
+ * - tier:unit(electron net 与 authManager 为进程内 fake)。
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+ netFetch: vi.fn(),
+ getAccessToken: vi.fn(() => 'account-access-token'),
+ refresh: vi.fn(async () => true),
+ invalidateSession: vi.fn(),
+ relay: null as null | import('../selfHostedRelayRouting').ActiveSelfHostedRelay,
+}));
+
+vi.mock('electron', () => ({ net: { fetch: mocks.netFetch } }));
+vi.mock('../../authManager', () => ({
+ getAccessToken: mocks.getAccessToken,
+ refresh: mocks.refresh,
+ invalidateSession: mocks.invalidateSession,
+}));
+vi.mock('../../i18n.js', () => ({ getResolvedMainLocale: () => 'zh-CN' }));
+vi.mock('../../logger', () => ({ createLogger: () => ({ error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() }) }));
+vi.mock('../../clientEndpointsService.js', () => ({
+ getClientEndpoint: () => 'https://device-link.official.invalid',
+}));
+
+import { deviceLinkApiFetch } from '../deviceLinkApi';
+import { setSelfHostedRelaySource } from '../selfHostedRelayRouting';
+
+setSelfHostedRelaySource(() => mocks.relay);
+
+function lastRequest(): { url: string; authorization: string | undefined } {
+ const [url, init] = mocks.netFetch.mock.calls.at(-1)!;
+ return { url, authorization: (init as { headers: Record<string, string> }).headers.Authorization };
+}
+
+describe('deviceLinkApiFetch', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.relay = null;
+ });
+
+ it('sends the relay credential, never the account token, and keeps the Cindy session on a relay 401', async () => {
+ mocks.relay = {
+ baseUrl: 'http://192.168.1.20:47820',
+ credential: 'relay-credential',
+ role: 'member',
+ relayId: 'r',
+ name: 'Home',
+ deviceId: 'pc',
+ signingSeed: 'A'.repeat(43),
+ ownerPublicKey: 'A'.repeat(43),
+ };
+ mocks.netFetch.mockResolvedValue(
+ new Response(JSON.stringify({ error: { code: 'UNAUTHORIZED', message: 'nope' } }), { status: 401 }),
+ );
+
+ await expect(deviceLinkApiFetch('/api/device-link/devices')).rejects.toMatchObject({ statusCode: 401 });
+
+ expect(mocks.netFetch).toHaveBeenCalledTimes(1);
+ expect(lastRequest()).toEqual({
+ url: 'http://192.168.1.20:47820/api/device-link/devices',
+ authorization: 'CindyRelay relay-credential',
+ });
+ expect(JSON.stringify(mocks.netFetch.mock.calls)).not.toContain('account-access-token');
+ expect(mocks.refresh).not.toHaveBeenCalled();
+ expect(mocks.invalidateSession).not.toHaveBeenCalled();
+ });
+
+ it('keeps the official relay on the account token', async () => {
+ mocks.netFetch.mockResolvedValue(new Response(JSON.stringify({ devices: [] }), { status: 200 }));
+
+ await expect(deviceLinkApiFetch('/api/device-link/devices')).resolves.toEqual({ devices: [] });
+
+ expect(lastRequest()).toEqual({
+ url: 'https://device-link.official.invalid/api/device-link/devices',
+ authorization: 'Bearer account-access-token',
+ });
+ });
+});
diff --git a/apps/desktop/src/main/device-link/__tests__/mediaTransfer.test.ts b/apps/desktop/src/main/device-link/__tests__/mediaTransfer.test.ts
index b1eecb26f1..2a6d4e4963 100644
--- a/apps/desktop/src/main/device-link/__tests__/mediaTransfer.test.ts
+++ b/apps/desktop/src/main/device-link/__tests__/mediaTransfer.test.ts
@@ -33,8 +33,9 @@ vi.mock('../../appCapabilities.js', () => ({
requireAppCapability: vi.fn(),
}));
-vi.mock('../index.js', () => ({
- deviceLinkApiBase: () => 'http://relay.test:3335',
+// presign 经 deviceLinkApi 发往当前中转;未启用自建中转时即官方清单里的 device-link 地址。
+vi.mock('../../clientEndpointsService.js', () => ({
+ getClientEndpoint: () => 'http://relay.test:3335',
}));
vi.mock('../../logger.js', () => ({
diff --git a/apps/desktop/src/main/device-link/__tests__/selfHostedRelayDeploy.test.ts b/apps/desktop/src/main/device-link/__tests__/selfHostedRelayDeploy.test.ts
new file mode 100644
index 0000000000..0fc910f062
--- /dev/null
+++ b/apps/desktop/src/main/device-link/__tests__/selfHostedRelayDeploy.test.ts
@@ -0,0 +1,163 @@
+/**
+ * 测试价值
+ * - 生产入口与可观察结果:`deployRelayToServer` —— 「部署到我的服务器」按服务器上的实际情况决定继续还是停下,
+ * 以及停下时给用户的错误码与原因(界面据此告诉用户去开安全组、换服务器还是清掉旧中转)。
+ * - Bug/规则依据:docs/self-hosted-relay-plan.md §15.3:没有 root / 免密 sudo 时停下而不索要密码;
+ * 80/443 被占时不覆盖别人的服务;服务器上已有别人的中转时不覆盖;证书失败时把 CA 给的原因带回来;
+ * 非 root 时所有改动经 `sudo -n`。
+ * - 现有覆盖缺口:部署脚本本身已在 systemd 容器 + Pebble 里实测(见方案),但「服务器输出 → 错误码」的判断只在这里。
+ * - 最小失败输入:每条用例一种服务器状态(ROOT none / BUSY 80 / 别的主人的 STATE / 证书 failed)与一条成功路径。
+ * - tier:unit。SSH 主机、HTTPS 检查为进程内 fake;轮询等待用 fake timers,不做真实等待。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cindy-relay-deploy-test-'));
+const appPath = path.join(appRoot, 'apps', 'desktop');
+const bundleDir = path.join(appRoot, 'packages', 'device-link-relay', 'dist');
+fs.mkdirSync(appPath, { recursive: true });
+fs.mkdirSync(bundleDir, { recursive: true });
+fs.writeFileSync(path.join(bundleDir, 'relay.mjs'), 'export {};\n');
+
+type Exec = { stdout: string; stderr: string; exitCode: number | null };
+const mocks = vi.hoisted(() => ({
+ responses: {} as Record<string, (command: string) => Exec>,
+ commands: [] as Array<{ label: string; command: string }>,
+ ensureReady: vi.fn(async () => undefined),
+}));
+
+vi.mock('electron', () => ({ app: { getAppPath: () => appPath } }));
+vi.mock('../../logger.js', () => ({ createLogger: () => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }) }));
+vi.mock('../../remote-ssh/index.js', () => ({
+ ensureRemoteHostReady: mocks.ensureReady,
+ getRemoteSshPool: () => ({
+ get: () => ({
+ exec: vi.fn(async (command: string, options: { label: string; input?: Buffer }) => {
+ mocks.commands.push({ label: options.label, command });
+ if (options.label === 'relay-deploy-upload') {
+ const { createHash } = await import('node:crypto');
+ return { stdout: `SHA ${createHash('sha256').update(options.input!).digest('hex')}\n`, stderr: '', exitCode: 0 };
+ }
+ const respond = mocks.responses[options.label];
+ return respond ? respond(command) : { stdout: '', stderr: '', exitCode: 0 };
+ }),
+ }),
+ }),
+}));
+
+import { deployRelayToServer, RelayDeployError } from '../selfHostedRelayDeploy';
+
+const ok = (stdout: string): Exec => ({ stdout, stderr: '', exitCode: 0 });
+const PROBE_SUDO = 'OS Linux\nARCH x86_64\nROOT sudo\nSYSTEMD yes\nIPV6 no\nFETCH yes\n';
+const init = {
+ name: 'My relay',
+ relayId: '0b7a4a52-8f6a-4d55-9a53-3f1f6f2c9e10',
+ ownerUserId: 'u1',
+ ownerDeviceId: 'pc-1',
+ ownerDeviceName: 'PC',
+ ownerCredentialHash: 'a'.repeat(64),
+ ownerPublicKey: 'Q'.repeat(43),
+ ownerCert: { v: 1 },
+};
+
+async function run(overrides: Partial<Parameters<typeof deployRelayToServer>[0]> = {}) {
+ const steps: string[] = [];
+ const promise = deployRelayToServer({
+ sshHostId: 'my-vps',
+ address: '203.0.113.10',
+ baseUrl: 'https://203.0.113.10',
+ replaceExisting: false,
+ init,
+ preferMirror: false,
+ onStep: (step) => steps.push(step),
+ ...overrides,
+ });
+ const settled = promise.then(
+ (value) => ({ value, error: null }),
+ (error: unknown) => ({ value: null, error }),
+ );
+ await vi.runAllTimersAsync();
+ return { ...(await settled), steps };
+}
+
+describe('deployRelayToServer', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['setTimeout'] });
+ mocks.commands = [];
+ mocks.ensureReady.mockReset().mockResolvedValue(undefined);
+ mocks.responses = {
+ 'relay-deploy-probe': () => ok(PROBE_SUDO),
+ 'relay-deploy-runtime': () => ok('NODE_READY v24.22.1\n'),
+ 'relay-deploy-configure': () => ok('INITIALIZED\nCONFIGURED\n'),
+ 'relay-deploy-status': () =>
+ ok(`ACTIVE active\nSTATUS {"certificate":{"state":"ready","identifier":"203.0.113.10"}}\n`),
+ };
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => new Response(JSON.stringify({ relayId: init.relayId }), { status: 200 })),
+ );
+ });
+
+ afterAll(() => {
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+ fs.rmSync(appRoot, { recursive: true, force: true });
+ });
+
+ it('runs every step through sudo -n and checks the relay over https', async () => {
+ const result = await run();
+ expect(result.error).toBeNull();
+ expect(result.steps).toEqual(['connect', 'check', 'runtime', 'upload', 'configure', 'certificate', 'verify']);
+ const privileged = mocks.commands.filter((c) => c.label !== 'relay-deploy-probe');
+ expect(privileged.length).toBeGreaterThan(0);
+ expect(privileged.every((c) => c.command.startsWith('sudo -n bash -c '))).toBe(true);
+ expect(fetch).toHaveBeenCalledWith('https://203.0.113.10/api/device-link/relay/info', expect.anything());
+ });
+
+ it.each([
+ ['no root or passwordless sudo', { 'relay-deploy-probe': () => ok(PROBE_SUDO.replace('ROOT sudo', 'ROOT none')) }, 'NEEDS_ROOT', undefined],
+ ['port 80 used by another program', { 'relay-deploy-inspect': () => ok('BUSY 80 nginx\n') }, 'PORT_BUSY', '80 nginx'],
+ [
+ 'a relay owned by someone else',
+ { 'relay-deploy-inspect': () => ok(`STATE 2 ${init.relayId} ${'R'.repeat(43)}\n`) },
+ 'RELAY_MISMATCH',
+ undefined,
+ ],
+ [
+ 'the CA rejecting validation',
+ {
+ 'relay-deploy-status': () =>
+ ok('ACTIVE active\nSTATUS {"certificate":{"state":"failed","error":"validation failed: connection refused"}}\n'),
+ },
+ 'CERTIFICATE_FAILED',
+ 'validation failed: connection refused',
+ ],
+ ])('stops on %s', async (_label, responses, code, detail) => {
+ Object.assign(mocks.responses, responses);
+ const { error } = await run();
+ expect(error).toBeInstanceOf(RelayDeployError);
+ expect(error).toMatchObject({ code, detail });
+ // 停下时不会走到写配置、重启服务那一步(证书失败除外:那时服务已经配置好)。
+ const configured = mocks.commands.some((c) => c.label === 'relay-deploy-configure');
+ expect(configured).toBe(code === 'CERTIFICATE_FAILED');
+ });
+
+ it('replaces a foreign relay only when asked to', async () => {
+ mocks.responses['relay-deploy-inspect'] = () => ok(`STATE 2 other-relay ${'R'.repeat(43)}\n`);
+ const { error } = await run({ replaceExisting: true });
+ expect(error).toBeNull();
+ const configure = mocks.commands.find((c) => c.label === 'relay-deploy-configure')!;
+ // 第 4 个位置参数是 REPLACE。
+ expect(configure.command).toContain(`'203.0.113.10' '0.0.0.0' 'https://203.0.113.10' '1'`);
+ });
+
+ it('does not access another account’s SSH connection after the owner changes while connecting', async () => {
+ let current = true;
+ mocks.ensureReady.mockImplementationOnce(async () => { current = false; });
+ const { error } = await run({ assertCurrent: () => { if (!current) throw new Error('owner changed'); } });
+ expect(error).toMatchObject({ message: 'owner changed' });
+ expect(mocks.commands).toEqual([]);
+ });
+});
diff --git a/apps/desktop/src/main/device-link/__tests__/selfHostedRelayRuntime.test.ts b/apps/desktop/src/main/device-link/__tests__/selfHostedRelayRuntime.test.ts
new file mode 100644
index 0000000000..9650220182
--- /dev/null
+++ b/apps/desktop/src/main/device-link/__tests__/selfHostedRelayRuntime.test.ts
@@ -0,0 +1,206 @@
+/**
+ * 测试价值
+ * - 生产入口与可观察结果:注册后的 self-hosted-relay:command IPC;部署完成会保存并切换中转,
+ * 账号切换后的迟到部署/退出响应不能改写新账号配置或覆盖新部署进度。
+ * - Bug/规则依据:appSessionState.activeOwnerScopeKey 的异步账号边界;原部署回调跨 await 读取当前账号,
+ * 会将旧账号的部署记录写入新账号,切换中转在等待退出旧中转时也有同样问题。
+ * - 现有覆盖缺口:部署器测试只验证 SSH 步骤,没有经过运行时 IPC 与账号切换,故单独覆盖该模块。
+ * - 最小失败输入:挂起一次部署或退出请求,换账号,再让原请求完成。
+ * - tier:unit;SSH、存储和 Electron 为进程内 fake,无网络、磁盘或真实等待。
+ * - 单文件实测:1.39 秒(6 例,测试体 22ms,Windows)。
+ */
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import type { RelayConfig } from '../selfHostedRelayConfig';
+import type { SelfHostedRelayCommand, SelfHostedRelayCommandResult } from '../../../shared/selfHostedRelay';
+
+const h = vi.hoisted(() => ({
+ owner: 'account-a',
+ generation: 0,
+ config: new Map<string, RelayConfig>(),
+ handlers: new Map<string, (event: unknown, raw: unknown) => Promise<SelfHostedRelayCommandResult>>(),
+ invalidated: () => {},
+ authChanged: () => {},
+ write: vi.fn(),
+ deleteSecrets: vi.fn(),
+ restart: vi.fn(),
+ deploy: vi.fn(),
+ uninstall: vi.fn(),
+ startServer: vi.fn(),
+}));
+
+vi.mock('electron', () => ({
+ app: { on: vi.fn(), getVersion: () => 'test' },
+ ipcMain: { handle: (key: string, fn: never) => h.handlers.set(key, fn) },
+}));
+vi.mock('node:fs', () => ({ default: { existsSync: () => true, rmSync: vi.fn() } }));
+vi.mock('../../appSessionState.js', () => ({
+ activeOwnerScopeKey: () => `${h.owner}:${h.generation}`,
+ getActiveAppSession: () => ({ mode: 'cloud', dataOwnerId: h.owner, generation: h.generation }),
+ isAppSessionBoundaryPending: () => false,
+ onAppSessionInvalidated: (cb: () => void) => { h.invalidated = cb; },
+}));
+vi.mock('../../authManager.js', () => ({
+ getAuthState: () => ({ isAuthenticated: true }),
+ getCurrentUserId: () => h.owner,
+ getDeviceId: () => 'test-device',
+ onAuthStateChange: (cb: () => void) => { h.authChanged = cb; },
+}));
+vi.mock('../../logger.js', () => ({ createLogger: () => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn() }) }));
+vi.mock('../../security/trustedAppRenderer.js', () => ({ assertTrustedAppRendererEvent: vi.fn() }));
+vi.mock('../../utils/ipcValidate.js', () => ({ throwIpcError: (code: string) => { throw new Error(code); } }));
+vi.mock('../invoke-context.js', () => ({ getDeviceLinkInvokeContext: () => null }));
+vi.mock('../deviceName.js', () => ({ deviceName: () => 'Test computer' }));
+vi.mock('../providerShareApi.js', () => ({ providerShareLinkApp: () => 'cindy' }));
+vi.mock('../settings-store.js', () => ({ readDeviceLinkSettings: () => ({ keepAwake: true }) }));
+vi.mock('../selfHostedRelayFrameAuth.js', () => ({ refreshRelayCertificatesSoon: vi.fn() }));
+vi.mock('../index.js', () => ({
+ broadcast: vi.fn(), getDeviceLinkConnectionIssue: () => null,
+ restartDeviceLinkForRelayChange: h.restart, setKeepAwakeEnabled: vi.fn(),
+}));
+vi.mock('@cindy/device-link-relay', () => ({
+ createDeviceCredential: () => ({ credential: 'fake-credential' }),
+ hashSecret: () => 'fake-hash', initializeRelay: vi.fn(), startRelayServer: h.startServer,
+}));
+vi.mock('../selfHostedRelayDeploy.js', () => ({
+ bundledRelayVersion: () => '0.2.0', deployRelayToServer: h.deploy, uninstallRelayFromServer: h.uninstall,
+ RelayDeployError: class extends Error {},
+}));
+vi.mock('../selfHostedRelayConfig.js', () => ({
+ readRelayConfig: () => structuredClone(h.config.get(h.owner)),
+ writeRelayConfig: (value: RelayConfig) => {
+ h.write(h.owner, structuredClone(value));
+ h.config.set(h.owner, structuredClone(value));
+ },
+ readRelaySecrets: () => ({ credential: 'fake-credential', seed: 'A'.repeat(43) }),
+ writeRelaySecrets: vi.fn(), deleteRelaySecrets: h.deleteSecrets,
+ activeSelfHostedRelay: () => {
+ const active = h.config.get(h.owner)?.active;
+ return active ? { ...active, credential: 'fake-credential', signingSeed: 'A'.repeat(43) } : null;
+ },
+ activeRelayOrigin: () => h.config.get(h.owner)?.active?.origin ?? null,
+ secureStorageAvailable: () => true, installSelfHostedRelayRouting: vi.fn(),
+ relayDataPath: () => 'in-memory-relay-data',
+}));
+
+import { getState, registerSelfHostedRelayIpc } from '../selfHostedRelayRuntime';
+
+function emptyConfig(): RelayConfig {
+ return { version: 2, active: null, host: { enabled: false, port: 47820, listenAll: false, externalUrl: null, relayId: null }, deployment: null };
+}
+
+function deferred<T>() {
+ let resolve!: (value: T) => void;
+ let reject!: (error: Error) => void;
+ const promise = new Promise<T>((yes, no) => { resolve = yes; reject = no; });
+ return { promise, resolve, reject };
+}
+
+const command = (value: SelfHostedRelayCommand) => h.handlers.get('self-hosted-relay:command')!({}, value);
+const deployCommand: SelfHostedRelayCommand = {
+ type: 'deploy', sshHostId: 'test-server', address: '203.0.113.10', name: 'Test relay', replaceExisting: false,
+};
+
+async function switchOwner(owner: string) {
+ h.invalidated();
+ h.owner = owner;
+ h.generation += 1;
+ h.authChanged();
+ await vi.runAllTimersAsync();
+}
+
+beforeEach(async () => {
+ vi.useFakeTimers();
+ vi.clearAllMocks();
+ h.owner = 'account-a';
+ h.generation += 1;
+ h.config = new Map([['account-a', emptyConfig()], ['account-b', emptyConfig()]]);
+ registerSelfHostedRelayIpc();
+ await vi.runAllTimersAsync();
+});
+
+afterEach(() => { vi.useRealTimers(); vi.unstubAllGlobals(); });
+
+it('records a completed deployment and activates it for the account that started it', async () => {
+ h.deploy.mockResolvedValue({ relayVersion: '0.2.0' });
+ await command(deployCommand);
+ await vi.runAllTimersAsync();
+ expect(h.config.get('account-a')?.deployment?.complete).toBe(true);
+ expect(h.config.get('account-a')?.active?.origin).toBe('server');
+ expect(getState().deployJob?.status).toBe('done');
+ expect(h.restart).toHaveBeenCalledOnce();
+});
+
+it.each(['resolve', 'reject'] as const)('ignores an old deployment that later %s after a new account starts its own', async (outcome) => {
+ const old = deferred<{ relayVersion: string }>();
+ const next = deferred<{ relayVersion: string }>();
+ h.deploy.mockReturnValueOnce(old.promise).mockReturnValueOnce(next.promise);
+ await command(deployCommand);
+ const oldStep = h.deploy.mock.calls[0][0].onStep;
+ await switchOwner('account-b');
+ expect(getState().deployJob).toBeNull();
+ await command(deployCommand);
+ const before = structuredClone(h.config.get('account-b'));
+ h.write.mockClear();
+ if (outcome === 'resolve') old.resolve({ relayVersion: '0.2.0' });
+ else old.reject(new Error('old server failed'));
+ await vi.runAllTimersAsync();
+ expect(h.write).not.toHaveBeenCalled();
+ expect(h.config.get('account-b')).toEqual(before);
+ expect(getState().deployJob?.status).toBe('running');
+ expect(() => oldStep('upload')).toThrow();
+ next.resolve({ relayVersion: '0.2.0' });
+ await vi.runAllTimersAsync();
+ expect(getState().deployJob?.status).toBe('done');
+});
+
+it('does not clear a new account’s settings when an old member leave finishes', async () => {
+ const leaving = deferred<Response>();
+ vi.stubGlobal('fetch', vi.fn(() => leaving.promise));
+ h.config.get('account-a')!.active = {
+ relayId: 'old-relay', name: 'Old relay', baseUrl: 'https://relay.invalid', origin: 'join', role: 'member',
+ deviceId: 'test-device', ownerPublicKey: 'A'.repeat(43),
+ };
+ const pending = command({ type: 'use-official' });
+ await switchOwner('account-b');
+ h.write.mockClear();
+ leaving.resolve(new Response(null, { status: 204 }));
+ const result = await pending;
+ expect(result.error).toBe('NOT_SIGNED_IN');
+ expect(h.write).not.toHaveBeenCalled();
+ expect(h.deleteSecrets).not.toHaveBeenCalled();
+ expect(h.restart).not.toHaveBeenCalled();
+});
+
+it('closes a local relay that finishes starting after its owner leaves', async () => {
+ const starting = deferred<{ port: number; close: ReturnType<typeof vi.fn> }>();
+ const close = vi.fn(async () => {});
+ h.config.get('account-a')!.host.relayId = 'existing-relay';
+ h.startServer.mockReturnValueOnce(starting.promise);
+ const pending = command({ type: 'enable-host', port: 47820, listenAll: false, externalUrl: null });
+ await vi.runAllTimersAsync();
+ expect(h.startServer).toHaveBeenCalledOnce();
+ await switchOwner('account-b');
+ h.write.mockClear();
+ starting.resolve({ port: 47820, close });
+ expect((await pending).error).toBe('NOT_SIGNED_IN');
+ expect(close).toHaveBeenCalledWith({ retire: false });
+ expect(getState().host.running).toBe(false);
+ expect(h.write).not.toHaveBeenCalled();
+});
+
+it('does not remove another account’s deployment after a delayed uninstall', async () => {
+ h.deploy.mockResolvedValueOnce({ relayVersion: '0.2.0' });
+ await command(deployCommand);
+ await vi.runAllTimersAsync();
+ const uninstall = deferred<void>();
+ h.uninstall.mockReturnValueOnce(uninstall.promise);
+ await command({ type: 'uninstall-deployment', removeData: true });
+ await switchOwner('account-b');
+ h.write.mockClear();
+ h.deleteSecrets.mockClear();
+ uninstall.resolve();
+ await vi.runAllTimersAsync();
+ expect(h.write).not.toHaveBeenCalled();
+ expect(h.deleteSecrets).not.toHaveBeenCalled();
+ expect(getState().deployJob).toBeNull();
+});
diff --git a/apps/desktop/src/main/device-link/deviceLinkApi.ts b/apps/desktop/src/main/device-link/deviceLinkApi.ts
new file mode 100644
index 0000000000..45e767031c
--- /dev/null
+++ b/apps/desktop/src/main/device-link/deviceLinkApi.ts
@@ -0,0 +1,30 @@
+/**
+ * device-link 中转的 REST 入口:按当前选择发往 Cindy 官方中转或自建中转。
+ *
+ * - 官方中转:原样走 serverApiFetch(Bearer 账号 token、401 刷新)。
+ * - 自建中转:`Authorization: CindyRelay <设备凭证>`,绝不携带账号 token;跳过刷新与会话失效,
+ * 自建中转的 401 只表示中转凭证失效,不能把 Cindy 账号登出。
+ */
+import { getClientEndpoint } from '../clientEndpointsService.js';
+import { serverApiFetch, type ApiFetchOptions } from '../serverApiClient.js';
+import { activeSelfHostedRelay } from './selfHostedRelayRouting.js';
+
+/** 当前中转的 REST 基础地址(WebSocket 地址由它推出)。 */
+export function resolveDeviceLinkApiBase(): string {
+ return activeSelfHostedRelay()?.baseUrl ?? getClientEndpoint('deviceLinkApiBaseUrl');
+}
+
+export function deviceLinkApiFetch<T>(
+ apiPath: string,
+ opts: Omit<ApiFetchOptions, 'baseUrl' | 'token' | 'authorization'> = {},
+): Promise<T> {
+ const relay = activeSelfHostedRelay();
+ if (!relay) return serverApiFetch<T>(apiPath, { ...opts, baseUrl: resolveDeviceLinkApiBase });
+ return serverApiFetch<T>(apiPath, {
+ ...opts,
+ baseUrl: relay.baseUrl,
+ authorization: `CindyRelay ${relay.credential}`,
+ skipAutoRefresh: true,
+ skipSessionInvalidation: true,
+ });
+}
diff --git a/apps/desktop/src/main/device-link/index.ts b/apps/desktop/src/main/device-link/index.ts
index d5cfa1bae0..720aa5b190 100644
--- a/apps/desktop/src/main/device-link/index.ts
+++ b/apps/desktop/src/main/device-link/index.ts
@@ -69,7 +69,6 @@ import { onQuit } from '../lifecycle';
import { getCurrentDbClientUserId } from '../localDb/client/current';
import { isSessionNotificationsMutedSync } from '../localDb/sessionFlagRegistry';
import { createOutboundHttpAgent } from '../maker-host/outbound-fetch';
-import { serverApiFetch } from '../serverApiClient';
import {
DeviceLinkOwnershipArbiter,
createSqliteExclusiveFileLock,
@@ -169,7 +168,9 @@ import {
} from './mobileNotify';
import { createSubscriptionReplayScheduler, isPermanentSubscriptionReplayError } from './subscriptionReplayScheduler';
import { getNotificationImageLabel, getSessionNotificationBody } from '../sessionNotificationCopy';
-import { getClientEndpoint } from '../clientEndpointsService';
+import { deviceLinkApiFetch, resolveDeviceLinkApiBase } from './deviceLinkApi.js';
+import { activeSelfHostedRelay } from './selfHostedRelayRouting.js';
+import { currentRelayFrameAuth } from './selfHostedRelayFrameAuth.js';
import {
handleContactsDeviceLinkStatusChanged,
handleContactsPeerPresenceChanged,
@@ -203,7 +204,8 @@ const WS_PATH = '/api/device-link/ws';
/** relay REST base(media presign / devices 等);供 mediaTransfer / ipc 复用。 */
export function deviceLinkApiBase(): string {
- return getClientEndpoint('deviceLinkApiBaseUrl');
+ // 自建中转(docs/self-hosted-relay-plan.md)时指向用户自己的中转,否则走官方清单。
+ return resolveDeviceLinkApiBase();
}
type DeviceDirectoryResponse = {
@@ -333,8 +335,7 @@ async function runControllerDisplayNamesFromDirectory(
presenceRequestEpoch: number,
): Promise<void> {
try {
- const result = await serverApiFetch<DeviceDirectoryResponse>('/api/device-link/devices', {
- baseUrl: deviceLinkApiBase,
+ const result = await deviceLinkApiFetch<DeviceDirectoryResponse>('/api/device-link/devices', {
timeoutMs: 10_000,
});
if (
@@ -617,6 +618,9 @@ let relayAuthRecoveryRetryTimer: ReturnType<typeof setTimeout> | null = null;
* refresh 路径自己走会话过期出口(清会话 + 弹重登),auth 监听随后会停掉本服务。
*/
function recoverFromRelayAuthFailure(): void {
+ // 自建中转拒绝的是中转凭证,与 Cindy 账号无关:不刷新、不轮换账号 token。
+ // 界面经 connection issue 提示「已被移出中转」,由用户重新加入或切回官方。
+ if (activeSelfHostedRelay()) return;
const now = Date.now();
const elapsed = now - lastRelayAuthRecoveryAt;
if (elapsed < RELAY_AUTH_RECOVERY_MIN_INTERVAL_MS) {
@@ -713,9 +717,15 @@ export function initDeviceLinkService(options: DeviceLinkServiceOptions = {}): v
directRuntime: desktopDirectRuntime,
getWsUrl: wsUrl,
transferCodec: desktopTransferCodec,
+ // 自建中转用中转凭证(CindyRelay),官方中转用账号 token(Bearer);两者每次建连前同一轮取值。
+ authorizationScheme: () => (activeSelfHostedRelay() ? 'CindyRelay' : 'Bearer'),
+ // 自建中转:每条对端消息签名,收到的对端消息核对签名(中转无法冒充设备);官方中转返回 null,行为不变。
+ frameAuth: currentRelayFrameAuth,
getToken: async () => {
// Prepare the name before the first hello without blocking Electron's main thread.
await deviceNameReady;
+ const relay = activeSelfHostedRelay();
+ if (relay) return authManager.getAuthState().isAuthenticated ? relay.credential : null;
const token = authManager.getAccessToken();
if (token) return token;
// 无现值(冷启动竞态/过期被清):尝试 refresh 一次,失败则跳过本轮重连
@@ -1354,6 +1364,24 @@ function restartDeviceLinkForAuthRealmChange(): void {
});
}
+/**
+ * 切换中转(官方 ↔ 自建,或换一个自建中转)后重连:与换区相同,先完整释放持有权并拆掉旧链路,
+ * 再按最新地址 / 凭证重新参与仲裁。不重连就会一直连着旧中转。
+ */
+export function restartDeviceLinkForRelayChange(): void {
+ if (!client || !arbiter) return;
+ if (!authManager.getAuthState().isAuthenticated) return;
+ const generation = ++authRealmReconnectGeneration;
+ void stopArbitrationAndTeardown()
+ .catch((error) => {
+ log.warn('device-link ownership release during relay switch failed', error);
+ })
+ .then(() => {
+ if (generation !== authRealmReconnectGeneration || !authManager.getAuthState().isAuthenticated) return;
+ arbiter?.start();
+ });
+}
+
/**
* 登出 / 掉登录态的统一收口:先停仲裁(若持有 → 释放行 + onDemote → teardown),
* 非持有者再补一次 teardown 保证被控状态彻底清空。可能被连续触发(显式登出释放
diff --git a/apps/desktop/src/main/device-link/ipc.ts b/apps/desktop/src/main/device-link/ipc.ts
index 74f50eca27..c6236e0e71 100644
--- a/apps/desktop/src/main/device-link/ipc.ts
+++ b/apps/desktop/src/main/device-link/ipc.ts
@@ -37,7 +37,8 @@ import {
type InvokeResultPayload,
type LinkAcceptPayload,
} from '@cindy/device-link';
-import { serverApiFetch, ServerApiError } from '../serverApiClient';
+import { ServerApiError } from '../serverApiClient';
+import { deviceLinkApiFetch } from './deviceLinkApi.js';
import { requireString, throwIpcError } from '../utils/ipcValidate';
import { assertTrustedAppRendererEvent } from '../security/trustedAppRenderer';
import { isIpcError, type IpcErrorCode } from '../../shared/ipc-errors';
@@ -67,7 +68,6 @@ import {
revokeController,
restoreController,
broadcast,
- deviceLinkApiBase,
applyControllerDisplayNameListSnapshot,
applyControllerPresenceListSnapshot,
beginControllerDisplayNameDirectoryRefresh,
@@ -208,7 +208,8 @@ export function defaultDeps(): DeviceLinkIpcDeps {
},
setEnabled: setRemoteControlEnabled,
setKeepAwake: setKeepAwakeEnabled,
- apiFetch: (path, opts) => serverApiFetch(path, { ...opts, baseUrl: deviceLinkApiBase }),
+ // 官方中转或自建中转(凭证与 401 语义不同,见 deviceLinkApi.ts)。
+ apiFetch: (path, opts) => deviceLinkApiFetch(path, opts),
openLink: (deviceId: string) => openRemoteLink(deviceId),
closeLink: closeRemoteLink,
invoke: (...args) => {
diff --git a/apps/desktop/src/main/device-link/mediaTransfer.ts b/apps/desktop/src/main/device-link/mediaTransfer.ts
index 4e95f330f8..8d21541e16 100644
--- a/apps/desktop/src/main/device-link/mediaTransfer.ts
+++ b/apps/desktop/src/main/device-link/mediaTransfer.ts
@@ -32,9 +32,8 @@ import path from 'node:path';
import { net } from 'electron';
import type { AttachmentIntegrity } from '@cindy/device-link';
-import { serverApiFetch } from '../serverApiClient.js';
import { requireAppCapability } from '../appCapabilities.js';
-import { deviceLinkApiBase } from './index.js';
+import { deviceLinkApiFetch } from './deviceLinkApi.js';
import { sharedTaskMediaId } from './sharedTaskMediaContext.js';
import { describeErrorChain } from '../utils/errorChain.js';
import { createLogger } from '../logger.js';
@@ -89,10 +88,9 @@ async function presignPut(
contentType: string,
): Promise<PresignPutResponse> {
requireAppCapability('canUseDeviceLink', 'Device Link requires a Cindy account.');
- return serverApiFetch<PresignPutResponse>(PRESIGN_PUT_PATH, {
+ return deviceLinkApiFetch<PresignPutResponse>(PRESIGN_PUT_PATH, {
method: 'POST',
body: { size, ext, contentType, ...(sharedTaskMediaId() ? { sharedTaskId: sharedTaskMediaId() } : {}) },
- baseUrl: deviceLinkApiBase,
});
}
@@ -111,10 +109,9 @@ const REMOVE_REMOTE_TIMEOUT_MS = 15_000;
/** 向 relay server 申请下载预签名(server 校验请求方 == key 内嵌 userId)。 */
async function presignGet(key: string): Promise<PresignGetResponse> {
requireAppCapability('canUseDeviceLink', 'Device Link requires a Cindy account.');
- return serverApiFetch<PresignGetResponse>(PRESIGN_GET_PATH, {
+ return deviceLinkApiFetch<PresignGetResponse>(PRESIGN_GET_PATH, {
method: 'POST',
body: { key },
- baseUrl: deviceLinkApiBase,
});
}
@@ -707,10 +704,9 @@ export async function downloadToFile(
export async function removeRemote(key: string): Promise<void> {
try {
requireAppCapability('canUseDeviceLink', 'Device Link requires a Cindy account.');
- await serverApiFetch<{ deleted: boolean }>(DELETE_PATH, {
+ await deviceLinkApiFetch<{ deleted: boolean }>(DELETE_PATH, {
method: 'DELETE',
body: { key },
- baseUrl: deviceLinkApiBase,
// Best-effort (the OSS lifecycle rule is the backstop): never let an unresponsive relay
// hold up the upload failure or copy cancellation waiting on it.
timeoutMs: REMOVE_REMOTE_TIMEOUT_MS,
diff --git a/apps/desktop/src/main/device-link/selfHostedRelayConfig.ts b/apps/desktop/src/main/device-link/selfHostedRelayConfig.ts
new file mode 100644
index 0000000000..fac87d5d09
--- /dev/null
+++ b/apps/desktop/src/main/device-link/selfHostedRelayConfig.ts
@@ -0,0 +1,320 @@
+/**
+ * 自建中转的本机配置与秘密(按当前账号隔离)。
+ *
+ * - `config.json`:当前用哪个中转(官方 / 自建)、本机中转的开启设置、部署到服务器的中转记录。不含秘密。
+ * - `secrets/<中转ID>.enc`:本机在这个中转上的设备凭证与签名私钥,经 Electron safeStorage
+ * (钥匙串 / DPAPI)加密。Linux 只有明文后端(basic_text)时不保存,直接报不可用。
+ * 主人(本机中转 / 部署的服务器中转)与成员(加入的中转)都按中转 ID 各存一份:切走再切回不用重新加入。
+ *
+ * device-link 的地址、认证方案、token、签名与 REST 都从这里同步读取当前选择(内存缓存,按账号作用域
+ * 失效),因此读取不能有异步 IO;写入是原子替换。
+ */
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { safeStorage } from 'electron';
+import { isRelayPublicKey } from '@cindy/device-link';
+import { activeOwnerScopeKey, getActiveAppSession, ownerScopedUserDataPath } from '../appSessionState.js';
+import { createLogger } from '../logger.js';
+import { oauthSecureStorageAvailable } from '../plugin-oauth/identityStore.js';
+import { DEFAULT_RELAY_PORT } from '../../shared/selfHostedRelay.js';
+import { setSelfHostedRelaySource, type ActiveSelfHostedRelay } from './selfHostedRelayRouting.js';
+
+const log = createLogger('self-hosted-relay:config');
+
+const DIR = 'device-link-relay';
+const CONFIG_VERSION = 2;
+const RELAY_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export type RelayRole = 'owner' | 'member';
+/** 当前中转从哪来:本机开启 / 部署到服务器 / 加入别人的。 */
+export type RelayOrigin = 'host' | 'server' | 'join';
+
+export interface ActiveRelay {
+ relayId: string;
+ name: string;
+ baseUrl: string;
+ role: RelayRole;
+ origin: RelayOrigin;
+ /** 本机在这个中转上的设备 ID。 */
+ deviceId: string;
+ ownerPublicKey: string;
+}
+
+export interface RelayHostSettings {
+ enabled: boolean;
+ port: number;
+ listenAll: boolean;
+ externalUrl: string | null;
+ /** 本机中转数据对应的中转 ID;null = 还没初始化过。 */
+ relayId: string | null;
+}
+
+/** 部署到服务器上的中转(本机是它的主人)。 */
+export interface RelayDeployment {
+ sshHostId: string;
+ /** 访问地址:域名或公网 IP(证书签给它)。 */
+ address: string;
+ baseUrl: string;
+ relayId: string;
+ name: string;
+ ownerPublicKey: string;
+ relayVersion: string;
+ deployedAt: string;
+ /** 上次部署 / 升级是否走完;未完成时保留身份,重试不会与服务器上已初始化的数据冲突。 */
+ complete: boolean;
+}
+
+export interface RelayConfig {
+ version: typeof CONFIG_VERSION;
+ /** null = 使用 Cindy 官方中转。 */
+ active: ActiveRelay | null;
+ host: RelayHostSettings;
+ deployment: RelayDeployment | null;
+}
+
+/** 本机在某个中转上的秘密。 */
+export interface RelaySecrets {
+ credential: string;
+ /** Ed25519 私钥种子(base64url)。 */
+ seed: string;
+}
+
+const DEFAULT_CONFIG: RelayConfig = {
+ version: CONFIG_VERSION,
+ active: null,
+ host: { enabled: false, port: DEFAULT_RELAY_PORT, listenAll: false, externalUrl: null, relayId: null },
+ deployment: null,
+};
+
+interface Cache {
+ scope: string;
+ config: RelayConfig;
+ secrets: Map<string, RelaySecrets | null>;
+}
+
+let cache: Cache | null = null;
+
+export function relayDataPath(...parts: string[]): string {
+ return ownerScopedUserDataPath(DIR, ...parts);
+}
+
+export function secureStorageAvailable(): boolean {
+ const backend = (safeStorage as { getSelectedStorageBackend?: () => string }).getSelectedStorageBackend?.();
+ return oauthSecureStorageAvailable({
+ platform: process.platform,
+ available: safeStorage.isEncryptionAvailable(),
+ backend,
+ });
+}
+
+function isString(value: unknown): value is string {
+ return typeof value === 'string' && value.length > 0;
+}
+
+function parseActive(raw: unknown): ActiveRelay | null {
+ if (!raw || typeof raw !== 'object') return null;
+ const a = raw as Record<string, unknown>;
+ if (
+ !isString(a.relayId) ||
+ !RELAY_ID_PATTERN.test(a.relayId) ||
+ !isString(a.name) ||
+ !isString(a.baseUrl) ||
+ (a.role !== 'owner' && a.role !== 'member') ||
+ (a.origin !== 'host' && a.origin !== 'server' && a.origin !== 'join') ||
+ !isString(a.deviceId) ||
+ !isRelayPublicKey(a.ownerPublicKey)
+ ) {
+ return null;
+ }
+ return {
+ relayId: a.relayId,
+ name: a.name,
+ baseUrl: a.baseUrl,
+ role: a.role,
+ origin: a.origin,
+ deviceId: a.deviceId,
+ ownerPublicKey: a.ownerPublicKey,
+ };
+}
+
+function parseDeployment(raw: unknown): RelayDeployment | null {
+ if (!raw || typeof raw !== 'object') return null;
+ const d = raw as Record<string, unknown>;
+ if (
+ !isString(d.sshHostId) ||
+ !isString(d.address) ||
+ !isString(d.baseUrl) ||
+ !isString(d.relayId) ||
+ !RELAY_ID_PATTERN.test(d.relayId) ||
+ !isString(d.name) ||
+ !isRelayPublicKey(d.ownerPublicKey) ||
+ typeof d.relayVersion !== 'string' ||
+ !isString(d.deployedAt)
+ ) {
+ return null;
+ }
+ return {
+ sshHostId: d.sshHostId,
+ address: d.address,
+ baseUrl: d.baseUrl,
+ relayId: d.relayId,
+ name: d.name,
+ ownerPublicKey: d.ownerPublicKey,
+ relayVersion: d.relayVersion,
+ deployedAt: d.deployedAt,
+ complete: d.complete === true,
+ };
+}
+
+function parseConfig(raw: unknown): RelayConfig {
+ if (!raw || typeof raw !== 'object') return structuredClone(DEFAULT_CONFIG);
+ const value = raw as Record<string, unknown>;
+ const host = (value.host ?? {}) as Partial<RelayHostSettings>;
+ // 第 1 版没有设备签名:它的中转身份与凭证不再可用,只保留本机中转的端口等设置。
+ const current = value.version === CONFIG_VERSION;
+ return {
+ version: CONFIG_VERSION,
+ active: current ? parseActive(value.active) : null,
+ host: {
+ enabled: current && host.enabled === true,
+ port: typeof host.port === 'number' && Number.isInteger(host.port) ? host.port : DEFAULT_RELAY_PORT,
+ listenAll: host.listenAll === true,
+ externalUrl: typeof host.externalUrl === 'string' && host.externalUrl ? host.externalUrl : null,
+ relayId: current && isString(host.relayId) && RELAY_ID_PATTERN.test(host.relayId) ? host.relayId : null,
+ },
+ deployment: current ? parseDeployment(value.deployment) : null,
+ };
+}
+
+function secretsFile(relayId: string): string {
+ return relayDataPath('secrets', `${relayId}.enc`);
+}
+
+function readSecretsFile(relayId: string): RelaySecrets | null {
+ if (!RELAY_ID_PATTERN.test(relayId) || !secureStorageAvailable()) return null;
+ try {
+ const encrypted = fs.readFileSync(secretsFile(relayId), 'utf8');
+ const parsed = JSON.parse(safeStorage.decryptString(Buffer.from(encrypted, 'base64'))) as Partial<RelaySecrets>;
+ return isString(parsed.credential) && isString(parsed.seed) ? { credential: parsed.credential, seed: parsed.seed } : null;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== 'ENOENT') log.warn('relay secrets unreadable');
+ return null;
+ }
+}
+
+/** 第 1 版的秘密文件:不再使用,迁移时删掉,不让旧凭证留在磁盘上。 */
+function removeLegacySecrets(): void {
+ for (const name of ['credential.enc', 'owner-credential.enc']) {
+ try {
+ fs.rmSync(relayDataPath(name), { force: true });
+ } catch {
+ // 尽力而为
+ }
+ }
+}
+
+function load(): Cache {
+ const scope = activeOwnerScopeKey();
+ if (cache?.scope === scope) return cache;
+ let config = structuredClone(DEFAULT_CONFIG);
+ if (getActiveAppSession().dataOwnerId) {
+ try {
+ const raw = JSON.parse(fs.readFileSync(relayDataPath('config.json'), 'utf8')) as Record<string, unknown>;
+ config = parseConfig(raw);
+ if (raw.version !== CONFIG_VERSION) removeLegacySecrets();
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== 'ENOENT') log.warn('relay config unreadable, using official relay');
+ }
+ }
+ cache = { scope, config, secrets: new Map() };
+ return cache;
+}
+
+function cachedSecrets(state: Cache, relayId: string): RelaySecrets | null {
+ if (!state.secrets.has(relayId)) state.secrets.set(relayId, readSecretsFile(relayId));
+ return state.secrets.get(relayId) ?? null;
+}
+
+export function readRelayConfig(): RelayConfig {
+ return structuredClone(load().config);
+}
+
+export function readRelaySecrets(relayId: string): RelaySecrets | null {
+ if (!getActiveAppSession().dataOwnerId) return null;
+ return cachedSecrets(load(), relayId);
+}
+
+/** 当前使用的自建中转与秘密;使用官方中转时返回 null。同步、无 IO(命中缓存时)。 */
+export function activeSelfHostedRelay(): ActiveSelfHostedRelay | null {
+ // 账号作用域还没提交时(启动早期 / 登出)一律走官方中转,不读任何账号私有文件。
+ if (!getActiveAppSession().dataOwnerId) return null;
+ const state = load();
+ const active = state.config.active;
+ // 秘密缺失(钥匙串被清 / 换机):退回官方,避免拿空凭证无限重连。
+ const secrets = active ? cachedSecrets(state, active.relayId) : null;
+ if (!active || !secrets) return null;
+ return {
+ relayId: active.relayId,
+ name: active.name,
+ baseUrl: active.baseUrl,
+ role: active.role,
+ credential: secrets.credential,
+ deviceId: active.deviceId,
+ signingSeed: secrets.seed,
+ ownerPublicKey: active.ownerPublicKey,
+ };
+}
+
+/** 当前中转的来源(界面区分本机中转 / 服务器中转 / 加入的中转)。 */
+export function activeRelayOrigin(): RelayOrigin | null {
+ return activeSelfHostedRelay() ? load().config.active!.origin : null;
+}
+
+/** 启动时把本模块登记为 device-link 的中转来源(见 selfHostedRelayRouting.ts)。 */
+export function installSelfHostedRelayRouting(): void {
+ setSelfHostedRelaySource(activeSelfHostedRelay);
+}
+
+function writeAtomically(file: string, content: string): void {
+ fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+ const tmp = `${file}.${randomUUID()}.tmp`;
+ try {
+ fs.writeFileSync(tmp, content, { mode: 0o600, flag: 'wx' });
+ fs.renameSync(tmp, file);
+ } catch (error) {
+ fs.rmSync(tmp, { force: true });
+ throw error;
+ }
+}
+
+function requireSignedIn(): void {
+ // 未登录(没有账号作用域)时拒绝写入,不把私有状态落到临时命名空间。
+ if (!getActiveAppSession().dataOwnerId) throw new Error('NOT_SIGNED_IN');
+}
+
+export function writeRelayConfig(next: RelayConfig): void {
+ requireSignedIn();
+ const state = load();
+ writeAtomically(relayDataPath('config.json'), JSON.stringify(next, null, 2));
+ state.config = structuredClone(next);
+}
+
+export function writeRelaySecrets(relayId: string, secrets: RelaySecrets): void {
+ requireSignedIn();
+ if (!RELAY_ID_PATTERN.test(relayId)) throw new Error('INVALID_RELAY_ID');
+ if (!secureStorageAvailable()) throw new Error('SECURE_STORAGE_UNAVAILABLE');
+ writeAtomically(secretsFile(relayId), safeStorage.encryptString(JSON.stringify(secrets)).toString('base64'));
+ load().secrets.set(relayId, { ...secrets });
+}
+
+export function deleteRelaySecrets(relayId: string): void {
+ if (!getActiveAppSession().dataOwnerId || !RELAY_ID_PATTERN.test(relayId)) return;
+ fs.rmSync(secretsFile(relayId), { force: true });
+ load().secrets.set(relayId, null);
+}
+
+/** 测试与账号切换后强制重新读取。 */
+export function invalidateRelayConfigCache(): void {
+ cache = null;
+}
diff --git a/apps/desktop/src/main/device-link/selfHostedRelayDeploy.ts b/apps/desktop/src/main/device-link/selfHostedRelayDeploy.ts
new file mode 100644
index 0000000000..8f778915f3
--- /dev/null
+++ b/apps/desktop/src/main/device-link/selfHostedRelayDeploy.ts
@@ -0,0 +1,456 @@
+/**
+ * 一键把自建中转部署到用户自己的 Linux 服务器(docs/self-hosted-relay-plan.md §15 方式 C)。
+ *
+ * 走「设置 → 远程」里已配置的 SSH 主机,需要 root 或免密 sudo(没有就停下来提示,不索要密码)。
+ * 服务器上:
+ * /opt/cindy-relay/node Node 运行环境(版本与 SHA-256 写死,官方源失败退回国内镜像)
+ * /opt/cindy-relay/relay.mjs 与 Cindy 内运行的同一个中转内核(单文件)
+ * /var/lib/cindy-relay 中转数据(设备档案、证书),属 cindy-relay 系统用户,0700
+ * cindy-relay.service systemd 服务,只放行绑定 80/443 的权限
+ * 证书由中转自己向 Let's Encrypt 申请并续期(IP 用 6 天短期证书,域名用常规证书)。
+ *
+ * 主人身份(中转 ID、主人凭证、主人密钥)只在这台电脑生成与保存;交给服务器的只有凭证哈希、
+ * 主人公钥与主人证书。命令里不出现任何秘密,也不把服务器输出写进日志。
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { app } from 'electron';
+import type { RemoteHost } from '@cindy/maker-remote-ssh';
+import { RELAY_VERSION } from '@cindy/device-link-relay';
+import { createLogger } from '../logger.js';
+import { ensureRemoteHostReady, getRemoteSshPool } from '../remote-ssh/index.js';
+import type { RelayDeployErrorCode, RelayDeployStep } from '../../shared/selfHostedRelay.js';
+
+const log = createLogger('self-hosted-relay:deploy');
+
+const INSTALL_DIR = '/opt/cindy-relay';
+const DATA_DIR = '/var/lib/cindy-relay';
+const NODE_VERSION = '24.22.1';
+const NODE_SHA256: Record<'x64' | 'arm64', string> = {
+ x64: 'eb6728e77c576a35162c122c45ccadf224d89ff00abc8dae46cc2897c6002d7c',
+ arm64: '33c37be234ba8bee041961047b19160f4d7d0f164e8e246f78bdd10feff148b3',
+};
+const CERTIFICATE_WAIT_MS = 4 * 60 * 1000;
+const CERTIFICATE_POLL_MS = 3_000;
+
+export class RelayDeployError extends Error {
+ constructor(
+ readonly code: RelayDeployErrorCode,
+ readonly detail?: string,
+ ) {
+ super(code);
+ this.name = 'RelayDeployError';
+ }
+}
+
+/** 首次部署时在服务器上初始化中转用的参数(都不是秘密)。 */
+export interface RelayInitArgs {
+ name: string;
+ relayId: string;
+ ownerUserId: string;
+ ownerDeviceId: string;
+ ownerDeviceName: string;
+ ownerCredentialHash: string;
+ ownerPublicKey: string;
+ ownerCert: unknown;
+}
+
+export interface DeployParams {
+ sshHostId: string;
+ address: string;
+ baseUrl: string;
+ /** 服务器上已有不属于这台电脑的中转时,是否清掉重来。 */
+ replaceExisting: boolean;
+ /** 服务器上没有中转数据时用它初始化;已有本机主人的数据时保留原数据(升级)。 */
+ init: RelayInitArgs;
+ /** 国内网络:先试镜像再试官方源。 */
+ preferMirror: boolean;
+ onStep(step: RelayDeployStep): void;
+ /** 每次继续 SSH 操作前核对发起账号,避免连接等待期间换账号后取到另一份主机配置。 */
+ assertCurrent?(): void;
+}
+
+function shellQuote(value: string): string {
+ return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/** 中转程序单文件:开发时取包的构建产物,安装包里取 extraResource。 */
+export function resolveRelayBundlePath(): string | null {
+ const appPath = app.getAppPath();
+ const candidates = [
+ path.join(appPath, '..', '..', 'packages', 'device-link-relay', 'dist', 'relay.mjs'),
+ path.join(process.resourcesPath ?? '', 'device-link-relay', 'relay.mjs'),
+ path.join(`${appPath}.unpacked`, 'packages', 'device-link-relay', 'dist', 'relay.mjs'),
+ ];
+ for (const candidate of candidates) {
+ try {
+ const stat = fs.statSync(candidate);
+ if (stat.isFile() && stat.size > 0) return candidate;
+ } catch {
+ // try next
+ }
+ }
+ return null;
+}
+
+/** 这个版本 Cindy 自带的中转版本;没带中转程序时为 null。 */
+export function bundledRelayVersion(): string | null {
+ return resolveRelayBundlePath() ? RELAY_VERSION : null;
+}
+
+function parseLines(stdout: string): Map<string, string[]> {
+ const result = new Map<string, string[]>();
+ for (const line of stdout.split('\n')) {
+ const [key, ...rest] = line.trim().split(' ');
+ if (!key || !/^[A-Z_]+$/.test(key)) continue;
+ result.set(key, [...(result.get(key) ?? []), rest.join(' ')]);
+ }
+ return result;
+}
+
+function first(lines: Map<string, string[]>, key: string): string | undefined {
+ return lines.get(key)?.[0];
+}
+
+type Privilege = 'root' | 'sudo';
+
+class Remote {
+ constructor(
+ private readonly host: RemoteHost,
+ private readonly privilege: Privilege | null,
+ private readonly assertCurrent: () => void,
+ ) {}
+
+ /** 以 root 运行一段脚本;参数逐个转义,脚本经 `bash -c` 传入,stdin 留给上传。 */
+ async root(script: string, args: string[], options: { timeoutMs?: number; label: string; input?: Buffer }) {
+ this.assertCurrent();
+ if (!this.privilege) throw new Error('privilege not determined');
+ const command = `bash -c ${shellQuote(script)} cindy-relay ${args.map(shellQuote).join(' ')}`;
+ return this.host.exec(this.privilege === 'root' ? command : `sudo -n ${command}`, {
+ timeoutMs: options.timeoutMs ?? 120_000,
+ label: options.label,
+ input: options.input,
+ });
+ }
+
+ async plain(script: string, label: string) {
+ this.assertCurrent();
+ return this.host.exec(`bash -c ${shellQuote(script)}`, { timeoutMs: 60_000, label });
+ }
+
+ withPrivilege(privilege: Privilege): Remote {
+ return new Remote(this.host, privilege, this.assertCurrent);
+ }
+}
+
+async function connect(sshHostId: string, assertCurrent: () => void): Promise<Remote> {
+ assertCurrent();
+ try {
+ await ensureRemoteHostReady(sshHostId);
+ } catch (error) {
+ throw new RelayDeployError('SSH_FAILED', error instanceof Error ? error.message.slice(0, 300) : undefined);
+ }
+ assertCurrent();
+ const host = getRemoteSshPool().get(sshHostId);
+ if (!host) throw new RelayDeployError('SSH_FAILED');
+ return new Remote(host, null, assertCurrent);
+}
+
+const PROBE_SCRIPT = `
+echo "OS $(uname -s)"
+echo "ARCH $(uname -m)"
+if [ "$(id -u)" = 0 ]; then echo "ROOT root"
+elif command -v sudo >/dev/null 2>&1 && sudo -n true 2>/dev/null; then echo "ROOT sudo"
+else echo "ROOT none"; fi
+if command -v systemctl >/dev/null 2>&1 && [ -d /run/systemd/system ]; then echo "SYSTEMD yes"; else echo "SYSTEMD no"; fi
+if [ -f /proc/net/if_inet6 ]; then echo "IPV6 yes"; else echo "IPV6 no"; fi
+if command -v curl >/dev/null 2>&1 || command -v wget >/dev/null 2>&1; then echo "FETCH yes"; else echo "FETCH no"; fi
+`;
+
+const INSPECT_SCRIPT = `
+NODE=${INSTALL_DIR}/node/bin/node
+STATE=${DATA_DIR}/relay-state.json
+if [ -x "$NODE" ]; then echo "NODE $("$NODE" --version 2>/dev/null)"; fi
+if [ -f "$STATE" ]; then
+ if [ -x "$NODE" ]; then
+ "$NODE" -e 'try{const s=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));console.log("STATE "+s.schema+" "+s.relayId+" "+s.ownerPublicKey)}catch(e){console.log("STATE invalid")}' "$STATE"
+ else echo "STATE unknown"; fi
+fi
+OWN=$(systemctl show -p MainPID --value cindy-relay 2>/dev/null || echo 0)
+if command -v ss >/dev/null 2>&1; then
+ ss -Hltnp 2>/dev/null | awk '{print $4" "$6}' | while read -r addr proc; do
+ port="\${addr##*:}"
+ if [ "$port" = 80 ] || [ "$port" = 443 ]; then
+ case "$proc" in *"pid=$OWN,"*) ;; *) echo "BUSY $port $(echo "$proc" | sed -n 's/.*(("\\([^"]*\\)".*/\\1/p')";; esac
+ fi
+ done
+fi
+`;
+
+const RUNTIME_SCRIPT = `
+set -e
+VERSION="$1"; SHA="$2"; URL_A="$3"; URL_B="$4"
+NODE_DIR=${INSTALL_DIR}/node
+if [ -x "$NODE_DIR/bin/node" ] && [ "$("$NODE_DIR/bin/node" --version 2>/dev/null)" = "v$VERSION" ]; then echo "NODE_READY cached"; exit 0; fi
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+ok=""
+for url in "$URL_A" "$URL_B"; do
+ if command -v curl >/dev/null 2>&1; then
+ curl -fsSL --retry 2 --retry-delay 2 --connect-timeout 15 --max-time 900 -o "$TMP/node.tgz" "$url" || continue
+ else
+ wget -q -t 3 -T 30 -O "$TMP/node.tgz" "$url" || continue
+ fi
+ if [ "$(sha256sum "$TMP/node.tgz" | cut -d' ' -f1)" = "$SHA" ]; then ok=1; break; fi
+ echo "HASH_MISMATCH $url"
+done
+[ -n "$ok" ] || { echo "ERROR DOWNLOAD"; exit 21; }
+mkdir -p "$TMP/x"
+tar -xzf "$TMP/node.tgz" -C "$TMP/x" --strip-components=1
+install -d -m 755 ${INSTALL_DIR}
+rm -rf "$NODE_DIR.new"
+mv "$TMP/x" "$NODE_DIR.new"
+chmod -R a+rX "$NODE_DIR.new"
+rm -rf "$NODE_DIR"
+mv "$NODE_DIR.new" "$NODE_DIR"
+echo "NODE_READY $("$NODE_DIR/bin/node" --version)"
+`;
+
+const UPLOAD_SCRIPT = `
+set -e
+install -d -m 755 ${INSTALL_DIR}
+umask 022
+cat > ${INSTALL_DIR}/relay.mjs.new
+echo "SHA $(sha256sum ${INSTALL_DIR}/relay.mjs.new | cut -d' ' -f1)"
+`;
+
+const CONFIGURE_SCRIPT = `
+set -e
+ADDRESS="$1"; LISTEN="$2"; PUBLIC_URL="$3"; REPLACE="$4"; ACME_DIRECTORY="$5"; shift 5
+NODE=${INSTALL_DIR}/node/bin/node
+if ! id cindy-relay >/dev/null 2>&1; then
+ useradd --system --home-dir ${DATA_DIR} --no-create-home --shell /usr/sbin/nologin cindy-relay 2>/dev/null \\
+ || useradd -r -d ${DATA_DIR} -s /sbin/nologin cindy-relay
+fi
+systemctl stop cindy-relay >/dev/null 2>&1 || true
+if [ "$REPLACE" = 1 ]; then rm -rf ${DATA_DIR}; fi
+install -d -m 700 -o cindy-relay -g cindy-relay ${DATA_DIR}
+mv -f ${INSTALL_DIR}/relay.mjs.new ${INSTALL_DIR}/relay.mjs
+if [ ! -f ${DATA_DIR}/relay-state.json ]; then
+ "$NODE" ${INSTALL_DIR}/relay.mjs init --data ${DATA_DIR} "$@" >/dev/null
+ echo "INITIALIZED"
+fi
+chown -R cindy-relay:cindy-relay ${DATA_DIR}
+rm -f ${DATA_DIR}/status.json
+EXTRA=""
+if [ -n "$ACME_DIRECTORY" ]; then EXTRA=" --acme-directory $ACME_DIRECTORY"; fi
+cat > /etc/systemd/system/cindy-relay.service <<UNIT
+[Unit]
+Description=Cindy self-hosted relay
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=cindy-relay
+Group=cindy-relay
+ExecStart=$NODE ${INSTALL_DIR}/relay.mjs serve --data ${DATA_DIR} --host $LISTEN --port 443 --public-url $PUBLIC_URL --acme-identifier $ADDRESS --acme-http-port 80$EXTRA
+Restart=always
+RestartSec=5
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+ReadWritePaths=${DATA_DIR}
+LimitNOFILE=65536
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+systemctl daemon-reload
+systemctl enable cindy-relay >/dev/null 2>&1
+if command -v ufw >/dev/null 2>&1 && ufw status 2>/dev/null | grep -q "Status: active"; then
+ ufw allow 80/tcp >/dev/null && ufw allow 443/tcp >/dev/null && echo "FIREWALL ufw"
+fi
+if command -v firewall-cmd >/dev/null 2>&1 && firewall-cmd --state >/dev/null 2>&1; then
+ firewall-cmd --permanent --add-service=http --add-service=https >/dev/null && firewall-cmd --reload >/dev/null && echo "FIREWALL firewalld"
+fi
+systemctl restart cindy-relay
+echo "CONFIGURED"
+`;
+
+const STATUS_SCRIPT = `
+echo "ACTIVE $(systemctl is-active cindy-relay 2>/dev/null)"
+if [ -f ${DATA_DIR}/status.json ]; then echo "STATUS $(cat ${DATA_DIR}/status.json)"; fi
+`;
+
+const JOURNAL_SCRIPT = `journalctl -u cindy-relay -n 15 --no-pager -o cat 2>/dev/null | tail -n 15`;
+
+const UNINSTALL_SCRIPT = `
+systemctl disable --now cindy-relay >/dev/null 2>&1 || true
+rm -f /etc/systemd/system/cindy-relay.service
+systemctl daemon-reload >/dev/null 2>&1 || true
+rm -rf ${INSTALL_DIR}
+if [ "$1" = 1 ]; then
+ rm -rf ${DATA_DIR}
+ userdel cindy-relay >/dev/null 2>&1 || true
+fi
+echo "UNINSTALLED"
+`;
+
+function nodeUrls(arch: 'x64' | 'arm64', preferMirror: boolean): [string, string] {
+ const file = `node-v${NODE_VERSION}-linux-${arch}.tar.gz`;
+ const official = `https://nodejs.org/dist/v${NODE_VERSION}/${file}`;
+ const mirror = `https://cdn.npmmirror.com/binaries/node/v${NODE_VERSION}/${file}`;
+ return preferMirror ? [mirror, official] : [official, mirror];
+}
+
+/** 连接并确认权限与系统;返回可用 root 执行的远端。 */
+async function prepare(sshHostId: string, assertCurrent: () => void): Promise<{ remote: Remote; arch: 'x64' | 'arm64'; ipv6: boolean }> {
+ const base = await connect(sshHostId, assertCurrent);
+ const probe = parseLines((await base.plain(PROBE_SCRIPT, 'relay-deploy-probe')).stdout);
+ const machine = first(probe, 'ARCH');
+ const arch = machine === 'x86_64' || machine === 'amd64' ? 'x64' : machine === 'aarch64' || machine === 'arm64' ? 'arm64' : null;
+ if (first(probe, 'OS') !== 'Linux' || !arch || first(probe, 'SYSTEMD') !== 'yes') {
+ throw new RelayDeployError('UNSUPPORTED_SYSTEM', `${first(probe, 'OS') ?? '?'} ${machine ?? '?'}`);
+ }
+ const privilege = first(probe, 'ROOT');
+ if (privilege !== 'root' && privilege !== 'sudo') throw new RelayDeployError('NEEDS_ROOT');
+ if (first(probe, 'FETCH') !== 'yes') throw new RelayDeployError('UNSUPPORTED_SYSTEM', 'curl / wget');
+ return { remote: base.withPrivilege(privilege), arch, ipv6: first(probe, 'IPV6') === 'yes' };
+}
+
+function expectOk(result: { exitCode: number | null; stdout: string; stderr: string }, code: RelayDeployErrorCode): Map<string, string[]> {
+ const lines = parseLines(result.stdout);
+ if (result.exitCode !== 0) {
+ const reason = result.stderr.trim().split('\n').slice(-2).join(' ').slice(0, 300);
+ throw new RelayDeployError(code, reason || undefined);
+ }
+ return lines;
+}
+
+async function waitForCertificate(remote: Remote): Promise<void> {
+ const deadline = Date.now() + CERTIFICATE_WAIT_MS;
+ while (Date.now() < deadline) {
+ await new Promise((resolve) => setTimeout(resolve, CERTIFICATE_POLL_MS));
+ const lines = parseLines((await remote.root(STATUS_SCRIPT, [], { label: 'relay-deploy-status' })).stdout);
+ const active = first(lines, 'ACTIVE');
+ let certificate: { state?: string; error?: string } | undefined;
+ try {
+ certificate = (JSON.parse(first(lines, 'STATUS') ?? '{}') as { certificate?: { state?: string; error?: string } }).certificate;
+ } catch {
+ certificate = undefined;
+ }
+ if (certificate?.state === 'ready') return;
+ if (certificate?.state === 'failed') throw new RelayDeployError('CERTIFICATE_FAILED', certificate.error?.slice(0, 400));
+ if (active === 'failed' || (active && active !== 'active' && active !== 'activating')) {
+ const journal = (await remote.root(JOURNAL_SCRIPT, [], { label: 'relay-deploy-journal' })).stdout;
+ const errorLine = journal
+ .split('\n')
+ .reverse()
+ .find((line) => line.includes('"error"') || line.includes('Error'));
+ throw new RelayDeployError('DEPLOY_FAILED', errorLine?.slice(0, 400));
+ }
+ }
+ throw new RelayDeployError('CERTIFICATE_FAILED', 'timed out waiting for the certificate');
+}
+
+async function verifyReachable(baseUrl: string, relayId: string): Promise<void> {
+ let lastError = '';
+ for (let attempt = 0; attempt < 4; attempt++) {
+ try {
+ const res = await fetch(`${baseUrl}/api/device-link/relay/info`, { signal: AbortSignal.timeout(10_000) });
+ const body = (await res.json()) as { relayId?: string };
+ if (res.ok && body.relayId === relayId) return;
+ lastError = `unexpected response (${res.status})`;
+ } catch (error) {
+ lastError = error instanceof Error ? (error.cause instanceof Error ? error.cause.message : error.message) : 'failed';
+ }
+ await new Promise((resolve) => setTimeout(resolve, 3_000));
+ }
+ throw new RelayDeployError('NOT_REACHABLE', lastError.slice(0, 300));
+}
+
+/** 部署或升级:服务器上已有本机主人的中转时保留数据,只换程序与配置。 */
+export async function deployRelayToServer(params: DeployParams): Promise<{ relayVersion: string }> {
+ const bundlePath = resolveRelayBundlePath();
+ if (!bundlePath) throw new RelayDeployError('BUNDLE_MISSING');
+ const bundle = fs.readFileSync(bundlePath);
+
+ params.onStep('connect');
+ const { remote, arch, ipv6 } = await prepare(params.sshHostId, params.assertCurrent ?? (() => {}));
+
+ params.onStep('check');
+ const inspected = parseLines((await remote.root(INSPECT_SCRIPT, [], { label: 'relay-deploy-inspect' })).stdout);
+ const busy = inspected.get('BUSY') ?? [];
+ if (busy.length > 0) throw new RelayDeployError('PORT_BUSY', busy.join(', '));
+ const state = first(inspected, 'STATE');
+ if (state && !params.replaceExisting) {
+ const [, relayId, ownerPublicKey] = state.split(' ');
+ if (relayId !== params.init.relayId || ownerPublicKey !== params.init.ownerPublicKey) {
+ throw new RelayDeployError('RELAY_MISMATCH');
+ }
+ }
+
+ params.onStep('runtime');
+ const [urlA, urlB] = nodeUrls(arch, params.preferMirror);
+ const runtime = await remote.root(RUNTIME_SCRIPT, [NODE_VERSION, NODE_SHA256[arch], urlA, urlB], {
+ timeoutMs: 20 * 60 * 1000,
+ label: 'relay-deploy-runtime',
+ });
+ expectOk(runtime, 'DOWNLOAD_FAILED');
+
+ params.onStep('upload');
+ const uploaded = expectOk(
+ await remote.root(UPLOAD_SCRIPT, [], { input: bundle, timeoutMs: 120_000, label: 'relay-deploy-upload' }),
+ 'DEPLOY_FAILED',
+ );
+ if (first(uploaded, 'SHA') !== createHash('sha256').update(bundle).digest('hex')) {
+ throw new RelayDeployError('DEPLOY_FAILED', 'upload checksum mismatch');
+ }
+
+ params.onStep('configure');
+ const init = params.init;
+ const initArgs = [
+ '--name', init.name,
+ '--owner-user', init.ownerUserId,
+ '--owner-device', init.ownerDeviceId,
+ '--owner-device-name', init.ownerDeviceName,
+ '--owner-credential-hash', init.ownerCredentialHash,
+ '--relay-id', init.relayId,
+ '--owner-public-key', init.ownerPublicKey,
+ '--owner-cert', Buffer.from(JSON.stringify(init.ownerCert)).toString('base64url'),
+ ];
+ const acmeDirectory = process.env.CINDY_RELAY_ACME_DIRECTORY ?? '';
+ const configured = await remote.root(
+ CONFIGURE_SCRIPT,
+ [params.address, ipv6 ? '::' : '0.0.0.0', params.baseUrl, params.replaceExisting ? '1' : '0', acmeDirectory, ...initArgs],
+ { timeoutMs: 180_000, label: 'relay-deploy-configure' },
+ );
+ const configureLines = expectOk(configured, 'DEPLOY_FAILED');
+ log.info('relay configured on server', {
+ initialized: configureLines.has('INITIALIZED'),
+ firewall: (configureLines.get('FIREWALL') ?? []).join(',') || 'none',
+ });
+
+ params.onStep('certificate');
+ await waitForCertificate(remote);
+
+ params.onStep('verify');
+ await verifyReachable(params.baseUrl, init.relayId);
+ return { relayVersion: RELAY_VERSION };
+}
+
+export async function uninstallRelayFromServer(
+ sshHostId: string,
+ removeData: boolean,
+ onStep: (step: RelayDeployStep) => void,
+ assertCurrent: () => void = () => {},
+): Promise<void> {
+ onStep('connect');
+ const { remote } = await prepare(sshHostId, assertCurrent);
+ onStep('configure');
+ expectOk(await remote.root(UNINSTALL_SCRIPT, [removeData ? '1' : '0'], { label: 'relay-deploy-uninstall' }), 'DEPLOY_FAILED');
+}
diff --git a/apps/desktop/src/main/device-link/selfHostedRelayFrameAuth.ts b/apps/desktop/src/main/device-link/selfHostedRelayFrameAuth.ts
new file mode 100644
index 0000000000..9301abd354
--- /dev/null
+++ b/apps/desktop/src/main/device-link/selfHostedRelayFrameAuth.ts
@@ -0,0 +1,127 @@
+/**
+ * 自建中转的设备签名(docs/self-hosted-relay-plan.md §16):给 DeviceLinkClient 的 `frameAuth`。
+ *
+ * - 发出:经中转转发的每条对端消息用本机签名密钥签名。
+ * - 收到:对端消息必须带发送设备的有效签名,证书由主人公钥核对;中转(哪怕被人控制)伪造、篡改、
+ * 重放的消息在分发前丢弃。电脑会执行远程请求,所以电脑端核对所有对端消息。
+ * - 证书列表从中转取,用主人公钥逐个核对(中转无法伪造);遇到不认识的设备时刷新。
+ *
+ * 只依赖路由模块与共享协议包,不碰 electron / 账号文件,device-link 主模块可直接引用。
+ */
+import {
+ fetchRelayCertificates,
+ RelayFrameAuthenticator,
+ type DeviceLinkFrameAuth,
+} from '@cindy/device-link';
+import { nodeRelayAuthCrypto } from '@cindy/device-link/node-relay-crypto';
+import { createLogger } from '../logger.js';
+import { activeSelfHostedRelay, type ActiveSelfHostedRelay } from './selfHostedRelayRouting.js';
+
+const log = createLogger('self-hosted-relay:signatures');
+
+const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
+const UNKNOWN_SIGNER_REFRESH_MIN_MS = 5_000;
+
+interface Current {
+ key: string;
+ relay: ActiveSelfHostedRelay;
+ authenticator: RelayFrameAuthenticator;
+ frameAuth: DeviceLinkFrameAuth;
+ timer: ReturnType<typeof setInterval>;
+ refreshing: Promise<void> | null;
+ lastRefreshAt: number;
+}
+
+let current: Current | null = null;
+
+function keyOf(relay: ActiveSelfHostedRelay): string {
+ // 种子不进 key 字符串以外的任何地方;key 只在内存里比较。
+ return [relay.relayId, relay.baseUrl, relay.deviceId, relay.ownerPublicKey, relay.signingSeed].join('\n');
+}
+
+function dispose(): void {
+ if (!current) return;
+ clearInterval(current.timer);
+ current = null;
+}
+
+async function refresh(target: Current): Promise<void> {
+ target.lastRefreshAt = Date.now();
+ try {
+ const certs = await fetchRelayCertificates(
+ (url, init) => fetch(url, init),
+ target.relay.baseUrl,
+ target.relay.credential,
+ AbortSignal.timeout(10_000),
+ );
+ if (current !== target) return;
+ const { accepted, rejected } = target.authenticator.setCertificates(certs);
+ if (rejected > 0) log.warn('relay returned certificates the owner did not issue; ignored', { accepted, rejected });
+ } catch (error) {
+ log.info('relay certificate refresh failed; will retry', { reason: error instanceof Error ? error.name : 'unknown' });
+ }
+}
+
+function scheduleRefresh(target: Current, minIntervalMs: number): void {
+ if (target.refreshing || Date.now() - target.lastRefreshAt < minIntervalMs) return;
+ target.refreshing = refresh(target).finally(() => {
+ target.refreshing = null;
+ });
+}
+
+function create(relay: ActiveSelfHostedRelay): Current {
+ let self: Current | null = null;
+ const authenticator = new RelayFrameAuthenticator({
+ crypto: nodeRelayAuthCrypto,
+ relayId: relay.relayId,
+ deviceId: relay.deviceId,
+ seed: relay.signingSeed,
+ ownerPublicKey: relay.ownerPublicKey,
+ onUnknownSigner: () => {
+ if (self) scheduleRefresh(self, UNKNOWN_SIGNER_REFRESH_MIN_MS);
+ },
+ });
+ const timer = setInterval(() => {
+ if (self) scheduleRefresh(self, 0);
+ }, REFRESH_INTERVAL_MS);
+ timer.unref?.();
+ self = {
+ key: keyOf(relay),
+ relay,
+ authenticator,
+ frameAuth: {
+ sign: (frame) => authenticator.sign(frame),
+ verify: (frame) => authenticator.verify(frame) === 'ok',
+ },
+ timer,
+ refreshing: null,
+ lastRefreshAt: 0,
+ };
+ scheduleRefresh(self, 0);
+ return self;
+}
+
+/** DeviceLinkClient 每帧调用:官方中转返回 null(不签名、不核对)。 */
+export function currentRelayFrameAuth(): DeviceLinkFrameAuth | null {
+ const relay = activeSelfHostedRelay();
+ if (!relay) {
+ dispose();
+ return null;
+ }
+ if (current?.key !== keyOf(relay)) {
+ dispose();
+ try {
+ current = create(relay);
+ } catch {
+ // 本机密钥损坏:不能签名就不能安全通信。返回一个全部拒绝的实现,界面会提示重新加入。
+ log.warn('relay signing key is unusable');
+ return { sign: () => undefined, verify: () => false };
+ }
+ }
+ return current.frameAuth;
+}
+
+/** 新设备刚加入后立刻刷新证书,不必等它的第一条消息被拒一次。 */
+export function refreshRelayCertificatesSoon(): void {
+ if (current) scheduleRefresh(current, 0);
+}
diff --git a/apps/desktop/src/main/device-link/selfHostedRelayRouting.ts b/apps/desktop/src/main/device-link/selfHostedRelayRouting.ts
new file mode 100644
index 0000000000..eeec022dd1
--- /dev/null
+++ b/apps/desktop/src/main/device-link/selfHostedRelayRouting.ts
@@ -0,0 +1,31 @@
+/**
+ * 当前 device-link 走哪个中转:官方(null)或自建中转。
+ *
+ * 刻意零依赖:device-link 主模块、REST 入口(deviceLinkApi)只读这里,不直接依赖读写配置的模块
+ * (那边要碰 electron safeStorage、账号作用域与文件)。配置模块在启动时把自己登记为来源;
+ * 没有登记(单测、未启用该功能的进程)时一律走官方中转,与引入自建中转之前的行为一致。
+ */
+export interface ActiveSelfHostedRelay {
+ relayId: string;
+ name: string;
+ baseUrl: string;
+ role: 'owner' | 'member';
+ credential: string;
+ /** 本机在这个中转上的设备 ID(与证书一致)。 */
+ deviceId: string;
+ /** 本机签名私钥种子(base64url),只在内存与安全存储里。 */
+ signingSeed: string;
+ /** 主人公钥:核对其他设备证书。 */
+ ownerPublicKey: string;
+}
+
+let source: (() => ActiveSelfHostedRelay | null) | null = null;
+
+export function setSelfHostedRelaySource(next: (() => ActiveSelfHostedRelay | null) | null): void {
+ source = next;
+}
+
+/** 当前使用的自建中转与凭证;使用官方中转时返回 null。同步读取。 */
+export function activeSelfHostedRelay(): ActiveSelfHostedRelay | null {
+ return source ? source() : null;
+}
diff --git a/apps/desktop/src/main/device-link/selfHostedRelayRuntime.ts b/apps/desktop/src/main/device-link/selfHostedRelayRuntime.ts
new file mode 100644
index 0000000000..97a54877c0
--- /dev/null
+++ b/apps/desktop/src/main/device-link/selfHostedRelayRuntime.ts
@@ -0,0 +1,919 @@
+/**
+ * 自建中转服务的桌面端运行时(docs/self-hosted-relay-plan.md)。
+ *
+ * - 在这台电脑上开启中转(方式 B):Cindy 主进程内运行 `@cindy/device-link-relay`,本机作为主人设备
+ * 连 `http://127.0.0.1:<端口>`;别的设备怎么访问到这台电脑由用户保证,Cindy 只列出本机地址。
+ * - 部署到自己的服务器(方式 C):经已配置的 SSH 主机安装同一个中转内核,自动申请证书;本机是主人,
+ * 远程生成加入链接、审批设备、升级与卸载(selfHostedRelayDeploy.ts)。
+ * - 加入别的中转:粘贴主人电脑给出的加入链接 → 申请 → 主人同意 → 保存中转凭证与签名密钥并切换。
+ * - 设备签名(§16):主人密钥只在主人电脑;同意加入时主人核对配对证明后签发设备证书。
+ *
+ * 只接受本机应用窗口的命令,不经设备互联代理。凭证、私钥、加入码、加入链接不写日志。
+ */
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import { app, ipcMain } from 'electron';
+import {
+ acceptRelayDeviceCert,
+ buildRelayJoinLink,
+ createRelayJoinIdentity,
+ createRelayPairSecret,
+ createRelaySigningKey,
+ fetchRelayInfo,
+ issueRelayDeviceCert,
+ parseRelayJoinLink,
+ relayPublicKeyOf,
+ RelayJoinError,
+ submitRelayPairRequest,
+ verifyRelayPairProof,
+ waitForRelayApproval,
+ type RelayFetch,
+} from '@cindy/device-link';
+import { nodeRelayAuthCrypto as crypto } from '@cindy/device-link/node-relay-crypto';
+import {
+ createDeviceCredential,
+ hashSecret,
+ initializeRelay,
+ startRelayServer,
+ type RelayServerHandle,
+} from '@cindy/device-link-relay';
+import * as authManager from '../authManager.js';
+import { createLogger } from '../logger.js';
+import { assertTrustedAppRendererEvent } from '../security/trustedAppRenderer.js';
+import { throwIpcError } from '../utils/ipcValidate.js';
+import {
+ parseSelfHostedRelayCommand,
+ relayBaseUrlForAddress,
+ SELF_HOSTED_RELAY_IPC,
+ type SelfHostedRelayCommand,
+ type SelfHostedRelayDeployJobView,
+ type SelfHostedRelayErrorCode,
+ type SelfHostedRelayJoinView,
+ type SelfHostedRelayPairRequestView,
+ type SelfHostedRelayState,
+} from '../../shared/selfHostedRelay.js';
+import { deviceName } from './deviceName.js';
+import {
+ broadcast,
+ getDeviceLinkConnectionIssue,
+ restartDeviceLinkForRelayChange,
+ setKeepAwakeEnabled,
+} from './index.js';
+import { getDeviceLinkInvokeContext } from './invoke-context.js';
+import { providerShareLinkApp } from './providerShareApi.js';
+import {
+ activeRelayOrigin,
+ activeSelfHostedRelay,
+ deleteRelaySecrets,
+ installSelfHostedRelayRouting,
+ readRelayConfig,
+ readRelaySecrets,
+ relayDataPath,
+ secureStorageAvailable,
+ writeRelayConfig,
+ writeRelaySecrets,
+ type RelayConfig,
+ type RelayDeployment,
+ type RelaySecrets,
+} from './selfHostedRelayConfig.js';
+import { bundledRelayVersion, deployRelayToServer, RelayDeployError, uninstallRelayFromServer } from './selfHostedRelayDeploy.js';
+import { refreshRelayCertificatesSoon } from './selfHostedRelayFrameAuth.js';
+import { readDeviceLinkSettings } from './settings-store.js';
+import { activeOwnerScopeKey, getActiveAppSession, isAppSessionBoundaryPending, onAppSessionInvalidated } from '../appSessionState.js';
+
+const log = createLogger('self-hosted-relay');
+
+const PENDING_POLL_MS = 2_000;
+const JOIN_LINK_TTL_MS = 10 * 60 * 1000;
+
+const relayFetch: RelayFetch = (url, init) => fetch(url, init);
+
+let host: RelayServerHandle | null = null;
+let hostKey: string | null = null;
+let hostError: SelfHostedRelayErrorCode | null = null;
+let hostStarting: Promise<void> | null = null;
+let joinLink: { link: string; expiresAt: number } | null = null;
+/** 这台电脑生成的加入链接里的配对秘密(只在内存,随链接一起过期)。 */
+let pairSecrets: Array<{ relayId: string; secret: string; expiresAt: number }> = [];
+let pendingRequests: SelfHostedRelayPairRequestView[] = [];
+let pendingRaw = new Map<string, { deviceId: string; publicKey: string }>();
+let pendingTimer: ReturnType<typeof setInterval> | null = null;
+let join: SelfHostedRelayJoinView = { status: 'idle' };
+let joinAbort: AbortController | null = null;
+let deployJob: SelfHostedRelayDeployJobView | null = null;
+let ownerEpoch = 0;
+
+/** 异步工作只属于发起时的账号代次;切走再切回同一账号也不能接收旧结果。 */
+class RelayOperationExpired extends Error {}
+
+function captureOwner(): () => void {
+ const scope = activeOwnerScopeKey();
+ const epoch = ownerEpoch;
+ return () => {
+ if (epoch !== ownerEpoch || scope !== activeOwnerScopeKey() || isAppSessionBoundaryPending()) {
+ throw new RelayOperationExpired();
+ }
+ };
+}
+
+function emitChanged(): void {
+ broadcast(SELF_HOSTED_RELAY_IPC.CHANGED, getState());
+}
+
+function lanAddresses(): string[] {
+ const result: string[] = [];
+ for (const entries of Object.values(os.networkInterfaces())) {
+ for (const entry of entries ?? []) {
+ if (entry.family === 'IPv4' && !entry.internal) result.push(entry.address);
+ }
+ }
+ return result;
+}
+
+function suggestedUrls(config: RelayConfig): string[] {
+ if (!config.host.listenAll) return [];
+ return lanAddresses().map((address) => `http://${address}:${config.host.port}`);
+}
+
+/** 本机中转加入链接里写的地址:用户填的对外地址优先;监听所有网络时退回第一个局域网地址。 */
+function hostJoinBaseUrl(config: RelayConfig): string | null {
+ return config.host.externalUrl ?? suggestedUrls(config)[0] ?? null;
+}
+
+function localBaseUrl(port: number): string {
+ return `http://127.0.0.1:${port}`;
+}
+
+export function getState(): SelfHostedRelayState {
+ const config = readRelayConfig();
+ const relay = activeSelfHostedRelay();
+ const origin = activeRelayOrigin();
+ const issue = relay ? getDeviceLinkConnectionIssue() : null;
+ if (joinLink && joinLink.expiresAt < Date.now()) joinLink = null;
+ const bundled = bundledRelayVersion();
+ const deployment = config.deployment;
+ return {
+ available: authManager.getAuthState().isAuthenticated && secureStorageAvailable(),
+ mode: relay ? 'self-hosted' : 'official',
+ relay: relay && origin ? { name: relay.name, baseUrl: relay.baseUrl, role: relay.role, origin } : null,
+ issue: issue?.kind === 'device-removed' ? 'removed' : issue?.kind === 'auth-failed' ? 'unauthorized' : null,
+ host: {
+ enabled: config.host.enabled,
+ running: host !== null,
+ error: hostError,
+ port: config.host.port,
+ listenAll: config.host.listenAll,
+ externalUrl: config.host.externalUrl,
+ suggestedUrls: suggestedUrls(config),
+ },
+ deployment: deployment
+ ? {
+ sshHostId: deployment.sshHostId,
+ address: deployment.address,
+ baseUrl: deployment.baseUrl,
+ name: deployment.name,
+ relayVersion: deployment.complete ? deployment.relayVersion : '',
+ deployedAt: deployment.deployedAt,
+ active: relay?.relayId === deployment.relayId,
+ upgradeAvailable: Boolean(bundled && deployment.complete && bundled !== deployment.relayVersion),
+ }
+ : null,
+ deployJob,
+ bundledRelayVersion: bundled,
+ joinLink: joinLink ? { link: joinLink.link, expiresAt: new Date(joinLink.expiresAt).toISOString() } : null,
+ pendingRequests,
+ join,
+ };
+}
+
+// ─── 主人身份 ────────────────────────────────────────────────────────────────
+
+/** 新建一份主人身份:凭证与签名私钥只存本机安全存储。 */
+function createOwnerSecrets(relayId: string): RelaySecrets {
+ const secrets = { credential: createDeviceCredential().credential, seed: createRelaySigningKey(crypto).seed };
+ writeRelaySecrets(relayId, secrets);
+ return secrets;
+}
+
+/** 交给中转初始化的主人信息(哈希、公钥、自签证书),不含秘密。 */
+function ownerInitArgs(relayId: string, secrets: RelaySecrets, name: string) {
+ const ownerPublicKey = relayPublicKeyOf(crypto, secrets.seed)!;
+ const ownerDeviceId = authManager.getDeviceId();
+ return {
+ name,
+ relayId,
+ ownerUserId: authManager.getCurrentUserId() ?? '',
+ ownerDeviceId,
+ ownerDeviceName: deviceName().slice(0, 64) || 'Cindy',
+ ownerCredentialHash: hashSecret(secrets.credential),
+ ownerPublicKey,
+ ownerCert: issueRelayDeviceCert(crypto, secrets.seed, {
+ relayId,
+ deviceId: ownerDeviceId,
+ publicKey: ownerPublicKey,
+ role: 'owner',
+ issuedAt: Date.now(),
+ }),
+ };
+}
+
+// ─── 本机中转(主人) ─────────────────────────────────────────────────────────
+
+function stopPairing(): void {
+ stopPendingPolling();
+ joinLink = null;
+ pairSecrets = [];
+ pendingRequests = [];
+ pendingRaw = new Map();
+}
+
+async function stopHost(retire: boolean): Promise<void> {
+ if (activeRelayOrigin() === 'host') stopPairing();
+ const current = host;
+ host = null;
+ hostKey = null;
+ if (current) await current.close({ retire }).catch((error) => log.warn('relay host close failed', String(error)));
+}
+
+/**
+ * 准备本机中转的数据目录与主人身份。主人秘密丢失(钥匙串被清)或数据来自旧版本时重建中转,
+ * 已加入的设备需要重新加入。返回中转 ID。
+ */
+async function prepareHostData(dataDir: string, config: RelayConfig): Promise<string> {
+ const assertOwner = captureOwner();
+ const stateFile = `${dataDir}/relay-state.json`;
+ const existingId = config.host.relayId;
+ if (existingId && readRelaySecrets(existingId) && fs.existsSync(stateFile)) return existingId;
+ if (!authManager.getCurrentUserId()) throw new Error('NOT_SIGNED_IN');
+ fs.rmSync(dataDir, { recursive: true, force: true });
+ if (existingId) deleteRelaySecrets(existingId);
+ const relayId = randomUUID();
+ const secrets = createOwnerSecrets(relayId);
+ await initializeRelay({ dataDir, ...ownerInitArgs(relayId, secrets, deviceName().slice(0, 64) || 'Cindy') });
+ assertOwner();
+ writeRelayConfig({ ...readRelayConfig(), host: { ...config.host, relayId } });
+ return relayId;
+}
+
+async function startHost(config: RelayConfig): Promise<void> {
+ const assertOwner = captureOwner();
+ const key = `${config.host.port}:${config.host.listenAll}`;
+ if (host && hostKey === key) return;
+ await stopHost(false);
+ assertOwner();
+ hostError = null;
+ const dataDir = relayDataPath('host');
+ try {
+ await prepareHostData(dataDir, config);
+ assertOwner();
+ const started = await startRelayServer({
+ dataDir,
+ host: config.host.listenAll ? '0.0.0.0' : '127.0.0.1',
+ port: config.host.port,
+ // 只监听本机时,请求来自同机的前置代理,可以信任它给的外部地址。
+ trustProxyHeaders: !config.host.listenAll,
+ logger: {
+ info: (message, fields) => log.info(message, fields ?? {}),
+ warn: (message, fields) => log.warn(message, fields ?? {}),
+ error: (message, fields) => log.error(message, fields ?? {}),
+ },
+ });
+ try {
+ assertOwner();
+ } catch (error) {
+ await started.close({ retire: false });
+ throw error;
+ }
+ host = started;
+ hostKey = key;
+ log.info('relay host started', { port: host.port, listenAll: config.host.listenAll });
+ } catch (error) {
+ assertOwner();
+ if (error instanceof RelayOperationExpired) throw error;
+ host = null;
+ hostKey = null;
+ hostError = (error as NodeJS.ErrnoException)?.code === 'EADDRINUSE' ? 'PORT_IN_USE' : 'START_FAILED';
+ log.warn('relay host failed to start', { reason: hostError });
+ }
+}
+
+function ensureHost(): Promise<void> {
+ if (requireReady()) return Promise.resolve();
+ const config = readRelayConfig();
+ if (!config.host.enabled) return Promise.resolve();
+ if (!hostStarting) {
+ const assertOwner = captureOwner();
+ const starting = startHost(config).finally(() => {
+ if (hostStarting === starting) hostStarting = null;
+ assertOwner();
+ emitChanged();
+ });
+ hostStarting = starting;
+ }
+ return hostStarting;
+}
+
+// ─── 主人管理(本机中转与服务器中转共用) ─────────────────────────────────────
+
+/** 当前作为主人使用的中转的管理入口地址。 */
+function ownerBase(): { baseUrl: string; credential: string; relayId: string; seed: string; ownerPublicKey: string } | null {
+ const relay = activeSelfHostedRelay();
+ const origin = activeRelayOrigin();
+ if (!relay || relay.role !== 'owner') return null;
+ if (origin === 'host') {
+ if (!host) return null;
+ return { baseUrl: localBaseUrl(host.port), credential: relay.credential, relayId: relay.relayId, seed: relay.signingSeed, ownerPublicKey: relay.ownerPublicKey };
+ }
+ return { baseUrl: relay.baseUrl, credential: relay.credential, relayId: relay.relayId, seed: relay.signingSeed, ownerPublicKey: relay.ownerPublicKey };
+}
+
+async function ownerFetch(path: string, init: { method: string; body?: unknown } = { method: 'GET' }): Promise<unknown> {
+ const owner = ownerBase();
+ if (!owner) throw new Error('NOT_OWNER');
+ const res = await fetch(`${owner.baseUrl}/api/device-link${path}`, {
+ method: init.method,
+ headers: {
+ authorization: `CindyRelay ${owner.credential}`,
+ ...(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+ },
+ body: init.body === undefined ? undefined : JSON.stringify(init.body),
+ signal: AbortSignal.timeout(15_000),
+ });
+ const body = (await res.json().catch(() => null)) as unknown;
+ if (!res.ok) throw new Error(`relay admin request failed (${res.status})`);
+ return body;
+}
+
+/** 配对证明与这台电脑当前有效的某个加入链接对得上。 */
+function proofMatches(relayId: string, request: { deviceId: string; publicKey: string; proof: unknown }): boolean {
+ const now = Date.now();
+ pairSecrets = pairSecrets.filter((entry) => entry.expiresAt + JOIN_LINK_TTL_MS > now);
+ return pairSecrets.some(
+ (entry) => entry.relayId === relayId && verifyRelayPairProof(crypto, entry.secret, { relayId, ...request }),
+ );
+}
+
+async function refreshPendingRequests(): Promise<void> {
+ const assertOwner = captureOwner();
+ const owner = ownerBase();
+ if (!owner) return;
+ try {
+ const body = (await ownerFetch('/relay/admin/pair-requests')) as { requests?: unknown[] };
+ assertOwner();
+ if (ownerBase()?.relayId !== owner.relayId) return;
+ const raw = new Map<string, { deviceId: string; publicKey: string }>();
+ const next = (body.requests ?? []).flatMap((item): SelfHostedRelayPairRequestView[] => {
+ const r = item as Record<string, unknown>;
+ if (
+ typeof r.requestId !== 'string' ||
+ typeof r.deviceId !== 'string' ||
+ typeof r.deviceName !== 'string' ||
+ typeof r.verifyCode !== 'string' ||
+ typeof r.publicKey !== 'string'
+ ) {
+ return [];
+ }
+ raw.set(r.requestId, { deviceId: r.deviceId, publicKey: r.publicKey });
+ return [{
+ requestId: r.requestId,
+ deviceName: r.deviceName,
+ platform: typeof r.platform === 'string' ? r.platform : null,
+ verifyCode: r.verifyCode,
+ replacesExisting: r.replacesExisting === true,
+ verified: proofMatches(owner.relayId, { deviceId: r.deviceId, publicKey: r.publicKey, proof: r.proof }),
+ }];
+ });
+ pendingRaw = raw;
+ if (JSON.stringify(next) !== JSON.stringify(pendingRequests)) {
+ pendingRequests = next;
+ emitChanged();
+ }
+ } catch {
+ // 中转刚重启或暂时连不上:下一轮再试;停用时轮询会被一并停掉。
+ }
+}
+
+function startPendingPolling(): void {
+ stopPendingPolling();
+ pendingTimer = setInterval(() => {
+ if (!joinLink || joinLink.expiresAt < Date.now()) {
+ // 加入码过期后最后再看一次,让已经提交的申请仍能被处理完。
+ if (pendingRequests.length === 0) stopPendingPolling();
+ }
+ void refreshPendingRequests();
+ }, PENDING_POLL_MS);
+ pendingTimer.unref?.();
+}
+
+function stopPendingPolling(): void {
+ if (pendingTimer) clearInterval(pendingTimer);
+ pendingTimer = null;
+}
+
+async function createJoinLink(): Promise<CommandResult> {
+ const assertOwner = captureOwner();
+ const owner = ownerBase();
+ if (!owner) return { state: getState(), error: activeRelayOrigin() === 'host' ? 'START_FAILED' : 'NOT_OWNER' };
+ const base = activeRelayOrigin() === 'host' ? hostJoinBaseUrl(readRelayConfig()) : activeSelfHostedRelay()!.baseUrl;
+ if (!base) return { state: getState(), error: 'EXTERNAL_URL_REQUIRED' };
+ try {
+ const body = (await ownerFetch('/relay/admin/join-codes', { method: 'POST' })) as { code: string };
+ assertOwner();
+ if (ownerBase()?.relayId !== owner.relayId) return { state: getState(), error: 'NOT_OWNER' };
+ const pairSecret = createRelayPairSecret(crypto);
+ const expiresAt = Date.now() + JOIN_LINK_TTL_MS;
+ pairSecrets.push({ relayId: owner.relayId, secret: pairSecret, expiresAt });
+ joinLink = {
+ link: buildRelayJoinLink({
+ baseUrl: base,
+ code: body.code,
+ ownerPublicKey: owner.ownerPublicKey,
+ pairSecret,
+ app: providerShareLinkApp(),
+ }),
+ expiresAt,
+ };
+ pendingRequests = [];
+ startPendingPolling();
+ return { state: getState() };
+ } catch {
+ return { state: getState(), error: 'FAILED' };
+ }
+}
+
+async function decide(requestId: string, approve: boolean): Promise<CommandResult> {
+ const owner = ownerBase();
+ if (!owner) return { state: getState(), error: 'NOT_OWNER' };
+ const view = pendingRequests.find((request) => request.requestId === requestId);
+ const raw = pendingRaw.get(requestId);
+ let error: SelfHostedRelayErrorCode | undefined;
+ try {
+ if (approve) {
+ // 配对证明对不上:公钥不是拿着这台电脑给出的链接的那台设备生成的(可能被中转替换),不能签发证书。
+ if (!view?.verified || !raw) {
+ error = 'PAIR_PROOF_INVALID';
+ } else {
+ const cert = issueRelayDeviceCert(crypto, owner.seed, {
+ relayId: owner.relayId,
+ deviceId: raw.deviceId,
+ publicKey: raw.publicKey,
+ role: 'member',
+ issuedAt: Date.now(),
+ });
+ await ownerFetch(`/relay/admin/pair-requests/${requestId}/approve`, { method: 'POST', body: { cert } });
+ // 新设备拿到凭证后很快就会发消息:提前刷新证书,不让它的第一条消息被拒。
+ setTimeout(refreshRelayCertificatesSoon, 3_000).unref?.();
+ }
+ } else {
+ await ownerFetch(`/relay/admin/pair-requests/${requestId}/reject`, { method: 'POST' });
+ }
+ } catch {
+ // 申请可能已过期:刷新列表让界面反映真实状态。
+ }
+ await refreshPendingRequests();
+ return { state: getState(), error };
+}
+
+// ─── 命令 ────────────────────────────────────────────────────────────────────
+
+type CommandResult = { state: SelfHostedRelayState; error?: SelfHostedRelayErrorCode };
+
+function requireReady(): SelfHostedRelayErrorCode | null {
+ // 账号数据作用域提交之前不能读写中转配置(否则会落进临时命名空间)。
+ if (isAppSessionBoundaryPending() || !authManager.getAuthState().isAuthenticated || !getActiveAppSession().dataOwnerId) return 'NOT_SIGNED_IN';
+ if (!secureStorageAvailable()) return 'SECURE_STORAGE_UNAVAILABLE';
+ return null;
+}
+
+/** 成员退出所加入的中转(尽力而为,中转不可达也照样在本机切回),并删掉本机在它上面的秘密。 */
+async function leaveMemberRelay(): Promise<void> {
+ const assertOwner = captureOwner();
+ const relay = activeSelfHostedRelay();
+ if (relay?.role !== 'member') return;
+ try {
+ await fetch(`${relay.baseUrl}/api/device-link/devices/${encodeURIComponent(relay.deviceId)}`, {
+ method: 'DELETE',
+ headers: { authorization: `CindyRelay ${relay.credential}` },
+ signal: AbortSignal.timeout(5_000),
+ });
+ } catch {
+ log.info('could not notify the relay before leaving; switching locally');
+ }
+ assertOwner();
+ deleteRelaySecrets(relay.relayId);
+}
+
+/** 切换到另一个中转前收尾:成员退出;本机中转停掉(不通知成员停用,切回时还能接着用)。 */
+async function leaveCurrent(): Promise<void> {
+ const assertOwner = captureOwner();
+ cancelJoin();
+ await leaveMemberRelay();
+ assertOwner();
+ stopPairing();
+}
+
+async function enableHost(command: Extract<SelfHostedRelayCommand, { type: 'enable-host' }>): Promise<CommandResult> {
+ const assertOwner = captureOwner();
+ const notReady = requireReady();
+ if (notReady) return { state: getState(), error: notReady };
+ if (command.externalUrl && !/^https?:\/\/[^\s/?#]+(\/[^\s?#]*)?$/.test(command.externalUrl)) {
+ return { state: getState(), error: 'INVALID_LINK' };
+ }
+ await leaveCurrent();
+ assertOwner();
+ const previous = readRelayConfig();
+ const config: RelayConfig = {
+ ...previous,
+ active: null,
+ host: { ...previous.host, enabled: true, port: command.port, listenAll: command.listenAll, externalUrl: command.externalUrl },
+ };
+ writeRelayConfig(config);
+ await startHost(config);
+ assertOwner();
+ const relayId = readRelayConfig().host.relayId;
+ const secrets = relayId ? readRelaySecrets(relayId) : null;
+ if (!host || !relayId || !secrets) {
+ writeRelayConfig({ ...readRelayConfig(), host: { ...readRelayConfig().host, enabled: false }, active: null });
+ restartDeviceLinkForRelayChange();
+ return { state: getState(), error: hostError ?? 'START_FAILED' };
+ }
+ const relayInfo = (await fetch(`${localBaseUrl(host.port)}/api/device-link/relay/info`).then((r) => r.json())) as { name: string };
+ assertOwner();
+ writeRelayConfig({
+ ...readRelayConfig(),
+ active: {
+ relayId,
+ name: relayInfo.name,
+ baseUrl: localBaseUrl(host.port),
+ role: 'owner',
+ origin: 'host',
+ deviceId: authManager.getDeviceId(),
+ ownerPublicKey: relayPublicKeyOf(crypto, secrets.seed)!,
+ },
+ });
+ // 中转所在电脑一休眠,所有设备都会断开:开启时顺带打开「保持唤醒」。
+ if (!readDeviceLinkSettings().keepAwake) await setKeepAwakeEnabled(true).catch(() => undefined);
+ assertOwner();
+ restartDeviceLinkForRelayChange();
+ return { state: getState() };
+}
+
+async function useOfficial(): Promise<CommandResult> {
+ const assertOwner = captureOwner();
+ cancelJoin();
+ const config = readRelayConfig();
+ const origin = activeRelayOrigin();
+ if (origin === 'host' || config.host.enabled) await stopHost(true);
+ else await leaveMemberRelay();
+ assertOwner();
+ stopPairing();
+ if (requireReady() !== 'NOT_SIGNED_IN') {
+ writeRelayConfig({ ...readRelayConfig(), active: null, host: { ...readRelayConfig().host, enabled: false } });
+ }
+ restartDeviceLinkForRelayChange();
+ return { state: getState() };
+}
+
+function cancelJoin(): void {
+ joinAbort?.abort();
+ joinAbort = null;
+ if (join.status === 'connecting' || join.status === 'waiting') join = { status: 'idle' };
+}
+
+function startJoin(rawLink: string): CommandResult {
+ const assertOwner = captureOwner();
+ const notReady = requireReady();
+ if (notReady) return { state: getState(), error: notReady };
+ if (readRelayConfig().host.enabled) return { state: getState(), error: 'HOSTING' };
+ const link = parseRelayJoinLink(rawLink);
+ if (!link) return { state: getState(), error: 'INVALID_LINK' };
+ cancelJoin();
+ const abort = new AbortController();
+ joinAbort = abort;
+ join = { status: 'connecting' };
+ const accountUserId = authManager.getCurrentUserId();
+ const deviceId = authManager.getDeviceId();
+ void (async () => {
+ try {
+ const info = await fetchRelayInfo(relayFetch, link.baseUrl, abort.signal);
+ assertOwner();
+ if (abort.signal.aborted) return;
+ const identity = createRelayJoinIdentity(crypto, link, info.relayId, deviceId);
+ const request = await submitRelayPairRequest(
+ relayFetch,
+ link,
+ {
+ deviceId,
+ deviceName: deviceName(),
+ platform: process.platform,
+ appVersion: app.getVersion(),
+ accountUserId: accountUserId ?? '',
+ publicKey: identity.publicKey,
+ proof: identity.proof,
+ },
+ abort.signal,
+ );
+ assertOwner();
+ if (abort.signal.aborted) return;
+ join = { status: 'waiting', relayName: info.name, verifyCode: request.verifyCode };
+ emitChanged();
+ const result = await waitForRelayApproval(relayFetch, link, request, { signal: abort.signal });
+ assertOwner();
+ // 等待期间换了账号:凭证属于旧账号,不能写进新账号的配置。
+ if (abort.signal.aborted || authManager.getCurrentUserId() !== accountUserId) return;
+ // 证书必须出自链接里的主人、发给本机这把公钥;否则中转可能被人替换,不加入。
+ acceptRelayDeviceCert(crypto, link, { relayId: info.relayId, deviceId, publicKey: identity.publicKey, cert: result.cert });
+ // 之前加入的中转先退出(不能用 leaveCurrent:它会取消正在进行的这次加入)。
+ await leaveMemberRelay();
+ assertOwner();
+ if (abort.signal.aborted) return;
+ stopPairing();
+ writeRelaySecrets(info.relayId, { credential: result.credential, seed: identity.seed });
+ writeRelayConfig({
+ ...readRelayConfig(),
+ active: {
+ relayId: info.relayId,
+ name: info.name,
+ baseUrl: link.baseUrl,
+ role: 'member',
+ origin: 'join',
+ deviceId,
+ ownerPublicKey: link.ownerPublicKey,
+ },
+ });
+ join = { status: 'joined', relayName: info.name };
+ restartDeviceLinkForRelayChange();
+ } catch (error) {
+ if (abort.signal.aborted || error instanceof RelayOperationExpired) return;
+ join = { status: 'failed', error: error instanceof RelayJoinError ? error.code : 'FAILED' };
+ } finally {
+ if (joinAbort === abort) joinAbort = null;
+ emitChanged();
+ }
+ })();
+ return { state: getState() };
+}
+
+// ─── 部署到服务器 ────────────────────────────────────────────────────────────
+
+function deploymentActive(deployment: RelayDeployment): RelayConfig['active'] {
+ return {
+ relayId: deployment.relayId,
+ name: deployment.name,
+ baseUrl: deployment.baseUrl,
+ role: 'owner',
+ origin: 'server',
+ deviceId: authManager.getDeviceId(),
+ ownerPublicKey: deployment.ownerPublicKey,
+ };
+}
+
+function runDeployJob(action: SelfHostedRelayDeployJobView['action'], work: (onStep: (step: SelfHostedRelayDeployJobView['step']) => void, assertOwner: () => void) => Promise<void>): void {
+ const assertOwner = captureOwner();
+ const isCurrent = () => {
+ try { assertOwner(); return true; } catch { return false; }
+ };
+ deployJob = { action, step: 'connect', status: 'running' };
+ const onStep = (step: SelfHostedRelayDeployJobView['step']) => {
+ assertOwner();
+ if (deployJob?.status !== 'running') return;
+ deployJob = { ...deployJob, step };
+ emitChanged();
+ };
+ void work(onStep, assertOwner)
+ .then(() => {
+ if (!isCurrent()) return;
+ deployJob = { action, step: 'finish', status: 'done' };
+ })
+ .catch((error: unknown) => {
+ if (!isCurrent()) return;
+ const step = deployJob?.step ?? 'connect';
+ if (error instanceof RelayDeployError) {
+ deployJob = { action, step, status: 'failed', error: error.code, detail: error.detail };
+ } else {
+ log.warn('relay deployment failed', { reason: error instanceof Error ? error.name : 'unknown' });
+ deployJob = { action, step, status: 'failed', error: 'DEPLOY_FAILED', detail: error instanceof Error ? error.message.slice(0, 300) : undefined };
+ }
+ })
+ .finally(() => { if (isCurrent()) emitChanged(); });
+}
+
+/** 部署或升级。身份(中转 ID、主人秘密)跟着部署记录走:重试与升级都保留它。 */
+function deploy(input: { sshHostId: string; address: string; name: string; replaceExisting: boolean }, action: 'deploy' | 'upgrade'): CommandResult {
+ const notReady = requireReady();
+ if (notReady) return { state: getState(), error: notReady };
+ if (deployJob?.status === 'running') return { state: getState(), error: 'BUSY' };
+ if (!bundledRelayVersion()) return { state: getState(), error: 'BUNDLE_MISSING' };
+ const config = readRelayConfig();
+ const previous = config.deployment;
+ const reuse = previous && previous.sshHostId === input.sshHostId && !input.replaceExisting ? readRelaySecrets(previous.relayId) : null;
+ const relayId = reuse && previous ? previous.relayId : randomUUID();
+ const secrets = reuse ?? createOwnerSecrets(relayId);
+ let replacedActive = false;
+ if (previous && previous.relayId !== relayId) {
+ // 换了一台服务器(或清掉重来):旧身份作废。正在用旧中转时先切回官方,不留下指向已删秘密的配置。
+ replacedActive = config.active?.relayId === previous.relayId;
+ if (replacedActive) {
+ stopPairing();
+ config.active = null;
+ }
+ deleteRelaySecrets(previous.relayId);
+ }
+ const init = ownerInitArgs(relayId, secrets, input.name);
+ const baseUrl = relayBaseUrlForAddress(input.address);
+ const record: RelayDeployment = {
+ sshHostId: input.sshHostId,
+ address: input.address,
+ baseUrl,
+ relayId,
+ name: input.name,
+ ownerPublicKey: init.ownerPublicKey,
+ relayVersion: previous?.relayId === relayId ? previous.relayVersion : '',
+ deployedAt: new Date().toISOString(),
+ complete: false,
+ };
+ // 先记下身份再动服务器:中途失败后重试,用的还是已经写进服务器的这一份。
+ writeRelayConfig({ ...config, deployment: record });
+ if (replacedActive) restartDeviceLinkForRelayChange();
+ runDeployJob(action, async (onStep, assertOwner) => {
+ const { relayVersion } = await deployRelayToServer({
+ sshHostId: input.sshHostId,
+ address: input.address,
+ baseUrl,
+ replaceExisting: input.replaceExisting,
+ init,
+ preferMirror: providerShareLinkApp() === 'cindycn',
+ onStep,
+ assertCurrent: assertOwner,
+ });
+ onStep('finish');
+ const done: RelayDeployment = { ...record, relayVersion, deployedAt: new Date().toISOString(), complete: true };
+ // 改用服务器上的中转:本机中转停掉,加入的中转退出。
+ const before = readRelayConfig();
+ if (activeRelayOrigin() !== 'server' || activeSelfHostedRelay()?.relayId !== relayId) {
+ if (before.host.enabled) await stopHost(false);
+ assertOwner();
+ await leaveCurrent();
+ assertOwner();
+ }
+ writeRelayConfig({ ...readRelayConfig(), deployment: done, active: deploymentActive(done), host: { ...before.host, enabled: false } });
+ restartDeviceLinkForRelayChange();
+ });
+ return { state: getState() };
+}
+
+function upgradeDeployment(): CommandResult {
+ const deployment = readRelayConfig().deployment;
+ if (!deployment) return { state: getState(), error: 'NO_DEPLOYMENT' };
+ return deploy({ sshHostId: deployment.sshHostId, address: deployment.address, name: deployment.name, replaceExisting: false }, 'upgrade');
+}
+
+function uninstallDeployment(removeData: boolean): CommandResult {
+ const notReady = requireReady();
+ if (notReady) return { state: getState(), error: notReady };
+ if (deployJob?.status === 'running') return { state: getState(), error: 'BUSY' };
+ const deployment = readRelayConfig().deployment;
+ if (!deployment) return { state: getState(), error: 'NO_DEPLOYMENT' };
+ runDeployJob('uninstall', async (onStep, assertOwner) => {
+ await uninstallRelayFromServer(deployment.sshHostId, removeData, onStep, assertOwner);
+ onStep('finish');
+ forgetDeploymentLocally(deployment, removeData);
+ });
+ return { state: getState() };
+}
+
+/** 本机删掉部署记录;保留数据时也保留身份,之后在同一台服务器重新部署可接着用已加入的设备。 */
+function forgetDeploymentLocally(deployment: RelayDeployment, removeIdentity: boolean): void {
+ const config = readRelayConfig();
+ const wasActive = config.active?.relayId === deployment.relayId;
+ if (wasActive) stopPairing();
+ if (removeIdentity) deleteRelaySecrets(deployment.relayId);
+ writeRelayConfig({
+ ...config,
+ active: wasActive ? null : config.active,
+ deployment: removeIdentity ? null : { ...deployment, complete: false },
+ });
+ if (wasActive) restartDeviceLinkForRelayChange();
+}
+
+async function useDeployment(): Promise<CommandResult> {
+ const assertOwner = captureOwner();
+ const notReady = requireReady();
+ if (notReady) return { state: getState(), error: notReady };
+ const config = readRelayConfig();
+ const deployment = config.deployment;
+ if (!deployment?.complete || !readRelaySecrets(deployment.relayId)) return { state: getState(), error: 'NO_DEPLOYMENT' };
+ if (config.host.enabled) await stopHost(false);
+ assertOwner();
+ await leaveCurrent();
+ assertOwner();
+ writeRelayConfig({ ...readRelayConfig(), active: deploymentActive(deployment), host: { ...readRelayConfig().host, enabled: false } });
+ restartDeviceLinkForRelayChange();
+ return { state: getState() };
+}
+
+async function execute(command: SelfHostedRelayCommand): Promise<CommandResult> {
+ switch (command.type) {
+ case 'state':
+ return { state: getState() };
+ case 'enable-host':
+ return enableHost(command);
+ case 'disable-host':
+ case 'use-official':
+ return useOfficial();
+ case 'create-join-link':
+ return createJoinLink();
+ case 'decide':
+ return decide(command.requestId, command.approve);
+ case 'join':
+ return startJoin(command.link);
+ case 'cancel-join':
+ cancelJoin();
+ join = { status: 'idle' };
+ return { state: getState() };
+ case 'deploy':
+ return deploy(command, 'deploy');
+ case 'upgrade-deployment':
+ return upgradeDeployment();
+ case 'uninstall-deployment':
+ return uninstallDeployment(command.removeData);
+ case 'forget-deployment': {
+ const deployment = readRelayConfig().deployment;
+ if (!deployment) return { state: getState(), error: 'NO_DEPLOYMENT' };
+ if (deployJob?.status === 'running') return { state: getState(), error: 'BUSY' };
+ forgetDeploymentLocally(deployment, true);
+ deployJob = null;
+ return { state: getState() };
+ }
+ case 'use-deployment':
+ return useDeployment();
+ }
+}
+
+export function registerSelfHostedRelayIpc(): void {
+ // 先登记中转来源:之后 device-link 每次建连都按当前账号的选择走官方或自建中转。
+ installSelfHostedRelayRouting();
+ ipcMain.handle(SELF_HOSTED_RELAY_IPC.COMMAND, async (event, raw: unknown) => {
+ // 账号级本机设置:只接受本机应用窗口,不经设备互联代理。
+ if (getDeviceLinkInvokeContext()) throwIpcError('PERMISSION_DENIED', 'Self-hosted relay settings are local only');
+ assertTrustedAppRendererEvent(event);
+ const command = parseSelfHostedRelayCommand(raw);
+ if (!command) throwIpcError('INVALID_PARAMS', 'Invalid self-hosted relay command');
+ let result: CommandResult;
+ try {
+ result = await execute(command);
+ } catch (error) {
+ if (!(error instanceof RelayOperationExpired)) throw error;
+ return { state: getState(), error: 'NOT_SIGNED_IN' };
+ }
+ if (command.type !== 'state') emitChanged();
+ return result;
+ });
+
+ // 登录后按设置拉起本机中转;登出 / 换账号时停掉(中转属于开启它的账号)。
+ // 登录态与账号数据作用域分两步就绪:作用域还没提交时短暂重试,不在临时命名空间里启动。
+ let lastKey: string | null = null;
+ let retryTimer: ReturnType<typeof setTimeout> | null = null;
+ let retries = 0;
+ const sync = () => {
+ if (retryTimer) clearTimeout(retryTimer);
+ retryTimer = null;
+ const authenticated = authManager.getAuthState().isAuthenticated;
+ const ownerId = getActiveAppSession().dataOwnerId;
+ if (authenticated && !ownerId && retries++ < 30) {
+ retryTimer = setTimeout(sync, 1_000);
+ retryTimer.unref?.();
+ return;
+ }
+ retries = 0;
+ const key = authenticated && ownerId ? activeOwnerScopeKey() : null;
+ if (key === lastKey) return;
+ lastKey = key;
+ ownerEpoch += 1;
+ cancelJoin();
+ join = { status: 'idle' };
+ stopPairing();
+ deployJob = null;
+ hostStarting = null;
+ const assertOwner = captureOwner();
+ void stopHost(false).then(() => {
+ assertOwner();
+ return key ? ensureHost() : undefined;
+ }).then(() => { assertOwner(); emitChanged(); }).catch((error: unknown) => {
+ if (!(error instanceof RelayOperationExpired)) log.warn('relay owner synchronization failed');
+ });
+ };
+ sync();
+ authManager.onAuthStateChange(sync);
+ onAppSessionInvalidated(() => {
+ ownerEpoch += 1;
+ cancelJoin();
+ stopPairing();
+ deployJob = null;
+ setTimeout(sync, 0);
+ });
+ app.on('before-quit', () => {
+ void stopHost(false);
+ });
+}
diff --git a/apps/desktop/src/main/remote-desktop/iceConfig.ts b/apps/desktop/src/main/remote-desktop/iceConfig.ts
index 2bc66a5ede..65d45b2d75 100644
--- a/apps/desktop/src/main/remote-desktop/iceConfig.ts
+++ b/apps/desktop/src/main/remote-desktop/iceConfig.ts
@@ -3,13 +3,12 @@ import {
REMOTE_DESKTOP_ICE_CONFIG_TIMEOUT_MS,
resolveDesktopIceServers,
} from '@cindy/device-link';
-import { getClientEndpoint } from '../clientEndpointsService.js';
-import { serverApiFetch } from '../serverApiClient.js';
+import { deviceLinkApiFetch } from '../device-link/deviceLinkApi.js';
export function loadDesktopIceServers() {
return resolveDesktopIceServers(() =>
- serverApiFetch(REMOTE_DESKTOP_ICE_CONFIG_PATH, {
- baseUrl: () => getClientEndpoint('deviceLinkApiBaseUrl'),
+ // 自建中转不提供 TURN(返回 404),按既有逻辑退回公共 STUN。
+ deviceLinkApiFetch(REMOTE_DESKTOP_ICE_CONFIG_PATH, {
timeoutMs: REMOTE_DESKTOP_ICE_CONFIG_TIMEOUT_MS,
cache: 'no-store',
redactErrorDetails: true,
diff --git a/apps/desktop/src/main/serverApiClient.ts b/apps/desktop/src/main/serverApiClient.ts
index 86e0bc903d..cb2b9055b6 100644
--- a/apps/desktop/src/main/serverApiClient.ts
+++ b/apps/desktop/src/main/serverApiClient.ts
@@ -44,6 +44,12 @@ export interface ApiFetchOptions {
cache?: RequestCache;
/** 显式传 token;不传则取 authManager.getAccessToken()。 */
token?: string | null;
+ /**
+ * 完整的 Authorization 头(如自建中转的 `CindyRelay <凭证>`)。提供时不注入 Cindy 账号
+ * token,调用方还应同时设置 skipAutoRefresh / skipSessionInvalidation,避免对方的 401
+ * 牵连官方登录态。
+ */
+ authorization?: string;
/** 跳过 401 自动 refresh(避免无限循环;refresh 自身调用时禁用)。 */
skipAutoRefresh?: boolean;
/** Fixed-identity teardown requests must not invalidate a newer active account. */
@@ -90,9 +96,13 @@ async function rawFetch<T>(apiPath: string, opts: ApiFetchOptions): Promise<RawR
'Accept-Language': getResolvedMainLocale(),
...(opts.headers ?? {}),
};
- const token = opts.token !== undefined ? opts.token : authManager.getAccessToken();
- if (token) {
- headers['Authorization'] = 'Bearer ' + token;
+ if (opts.authorization !== undefined) {
+ headers['Authorization'] = opts.authorization;
+ } else {
+ const token = opts.token !== undefined ? opts.token : authManager.getAccessToken();
+ if (token) {
+ headers['Authorization'] = 'Bearer ' + token;
+ }
}
const timeoutMs = opts.timeoutMs ?? 0;
const controller = timeoutMs > 0 ? new AbortController() : null;
diff --git a/apps/desktop/src/preload/preload.ts b/apps/desktop/src/preload/preload.ts
index 096ebd7ed1..9157fb7cb6 100644
--- a/apps/desktop/src/preload/preload.ts
+++ b/apps/desktop/src/preload/preload.ts
@@ -37,6 +37,7 @@ import {
import { contextBridge, ipcRenderer, webUtils } from 'electron';
import { createChatFolderUpload } from './chatFolderUpload';
import { DESKTOP_LOCAL, type RemoteDesktopApi } from '../shared/remoteDesktop';
+import { SELF_HOSTED_RELAY_IPC, type SelfHostedRelayApi } from '../shared/selfHostedRelay';
import { DEVICE_LINK_PUSH } from '../shared/deviceLinkIpc';
import { PROVIDER_SHARE_IPC, type ProviderShareCommand } from '../shared/providerShare';
import { PROVIDER_GROUP_IPC, type ProviderGroupCommand } from '../shared/providerGroup';
@@ -897,6 +898,7 @@ const fanOutProviderShareSettled = createIpcFanOut(PROVIDER_SHARE_IPC.SETTLED);
const fanOutProviderShareOpenJoin = createIpcFanOut(PROVIDER_SHARE_IPC.OPEN_JOIN);
const fanOutProviderShareOpenManage = createIpcFanOut(PROVIDER_SHARE_IPC.OPEN_MANAGE);
const fanOutProviderShareReshareRequested = createIpcFanOut(PROVIDER_SHARE_IPC.RESHARE_REQUESTED);
+const fanOutSelfHostedRelayChanged = createIpcFanOut(SELF_HOSTED_RELAY_IPC.CHANGED);
const fanOutDeviceLinkOwnershipChanged = createIpcFanOut('device-link:ownership-changed');
// 控制端:目标设备「无响应」熔断状态翻转(payload = { deviceId, unresponsive })
const fanOutDeviceLinkResponsivenessChanged = createIpcFanOut('device-link:responsiveness-changed');
@@ -4844,6 +4846,11 @@ contextBridge.exposeInMainWorld('electronAPI', {
windowsSupport: (enabled) => ipcRenderer.invoke(DESKTOP_LOCAL.WINDOWS_SUPPORT, enabled),
stop: () => ipcRenderer.invoke(DESKTOP_LOCAL.STOP),
} satisfies RemoteDesktopApi,
+ // 自建中转服务:本机中转与加入别的中转(只接受本机应用窗口)。
+ selfHostedRelay: {
+ command: (command) => ipcRenderer.invoke(SELF_HOSTED_RELAY_IPC.COMMAND, command),
+ onChanged: fanOutSelfHostedRelayChanged as SelfHostedRelayApi['onChanged'],
+ } satisfies SelfHostedRelayApi,
sharedTask: {
host: (command: import('@cindy/device-link').SharedTaskHostCommand): Promise<unknown> =>
ipcRenderer.invoke('maker:shared-task', command),
diff --git a/apps/desktop/src/renderer/components/settings/RelayServicePanel.tsx b/apps/desktop/src/renderer/components/settings/RelayServicePanel.tsx
new file mode 100644
index 0000000000..45b6a68680
--- /dev/null
+++ b/apps/desktop/src/renderer/components/settings/RelayServicePanel.tsx
@@ -0,0 +1,780 @@
+/**
+ * 「远程连接 → 中转服务」:选择设备之间经 Cindy 官方中转,还是用户自己的中转
+ * (这台电脑当中转 / 部署到自己的服务器 / 加入别的中转)。方案见 docs/self-hosted-relay-plan.md。
+ *
+ * 状态以 main 为准(`window.electronAPI.selfHostedRelay`):命令返回最新状态,另有 CHANGED 推送;
+ * 连接问题(被移出中转)来自 device-link 链路,低频轮询兜底。
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import * as QRCode from 'qrcode';
+
+import { Button } from '@/components/ui/button';
+import { useOptionalConfirmDialog } from '@/components/ui/confirm-dialog-provider';
+import { Input } from '@/components/ui/input';
+import { SegmentedControl } from '@/components/ui/segmented-control';
+import { Select } from '@/components/ui/select';
+import { toast } from '@/lib/toast';
+import {
+ DEFAULT_RELAY_PORT,
+ normalizeRelayAddress,
+ RELAY_DEPLOY_STEPS,
+ type SelfHostedRelayCommand,
+ type SelfHostedRelayDeployJobView,
+ type SelfHostedRelayErrorCode,
+ type SelfHostedRelayState,
+} from '../../../shared/selfHostedRelay';
+
+const STATE_POLL_MS = 3_000;
+
+export function useSelfHostedRelayState(enabled: boolean) {
+ const [state, setState] = useState<SelfHostedRelayState | null>(null);
+ const [error, setError] = useState<SelfHostedRelayErrorCode | null>(null);
+ const [busy, setBusy] = useState(false);
+
+ useEffect(() => {
+ const api = window.electronAPI?.selfHostedRelay;
+ if (!enabled || !api) return;
+ let active = true;
+ const refresh = () => {
+ void api
+ .command({ type: 'state' })
+ .then((result) => {
+ if (active) setState(result.state);
+ })
+ .catch(() => undefined);
+ };
+ refresh();
+ const off = api.onChanged((next) => {
+ if (active) setState(next);
+ });
+ const timer = setInterval(refresh, STATE_POLL_MS);
+ return () => {
+ active = false;
+ off();
+ clearInterval(timer);
+ };
+ }, [enabled]);
+
+ const run = useCallback(async (command: SelfHostedRelayCommand): Promise<boolean> => {
+ const api = window.electronAPI?.selfHostedRelay;
+ if (!api) return false;
+ setBusy(true);
+ setError(null);
+ try {
+ const result = await api.command(command);
+ setState(result.state);
+ if (result.error) setError(result.error);
+ return !result.error;
+ } catch {
+ setError('FAILED');
+ return false;
+ } finally {
+ setBusy(false);
+ }
+ }, []);
+
+ return { state, error, busy, run, clearError: () => setError(null) };
+}
+
+export type SelfHostedRelayController = ReturnType<typeof useSelfHostedRelayState>;
+
+/** 收起态摘要:官方 / 本机中转 / 已加入的中转名。 */
+export function relaySummary(
+ state: SelfHostedRelayState | null,
+ t: (key: string, options?: Record<string, unknown>) => string,
+): string | null {
+ if (!state) return null;
+ if (state.mode === 'official' || !state.relay) return t('settings.remoteControl.relay.summary.official');
+ if (state.relay.origin === 'host') return t('settings.remoteControl.relay.summary.owner');
+ if (state.relay.origin === 'server') return t('settings.remoteControl.relay.summary.server', { name: state.relay.name });
+ return t('settings.remoteControl.relay.summary.member', { name: state.relay.name });
+}
+
+function Card({ children }: { children: React.ReactNode }) {
+ return <section className="flex flex-col gap-3 rounded-lg bg-[var(--settings-input-bg)] p-3">{children}</section>;
+}
+
+function Hint({ children }: { children: React.ReactNode }) {
+ return <p className="text-12 leading-[1.5] text-[var(--text-tertiary)]">{children}</p>;
+}
+
+function ErrorText({ children }: { children: React.ReactNode }) {
+ return (
+ <p role="alert" className="text-12 leading-[1.5] text-[var(--error-fg)]">
+ {children}
+ </p>
+ );
+}
+
+function HostForm({
+ state,
+ controller,
+ onDone,
+}: {
+ state: SelfHostedRelayState;
+ controller: SelfHostedRelayController;
+ onDone: () => void;
+}) {
+ const { t } = useTranslation();
+ const [port, setPort] = useState(String(state.host.port || DEFAULT_RELAY_PORT));
+ const [scope, setScope] = useState<'local' | 'all'>(state.host.listenAll ? 'all' : 'local');
+ const [externalUrl, setExternalUrl] = useState(state.host.externalUrl ?? '');
+ const portNumber = Number(port);
+ const portValid = Number.isInteger(portNumber) && portNumber >= 1024 && portNumber <= 65535;
+ const k = 'settings.remoteControl.relay.host';
+ return (
+ <Card>
+ <div className="flex flex-col gap-1">
+ <p className="text-13 font-medium text-[var(--text-primary)]">{t(`${k}.title`)}</p>
+ <Hint>{t(`${k}.hint`)}</Hint>
+ </div>
+ <label className="flex items-center justify-between gap-4">
+ <span className="text-13 text-[var(--text-primary)]">{t(`${k}.port`)}</span>
+ <Input
+ value={port}
+ onChange={setPort}
+ inputMode="numeric"
+ size="sm"
+ className="w-28"
+ error={!portValid}
+ ariaLabel={t(`${k}.port`)}
+ />
+ </label>
+ <div className="flex flex-col gap-2">
+ <div className="flex items-center justify-between gap-4">
+ <span className="text-13 text-[var(--text-primary)]">{t(`${k}.scope`)}</span>
+ <SegmentedControl
+ aria-label={t(`${k}.scope`)}
+ value={scope}
+ onValueChange={setScope}
+ options={[
+ { value: 'local', label: t(`${k}.scopeLocal`) },
+ { value: 'all', label: t(`${k}.scopeAll`) },
+ ]}
+ />
+ </div>
+ <Hint>{t(scope === 'all' ? `${k}.scopeAllHint` : `${k}.scopeLocalHint`)}</Hint>
+ </div>
+ <div className="flex flex-col gap-2">
+ <span className="text-13 text-[var(--text-primary)]">{t(`${k}.externalUrl`)}</span>
+ <Input
+ value={externalUrl}
+ onChange={setExternalUrl}
+ placeholder={t(`${k}.externalUrlPlaceholder`)}
+ size="sm"
+ mono
+ ariaLabel={t(`${k}.externalUrl`)}
+ />
+ <Hint>{t(scope === 'all' ? `${k}.externalUrlHintAll` : `${k}.externalUrlHintLocal`)}</Hint>
+ {state.host.suggestedUrls.length > 0 ? (
+ <Hint>
+ {t(`${k}.suggested`)} <span className="font-mono">{state.host.suggestedUrls.join(' ')}</span>
+ </Hint>
+ ) : null}
+ </div>
+ <div className="flex justify-end gap-2">
+ <Button variant="secondary" size="sm" onClick={onDone} disabled={controller.busy}>
+ {t(`${k}.cancel`)}
+ </Button>
+ <Button
+ size="sm"
+ loading={controller.busy}
+ disabled={!portValid || controller.busy}
+ onClick={() => {
+ void controller
+ .run({
+ type: 'enable-host',
+ port: portNumber,
+ listenAll: scope === 'all',
+ externalUrl: externalUrl.trim() || null,
+ })
+ .then((ok) => {
+ if (ok) onDone();
+ });
+ }}
+ >
+ {t(state.host.enabled ? `${k}.save` : `${k}.start`)}
+ </Button>
+ </div>
+ </Card>
+ );
+}
+
+function AddDevice({ state, controller }: { state: SelfHostedRelayState; controller: SelfHostedRelayController }) {
+ const { t } = useTranslation();
+ const [qr, setQr] = useState<string | null>(null);
+ const link = state.joinLink?.link ?? null;
+ const k = 'settings.remoteControl.relay.add';
+
+ useEffect(() => {
+ if (!link) {
+ setQr(null);
+ return;
+ }
+ let active = true;
+ void QRCode.toDataURL(link, { margin: 2, width: 200 }).then((url) => {
+ if (active) setQr(url);
+ });
+ return () => {
+ active = false;
+ };
+ }, [link]);
+
+ return (
+ <div className="flex flex-col gap-3 border-t border-[var(--border-default)] pt-3">
+ {link ? (
+ <>
+ <Hint>{t(`${k}.hint`)}</Hint>
+ <div className="flex items-start gap-4">
+ {qr ? (
+ <img src={qr} alt={t(`${k}.qrAlt`)} className="h-[160px] w-[160px] shrink-0 rounded-md" />
+ ) : (
+ <div className="h-[160px] w-[160px] shrink-0 rounded-md bg-[var(--surface-elevated)]" />
+ )}
+ <div className="flex min-w-0 flex-col gap-2">
+ <p className="break-all font-mono text-12 text-[var(--text-secondary)]">{link}</p>
+ <div className="flex gap-2">
+ <Button
+ variant="secondary"
+ size="sm"
+ onClick={() => {
+ void navigator.clipboard.writeText(link).then(() => toast.success(t(`${k}.copied`)));
+ }}
+ >
+ {t(`${k}.copy`)}
+ </Button>
+ <Button variant="secondary" size="sm" disabled={controller.busy} onClick={() => void controller.run({ type: 'create-join-link' })}>
+ {t(`${k}.newLink`)}
+ </Button>
+ </div>
+ </div>
+ </div>
+ {state.pendingRequests.length === 0 ? <Hint>{t(`${k}.waiting`)}</Hint> : null}
+ </>
+ ) : (
+ <div className="flex items-center justify-between gap-4">
+ <Hint>{t(`${k}.intro`)}</Hint>
+ <Button size="sm" disabled={controller.busy} onClick={() => void controller.run({ type: 'create-join-link' })}>
+ {t(`${k}.create`)}
+ </Button>
+ </div>
+ )}
+ {state.pendingRequests.map((request) => (
+ <div
+ key={request.requestId}
+ className="flex items-center justify-between gap-4 rounded-md border border-[var(--border-default)] p-3"
+ >
+ <div className="flex min-w-0 flex-col gap-1">
+ <p className="truncate text-13 font-medium text-[var(--text-primary)]">
+ {t('settings.remoteControl.relay.requests.item', { name: request.deviceName })}
+ </p>
+ <p className="text-13 text-[var(--text-primary)]">
+ {t('settings.remoteControl.relay.requests.verify')}{' '}
+ <span className="font-mono text-16 font-medium tracking-[0.2em]">{request.verifyCode}</span>
+ </p>
+ {request.verified ? (
+ <Hint>
+ {t('settings.remoteControl.relay.requests.verifyHint')}
+ {request.replacesExisting ? ` ${t('settings.remoteControl.relay.requests.replaces')}` : ''}
+ </Hint>
+ ) : (
+ <ErrorText>{t('settings.remoteControl.relay.requests.unverified')}</ErrorText>
+ )}
+ </div>
+ <div className="flex shrink-0 gap-2">
+ <Button
+ variant="secondary"
+ size="sm"
+ disabled={controller.busy}
+ onClick={() => void controller.run({ type: 'decide', requestId: request.requestId, approve: false })}
+ >
+ {t('settings.remoteControl.relay.requests.reject')}
+ </Button>
+ <Button
+ size="sm"
+ disabled={controller.busy || !request.verified}
+ onClick={() => void controller.run({ type: 'decide', requestId: request.requestId, approve: true })}
+ >
+ {t('settings.remoteControl.relay.requests.approve')}
+ </Button>
+ </div>
+ </div>
+ ))}
+ </div>
+ );
+}
+
+function JoinForm({
+ state,
+ controller,
+ onDone,
+}: {
+ state: SelfHostedRelayState;
+ controller: SelfHostedRelayController;
+ onDone: () => void;
+}) {
+ const { t } = useTranslation();
+ const [link, setLink] = useState('');
+ const k = 'settings.remoteControl.relay.join';
+ const join = state.join;
+ const inProgress = join.status === 'connecting' || join.status === 'waiting';
+ return (
+ <Card>
+ <div className="flex flex-col gap-1">
+ <p className="text-13 font-medium text-[var(--text-primary)]">{t(`${k}.title`)}</p>
+ <Hint>{t(`${k}.hint`)}</Hint>
+ </div>
+ {join.status === 'waiting' ? (
+ <div className="flex flex-col gap-2">
+ <p className="text-13 text-[var(--text-primary)]">{t(`${k}.waiting`, { name: join.relayName })}</p>
+ <p className="font-mono text-24 font-medium tracking-[0.3em] text-[var(--text-primary)]">{join.verifyCode}</p>
+ </div>
+ ) : join.status === 'connecting' ? (
+ <Hint>{t(`${k}.connecting`)}</Hint>
+ ) : (
+ <Input
+ value={link}
+ onChange={setLink}
+ placeholder={t(`${k}.placeholder`)}
+ size="sm"
+ mono
+ ariaLabel={t(`${k}.placeholder`)}
+ />
+ )}
+ {join.status === 'failed' ? <ErrorText>{t(`settings.remoteControl.relay.errors.${join.error}`)}</ErrorText> : null}
+ <div className="flex justify-end gap-2">
+ <Button
+ variant="secondary"
+ size="sm"
+ onClick={() => {
+ if (inProgress) void controller.run({ type: 'cancel-join' });
+ onDone();
+ }}
+ >
+ {t(`${k}.cancel`)}
+ </Button>
+ {!inProgress ? (
+ <Button
+ size="sm"
+ disabled={!link.trim() || controller.busy}
+ onClick={() => void controller.run({ type: 'join', link: link.trim() })}
+ >
+ {t(`${k}.submit`)}
+ </Button>
+ ) : null}
+ </div>
+ </Card>
+ );
+}
+
+type SshHostOption = { id: string; label: string; hostname: string };
+
+function useSshHosts(enabled: boolean): SshHostOption[] | null {
+ const [hosts, setHosts] = useState<SshHostOption[] | null>(null);
+ useEffect(() => {
+ if (!enabled) return;
+ let active = true;
+ void window.electronAPI.remoteSsh
+ .list()
+ .then((res) => {
+ if (!active) return;
+ setHosts(
+ res.hosts.map((host) => ({
+ id: host.config.id,
+ label: host.config.displayName || host.config.id,
+ hostname: host.config.hostname,
+ })),
+ );
+ })
+ .catch(() => {
+ if (active) setHosts([]);
+ });
+ return () => {
+ active = false;
+ };
+ }, [enabled]);
+ return hosts;
+}
+
+function DeployForm({
+ state,
+ controller,
+ onDone,
+}: {
+ state: SelfHostedRelayState;
+ controller: SelfHostedRelayController;
+ onDone: () => void;
+}) {
+ const { t } = useTranslation();
+ const k = 'settings.remoteControl.relay.deploy';
+ const hosts = useSshHosts(true);
+ const previous = state.deployment;
+ const [hostId, setHostId] = useState(previous?.sshHostId ?? '');
+ const [address, setAddress] = useState(previous?.address ?? '');
+ const [name, setName] = useState(previous?.name ?? t(`${k}.defaultName`));
+ const [addressTouched, setAddressTouched] = useState(Boolean(previous));
+
+ // 选服务器时,访问地址默认取 SSH 主机地址(是 IP 或域名时),用户可以改。
+ useEffect(() => {
+ if (!hosts || hosts.length === 0) return;
+ const selected = hosts.find((host) => host.id === hostId) ?? hosts[0];
+ if (!hostId) setHostId(selected.id);
+ if (!addressTouched) setAddress(normalizeRelayAddress(selected.hostname) ?? '');
+ }, [hosts, hostId, addressTouched]);
+
+ const normalized = normalizeRelayAddress(address);
+ const canSubmit = Boolean(hostId && normalized && name.trim()) && !controller.busy;
+ return (
+ <Card>
+ <div className="flex flex-col gap-1">
+ <p className="text-13 font-medium text-[var(--text-primary)]">{t(`${k}.title`)}</p>
+ <Hint>{t(`${k}.hint`)}</Hint>
+ <Hint>{t(`${k}.requirements`)}</Hint>
+ </div>
+ {hosts && hosts.length === 0 ? (
+ <Hint>{t(`${k}.noHosts`)}</Hint>
+ ) : (
+ <>
+ <label className="flex items-center justify-between gap-4">
+ <span className="text-13 text-[var(--text-primary)]">{t(`${k}.server`)}</span>
+ <Select
+ label={t(`${k}.server`)}
+ value={hostId}
+ className="w-56"
+ truncateOptions
+ disabled={!hosts}
+ onValueChange={(value) => {
+ setHostId(value);
+ setAddressTouched(false);
+ }}
+ options={(hosts ?? []).map((host) => ({ value: host.id, label: host.label }))}
+ />
+ </label>
+ <div className="flex flex-col gap-2">
+ <span className="text-13 text-[var(--text-primary)]">{t(`${k}.address`)}</span>
+ <Input
+ value={address}
+ onChange={(value) => {
+ setAddress(value);
+ setAddressTouched(true);
+ }}
+ placeholder={t(`${k}.addressPlaceholder`)}
+ size="sm"
+ mono
+ error={Boolean(address.trim()) && !normalized}
+ ariaLabel={t(`${k}.address`)}
+ />
+ <Hint>{t(`${k}.addressHint`)}</Hint>
+ </div>
+ <label className="flex items-center justify-between gap-4">
+ <span className="text-13 text-[var(--text-primary)]">{t(`${k}.name`)}</span>
+ <Input value={name} onChange={setName} size="sm" className="w-56" ariaLabel={t(`${k}.name`)} />
+ </label>
+ </>
+ )}
+ <div className="flex justify-end gap-2">
+ <Button variant="secondary" size="sm" onClick={onDone} disabled={controller.busy}>
+ {t(`${k}.cancel`)}
+ </Button>
+ <Button
+ size="sm"
+ disabled={!canSubmit}
+ onClick={() => {
+ void controller
+ .run({ type: 'deploy', sshHostId: hostId, address: normalized!, name: name.trim(), replaceExisting: false })
+ .then((ok) => {
+ if (ok) onDone();
+ });
+ }}
+ >
+ {t(`${k}.submit`)}
+ </Button>
+ </div>
+ </Card>
+ );
+}
+
+function DeployProgress({
+ job,
+ state,
+ controller,
+}: {
+ job: SelfHostedRelayDeployJobView;
+ state: SelfHostedRelayState;
+ controller: SelfHostedRelayController;
+}) {
+ const { t } = useTranslation();
+ const k = 'settings.remoteControl.relay.deploy';
+ const steps = job.action === 'uninstall' ? (['connect', 'configure', 'finish'] as const) : RELAY_DEPLOY_STEPS;
+ const currentIndex = steps.indexOf(job.step as (typeof steps)[number]);
+ const deployment = state.deployment;
+ const retry = (replaceExisting: boolean) => {
+ if (!deployment) return;
+ void controller.run(
+ job.action === 'upgrade' && !replaceExisting
+ ? { type: 'upgrade-deployment' }
+ : { type: 'deploy', sshHostId: deployment.sshHostId, address: deployment.address, name: deployment.name, replaceExisting },
+ );
+ };
+ return (
+ <Card>
+ <p className="text-13 font-medium text-[var(--text-primary)]">
+ {t(job.status === 'done' ? `${k}.done.${job.action}` : `${k}.running.${job.action}`, {
+ version: state.bundledRelayVersion ?? '',
+ })}
+ </p>
+ {job.status !== 'done' ? (
+ <ol className="flex flex-col gap-1.5">
+ {steps.map((step, index) => {
+ const done = index < currentIndex || job.status === 'done';
+ const current = index === currentIndex;
+ const failed = current && job.status === 'failed';
+ return (
+ <li key={step} className="flex items-center gap-2 text-13">
+ <span
+ aria-hidden
+ className={
+ failed
+ ? 'h-2 w-2 rounded-full bg-[var(--error-fg)]'
+ : done
+ ? 'h-2 w-2 rounded-full bg-[var(--text-secondary)]'
+ : current
+ ? 'h-2 w-2 rounded-full motion-safe:animate-pulse bg-[var(--text-primary)]'
+ : 'h-2 w-2 rounded-full border border-[var(--border-default)]'
+ }
+ />
+ <span className={done || current ? 'text-[var(--text-primary)]' : 'text-[var(--text-tertiary)]'}>
+ {t(`${k}.steps.${job.action === 'uninstall' && step === 'configure' ? 'remove' : step}`)}
+ </span>
+ </li>
+ );
+ })}
+ </ol>
+ ) : null}
+ {job.status === 'failed' && job.error ? (
+ <div className="flex flex-col gap-1">
+ <ErrorText>{t(`settings.remoteControl.relay.errors.${job.error}`)}</ErrorText>
+ {job.detail ? <Hint>{t(`${k}.detail`, { detail: job.detail })}</Hint> : null}
+ </div>
+ ) : null}
+ {job.status === 'failed' && job.action !== 'uninstall' && deployment ? (
+ <div className="flex flex-wrap justify-end gap-2">
+ {job.error === 'RELAY_MISMATCH' ? (
+ <Button variant="secondary" size="sm" disabled={controller.busy} onClick={() => retry(true)}>
+ {t(`${k}.replace`)}
+ </Button>
+ ) : null}
+ <Button size="sm" disabled={controller.busy} onClick={() => retry(false)}>
+ {t(`${k}.retry`)}
+ </Button>
+ </div>
+ ) : null}
+ </Card>
+ );
+}
+
+function DeploymentCard({ state, controller }: { state: SelfHostedRelayState; controller: SelfHostedRelayController }) {
+ const { t } = useTranslation();
+ const confirmDialog = useOptionalConfirmDialog();
+ const deployment = state.deployment!;
+ const running = state.deployJob?.status === 'running';
+ const k = 'settings.remoteControl.relay.server';
+ const confirm = async (title: string, description: string, confirmText: string) =>
+ !confirmDialog || (await confirmDialog.confirm({ title, description, confirmText, confirmVariant: 'destructive' }));
+ return (
+ <Card>
+ <div className="flex items-center justify-between gap-4">
+ <div className="flex min-w-0 flex-col gap-1">
+ <p className="text-12 text-[var(--text-tertiary)]">{t(`${k}.title`)}</p>
+ <p className="truncate text-13 font-medium text-[var(--text-primary)]">{deployment.name}</p>
+ <p className="truncate font-mono text-12 text-[var(--text-tertiary)]">{deployment.baseUrl}</p>
+ <Hint>
+ {deployment.relayVersion ? t(`${k}.version`, { version: deployment.relayVersion }) : t(`${k}.incomplete`)}
+ </Hint>
+ </div>
+ {!deployment.active && deployment.relayVersion ? (
+ <Button size="sm" disabled={controller.busy || running} onClick={() => void controller.run({ type: 'use-deployment' })}>
+ {t('settings.remoteControl.relay.actions.useDeployment')}
+ </Button>
+ ) : null}
+ </div>
+ <div className="flex flex-wrap justify-end gap-2">
+ {deployment.upgradeAvailable ? (
+ <Button
+ variant="secondary"
+ size="sm"
+ disabled={controller.busy || running}
+ onClick={() => void controller.run({ type: 'upgrade-deployment' })}
+ >
+ {t(`${k}.upgrade`, { version: state.bundledRelayVersion ?? '' })}
+ </Button>
+ ) : null}
+ <Button
+ variant="secondary"
+ size="sm"
+ disabled={controller.busy || running}
+ onClick={() => {
+ void confirm(t(`${k}.forgetTitle`), t(`${k}.forgetDescription`), t(`${k}.forget`)).then((ok) => {
+ if (ok) void controller.run({ type: 'forget-deployment' });
+ });
+ }}
+ >
+ {t(`${k}.forget`)}
+ </Button>
+ <Button
+ variant="secondary"
+ size="sm"
+ disabled={controller.busy || running}
+ onClick={() => {
+ void confirm(t(`${k}.uninstallTitle`), t(`${k}.uninstallDescription`), t(`${k}.uninstall`)).then((ok) => {
+ if (ok) void controller.run({ type: 'uninstall-deployment', removeData: true });
+ });
+ }}
+ >
+ {t(`${k}.uninstall`)}
+ </Button>
+ </div>
+ </Card>
+ );
+}
+
+export function RelayServicePanel({ controller }: { controller: SelfHostedRelayController }) {
+ const { t } = useTranslation();
+ const confirmDialog = useOptionalConfirmDialog();
+ const [form, setForm] = useState<'none' | 'host' | 'join' | 'deploy'>('none');
+ const { state, error } = controller;
+ const k = 'settings.remoteControl.relay';
+
+ // 加入成功后收起表单(main 已切换中转)。
+ useEffect(() => {
+ if (state?.join.status === 'joined' && form === 'join') setForm('none');
+ }, [state?.join.status, form]);
+
+ if (!state) return null;
+ if (!state.available) {
+ return (
+ <Card>
+ <Hint>{t(`${k}.unavailable`)}</Hint>
+ </Card>
+ );
+ }
+
+ const relay = state.relay;
+ const isHost = relay?.origin === 'host';
+ const isServer = relay?.origin === 'server';
+ const isOwner = relay?.role === 'owner';
+ const currentLabel = !relay ? t(`${k}.summary.official`) : isHost ? t(`${k}.ownerName`) : relay.name;
+ const confirmKey = isHost ? 'owner' : isServer ? 'server' : 'member';
+ const job = state.deployJob;
+
+ const switchToOfficial = async () => {
+ const ok = !confirmDialog || (await confirmDialog.confirm({
+ title: t(`${k}.confirm.${confirmKey}Title`),
+ description: t(`${k}.confirm.${confirmKey}Description`, { name: relay?.name ?? '' }),
+ confirmText: t(`${k}.actions.useOfficial`),
+ confirmVariant: isHost ? 'destructive' : 'default',
+ }));
+ if (ok) {
+ setForm('none');
+ await controller.run({ type: 'use-official' });
+ }
+ };
+
+ return (
+ <div className="flex flex-col gap-3">
+ <Hint>{t(`${k}.description`)}</Hint>
+ <Card>
+ <div className="flex items-center justify-between gap-4">
+ <div className="flex min-w-0 flex-col gap-1">
+ <p className="text-12 text-[var(--text-tertiary)]">{t(`${k}.current`)}</p>
+ <p className="truncate text-13 font-medium text-[var(--text-primary)]">{currentLabel}</p>
+ {relay ? <p className="truncate font-mono text-12 text-[var(--text-tertiary)]">{relay.baseUrl}</p> : null}
+ </div>
+ {relay ? (
+ <Button variant="secondary" size="sm" disabled={controller.busy} onClick={() => void switchToOfficial()}>
+ {t(`${k}.actions.useOfficial`)}
+ </Button>
+ ) : null}
+ </div>
+ {state.issue ? (
+ <ErrorText>
+ {t(`${k}.issue.${state.issue}`)} {t(`${k}.issue.next`)}
+ </ErrorText>
+ ) : null}
+ {isHost && state.host.error ? (
+ <ErrorText>{t(`${k}.errors.${state.host.error}`, { port: state.host.port })}</ErrorText>
+ ) : null}
+ {isHost && state.host.running ? (
+ <>
+ <Hint>
+ {t(`${k}.host.running`, {
+ address: state.host.externalUrl ?? state.host.suggestedUrls[0] ?? `127.0.0.1:${state.host.port}`,
+ })}
+ </Hint>
+ <AddDevice state={state} controller={controller} />
+ </>
+ ) : null}
+ {isServer ? <AddDevice state={state} controller={controller} /> : null}
+ {relay ? <Hint>{t(`${k}.limits`)}</Hint> : null}
+ {!relay && form === 'none' ? (
+ <div className="flex flex-wrap justify-end gap-2">
+ <Button variant="secondary" size="sm" onClick={() => setForm('join')}>
+ {t(`${k}.actions.join`)}
+ </Button>
+ <Button variant="secondary" size="sm" onClick={() => setForm('host')}>
+ {t(`${k}.actions.host`)}
+ </Button>
+ {!state.deployment ? (
+ <Button size="sm" disabled={!state.bundledRelayVersion} onClick={() => setForm('deploy')}>
+ {t(`${k}.actions.deploy`)}
+ </Button>
+ ) : null}
+ </div>
+ ) : null}
+ {isHost && form === 'none' ? (
+ <div className="flex justify-end">
+ <Button variant="secondary" size="sm" onClick={() => setForm('host')}>
+ {t(`${k}.actions.editHost`)}
+ </Button>
+ </div>
+ ) : null}
+ </Card>
+ {error && error !== 'CANCELLED' ? (
+ <ErrorText>{t(`${k}.errors.${error}`, { port: state.host.port })}</ErrorText>
+ ) : null}
+ {form === 'host' ? (
+ <HostForm
+ state={state}
+ controller={controller}
+ onDone={() => {
+ controller.clearError();
+ setForm('none');
+ }}
+ />
+ ) : null}
+ {job && (job.status !== 'done' || form === 'none') ? <DeployProgress job={job} state={state} controller={controller} /> : null}
+ {state.deployment && form !== 'deploy' ? <DeploymentCard state={state} controller={controller} /> : null}
+ {form === 'deploy' ? (
+ <DeployForm
+ state={state}
+ controller={controller}
+ onDone={() => {
+ controller.clearError();
+ setForm('none');
+ }}
+ />
+ ) : null}
+ {form === 'join' ? (
+ <JoinForm
+ state={state}
+ controller={controller}
+ onDone={() => {
+ controller.clearError();
+ setForm('none');
+ }}
+ />
+ ) : null}
+ </div>
+ );
+}
diff --git a/apps/desktop/src/renderer/components/settings/RemoteControlSection.tsx b/apps/desktop/src/renderer/components/settings/RemoteControlSection.tsx
index 25575dface..aa523ceb8c 100644
--- a/apps/desktop/src/renderer/components/settings/RemoteControlSection.tsx
+++ b/apps/desktop/src/renderer/components/settings/RemoteControlSection.tsx
@@ -24,6 +24,7 @@ import { ChevronDown, ChevronRight } from 'lucide-react';
import { useDeviceLinkSettings, type DeviceLinkSettings } from '@/hooks/useDeviceLinkSettings';
import { MyDevicesPanel } from './MyDevicesPanel';
+import { RelayServicePanel, relaySummary, useSelfHostedRelayState } from './RelayServicePanel';
import { RemoteDesktopSetting } from './RemoteDesktopSetting';
import { RemoteSection } from './RemoteSection';
import { useAuth } from '@/contexts/AuthContext';
@@ -165,6 +166,10 @@ export function RemoteControlSection() {
// 深链 ?section=devices 必须在首帧就是展开态:放到 effect 里会先画一帧收起,
// 再把下方内容顶开一格。
const [devicesOpen, setDevicesOpen] = useState(() => isDevicesSection(location.search));
+ const relay = useSelfHostedRelayState(deviceLinkAvailable);
+ const [relayOpen, setRelayOpen] = useState(
+ () => new URLSearchParams(location.search).get('section') === 'remoteControl.relay',
+ );
const [sshOpen, setSshOpen] = useState(
() => new URLSearchParams(location.search).get('section') === 'remoteControl.ssh',
);
@@ -293,6 +298,17 @@ export function RemoteControlSection() {
/>
</CollapsibleSubSection>
<div className="h-px w-full bg-[var(--border-default)]" />
+ <CollapsibleSubSection
+ id="settings-search-target-remote-relay"
+ title={t('settings.remoteControl.sections.relay')}
+ summary={relaySummary(relay.state, t)}
+ dotColor={null}
+ open={relayOpen}
+ onToggle={() => setRelayOpen((value) => !value)}
+ >
+ <RelayServicePanel controller={relay} />
+ </CollapsibleSubSection>
+ <div className="h-px w-full bg-[var(--border-default)]" />
</>
) : null}
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index 402707264c..1a714df768 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -5589,6 +5589,172 @@
}
},
"remoteControl": {
+ "relay": {
+ "summary": {
+ "official": "Cindy relay",
+ "owner": "This computer is the relay",
+ "member": "Joined {{name}}",
+ "server": "Server relay \"{{name}}\""
+ },
+ "description": "Remote control between your devices goes through the Cindy relay by default. You can instead deploy a relay to your own server, run one on this computer, or join a relay on another computer of yours. Sign-in, models and other services are not affected.",
+ "current": "In use",
+ "ownerName": "This computer",
+ "unavailable": "To use your own relay, sign in to Cindy and make sure the system keychain is available.",
+ "limits": "While you use your own relay, phone push notifications, provider sharing and shared tasks are unavailable.",
+ "actions": {
+ "host": "Run on this computer",
+ "join": "Join another relay",
+ "useOfficial": "Switch back to Cindy relay",
+ "editHost": "Change settings",
+ "deploy": "Deploy to my server",
+ "useDeployment": "Use this relay"
+ },
+ "host": {
+ "title": "Run a relay on this computer",
+ "hint": "Your other devices must be able to reach this computer: the same local network, router port forwarding, a tunnel or a mesh VPN all work, and you are responsible for that. If this computer sleeps or Cindy quits, every device disconnects, so Keep computer awake is turned on.",
+ "port": "Port",
+ "scope": "Who can connect",
+ "scopeLocal": "This computer only",
+ "scopeAll": "Any network",
+ "scopeLocalHint": "Accepts connections from this computer only. Use it with your own reverse proxy, tunnel or mesh VPN.",
+ "scopeAllHint": "Devices on your local network can connect directly. The connection is not encrypted, so use it only on trusted networks. Phones need an https address.",
+ "externalUrl": "Address other devices use",
+ "externalUrlPlaceholder": "e.g. https://relay.example.com",
+ "externalUrlHintAll": "Included in join links. If empty, this computer's local network address is used.",
+ "externalUrlHintLocal": "Included in join links. Enter the public address of your proxy or tunnel.",
+ "suggested": "This computer's addresses:",
+ "start": "Start",
+ "save": "Save and restart relay",
+ "cancel": "Cancel",
+ "running": "Relay is running. Other devices connect to {{address}}"
+ },
+ "add": {
+ "intro": "Create a join link so a phone or another computer can join this relay.",
+ "create": "Add device",
+ "hint": "Scan it with your phone's camera, or send the link to another computer and paste it under Join another relay. The link works once and expires in 10 minutes.",
+ "qrAlt": "QR code to join the relay",
+ "copy": "Copy link",
+ "copied": "Join link copied",
+ "newLink": "New link",
+ "waiting": "Waiting for a device to ask…"
+ },
+ "requests": {
+ "item": "{{name}} wants to join",
+ "verify": "Pairing code",
+ "verifyHint": "Approve only if it matches the code on that device.",
+ "replaces": "This device joined before. Approving revokes its old credential.",
+ "approve": "Approve",
+ "reject": "Decline",
+ "unverified": "This request can't be verified: it doesn't match a join link from this computer and may have been tampered with, so it can only be declined. If it's your device, create a new join link and try again."
+ },
+ "join": {
+ "title": "Join another relay",
+ "hint": "Paste the join link from Add device on the relay's computer. Cindy switches over once it's approved.",
+ "placeholder": "Paste the join link",
+ "submit": "Join",
+ "connecting": "Connecting to the relay…",
+ "waiting": "Request sent. On {{name}}, check that these digits match and approve:",
+ "cancel": "Cancel"
+ },
+ "issue": {
+ "removed": "This computer was removed from the relay, or the relay was stopped.",
+ "unauthorized": "The relay no longer accepts this computer's credential.",
+ "next": "Join again, or switch back to the Cindy relay."
+ },
+ "confirm": {
+ "ownerTitle": "Stop the relay on this computer?",
+ "ownerDescription": "Devices that joined will disconnect and be told the relay was stopped. This computer switches back to the Cindy relay.",
+ "memberTitle": "Switch back to the Cindy relay?",
+ "memberDescription": "This computer leaves \"{{name}}\" and uses the Cindy relay. To join again, ask for a new join link.",
+ "serverTitle": "Switch back to the Cindy relay?",
+ "serverDescription": "The relay \"{{name}}\" keeps running on your server, and devices that joined can still reach each other through it. You can switch this computer back at any time."
+ },
+ "errors": {
+ "INVALID_LINK": "The join link or address is not valid.",
+ "UNREACHABLE": "Can't reach this relay. Make sure this computer can open the address in the link.",
+ "NOT_A_RELAY": "This address is not a Cindy relay.",
+ "INCOMPATIBLE": "This relay's version isn't compatible. Update Cindy on both computers.",
+ "ACCOUNT_MISMATCH": "This relay belongs to another Cindy account.",
+ "CODE_INVALID": "This join link has expired or was already used. Ask for a new one.",
+ "RATE_LIMITED": "Too many attempts. Try again in a few minutes.",
+ "REJECTED": "The request was declined.",
+ "EXPIRED": "Timed out waiting for approval. Join again.",
+ "CANCELLED": "Cancelled.",
+ "FAILED": "The action didn't complete.",
+ "HOSTING": "This computer is running a relay. Switch back to the Cindy relay before joining another one.",
+ "NOT_SIGNED_IN": "Sign in to Cindy first.",
+ "SECURE_STORAGE_UNAVAILABLE": "The system keychain isn't available, so the relay credential can't be stored safely.",
+ "PORT_IN_USE": "Port {{port}} is already in use. Choose another port.",
+ "START_FAILED": "The relay couldn't start. Try another port.",
+ "EXTERNAL_URL_REQUIRED": "Enter the address other devices use, or set Who can connect to Any network.",
+ "SSH_FAILED": "Can't connect to the server. Check its SSH settings under Remote.",
+ "NEEDS_ROOT": "This needs the root account, or an account that can use sudo without a password. Cindy never asks for your server password.",
+ "UNSUPPORTED_SYSTEM": "Only 64-bit Linux with systemd (x64 / arm64) is supported, and curl or wget must be installed.",
+ "PORT_BUSY": "Port 80 or 443 on the server is used by another program, such as a web server. Stop it first, or use another server.",
+ "DOWNLOAD_FAILED": "The server couldn't download the runtime from the official source or the mirror. Check that the server can reach the internet.",
+ "RELAY_MISMATCH": "This server already has a relay that wasn't deployed from this computer. You can remove it and redeploy.",
+ "CERTIFICATE_FAILED": "Couldn't get an HTTPS certificate. Usually port 80 isn't allowed in the cloud security group, or the domain doesn't point to this server yet. Fix that, then retry.",
+ "NOT_REACHABLE": "The relay is running on the server, but this computer can't reach it. Allow port 443 in the cloud security group.",
+ "BUNDLE_MISSING": "This version of Cindy doesn't include the relay. Update Cindy.",
+ "DEPLOY_FAILED": "Deployment didn't complete.",
+ "PAIR_PROOF_INVALID": "This device's request can't be verified, so it can't be approved. Create a new join link.",
+ "NOT_OWNER": "Only the computer that deployed or started this relay can manage it.",
+ "BUSY": "A deployment is in progress. Please wait.",
+ "INVALID_ADDRESS": "Enter a public IP or domain, without http:// or a port.",
+ "NO_DEPLOYMENT": "Nothing has been deployed to a server yet.",
+ "OWNER_MISMATCH": "The relay returned a certificate that the owner in the join link didn't issue. You may be connected to a fake relay, so joining stopped."
+ },
+ "deploy": {
+ "title": "Deploy to my server",
+ "hint": "Install the relay on your own Linux server so your phone and devices on other networks can connect. Cindy installs it over the SSH connection set up under Remote, gets an HTTPS certificate and renews it automatically.",
+ "requirements": "Requires 64-bit Linux with systemd, root or passwordless sudo, ports 80 and 443 not used by another program, and TCP 80 and 443 allowed in your cloud provider's security group or firewall.",
+ "noHosts": "No servers yet. Add an SSH host under Remote, then come back to deploy.",
+ "server": "Server",
+ "address": "Address",
+ "addressPlaceholder": "Public IP or domain, e.g. 203.0.113.10",
+ "addressHint": "The address other devices use to reach the relay. A public IP gets a 6-day IP certificate that renews automatically; a domain must already point to this server.",
+ "name": "Name",
+ "defaultName": "My relay",
+ "submit": "Deploy",
+ "cancel": "Cancel",
+ "detail": "Details: {{detail}}",
+ "retry": "Retry",
+ "replace": "Remove the old relay and redeploy",
+ "running": {
+ "deploy": "Deploying to your server…",
+ "upgrade": "Upgrading the relay on your server…",
+ "uninstall": "Removing the relay from your server…"
+ },
+ "done": {
+ "deploy": "Deployed. This computer now uses the relay on your server. Use Add device to bring in your phone and other computers.",
+ "upgrade": "The relay on your server is now version {{version}}.",
+ "uninstall": "The relay was removed from your server."
+ },
+ "steps": {
+ "connect": "Connect to the server",
+ "check": "Check the system and ports",
+ "runtime": "Install the runtime",
+ "upload": "Upload the relay",
+ "configure": "Configure and start the service",
+ "certificate": "Get an HTTPS certificate",
+ "verify": "Check this computer can reach it",
+ "finish": "Done",
+ "remove": "Stop the service and delete files"
+ }
+ },
+ "server": {
+ "title": "My server relay",
+ "version": "Relay version {{version}}",
+ "incomplete": "The last deployment didn't finish. Retry or uninstall.",
+ "upgrade": "Upgrade to {{version}}",
+ "uninstall": "Uninstall from server",
+ "uninstallTitle": "Uninstall the relay from your server?",
+ "uninstallDescription": "The relay and its device records are deleted from the server, and devices using it disconnect. If you deploy again, every device needs to join again.",
+ "forget": "Remove from this computer only",
+ "forgetTitle": "Remove from this computer only?",
+ "forgetDescription": "The relay keeps running on the server, but this computer stops managing it and can't add devices to it anymore. Do this only if you no longer use that server."
+ }
+ },
"title": "Remote Connection",
"description": "Control your other signed-in devices remotely, or connect to a remote host over SSH.",
"accessRevokedByPeer": "Access revoked — the other device must restore it in its settings",
@@ -5608,6 +5774,7 @@
"restoreFailed": "Failed to restore access"
},
"sections": {
+ "relay": "Relay service",
"myDevices": "My devices",
"ssh": "SSH remote hosts",
"hook": "Cindy IM bots"
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index 15c4b50d8d..58be0e249a 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -5558,6 +5558,172 @@
}
},
"remoteControl": {
+ "relay": {
+ "summary": {
+ "official": "Cindy 公式リレー",
+ "owner": "このコンピュータがリレー",
+ "member": "{{name}} に参加中",
+ "server": "サーバーのリレー「{{name}}」"
+ },
+ "description": "デバイス間のリモート操作は、既定では Cindy 公式リレーを経由します。リレーを自分のサーバーにデプロイしたり、このコンピュータをリレーにしたり、自分の別のコンピュータ上のリレーに参加したりすることもできます。サインインやモデルなど他のサービスには影響しません。",
+ "current": "使用中",
+ "ownerName": "このコンピュータ",
+ "unavailable": "自分のリレーを使うには、Cindy にサインインし、システムのキーチェーンが使える必要があります。",
+ "limits": "自分のリレーを使っている間は、スマホのプッシュ通知、プロバイダー共有、共有タスクは使えません。",
+ "actions": {
+ "host": "このコンピュータで開始",
+ "join": "別のリレーに参加",
+ "useOfficial": "公式リレーに戻す",
+ "editHost": "設定を変更",
+ "deploy": "自分のサーバーにデプロイ",
+ "useDeployment": "このリレーを使う"
+ },
+ "host": {
+ "title": "このコンピュータでリレーを開始",
+ "hint": "他のデバイスからこのコンピュータに接続できる必要があります。同じローカルネットワーク、ルーターのポート転送、トンネル、メッシュ VPN などで、ご自身で確保してください。このコンピュータがスリープしたり Cindy を終了したりすると全デバイスが切断されるため、「コンピュータをスリープさせない」をオンにします。",
+ "port": "ポート",
+ "scope": "接続を許可する範囲",
+ "scopeLocal": "このコンピュータのみ",
+ "scopeAll": "すべてのネットワーク",
+ "scopeLocalHint": "このコンピュータからの接続のみ受け付けます。ご自身のリバースプロキシ、トンネル、メッシュ VPN と組み合わせて使います。",
+ "scopeAllHint": "ローカルネットワーク内のデバイスが直接接続できます。通信は暗号化されないため、信頼できるネットワークでのみ使ってください。スマホは https アドレスが必要です。",
+ "externalUrl": "他のデバイスが使うアドレス",
+ "externalUrlPlaceholder": "例: https://relay.example.com",
+ "externalUrlHintAll": "参加リンクに含まれます。空欄の場合はこのコンピュータのローカルアドレスを使います。",
+ "externalUrlHintLocal": "参加リンクに含まれます。プロキシやトンネルの公開アドレスを入力してください。",
+ "suggested": "このコンピュータのアドレス:",
+ "start": "開始",
+ "save": "保存してリレーを再起動",
+ "cancel": "キャンセル",
+ "running": "リレー稼働中。他のデバイスの接続先: {{address}}"
+ },
+ "add": {
+ "intro": "参加リンクを作成して、スマホや別のコンピュータをこのリレーに参加させます。",
+ "create": "デバイスを追加",
+ "hint": "スマホのカメラでスキャンするか、リンクを別のコンピュータに送り「別のリレーに参加」に貼り付けてください。リンクは 10 分間有効で、1 回だけ使えます。",
+ "qrAlt": "リレーに参加する QR コード",
+ "copy": "リンクをコピー",
+ "copied": "参加リンクをコピーしました",
+ "newLink": "再生成",
+ "waiting": "デバイスからの申請を待っています…"
+ },
+ "requests": {
+ "item": "{{name}} が参加を申請しています",
+ "verify": "ペアリングコード",
+ "verifyHint": "相手の画面のコードと一致する場合のみ承認してください。",
+ "replaces": "このデバイスは以前参加していました。承認すると古い認証情報は無効になります。",
+ "approve": "承認",
+ "reject": "拒否",
+ "unverified": "このデバイスを確認できません。申請がこのコンピュータの参加リンクと一致せず、改ざんされた可能性があるため、拒否のみ可能です。自分のデバイスなら、参加リンクを作り直してもう一度試してください。"
+ },
+ "join": {
+ "title": "別のリレーに参加",
+ "hint": "リレーのコンピュータの「デバイスを追加」で表示された参加リンクを貼り付けてください。承認されると自動で切り替わります。",
+ "placeholder": "参加リンクを貼り付け",
+ "submit": "参加",
+ "connecting": "リレーに接続しています…",
+ "waiting": "申請しました。{{name}} でこの数字が一致することを確認して承認してください:",
+ "cancel": "キャンセル"
+ },
+ "issue": {
+ "removed": "このコンピュータはリレーから外されたか、リレーが停止されました。",
+ "unauthorized": "リレーがこのコンピュータの認証情報を受け付けなくなりました。",
+ "next": "もう一度参加するか、公式リレーに戻してください。"
+ },
+ "confirm": {
+ "ownerTitle": "このコンピュータのリレーを停止しますか?",
+ "ownerDescription": "参加しているデバイスは切断され、リレーが停止されたと表示されます。このコンピュータは Cindy 公式リレーに戻ります。",
+ "memberTitle": "公式リレーに戻しますか?",
+ "memberDescription": "このコンピュータは「{{name}}」から抜け、Cindy 公式リレーを使います。再参加するには新しい参加リンクが必要です。",
+ "serverTitle": "公式リレーに戻しますか?",
+ "serverDescription": "サーバー上のリレー「{{name}}」は動作し続け、参加済みの他のデバイスは引き続き互いに接続できます。このコンピュータはいつでも戻せます。"
+ },
+ "errors": {
+ "INVALID_LINK": "参加リンクまたはアドレスの形式が正しくありません。",
+ "UNREACHABLE": "このリレーに接続できません。このコンピュータからリンク内のアドレスにアクセスできるか確認してください。",
+ "NOT_A_RELAY": "このアドレスは Cindy リレーではありません。",
+ "INCOMPATIBLE": "このリレーのバージョンは互換性がありません。両方の Cindy を最新版に更新してください。",
+ "ACCOUNT_MISMATCH": "このリレーは別の Cindy アカウントのものです。",
+ "CODE_INVALID": "参加リンクの有効期限が切れたか、すでに使われています。新しいリンクを作ってもらってください。",
+ "RATE_LIMITED": "試行回数が多すぎます。数分後にもう一度お試しください。",
+ "REJECTED": "参加が拒否されました。",
+ "EXPIRED": "承認待ちがタイムアウトしました。もう一度参加してください。",
+ "CANCELLED": "キャンセルしました。",
+ "FAILED": "操作を完了できませんでした。",
+ "HOSTING": "このコンピュータはリレーを稼働中です。別のリレーに参加するには、先に公式リレーに戻してください。",
+ "NOT_SIGNED_IN": "先に Cindy にサインインしてください。",
+ "SECURE_STORAGE_UNAVAILABLE": "システムのキーチェーンが使えないため、リレーの認証情報を安全に保存できません。",
+ "PORT_IN_USE": "ポート {{port}} はすでに使われています。別のポートを選んでください。",
+ "START_FAILED": "リレーを開始できませんでした。別のポートでお試しください。",
+ "EXTERNAL_URL_REQUIRED": "他のデバイスが使うアドレスを入力するか、「接続を許可する範囲」をすべてのネットワークにしてください。",
+ "SSH_FAILED": "サーバーに接続できません。「リモート」でこのサーバーの SSH 設定を確認してください。",
+ "NEEDS_ROOT": "root アカウント、またはパスワードなしで sudo を使えるアカウントが必要です。Cindy がサーバーのパスワードを求めることはありません。",
+ "UNSUPPORTED_SYSTEM": "対応しているのは systemd のある 64 ビット Linux(x64 / arm64)のみで、curl または wget が必要です。",
+ "PORT_BUSY": "サーバーの 80 または 443 ポートを他のプログラム(Web サーバーなど)が使っています。停止するか、別のサーバーを使ってください。",
+ "DOWNLOAD_FAILED": "サーバーが実行環境をダウンロードできませんでした(公式ソースとミラーの両方で失敗)。サーバーがインターネットに接続できるか確認してください。",
+ "RELAY_MISMATCH": "このサーバーには、このコンピュータ以外からデプロイされたリレーがあります。削除して再デプロイできます。",
+ "CERTIFICATE_FAILED": "HTTPS 証明書を取得できませんでした。多くの場合、クラウドのセキュリティグループで 80 ポートが許可されていないか、ドメインがまだこのサーバーを指していません。対処してから再試行してください。",
+ "NOT_REACHABLE": "サーバーのリレーは動作していますが、このコンピュータから接続できません。クラウドのセキュリティグループで 443 ポートを許可してください。",
+ "BUNDLE_MISSING": "このバージョンの Cindy にはリレーが含まれていません。Cindy を更新してください。",
+ "DEPLOY_FAILED": "デプロイを完了できませんでした。",
+ "PAIR_PROOF_INVALID": "このデバイスの申請を確認できないため、承認できません。参加リンクを作り直してください。",
+ "NOT_OWNER": "このリレーを管理できるのは、デプロイまたは開始したコンピュータだけです。",
+ "BUSY": "デプロイ中です。しばらくお待ちください。",
+ "INVALID_ADDRESS": "グローバル IP またはドメインを、http:// やポートを付けずに入力してください。",
+ "NO_DEPLOYMENT": "まだサーバーにデプロイしていません。",
+ "OWNER_MISMATCH": "リレーから返された証明書は、参加リンクの所有者が発行したものではありません。偽のリレーに接続している可能性があるため、参加を中止しました。"
+ },
+ "deploy": {
+ "title": "自分のサーバーにデプロイ",
+ "hint": "リレーを自分の Linux サーバーにインストールすると、スマホや別のネットワークのデバイスからも接続できます。Cindy は「リモート」で設定した SSH 接続でインストールし、HTTPS 証明書を自動で取得・更新します。",
+ "requirements": "必要なもの:systemd のある 64 ビット Linux、root またはパスワードなしの sudo、他のプログラムが使っていない 80 と 443 ポート、クラウドのセキュリティグループやファイアウォールでの TCP 80 と 443 の許可。",
+ "noHosts": "使えるサーバーがまだありません。「リモート」で SSH ホストを追加してから戻ってきてください。",
+ "server": "サーバー",
+ "address": "アクセス用アドレス",
+ "addressPlaceholder": "グローバル IP またはドメイン(例:203.0.113.10)",
+ "addressHint": "他のデバイスがリレーに接続するアドレスです。グローバル IP なら有効期間 6 日で自動更新される IP 証明書を取得します。ドメインの場合は、先にこのサーバーを指すよう DNS を設定してください。",
+ "name": "名前",
+ "defaultName": "マイリレー",
+ "submit": "デプロイ",
+ "cancel": "キャンセル",
+ "detail": "詳細:{{detail}}",
+ "retry": "再試行",
+ "replace": "古いリレーを削除して再デプロイ",
+ "running": {
+ "deploy": "サーバーにデプロイしています…",
+ "upgrade": "サーバーのリレーを更新しています…",
+ "uninstall": "サーバーから削除しています…"
+ },
+ "done": {
+ "deploy": "デプロイが完了し、このコンピュータはサーバーのリレーを使うようになりました。「デバイスを追加」でスマホや他のコンピュータを参加させてください。",
+ "upgrade": "サーバーのリレーを {{version}} に更新しました。",
+ "uninstall": "サーバーからリレーを削除しました。"
+ },
+ "steps": {
+ "connect": "サーバーに接続",
+ "check": "システムとポートを確認",
+ "runtime": "実行環境をインストール",
+ "upload": "リレーをアップロード",
+ "configure": "サービスを設定して起動",
+ "certificate": "HTTPS 証明書を取得",
+ "verify": "このコンピュータから接続を確認",
+ "finish": "完了",
+ "remove": "サービスを停止してファイルを削除"
+ }
+ },
+ "server": {
+ "title": "自分のサーバーのリレー",
+ "version": "リレーのバージョン {{version}}",
+ "incomplete": "前回のデプロイは完了していません。再試行するか削除してください。",
+ "upgrade": "{{version}} に更新",
+ "uninstall": "サーバーから削除",
+ "uninstallTitle": "サーバーからリレーを削除しますか?",
+ "uninstallDescription": "サーバー上のリレーとデバイス情報が削除され、使用中のデバイスは切断されます。再デプロイした場合、すべてのデバイスが再参加する必要があります。",
+ "forget": "このコンピュータからのみ削除",
+ "forgetTitle": "このコンピュータからのみ削除しますか?",
+ "forgetDescription": "サーバー上のリレーは削除されませんが、このコンピュータでは管理できなくなり、デバイスも追加できなくなります。そのサーバーを使わなくなった場合にのみ行ってください。"
+ }
+ },
"title": "リモート接続",
"description": "同じアカウントのデバイスを相互に遠隔操作したり、SSH でリモートホストに接続したりできます。",
"accessRevokedByPeer": "アクセス権が撤回されました。相手側の設定で復元する必要があります",
@@ -5577,6 +5743,7 @@
"restoreFailed": "復元に失敗しました"
},
"sections": {
+ "relay": "リレーサービス",
"myDevices": "マイデバイス",
"ssh": "SSH リモートホスト",
"hook": "Cindy IM ボット"
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index 4a73770ea0..fe735e14bf 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -5558,6 +5558,172 @@
}
},
"remoteControl": {
+ "relay": {
+ "summary": {
+ "official": "Cindy 공식 중계",
+ "owner": "이 컴퓨터가 중계",
+ "member": "{{name}}에 참여함",
+ "server": "서버 중계 \"{{name}}\""
+ },
+ "description": "기기 간 원격 제어는 기본적으로 Cindy 공식 중계를 거칩니다. 중계를 내 서버에 배포하거나, 이 컴퓨터를 중계로 쓰거나, 내 다른 컴퓨터의 중계에 참여할 수도 있습니다. 로그인, 모델 등 다른 서비스에는 영향이 없습니다.",
+ "current": "사용 중",
+ "ownerName": "이 컴퓨터",
+ "unavailable": "내 중계를 사용하려면 Cindy에 로그인하고 시스템 키체인을 사용할 수 있어야 합니다.",
+ "limits": "내 중계를 사용하는 동안에는 휴대폰 푸시 알림, 제공자 공유, 공유 작업을 사용할 수 없습니다.",
+ "actions": {
+ "host": "이 컴퓨터에서 시작",
+ "join": "다른 중계에 참여",
+ "useOfficial": "공식 중계로 돌아가기",
+ "editHost": "설정 변경",
+ "deploy": "내 서버에 배포",
+ "useDeployment": "이 중계 사용"
+ },
+ "host": {
+ "title": "이 컴퓨터에서 중계 시작",
+ "hint": "다른 기기가 이 컴퓨터에 접속할 수 있어야 합니다. 같은 로컬 네트워크, 공유기 포트 포워딩, 터널, 메시 VPN 등으로 직접 확보해 주세요. 이 컴퓨터가 잠자기 상태가 되거나 Cindy를 종료하면 모든 기기의 연결이 끊어지므로 \"컴퓨터 깨어 있게 하기\"를 켭니다.",
+ "port": "포트",
+ "scope": "연결 허용 범위",
+ "scopeLocal": "이 컴퓨터만",
+ "scopeAll": "모든 네트워크",
+ "scopeLocalHint": "이 컴퓨터에서 오는 연결만 받습니다. 직접 운영하는 리버스 프록시, 터널, 메시 VPN과 함께 사용하세요.",
+ "scopeAllHint": "로컬 네트워크의 기기가 바로 연결할 수 있습니다. 연결이 암호화되지 않으므로 신뢰할 수 있는 네트워크에서만 사용하세요. 휴대폰은 https 주소가 필요합니다.",
+ "externalUrl": "다른 기기가 사용할 주소",
+ "externalUrlPlaceholder": "예: https://relay.example.com",
+ "externalUrlHintAll": "참여 링크에 포함됩니다. 비워 두면 이 컴퓨터의 로컬 네트워크 주소를 사용합니다.",
+ "externalUrlHintLocal": "참여 링크에 포함됩니다. 프록시나 터널의 공개 주소를 입력하세요.",
+ "suggested": "이 컴퓨터의 주소:",
+ "start": "시작",
+ "save": "저장하고 중계 다시 시작",
+ "cancel": "취소",
+ "running": "중계 실행 중. 다른 기기의 접속 주소: {{address}}"
+ },
+ "add": {
+ "intro": "참여 링크를 만들어 휴대폰이나 다른 컴퓨터를 이 중계에 참여시킵니다.",
+ "create": "기기 추가",
+ "hint": "휴대폰 카메라로 스캔하거나, 링크를 다른 컴퓨터로 보내 '다른 중계에 참여'에 붙여 넣으세요. 링크는 10분 동안 한 번만 사용할 수 있습니다.",
+ "qrAlt": "중계 참여 QR 코드",
+ "copy": "링크 복사",
+ "copied": "참여 링크를 복사했습니다",
+ "newLink": "새 링크",
+ "waiting": "기기의 참여 요청을 기다리는 중…"
+ },
+ "requests": {
+ "item": "{{name}}이(가) 참여를 요청했습니다",
+ "verify": "페어링 코드",
+ "verifyHint": "상대 기기 화면의 코드와 같을 때만 승인하세요.",
+ "replaces": "이 기기는 이전에 참여한 적이 있습니다. 승인하면 이전 인증 정보는 무효가 됩니다.",
+ "approve": "승인",
+ "reject": "거절",
+ "unverified": "이 기기를 확인할 수 없습니다. 요청이 이 컴퓨터의 참여 링크와 맞지 않아 변조되었을 수 있으므로 거절만 할 수 있습니다. 내 기기라면 참여 링크를 다시 만든 뒤 다시 시도하세요."
+ },
+ "join": {
+ "title": "다른 중계에 참여",
+ "hint": "중계가 실행 중인 컴퓨터의 '기기 추가'에서 받은 참여 링크를 붙여 넣으세요. 승인되면 자동으로 전환됩니다.",
+ "placeholder": "참여 링크 붙여 넣기",
+ "submit": "참여",
+ "connecting": "중계에 연결하는 중…",
+ "waiting": "요청을 보냈습니다. {{name}}에서 이 숫자가 같은지 확인하고 승인하세요:",
+ "cancel": "취소"
+ },
+ "issue": {
+ "removed": "이 컴퓨터가 중계에서 제외되었거나 중계가 중지되었습니다.",
+ "unauthorized": "중계가 더 이상 이 컴퓨터의 인증 정보를 받지 않습니다.",
+ "next": "다시 참여하거나 공식 중계로 돌아가세요."
+ },
+ "confirm": {
+ "ownerTitle": "이 컴퓨터의 중계를 중지할까요?",
+ "ownerDescription": "참여한 기기의 연결이 끊어지고 중계가 중지되었다고 표시됩니다. 이 컴퓨터는 Cindy 공식 중계로 돌아갑니다.",
+ "memberTitle": "공식 중계로 돌아갈까요?",
+ "memberDescription": "이 컴퓨터는 '{{name}}'에서 나가고 Cindy 공식 중계를 사용합니다. 다시 참여하려면 새 참여 링크가 필요합니다.",
+ "serverTitle": "공식 중계로 돌아갈까요?",
+ "serverDescription": "서버의 중계 \"{{name}}\"은(는) 계속 실행되며, 참여한 다른 기기는 계속 서로 연결할 수 있습니다. 이 컴퓨터는 언제든 다시 바꿀 수 있습니다."
+ },
+ "errors": {
+ "INVALID_LINK": "참여 링크나 주소 형식이 올바르지 않습니다.",
+ "UNREACHABLE": "이 중계에 연결할 수 없습니다. 이 컴퓨터에서 링크의 주소에 접속할 수 있는지 확인하세요.",
+ "NOT_A_RELAY": "이 주소는 Cindy 중계가 아닙니다.",
+ "INCOMPATIBLE": "이 중계의 버전과 호환되지 않습니다. 양쪽 Cindy를 최신 버전으로 업데이트하세요.",
+ "ACCOUNT_MISMATCH": "이 중계는 다른 Cindy 계정의 것입니다.",
+ "CODE_INVALID": "참여 링크가 만료되었거나 이미 사용되었습니다. 새 링크를 요청하세요.",
+ "RATE_LIMITED": "시도 횟수가 너무 많습니다. 몇 분 후 다시 시도하세요.",
+ "REJECTED": "참여 요청이 거절되었습니다.",
+ "EXPIRED": "승인 대기 시간이 초과되었습니다. 다시 참여하세요.",
+ "CANCELLED": "취소했습니다.",
+ "FAILED": "작업을 완료하지 못했습니다.",
+ "HOSTING": "이 컴퓨터에서 중계를 실행 중입니다. 다른 중계에 참여하려면 먼저 공식 중계로 돌아가세요.",
+ "NOT_SIGNED_IN": "먼저 Cindy에 로그인하세요.",
+ "SECURE_STORAGE_UNAVAILABLE": "시스템 키체인을 사용할 수 없어 중계 인증 정보를 안전하게 저장할 수 없습니다.",
+ "PORT_IN_USE": "포트 {{port}}이(가) 이미 사용 중입니다. 다른 포트를 선택하세요.",
+ "START_FAILED": "중계를 시작하지 못했습니다. 다른 포트로 시도해 보세요.",
+ "EXTERNAL_URL_REQUIRED": "다른 기기가 사용할 주소를 입력하거나 '연결 허용 범위'를 모든 네트워크로 바꾸세요.",
+ "SSH_FAILED": "서버에 연결할 수 없습니다. 원격에서 이 서버의 SSH 설정을 확인하세요.",
+ "NEEDS_ROOT": "root 계정이나 암호 없이 sudo를 쓸 수 있는 계정이 필요합니다. Cindy는 서버 암호를 묻지 않습니다.",
+ "UNSUPPORTED_SYSTEM": "systemd가 있는 64비트 Linux(x64 / arm64)만 지원하며, curl 또는 wget이 필요합니다.",
+ "PORT_BUSY": "서버의 80 또는 443 포트를 다른 프로그램(예: 웹 서버)이 사용 중입니다. 먼저 중지하거나 다른 서버를 사용하세요.",
+ "DOWNLOAD_FAILED": "서버가 실행 환경을 내려받지 못했습니다(공식 소스와 미러 모두 실패). 서버가 인터넷에 연결되는지 확인하세요.",
+ "RELAY_MISMATCH": "이 서버에는 이 컴퓨터가 배포하지 않은 중계가 이미 있습니다. 지우고 다시 배포할 수 있습니다.",
+ "CERTIFICATE_FAILED": "HTTPS 인증서를 발급받지 못했습니다. 대개 클라우드 보안 그룹에서 80 포트를 허용하지 않았거나 도메인이 아직 이 서버를 가리키지 않기 때문입니다. 해결한 뒤 다시 시도하세요.",
+ "NOT_REACHABLE": "서버의 중계는 실행 중이지만 이 컴퓨터에서 연결할 수 없습니다. 클라우드 보안 그룹에서 443 포트를 허용하세요.",
+ "BUNDLE_MISSING": "이 버전의 Cindy에는 중계가 포함되어 있지 않습니다. Cindy를 업데이트하세요.",
+ "DEPLOY_FAILED": "배포를 완료하지 못했습니다.",
+ "PAIR_PROOF_INVALID": "이 기기의 요청을 확인할 수 없어 승인할 수 없습니다. 참여 링크를 다시 만드세요.",
+ "NOT_OWNER": "이 중계는 배포하거나 시작한 컴퓨터에서만 관리할 수 있습니다.",
+ "BUSY": "배포가 진행 중입니다. 잠시 기다려 주세요.",
+ "INVALID_ADDRESS": "http://와 포트 없이 공인 IP 또는 도메인을 입력하세요.",
+ "NO_DEPLOYMENT": "아직 서버에 배포하지 않았습니다.",
+ "OWNER_MISMATCH": "중계가 보낸 인증서를 참여 링크의 소유자가 발급하지 않았습니다. 가짜 중계에 연결되었을 수 있어 참여를 중단했습니다."
+ },
+ "deploy": {
+ "title": "내 서버에 배포",
+ "hint": "중계를 내 Linux 서버에 설치하면 휴대폰과 다른 네트워크의 기기도 연결할 수 있습니다. Cindy는 원격에서 설정한 SSH 연결로 설치하고, HTTPS 인증서를 자동으로 발급받아 만료 전에 갱신합니다.",
+ "requirements": "필요 조건: systemd가 있는 64비트 Linux, root 또는 암호 없는 sudo, 다른 프로그램이 쓰지 않는 80·443 포트, 클라우드 보안 그룹이나 방화벽에서 TCP 80·443 허용.",
+ "noHosts": "사용할 수 있는 서버가 없습니다. 원격에서 SSH 호스트를 추가한 뒤 다시 오세요.",
+ "server": "서버",
+ "address": "접속 주소",
+ "addressPlaceholder": "공인 IP 또는 도메인 (예: 203.0.113.10)",
+ "addressHint": "다른 기기가 중계에 연결할 주소입니다. 공인 IP를 입력하면 6일간 유효하고 자동 갱신되는 IP 인증서를 발급받습니다. 도메인은 먼저 이 서버를 가리키도록 설정해야 합니다.",
+ "name": "이름",
+ "defaultName": "내 중계",
+ "submit": "배포",
+ "cancel": "취소",
+ "detail": "자세한 원인: {{detail}}",
+ "retry": "다시 시도",
+ "replace": "이전 중계를 지우고 다시 배포",
+ "running": {
+ "deploy": "서버에 배포하는 중…",
+ "upgrade": "서버의 중계를 업그레이드하는 중…",
+ "uninstall": "서버에서 제거하는 중…"
+ },
+ "done": {
+ "deploy": "배포를 마쳤습니다. 이제 이 컴퓨터는 서버의 중계를 사용합니다. 기기 추가로 휴대폰과 다른 컴퓨터를 참여시키세요.",
+ "upgrade": "서버의 중계를 {{version}}(으)로 업그레이드했습니다.",
+ "uninstall": "서버에서 중계를 제거했습니다."
+ },
+ "steps": {
+ "connect": "서버에 연결",
+ "check": "시스템과 포트 확인",
+ "runtime": "실행 환경 설치",
+ "upload": "중계 업로드",
+ "configure": "서비스 설정 및 시작",
+ "certificate": "HTTPS 인증서 발급",
+ "verify": "이 컴퓨터에서 연결 확인",
+ "finish": "완료",
+ "remove": "서비스 중지 및 파일 삭제"
+ }
+ },
+ "server": {
+ "title": "내 서버 중계",
+ "version": "중계 버전 {{version}}",
+ "incomplete": "지난 배포가 끝나지 않았습니다. 다시 시도하거나 제거하세요.",
+ "upgrade": "{{version}}(으)로 업그레이드",
+ "uninstall": "서버에서 제거",
+ "uninstallTitle": "서버에서 중계를 제거할까요?",
+ "uninstallDescription": "서버의 중계와 기기 기록이 삭제되고, 사용 중인 기기는 연결이 끊어집니다. 다시 배포하면 모든 기기가 다시 참여해야 합니다.",
+ "forget": "이 컴퓨터에서만 제거",
+ "forgetTitle": "이 컴퓨터에서만 제거할까요?",
+ "forgetDescription": "서버의 중계는 그대로 실행되지만, 이 컴퓨터에서 더 이상 관리하거나 기기를 추가할 수 없습니다. 그 서버를 더 이상 쓰지 않을 때만 하세요."
+ }
+ },
"title": "원격 연결",
"description": "같은 계정의 기기를 서로 원격으로 제어하거나 SSH로 원격 호스트에 연결합니다.",
"accessRevokedByPeer": "액세스 권한이 철회되었습니다. 상대방이 설정에서 복원해야 합니다",
@@ -5577,6 +5743,7 @@
"restoreFailed": "복원에 실패했습니다"
},
"sections": {
+ "relay": "중계 서비스",
"myDevices": "내 기기",
"ssh": "SSH 원격 호스트",
"hook": "Cindy IM 봇"
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index aaf35373ed..fb7d12e903 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -5558,6 +5558,172 @@
}
},
"remoteControl": {
+ "relay": {
+ "summary": {
+ "official": "Cindy 官方中转",
+ "owner": "这台电脑当中转",
+ "member": "已加入 {{name}}",
+ "server": "服务器中转「{{name}}」"
+ },
+ "description": "设备之间的远程控制默认经 Cindy 官方中转。你也可以把中转部署到自己的服务器、让这台电脑当中转,或加入你自己另一台电脑上的中转。登录、模型等其他服务不受影响。",
+ "current": "当前使用",
+ "ownerName": "这台电脑",
+ "unavailable": "登录 Cindy 账号,并且系统钥匙串可用时,才能使用自己的中转。",
+ "limits": "使用自己的中转时,手机系统推送、供应商分享和共享任务暂不可用。",
+ "actions": {
+ "host": "在这台电脑上开启",
+ "join": "加入别的中转",
+ "useOfficial": "切回官方中转",
+ "editHost": "修改设置",
+ "deploy": "部署到我的服务器",
+ "useDeployment": "改用这个中转"
+ },
+ "host": {
+ "title": "在这台电脑上开启中转",
+ "hint": "其他设备要能访问到这台电脑:同一局域网、路由器端口映射、内网穿透或组网工具都可以,由你自己保证。这台电脑休眠或退出 Cindy 时,所有设备都会断开,开启后会自动打开「保持电脑唤醒」。",
+ "port": "端口",
+ "scope": "允许谁连接",
+ "scopeLocal": "仅本机",
+ "scopeAll": "所有网络",
+ "scopeLocalHint": "只接受本机连接,适合配合你自己的反向 Proxy、内网穿透或组网工具。",
+ "scopeAllHint": "局域网里的设备可以直接连接。连接不加密,只建议在可信网络中使用;手机需要 https 地址才能连接。",
+ "externalUrl": "其他设备访问的地址",
+ "externalUrlPlaceholder": "例如 https://relay.example.com",
+ "externalUrlHintAll": "会写进加入链接。不填时使用这台电脑的局域网地址。",
+ "externalUrlHintLocal": "会写进加入链接。填你的 Proxy 或穿透服务对外的地址。",
+ "suggested": "这台电脑的地址:",
+ "start": "开启",
+ "save": "保存并重启中转",
+ "cancel": "取消",
+ "running": "中转运行中,其他设备访问地址:{{address}}"
+ },
+ "add": {
+ "intro": "生成加入链接,让手机或另一台电脑加入这个中转。",
+ "create": "添加设备",
+ "hint": "用手机相机扫码,或把链接发给另一台电脑,在「加入别的中转」里粘贴。链接 10 分钟内有效,只能用一次。",
+ "qrAlt": "加入中转的二维码",
+ "copy": "复制链接",
+ "copied": "已复制加入链接",
+ "newLink": "重新生成",
+ "waiting": "等待设备申请…"
+ },
+ "requests": {
+ "item": "{{name}} 请求加入",
+ "verify": "配对码",
+ "verifyHint": "和对方屏幕上显示的一致再同意。",
+ "replaces": "这台设备之前加入过,同意后它的旧凭证失效。",
+ "approve": "同意",
+ "reject": "拒绝",
+ "unverified": "无法核对这台设备:它的申请和这台电脑给出的加入链接对不上,可能被人篡改,只能拒绝。如果是你自己的设备,请重新生成加入链接再试。"
+ },
+ "join": {
+ "title": "加入别的中转",
+ "hint": "粘贴主人电脑上「添加设备」给出的加入链接,等对方同意后自动切换。",
+ "placeholder": "粘贴加入链接",
+ "submit": "加入",
+ "connecting": "正在连接中转…",
+ "waiting": "已发出申请。请在 {{name}} 上核对这串数字并点同意:",
+ "cancel": "取消"
+ },
+ "issue": {
+ "removed": "这台电脑已被移出中转,或中转已停用。",
+ "unauthorized": "中转不再接受这台电脑的凭证。",
+ "next": "可以重新加入,或切回官方中转。"
+ },
+ "confirm": {
+ "ownerTitle": "停用这台电脑上的中转?",
+ "ownerDescription": "已加入的设备会断开,并提示中转已停用。这台电脑切回 Cindy 官方中转。",
+ "memberTitle": "切回官方中转?",
+ "memberDescription": "这台电脑会退出「{{name}}」,改用 Cindy 官方中转。之后要再加入,需要对方重新生成加入链接。",
+ "serverTitle": "切回官方中转?",
+ "serverDescription": "服务器上的中转「{{name}}」会继续运行,已加入的其他设备仍能通过它互相连接。这台电脑随时可以改回来。"
+ },
+ "errors": {
+ "INVALID_LINK": "加入链接或地址格式不正确。",
+ "UNREACHABLE": "连不上这个中转。请确认这台电脑能访问链接里的地址。",
+ "NOT_A_RELAY": "这个地址不是 Cindy 中转。",
+ "INCOMPATIBLE": "这个中转的版本与本机不兼容,请把两边的 Cindy 都更新到最新版。",
+ "ACCOUNT_MISMATCH": "这个中转属于另一个 Cindy 账号。",
+ "CODE_INVALID": "加入链接已失效或已被使用,请让对方重新生成。",
+ "RATE_LIMITED": "尝试次数太多,请过几分钟再试。",
+ "REJECTED": "对方拒绝了这次加入。",
+ "EXPIRED": "等待同意超时,请重新加入。",
+ "CANCELLED": "已取消。",
+ "FAILED": "操作没有完成。",
+ "HOSTING": "这台电脑正在当中转。要加入别的中转,请先切回官方中转。",
+ "NOT_SIGNED_IN": "请先登录 Cindy 账号。",
+ "SECURE_STORAGE_UNAVAILABLE": "系统钥匙串不可用,无法安全保存中转凭证。",
+ "PORT_IN_USE": "端口 {{port}} 已被占用,请换一个端口。",
+ "START_FAILED": "中转没能启动,可以换一个端口再试。",
+ "EXTERNAL_URL_REQUIRED": "请先填写其他设备访问的地址,或把「允许谁连接」改为所有网络。",
+ "SSH_FAILED": "连不上服务器。请在「远程」里检查这台服务器的 SSH 设置。",
+ "NEEDS_ROOT": "需要 root 账号,或这个账号能免密码使用 sudo。Cindy 不会索要服务器密码。",
+ "UNSUPPORTED_SYSTEM": "目前只支持带 systemd 的 64 位 Linux(x64 / arm64),并且需要 curl 或 wget。",
+ "PORT_BUSY": "服务器的 80 或 443 端口已被其他程序占用(例如网站服务)。请先停用它,或换一台服务器。",
+ "DOWNLOAD_FAILED": "服务器下载运行环境失败(官方源和国内镜像都没成功)。请检查服务器能否访问外网。",
+ "RELAY_MISMATCH": "这台服务器上已有一个不是这台电脑部署的中转。可以清除它后重新部署。",
+ "CERTIFICATE_FAILED": "申请 HTTPS 证书失败。通常是云服务器安全组没有放行 80 端口,或域名还没解析到这台服务器。处理后点重试。",
+ "NOT_REACHABLE": "服务器上的中转已经运行,但这台电脑连不上它。请在云服务器安全组里放行 443 端口。",
+ "BUNDLE_MISSING": "这个版本的 Cindy 没有带中转程序,请更新 Cindy。",
+ "DEPLOY_FAILED": "部署没有完成。",
+ "PAIR_PROOF_INVALID": "无法核对这台设备的申请,不能同意。请重新生成加入链接。",
+ "NOT_OWNER": "只有部署或开启这个中转的电脑才能管理它。",
+ "BUSY": "正在部署,请稍候。",
+ "INVALID_ADDRESS": "请填写公网 IP 或域名,不带 http:// 和端口。",
+ "NO_DEPLOYMENT": "还没有部署到服务器。",
+ "OWNER_MISMATCH": "中转返回的证书不是加入链接里的主人签发的,可能连到了别人伪造的中转,已停止加入。"
+ },
+ "deploy": {
+ "title": "部署到我的服务器",
+ "hint": "把中转装到你自己的 Linux 服务器上,手机和不在同一网络的设备都能连。Cindy 通过「远程」里配置的 SSH 连接安装,并自动申请 HTTPS 证书、到期前自动续期。",
+ "requirements": "需要:64 位 Linux(带 systemd)、root 或免密 sudo,服务器的 80 和 443 端口没被其他程序占用,并在云服务器控制台的安全组或防火墙里放行 TCP 80 和 443。",
+ "noHosts": "还没有可用的服务器。先在「远程」里添加 SSH 主机,再回来部署。",
+ "server": "服务器",
+ "address": "访问地址",
+ "addressPlaceholder": "公网 IP 或域名,例如 203.0.113.10",
+ "addressHint": "其他设备连接中转用的地址。填公网 IP 会申请 6 天有效、自动续期的 IP 证书;填域名需要先把域名解析到这台服务器。",
+ "name": "名称",
+ "defaultName": "我的中转",
+ "submit": "开始部署",
+ "cancel": "取消",
+ "detail": "详细原因:{{detail}}",
+ "retry": "重试",
+ "replace": "清除旧中转并重新部署",
+ "running": {
+ "deploy": "正在部署到服务器…",
+ "upgrade": "正在升级服务器上的中转…",
+ "uninstall": "正在从服务器卸载…"
+ },
+ "done": {
+ "deploy": "部署完成,这台电脑已改用服务器上的中转。用「添加设备」让手机和其他电脑加入。",
+ "upgrade": "服务器上的中转已升级到 {{version}}。",
+ "uninstall": "已从服务器卸载中转。"
+ },
+ "steps": {
+ "connect": "连接服务器",
+ "check": "检查系统和端口",
+ "runtime": "安装运行环境",
+ "upload": "上传中转程序",
+ "configure": "配置并启动服务",
+ "certificate": "申请 HTTPS 证书",
+ "verify": "从这台电脑检查能否连上",
+ "finish": "完成",
+ "remove": "停止服务并删除文件"
+ }
+ },
+ "server": {
+ "title": "我的服务器中转",
+ "version": "中转版本 {{version}}",
+ "incomplete": "上次部署没有完成,可以重试或卸载。",
+ "upgrade": "升级到 {{version}}",
+ "uninstall": "从服务器卸载",
+ "uninstallTitle": "从服务器卸载中转?",
+ "uninstallDescription": "服务器上的中转程序和设备档案都会被删除,正在用它的设备会断开。之后重新部署,所有设备都需要重新加入。",
+ "forget": "只在本机移除",
+ "forgetTitle": "只在这台电脑上移除?",
+ "forgetDescription": "服务器上的中转不会被删除,但这台电脑不再管理它,也不能再为它添加设备。确定不再使用那台服务器时再这样做。"
+ }
+ },
"title": "远程连接",
"description": "在同账号的设备之间互相远程操控,或通过 SSH 连接远端主机。",
"accessRevokedByPeer": "访问权限已被撤销,需对方在选项中恢复",
@@ -5577,6 +5743,7 @@
"restoreFailed": "恢复失败"
},
"sections": {
+ "relay": "中转服务",
"myDevices": "我的设备",
"ssh": "SSH 远程主机",
"hook": "Cindy IM 机器人"
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index 565e46a6aa..b107446d26 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -5558,6 +5558,172 @@
}
},
"remoteControl": {
+ "relay": {
+ "summary": {
+ "official": "Cindy 官方中繼",
+ "owner": "這台電腦當中繼",
+ "member": "已加入 {{name}}",
+ "server": "伺服器中繼「{{name}}」"
+ },
+ "description": "裝置之間的遠端控制預設經 Cindy 官方中繼。你也可以把中繼部署到自己的伺服器、讓這台電腦當中繼,或加入你自己另一台電腦上的中繼。登入、模型等其他服務不受影響。",
+ "current": "目前使用",
+ "ownerName": "這台電腦",
+ "unavailable": "登入 Cindy 帳號,並且系統鑰匙圈可用時,才能使用自己的中繼。",
+ "limits": "使用自己的中繼時,手機系統推播、供應商分享和共享任務暫不可用。",
+ "actions": {
+ "host": "在這台電腦上開啟",
+ "join": "加入別的中繼",
+ "useOfficial": "切回官方中繼",
+ "editHost": "修改設定",
+ "deploy": "部署到我的伺服器",
+ "useDeployment": "改用這個中繼"
+ },
+ "host": {
+ "title": "在這台電腦上開啟中繼",
+ "hint": "其他裝置要能連到這台電腦:同一區域網路、路由器連接埠轉送、內網穿透或組網工具都可以,由你自己確保。這台電腦休眠或結束 Cindy 時,所有裝置都會斷線,開啟後會自動開啟「保持電腦喚醒」。",
+ "port": "連接埠",
+ "scope": "允許誰連線",
+ "scopeLocal": "僅本機",
+ "scopeAll": "所有網路",
+ "scopeLocalHint": "只接受本機連線,適合搭配你自己的反向 Proxy、內網穿透或組網工具。",
+ "scopeAllHint": "區域網路裡的裝置可以直接連線。連線不加密,只建議在可信任的網路中使用;手機需要 https 位址才能連線。",
+ "externalUrl": "其他裝置連線的位址",
+ "externalUrlPlaceholder": "例如 https://relay.example.com",
+ "externalUrlHintAll": "會寫進加入連結。不填時使用這台電腦的區域網路位址。",
+ "externalUrlHintLocal": "會寫進加入連結。填你的 Proxy 或穿透服務對外的位址。",
+ "suggested": "這台電腦的位址:",
+ "start": "開啟",
+ "save": "儲存並重新啟動中繼",
+ "cancel": "取消",
+ "running": "中繼執行中,其他裝置連線位址:{{address}}"
+ },
+ "add": {
+ "intro": "產生加入連結,讓手機或另一台電腦加入這個中繼。",
+ "create": "新增裝置",
+ "hint": "用手機相機掃描,或把連結傳給另一台電腦,在「加入別的中繼」裡貼上。連結 10 分鐘內有效,只能用一次。",
+ "qrAlt": "加入中繼的 QR 碼",
+ "copy": "複製連結",
+ "copied": "已複製加入連結",
+ "newLink": "重新產生",
+ "waiting": "等待裝置申請…"
+ },
+ "requests": {
+ "item": "{{name}} 請求加入",
+ "verify": "配對碼",
+ "verifyHint": "和對方螢幕上顯示的一致再同意。",
+ "replaces": "這台裝置之前加入過,同意後它的舊憑證失效。",
+ "approve": "同意",
+ "reject": "拒絕",
+ "unverified": "無法核對這台裝置:它的申請和這台電腦給出的加入連結對不上,可能被人竄改,只能拒絕。如果是你自己的裝置,請重新產生加入連結再試。"
+ },
+ "join": {
+ "title": "加入別的中繼",
+ "hint": "貼上主人電腦上「新增裝置」給出的加入連結,等對方同意後自動切換。",
+ "placeholder": "貼上加入連結",
+ "submit": "加入",
+ "connecting": "正在連線中繼…",
+ "waiting": "已送出申請。請在 {{name}} 上核對這串數字並按同意:",
+ "cancel": "取消"
+ },
+ "issue": {
+ "removed": "這台電腦已被移出中繼,或中繼已停用。",
+ "unauthorized": "中繼不再接受這台電腦的憑證。",
+ "next": "可以重新加入,或切回官方中繼。"
+ },
+ "confirm": {
+ "ownerTitle": "停用這台電腦上的中繼?",
+ "ownerDescription": "已加入的裝置會斷線,並提示中繼已停用。這台電腦切回 Cindy 官方中繼。",
+ "memberTitle": "切回官方中繼?",
+ "memberDescription": "這台電腦會退出「{{name}}」,改用 Cindy 官方中繼。之後要再加入,需要對方重新產生加入連結。",
+ "serverTitle": "切回官方中繼?",
+ "serverDescription": "伺服器上的中繼「{{name}}」會繼續執行,已加入的其他裝置仍能透過它互相連線。這台電腦隨時可以改回來。"
+ },
+ "errors": {
+ "INVALID_LINK": "加入連結或位址格式不正確。",
+ "UNREACHABLE": "連不上這個中繼。請確認這台電腦能連到連結裡的位址。",
+ "NOT_A_RELAY": "這個位址不是 Cindy 中繼。",
+ "INCOMPATIBLE": "這個中繼的版本與本機不相容,請把兩邊的 Cindy 都更新到最新版。",
+ "ACCOUNT_MISMATCH": "這個中繼屬於另一個 Cindy 帳號。",
+ "CODE_INVALID": "加入連結已失效或已被使用,請讓對方重新產生。",
+ "RATE_LIMITED": "嘗試次數太多,請過幾分鐘再試。",
+ "REJECTED": "對方拒絕了這次加入。",
+ "EXPIRED": "等待同意逾時,請重新加入。",
+ "CANCELLED": "已取消。",
+ "FAILED": "操作沒有完成。",
+ "HOSTING": "這台電腦正在當中繼。要加入別的中繼,請先切回官方中繼。",
+ "NOT_SIGNED_IN": "請先登入 Cindy 帳號。",
+ "SECURE_STORAGE_UNAVAILABLE": "系統鑰匙圈不可用,無法安全保存中繼憑證。",
+ "PORT_IN_USE": "連接埠 {{port}} 已被占用,請換一個連接埠。",
+ "START_FAILED": "中繼沒能啟動,可以換一個連接埠再試。",
+ "EXTERNAL_URL_REQUIRED": "請先填寫其他裝置連線的位址,或把「允許誰連線」改為所有網路。",
+ "SSH_FAILED": "連不上伺服器。請在「遠端」裡檢查這台伺服器的 SSH 設定。",
+ "NEEDS_ROOT": "需要 root 帳號,或這個帳號能免密碼使用 sudo。Cindy 不會索取伺服器密碼。",
+ "UNSUPPORTED_SYSTEM": "目前只支援含 systemd 的 64 位元 Linux(x64 / arm64),並且需要 curl 或 wget。",
+ "PORT_BUSY": "伺服器的 80 或 443 連接埠已被其他程式佔用(例如網站服務)。請先停用它,或換一台伺服器。",
+ "DOWNLOAD_FAILED": "伺服器下載執行環境失敗(官方來源和鏡像都沒成功)。請檢查伺服器能否連上外網。",
+ "RELAY_MISMATCH": "這台伺服器上已有一個不是這台電腦部署的中繼。可以清除它後重新部署。",
+ "CERTIFICATE_FAILED": "申請 HTTPS 憑證失敗。通常是雲端主機安全群組沒有放行 80 連接埠,或網域還沒解析到這台伺服器。處理後點重試。",
+ "NOT_REACHABLE": "伺服器上的中繼已經執行,但這台電腦連不上它。請在雲端主機安全群組裡放行 443 連接埠。",
+ "BUNDLE_MISSING": "這個版本的 Cindy 沒有附帶中繼程式,請更新 Cindy。",
+ "DEPLOY_FAILED": "部署沒有完成。",
+ "PAIR_PROOF_INVALID": "無法核對這台裝置的申請,不能同意。請重新產生加入連結。",
+ "NOT_OWNER": "只有部署或開啟這個中繼的電腦才能管理它。",
+ "BUSY": "正在部署,請稍候。",
+ "INVALID_ADDRESS": "請填寫公網 IP 或網域,不含 http:// 和連接埠。",
+ "NO_DEPLOYMENT": "還沒有部署到伺服器。",
+ "OWNER_MISMATCH": "中繼回傳的憑證不是加入連結裡的主人簽發的,可能連到了別人偽造的中繼,已停止加入。"
+ },
+ "deploy": {
+ "title": "部署到我的伺服器",
+ "hint": "把中繼裝到你自己的 Linux 伺服器上,手機和不在同一網路的裝置都能連。Cindy 透過「遠端」裡設定的 SSH 連線安裝,並自動申請 HTTPS 憑證、到期前自動續期。",
+ "requirements": "需要:64 位元 Linux(含 systemd)、root 或免密碼 sudo,伺服器的 80 和 443 連接埠沒被其他程式佔用,並在雲端主機控制台的安全群組或防火牆裡放行 TCP 80 和 443。",
+ "noHosts": "還沒有可用的伺服器。先在「遠端」裡新增 SSH 主機,再回來部署。",
+ "server": "伺服器",
+ "address": "存取位址",
+ "addressPlaceholder": "公網 IP 或網域,例如 203.0.113.10",
+ "addressHint": "其他裝置連線中繼用的位址。填公網 IP 會申請 6 天有效、自動續期的 IP 憑證;填網域需要先把網域解析到這台伺服器。",
+ "name": "名稱",
+ "defaultName": "我的中繼",
+ "submit": "開始部署",
+ "cancel": "取消",
+ "detail": "詳細原因:{{detail}}",
+ "retry": "重試",
+ "replace": "清除舊中繼並重新部署",
+ "running": {
+ "deploy": "正在部署到伺服器…",
+ "upgrade": "正在升級伺服器上的中繼…",
+ "uninstall": "正在從伺服器解除安裝…"
+ },
+ "done": {
+ "deploy": "部署完成,這台電腦已改用伺服器上的中繼。用「新增裝置」讓手機和其他電腦加入。",
+ "upgrade": "伺服器上的中繼已升級到 {{version}}。",
+ "uninstall": "已從伺服器解除安裝中繼。"
+ },
+ "steps": {
+ "connect": "連線伺服器",
+ "check": "檢查系統和連接埠",
+ "runtime": "安裝執行環境",
+ "upload": "上傳中繼程式",
+ "configure": "設定並啟動服務",
+ "certificate": "申請 HTTPS 憑證",
+ "verify": "從這台電腦檢查能否連上",
+ "finish": "完成",
+ "remove": "停止服務並刪除檔案"
+ }
+ },
+ "server": {
+ "title": "我的伺服器中繼",
+ "version": "中繼版本 {{version}}",
+ "incomplete": "上次部署沒有完成,可以重試或解除安裝。",
+ "upgrade": "升級到 {{version}}",
+ "uninstall": "從伺服器解除安裝",
+ "uninstallTitle": "從伺服器解除安裝中繼?",
+ "uninstallDescription": "伺服器上的中繼程式和裝置檔案都會被刪除,正在使用它的裝置會斷線。之後重新部署,所有裝置都需要重新加入。",
+ "forget": "只在本機移除",
+ "forgetTitle": "只在這台電腦上移除?",
+ "forgetDescription": "伺服器上的中繼不會被刪除,但這台電腦不再管理它,也不能再為它新增裝置。確定不再使用那台伺服器時再這樣做。"
+ }
+ },
"title": "遠端連線",
"description": "在同帳號的裝置之間互相遠端操控,或透過 SSH 連線遠端主機。",
"accessRevokedByPeer": "訪問權限已被撤銷,需對方在選項中恢復",
@@ -5577,6 +5743,7 @@
"restoreFailed": "恢復失敗"
},
"sections": {
+ "relay": "中繼服務",
"myDevices": "我的裝置",
"ssh": "SSH 遠端主機",
"hook": "Cindy IM 機器人"
diff --git a/apps/desktop/src/renderer/vite-env.d.ts b/apps/desktop/src/renderer/vite-env.d.ts
index 51ff58a86b..60839b895d 100644
--- a/apps/desktop/src/renderer/vite-env.d.ts
+++ b/apps/desktop/src/renderer/vite-env.d.ts
@@ -4116,6 +4116,7 @@ interface ElectronAPI {
openRemoteDesktop: (target: { deviceId: string; name: string; handoff?: string }) => Promise<void>;
remoteDesktopViewer: import('../shared/remoteDesktopViewer').RemoteDesktopViewerApi;
remoteDesktop: import('../shared/remoteDesktop').RemoteDesktopApi;
+ selfHostedRelay: import('../shared/selfHostedRelay').SelfHostedRelayApi;
sharedTask: {
host(command: import('@cindy/device-link').SharedTaskHostCommand): Promise<unknown>;
account(command: import('@cindy/device-link').SharedTaskAccountCommand): Promise<unknown>;
diff --git a/apps/desktop/src/shared/selfHostedRelay.ts b/apps/desktop/src/shared/selfHostedRelay.ts
new file mode 100644
index 0000000000..30f5900c1f
--- /dev/null
+++ b/apps/desktop/src/shared/selfHostedRelay.ts
@@ -0,0 +1,244 @@
+/**
+ * 自建中转服务:main / preload / renderer 共用的 IPC 契约。
+ * 方案见 docs/self-hosted-relay-plan.md。只接受本机应用窗口调用,不经设备互联代理。
+ */
+import type { RelayJoinErrorCode } from '@cindy/device-link';
+
+export const SELF_HOSTED_RELAY_IPC = {
+ COMMAND: 'self-hosted-relay:command',
+ CHANGED: 'self-hosted-relay:changed',
+} as const;
+
+export const DEFAULT_RELAY_PORT = 47820;
+
+export type SelfHostedRelayCommand =
+ | { type: 'state' }
+ /** 在这台电脑上开启中转;已开启时按新设置重启。 */
+ | { type: 'enable-host'; port: number; listenAll: boolean; externalUrl: string | null }
+ /** 停用本机中转,并切回官方中转。 */
+ | { type: 'disable-host' }
+ /** 生成一次性加入链接(10 分钟有效)。 */
+ | { type: 'create-join-link' }
+ | { type: 'decide'; requestId: string; approve: boolean }
+ /** 加入别的中转:粘贴主人电脑给出的加入链接。 */
+ | { type: 'join'; link: string }
+ | { type: 'cancel-join' }
+ /** 切回 Cindy 官方中转(成员退出中转;主人停用本机中转;服务器上的中转继续运行)。 */
+ | { type: 'use-official' }
+ /**
+ * 部署到自己的服务器(经已配置的 SSH 主机)。`address` 是其他设备访问用的域名或公网 IP,证书签给它。
+ * `replaceExisting`:服务器上已有不属于这台电脑的中转时,清掉它重新部署。
+ */
+ | { type: 'deploy'; sshHostId: string; address: string; name: string; replaceExisting: boolean }
+ /** 把服务器上的中转升级到这个版本 Cindy 自带的版本(保留已加入的设备)。 */
+ | { type: 'upgrade-deployment' }
+ /** 从服务器卸载中转;`removeData` 同时删除设备档案(已加入的设备需要重新加入)。 */
+ | { type: 'uninstall-deployment'; removeData: boolean }
+ /** 服务器已不可用时,只在本机删掉部署记录。 */
+ | { type: 'forget-deployment' }
+ /** 改回使用服务器上的中转(之前切回过官方中转)。 */
+ | { type: 'use-deployment' };
+
+/** 部署的步骤(界面逐步展示)。 */
+export type RelayDeployStep =
+ | 'connect'
+ | 'check'
+ | 'runtime'
+ | 'upload'
+ | 'configure'
+ | 'certificate'
+ | 'verify'
+ | 'finish';
+
+export const RELAY_DEPLOY_STEPS: readonly RelayDeployStep[] = [
+ 'connect',
+ 'check',
+ 'runtime',
+ 'upload',
+ 'configure',
+ 'certificate',
+ 'verify',
+ 'finish',
+];
+
+export type RelayDeployErrorCode =
+ /** 连不上 SSH 主机(未配置、离线、认证失败)。 */
+ | 'SSH_FAILED'
+ /** 需要 root 或免密 sudo。 */
+ | 'NEEDS_ROOT'
+ /** 只支持带 systemd 的 64 位 Linux(x64 / arm64)。 */
+ | 'UNSUPPORTED_SYSTEM'
+ /** 80 或 443 端口被其他程序占用。 */
+ | 'PORT_BUSY'
+ /** 下载运行环境失败(官方源与国内镜像都失败,或校验不符)。 */
+ | 'DOWNLOAD_FAILED'
+ /** 服务器上已有不属于这台电脑的中转。 */
+ | 'RELAY_MISMATCH'
+ /** 证书申请失败(通常是 80 端口没对外开放,或域名没解析到这台服务器)。 */
+ | 'CERTIFICATE_FAILED'
+ /** 服务器上中转已运行,但这台电脑访问不到(通常是 443 端口没对外开放)。 */
+ | 'NOT_REACHABLE'
+ /** 这个版本的 Cindy 没有带中转程序(开发环境未构建)。 */
+ | 'BUNDLE_MISSING'
+ | 'DEPLOY_FAILED';
+
+export type SelfHostedRelayErrorCode =
+ | RelayJoinErrorCode
+ | RelayDeployErrorCode
+ | 'INVALID_LINK'
+ | 'NOT_SIGNED_IN'
+ | 'HOSTING'
+ | 'SECURE_STORAGE_UNAVAILABLE'
+ | 'PORT_IN_USE'
+ | 'START_FAILED'
+ | 'EXTERNAL_URL_REQUIRED'
+ /** 申请里的配对证明对不上这台电脑生成的加入链接:不能同意。 */
+ | 'PAIR_PROOF_INVALID'
+ /** 只有主人电脑能做这件事。 */
+ | 'NOT_OWNER'
+ /** 已有部署任务在进行。 */
+ | 'BUSY'
+ | 'INVALID_ADDRESS'
+ | 'NO_DEPLOYMENT';
+
+export interface SelfHostedRelayPairRequestView {
+ requestId: string;
+ deviceName: string;
+ platform: string | null;
+ verifyCode: string;
+ replacesExisting: boolean;
+ /** 配对证明与这台电脑生成的加入链接一致;为 false 时只能拒绝。 */
+ verified: boolean;
+}
+
+export type SelfHostedRelayJoinView =
+ | { status: 'idle' }
+ | { status: 'connecting' }
+ | { status: 'waiting'; relayName: string; verifyCode: string }
+ | { status: 'joined'; relayName: string }
+ | { status: 'failed'; error: SelfHostedRelayErrorCode };
+
+export interface SelfHostedRelayDeployJobView {
+ action: 'deploy' | 'upgrade' | 'uninstall';
+ step: RelayDeployStep;
+ status: 'running' | 'failed' | 'done';
+ error?: SelfHostedRelayErrorCode;
+ /** 失败时给用户看的补充信息(端口、服务器返回的原因),不含秘密。 */
+ detail?: string;
+}
+
+export interface SelfHostedRelayDeploymentView {
+ sshHostId: string;
+ address: string;
+ baseUrl: string;
+ name: string;
+ relayVersion: string;
+ deployedAt: string;
+ /** 这台电脑当前正在用它。 */
+ active: boolean;
+ /** 这个版本 Cindy 带的中转版本不同,可以升级。 */
+ upgradeAvailable: boolean;
+}
+
+export interface SelfHostedRelayState {
+ /** 已登录且系统安全存储可用。 */
+ available: boolean;
+ mode: 'official' | 'self-hosted';
+ relay: { name: string; baseUrl: string; role: 'owner' | 'member'; origin: 'host' | 'server' | 'join' } | null;
+ /** 自建模式下的连接情况:设备被移出中转 / 凭证被拒。 */
+ issue: 'removed' | 'unauthorized' | null;
+ host: {
+ enabled: boolean;
+ running: boolean;
+ error: SelfHostedRelayErrorCode | null;
+ port: number;
+ listenAll: boolean;
+ externalUrl: string | null;
+ /** 本机局域网地址(含端口),用于填写对外地址。 */
+ suggestedUrls: string[];
+ };
+ deployment: SelfHostedRelayDeploymentView | null;
+ deployJob: SelfHostedRelayDeployJobView | null;
+ /** 这个版本 Cindy 自带的中转版本;null = 没带(开发环境未构建)。 */
+ bundledRelayVersion: string | null;
+ joinLink: { link: string; expiresAt: string } | null;
+ pendingRequests: SelfHostedRelayPairRequestView[];
+ join: SelfHostedRelayJoinView;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+const SSH_HOST_ID_PATTERN = /^[A-Za-z0-9._@:-]{1,128}$/;
+
+/** 访问地址:域名或 IP(不带协议、端口、路径)。 */
+export function normalizeRelayAddress(value: string): string | null {
+ const trimmed = value.trim().toLowerCase().replace(/^\[|\]$/g, '');
+ if (!trimmed || trimmed.length > 253) return null;
+ if (/^\d{1,3}(\.\d{1,3}){3}$/.test(trimmed)) {
+ return trimmed.split('.').every((part) => Number(part) <= 255) ? trimmed : null;
+ }
+ if (trimmed.includes(':')) return /^[0-9a-f:]+$/.test(trimmed) && trimmed.split(':').length <= 8 ? trimmed : null;
+ return /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(trimmed) ? trimmed : null;
+}
+
+/** 访问地址对应的 https 基础地址(IPv6 加方括号)。 */
+export function relayBaseUrlForAddress(address: string): string {
+ return address.includes(':') ? `https://[${address}]` : `https://${address}`;
+}
+
+/** 校验来自 renderer 的命令;不合法时返回 null。 */
+export function parseSelfHostedRelayCommand(raw: unknown): SelfHostedRelayCommand | null {
+ if (!isRecord(raw) || typeof raw.type !== 'string') return null;
+ switch (raw.type) {
+ case 'state':
+ case 'disable-host':
+ case 'create-join-link':
+ case 'cancel-join':
+ case 'use-official':
+ case 'upgrade-deployment':
+ case 'forget-deployment':
+ case 'use-deployment':
+ return { type: raw.type };
+ case 'enable-host': {
+ const port = raw.port;
+ if (typeof port !== 'number' || !Number.isInteger(port) || port < 1024 || port > 65535) return null;
+ if (typeof raw.listenAll !== 'boolean') return null;
+ const externalUrl = raw.externalUrl;
+ if (externalUrl !== null && (typeof externalUrl !== 'string' || externalUrl.length > 512)) return null;
+ return { type: 'enable-host', port, listenAll: raw.listenAll, externalUrl: externalUrl?.trim() || null };
+ }
+ case 'decide':
+ if (typeof raw.requestId !== 'string' || !/^[0-9a-f-]{36}$/.test(raw.requestId)) return null;
+ if (typeof raw.approve !== 'boolean') return null;
+ return { type: 'decide', requestId: raw.requestId, approve: raw.approve };
+ case 'join':
+ if (typeof raw.link !== 'string' || raw.link.length > 2048) return null;
+ return { type: 'join', link: raw.link };
+ case 'deploy': {
+ if (typeof raw.sshHostId !== 'string' || !SSH_HOST_ID_PATTERN.test(raw.sshHostId)) return null;
+ if (typeof raw.address !== 'string' || typeof raw.name !== 'string' || typeof raw.replaceExisting !== 'boolean') return null;
+ const address = normalizeRelayAddress(raw.address);
+ const name = raw.name.trim();
+ if (!address || !name || name.length > 64) return null;
+ return { type: 'deploy', sshHostId: raw.sshHostId, address, name, replaceExisting: raw.replaceExisting };
+ }
+ case 'uninstall-deployment':
+ if (typeof raw.removeData !== 'boolean') return null;
+ return { type: 'uninstall-deployment', removeData: raw.removeData };
+ default:
+ return null;
+ }
+}
+
+export interface SelfHostedRelayCommandResult {
+ state: SelfHostedRelayState;
+ error?: SelfHostedRelayErrorCode;
+}
+
+/** `window.electronAPI.selfHostedRelay`。 */
+export interface SelfHostedRelayApi {
+ command(command: SelfHostedRelayCommand): Promise<SelfHostedRelayCommandResult>;
+ onChanged(cb: (state: SelfHostedRelayState) => void): () => void;
+}
diff --git a/apps/mobile/app/+native-intent.ts b/apps/mobile/app/+native-intent.ts
index 8aef3e24ae..74563f57eb 100644
--- a/apps/mobile/app/+native-intent.ts
+++ b/apps/mobile/app/+native-intent.ts
@@ -20,6 +20,7 @@ import {
PROVIDER_SHARE_LINK_ROUTE,
receiveProviderShareLinkIntent,
} from '@/device-link/providerShareLinkIntent';
+import { isRelayJoinPath, RELAY_JOIN_ROUTE, receiveRelayJoinIntent } from '@/device-link/relayJoinIntent';
import { WECHAT_APP_ID, WECHAT_UNIVERSAL_LINK } from '@/config/env';
import { isWechatSdkCallback } from '@/auth/wechatCallback';
@@ -35,6 +36,9 @@ export function redirectSystemPath({ path, initial }: { path: string; initial: b
// 供应商分享链接只能在电脑上申请:手机只显示「请在电脑上打开」的提示页。口令不进路由
// 状态与诊断(提示页从内存取走可复制的链接),不合法的链接同样落到提示页、什么都不留。
if (receiveProviderShareLinkIntent(path)) return PROVIDER_SHARE_LINK_ROUTE;
+ // 加入自建中转(扫电脑上的二维码):加入码只留在内存,加入页不带参数;不合法的链接同样
+ // 落到加入页显示「链接无效」,什么都不留。
+ if (receiveRelayJoinIntent(path)) return RELAY_JOIN_ROUTE;
const invitationUrl = /^\/(?:shared-session|shared-task\/join)\?/.test(path) ? `cindy:/${path}` : path;
if (receiveSharedTaskInvitationIntent(invitationUrl)) return '/shared-session';
// path 可能是完整 URL('cindycn://auth?code=...')或路径('/auth?code=...'),统一取出 pathname。
@@ -54,7 +58,8 @@ export function redirectSystemPath({ path, initial }: { path: string; initial: b
}
return path;
} catch {
- // 分享口令绝不随原始链接进路由状态。
- return isProviderShareLinkPath(path) ? PROVIDER_SHARE_LINK_ROUTE : path;
+ // 分享口令与中转加入码绝不随原始链接进路由状态。
+ if (isProviderShareLinkPath(path)) return PROVIDER_SHARE_LINK_ROUTE;
+ return isRelayJoinPath(path) ? RELAY_JOIN_ROUTE : path;
}
}
diff --git a/apps/mobile/app/_layout.tsx b/apps/mobile/app/_layout.tsx
index 43764df447..6fef082536 100644
--- a/apps/mobile/app/_layout.tsx
+++ b/apps/mobile/app/_layout.tsx
@@ -83,6 +83,7 @@ import {
} from '@/session/precreatedWorktreeRecovery';
import { IncomingShareBridge } from '@/session/IncomingShareBridge';
import { usePendingSharedTaskInvitationIntent } from '@/device-link/sharedTaskInvitationIntent';
+import { usePendingRelayJoinIntent } from '@/device-link/relayJoinIntent';
import { removeLegacyClipboardInvitationHistory } from '@/device-link/legacyClipboardInvitationHistory';
import { useHomeStartupSplashRelease } from '@/session/useHomeMode';
import { RemoteDesktopHost } from '@/remote-desktop/RemoteDesktopHost';
@@ -91,6 +92,8 @@ const holdSplash = () => undefined;
function NavigationGate() {
const pendingSharedTaskInvitation = usePendingSharedTaskInvitationIntent();
+ // 登录前扫了「加入中转」二维码:登录完成后回到加入页继续(加入码只在内存里)。
+ const pendingRelayJoin = Boolean(usePendingRelayJoinIntent()?.link);
const windowGeometry = useAdaptiveWindow();
// Establish chrome before push starts, rather than revealing a hidden bar after mount.
const sessionHeaderShown = Platform.OS === 'ios'
@@ -135,17 +138,24 @@ function NavigationGate() {
if (!auth.initialized) return;
const inAuthGroup = segments[0] === '(auth)';
// 供应商分享链接的提示页只说明「请在电脑上打开」,不读账号数据,未登录也直接显示。
- if (!auth.isAuthenticated && !inAuthGroup && segments[0] !== 'provider-share') {
+ // 加入中转页未登录时只提示先登录(不发任何请求),同样直接显示。
+ if (
+ !auth.isAuthenticated &&
+ !inAuthGroup &&
+ segments[0] !== 'provider-share' &&
+ segments[0] !== 'relay-join'
+ ) {
router.replace('/login');
return;
}
if (auth.isAuthenticated && inAuthGroup) {
if (pendingSharedTaskInvitation) router.replace('/shared-session');
+ else if (pendingRelayJoin) router.replace('/relay-join');
else router.replace('/');
} else if (auth.isAuthenticated && pendingSharedTaskInvitation && segments.join('/') !== 'shared-session') {
router.replace('/shared-session');
}
- }, [auth.initialized, auth.isAuthenticated, pendingSharedTaskInvitation, router, segments]);
+ }, [auth.initialized, auth.isAuthenticated, pendingRelayJoin, pendingSharedTaskInvitation, router, segments]);
useEffect(() => {
if (!auth.isAuthenticated || !auth.accountDeletionRestored) return;
diff --git a/apps/mobile/app/relay-join.tsx b/apps/mobile/app/relay-join.tsx
new file mode 100644
index 0000000000..49984a079c
--- /dev/null
+++ b/apps/mobile/app/relay-join.tsx
@@ -0,0 +1,457 @@
+/**
+ * 加入自建中转(docs/self-hosted-relay-plan.md §5.1):手机用系统相机扫电脑上的加入二维码,
+ * 深链经 +native-intent 把链接留在内存(加入码不进路由状态),这里不带参数打开。
+ *
+ * 流程:探测中转(relay/info)→ 用户点「加入」→ 生成本机签名密钥,提交加入申请(上报与官方登录相同的
+ * 设备 ID、当前账号、签名公钥和用链接里的配对秘密做的证明)→ 显示 4 位配对码,等主人在中转所在的电脑上
+ * 核对并同意 → 用链接里的主人公钥核对证书(不是主人签发的就不加入,§16)→ 凭证与签名种子存进安全存储、
+ * 切换到这个中转。凭证和种子只交给 saveSelfHostedRelay,不进状态、日志或界面。
+ */
+import Constants from 'expo-constants';
+import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
+import { ActivityIndicator, Platform, ScrollView, StyleSheet, View } from 'react-native';
+import { SafeAreaView } from 'react-native-safe-area-context';
+import { useRouter } from 'expo-router';
+import { useTranslation } from 'react-i18next';
+import { CircleAlert, CircleCheck, Server } from 'lucide-react-native';
+import {
+ acceptRelayDeviceCert,
+ createRelayJoinIdentity,
+ fetchRelayInfo,
+ RelayJoinError,
+ submitRelayPairRequest,
+ waitForRelayApproval,
+ type RelayInfo,
+ type RelayJoinErrorCode,
+ type RelayJoinLink,
+} from '@cindy/device-link';
+
+import { useAuth } from '@/auth/AuthContext';
+import { getMobileAuthOwner } from '@/auth/authOwnerGeneration';
+import { Text } from '@/components/AppText';
+import { MainWindowActionButton } from '@/components/MobilePrimitives';
+import { APP_BINARY_VERSION } from '@/config/env';
+import { buildMobileDeviceName } from '@/device-link/mobileDeviceIdentity';
+import { mobileRelayAuthCrypto } from '@/device-link/relayAuthCrypto';
+import { clearRelayJoinIntent, usePendingRelayJoinIntent } from '@/device-link/relayJoinIntent';
+import { createRelayJoinFetch, saveSelfHostedRelay, useSelfHostedRelay } from '@/device-link/selfHostedRelay';
+import {
+ SimpleStackHeader,
+ simpleScrollInsetProps,
+ simpleScrollScreenSafeAreaEdges,
+} from '@/platform/chrome/SimpleStackHeader';
+import { monoFont, useTheme, useThemedStyles, type ThemeColors } from '@/theme';
+import { fontWeight, iconSize, lineHeight, radius, spacing, typeScale } from '@/theme/tokens';
+import { goBackGuarded } from '@/utils/backGuard';
+
+/** 探测与提交是小请求;等待同意是长轮询(中转最多挂 20 秒),每轮留出余量。 */
+const REQUEST_TIMEOUT_MS = 12_000;
+const APPROVAL_POLL_TIMEOUT_MS = 35_000;
+
+type JoinErrorCode = RelayJoinErrorCode | 'SAVE_FAILED';
+
+type Phase =
+ | { kind: 'idle' }
+ | { kind: 'probing' }
+ | { kind: 'ready'; info: RelayInfo }
+ | { kind: 'submitting'; info: RelayInfo }
+ | { kind: 'waiting'; info: RelayInfo; verifyCode: string }
+ | { kind: 'joined'; info: RelayInfo }
+ | { kind: 'failed'; info: RelayInfo | null; code: JoinErrorCode; retry: 'probe' | 'join' | null };
+
+const ERROR_MESSAGE_KEYS: Record<JoinErrorCode, string> = {
+ UNREACHABLE: 'relay.errors.unreachable',
+ NOT_A_RELAY: 'relay.errors.notRelay',
+ INCOMPATIBLE: 'relay.errors.incompatible',
+ ACCOUNT_MISMATCH: 'relay.errors.accountMismatch',
+ CODE_INVALID: 'relay.errors.codeInvalid',
+ RATE_LIMITED: 'relay.errors.rateLimited',
+ REJECTED: 'relay.errors.rejected',
+ EXPIRED: 'relay.errors.expired',
+ OWNER_MISMATCH: 'relay.errors.ownerMismatch',
+ CANCELLED: 'relay.join.cancelled',
+ FAILED: 'relay.errors.failed',
+ SAVE_FAILED: 'relay.errors.saveFailed',
+};
+
+/** 加入码还没交给中转时,这些失败可以原样重试;交出去之后中转已作废它,只能在电脑上重新生成。 */
+const RETRYABLE_BEFORE_SUBMIT: ReadonlySet<JoinErrorCode> = new Set(['UNREACHABLE', 'RATE_LIMITED', 'FAILED']);
+
+function joinErrorCode(error: unknown): JoinErrorCode {
+ return error instanceof RelayJoinError ? error.code : 'FAILED';
+}
+
+function errorMessageKey(code: JoinErrorCode, link: RelayJoinLink | null): string {
+ // 手机正式包只能用受信任的 https 连接中转(§1):明文地址连不上时直接说清原因。
+ if (code === 'UNREACHABLE' && link?.baseUrl.startsWith('http:')) return 'relay.errors.insecureUnreachable';
+ return ERROR_MESSAGE_KEYS[code];
+}
+
+export default function RelayJoinScreen() {
+ const router = useRouter();
+ const { t } = useTranslation();
+ const { colors } = useTheme();
+ const styles = useThemedStyles(makeStyles);
+ const auth = useAuth();
+ const currentRelay = useSelfHostedRelay();
+ const intent = usePendingRelayJoinIntent();
+ // 页面自己留一份链接:加入码一交给中转就清掉内存里的待处理链接,但等待同意还要用地址。
+ const [link, setLink] = useState<RelayJoinLink | null>(() => intent?.link ?? null);
+ const intentIdRef = useRef(intent?.id ?? 0);
+ const [phase, setPhase] = useState<Phase>({ kind: 'idle' });
+ const abortRef = useRef<AbortController | null>(null);
+
+ const restartFlow = useCallback((): AbortController => {
+ abortRef.current?.abort();
+ const controller = new AbortController();
+ abortRef.current = controller;
+ return controller;
+ }, []);
+
+ useEffect(() => () => abortRef.current?.abort(), []);
+
+ // 页面开着时又扫了一个新链接:放弃当前流程,换成新链接。
+ useEffect(() => {
+ if (!intent || intent.id === intentIdRef.current) return;
+ intentIdRef.current = intent.id;
+ abortRef.current?.abort();
+ setLink(intent.link);
+ setPhase({ kind: 'idle' });
+ }, [intent]);
+
+ const probe = useCallback(async (target: RelayJoinLink) => {
+ const controller = restartFlow();
+ setPhase({ kind: 'probing' });
+ try {
+ const info = await fetchRelayInfo(createRelayJoinFetch(REQUEST_TIMEOUT_MS), target.baseUrl, controller.signal);
+ if (!controller.signal.aborted) setPhase({ kind: 'ready', info });
+ } catch (error) {
+ if (!controller.signal.aborted) {
+ setPhase({ kind: 'failed', info: null, code: joinErrorCode(error), retry: 'probe' });
+ }
+ }
+ }, [restartFlow]);
+
+ const signedIn = auth.isAuthenticated;
+ useEffect(() => {
+ if (link && signedIn && phase.kind === 'idle') void probe(link);
+ }, [link, phase.kind, probe, signedIn]);
+
+ const join = useCallback(async (info: RelayInfo) => {
+ if (!link) return;
+ const owner = getMobileAuthOwner();
+ const accountUserId = auth.user?.id;
+ const deviceId = auth.deviceId;
+ if (!owner.accountKey || owner.switching || !accountUserId || !deviceId) {
+ setPhase({ kind: 'failed', info, code: 'FAILED', retry: 'join' });
+ return;
+ }
+ const controller = restartFlow();
+ setPhase({ kind: 'submitting', info });
+ let codeSubmitted = false;
+ try {
+ // 本机签名密钥:公钥连同用链接里配对秘密做的证明一起提交,中转换不掉它。
+ const identity = createRelayJoinIdentity(mobileRelayAuthCrypto, link, info.relayId, deviceId);
+ const request = await submitRelayPairRequest(
+ createRelayJoinFetch(REQUEST_TIMEOUT_MS),
+ link,
+ {
+ deviceId,
+ deviceName: buildMobileDeviceName({ constantsDeviceName: Constants.deviceName, platform: Platform.OS }),
+ platform: Platform.OS === 'android' ? 'android' : 'ios',
+ appVersion: APP_BINARY_VERSION || Constants.expoConfig?.version || '',
+ accountUserId,
+ publicKey: identity.publicKey,
+ proof: identity.proof,
+ },
+ controller.signal,
+ );
+ // 中转已作废这个加入码:内存里不再留它。
+ codeSubmitted = true;
+ clearRelayJoinIntent();
+ if (controller.signal.aborted) return;
+ setPhase({ kind: 'waiting', info, verifyCode: request.verifyCode });
+ const approved = await waitForRelayApproval(
+ createRelayJoinFetch(APPROVAL_POLL_TIMEOUT_MS),
+ link,
+ request,
+ { signal: controller.signal },
+ );
+ // 证书必须出自链接里的主人、发给本机这把公钥;否则中转可能被人替换,不加入(抛 OWNER_MISMATCH)。
+ acceptRelayDeviceCert(mobileRelayAuthCrypto, link, {
+ relayId: info.relayId,
+ deviceId,
+ publicKey: identity.publicKey,
+ cert: approved.cert,
+ });
+ // 凭证只返回一次:拿到就保存,哪怕页面刚好被关掉。
+ try {
+ await saveSelfHostedRelay({
+ owner,
+ relayId: info.relayId,
+ name: info.name,
+ baseUrl: link.baseUrl,
+ deviceId,
+ ownerPublicKey: link.ownerPublicKey,
+ credential: approved.credential,
+ seed: identity.seed,
+ });
+ } catch {
+ if (!controller.signal.aborted) setPhase({ kind: 'failed', info, code: 'SAVE_FAILED', retry: null });
+ return;
+ }
+ if (!controller.signal.aborted) setPhase({ kind: 'joined', info });
+ } catch (error) {
+ if (controller.signal.aborted) return;
+ const code = joinErrorCode(error);
+ setPhase({
+ kind: 'failed',
+ info,
+ code,
+ retry: !codeSubmitted && RETRYABLE_BEFORE_SUBMIT.has(code) ? 'join' : null,
+ });
+ }
+ }, [auth.deviceId, auth.user?.id, link, restartFlow]);
+
+ const cancelWaiting = useCallback(() => {
+ if (phase.kind !== 'waiting') return;
+ setPhase({ kind: 'failed', info: phase.info, code: 'CANCELLED', retry: null });
+ abortRef.current?.abort();
+ }, [phase]);
+
+ const leave = useCallback(() => {
+ abortRef.current?.abort();
+ goBackGuarded(router);
+ }, [router]);
+
+ const retry = useCallback(() => {
+ if (phase.kind !== 'failed' || !link) return;
+ if (phase.retry === 'probe') void probe(link);
+ else if (phase.retry === 'join' && phase.info) void join(phase.info);
+ }, [join, link, phase, probe]);
+
+ const switchNote = currentRelay && link && currentRelay.baseUrl !== link.baseUrl
+ ? t('relay.join.switchNote', { current: currentRelay.name })
+ : null;
+
+ let content: ReactNode;
+ if (!link) {
+ content = (
+ <Notice
+ icon={<CircleAlert size={iconSize.xl} color={colors.textSecondary} />}
+ message={t('relay.join.invalidLink')}
+ action={{ label: t('relay.join.done'), onPress: leave, testID: 'relayJoin.done' }}
+ />
+ );
+ } else if (!signedIn) {
+ content = (
+ <Notice
+ icon={<Server size={iconSize.xl} color={colors.textSecondary} />}
+ message={t('relay.join.signedOut')}
+ action={{ label: t('relay.join.signIn'), onPress: () => router.replace('/login'), testID: 'relayJoin.signIn', primary: true }}
+ />
+ );
+ } else if (phase.kind === 'idle' || phase.kind === 'probing') {
+ content = (
+ <View style={styles.loading} testID="relayJoin.checking">
+ <ActivityIndicator color={colors.textSecondary} />
+ <Text style={styles.note}>{t('relay.join.checking')}</Text>
+ </View>
+ );
+ } else if (phase.kind === 'ready' || phase.kind === 'submitting') {
+ content = (
+ <>
+ <RelayIdentity info={phase.info} baseUrl={link.baseUrl} />
+ <Text style={styles.body}>{t('relay.join.body')}</Text>
+ {switchNote ? <Text style={styles.note}>{switchNote}</Text> : null}
+ <View style={styles.actions}>
+ <MainWindowActionButton
+ action={{
+ label: t('relay.join.action'),
+ tone: 'primary',
+ busy: phase.kind === 'submitting',
+ onPress: () => { void join(phase.info); },
+ testID: 'relayJoin.join',
+ }}
+ />
+ </View>
+ </>
+ );
+ } else if (phase.kind === 'waiting') {
+ content = (
+ <>
+ <RelayIdentity info={phase.info} baseUrl={link.baseUrl} />
+ <View style={styles.codeBlock}>
+ <Text style={styles.sectionLabel}>{t('relay.join.pairingCodeLabel')}</Text>
+ <Text
+ accessibilityLabel={`${t('relay.join.pairingCodeLabel')} ${phase.verifyCode.split('').join(' ')}`}
+ selectable
+ style={styles.pairingCode}
+ testID="relayJoin.pairingCode"
+ >
+ {phase.verifyCode}
+ </Text>
+ </View>
+ <Text style={styles.body}>{t('relay.join.verifyHint')}</Text>
+ <View style={styles.waitingRow}>
+ <ActivityIndicator color={colors.textSecondary} size="small" />
+ <Text accessibilityLiveRegion="polite" style={styles.note}>{t('relay.join.waiting')}</Text>
+ </View>
+ <View style={styles.actions}>
+ <MainWindowActionButton
+ action={{ label: t('relay.join.cancel'), onPress: cancelWaiting, testID: 'relayJoin.cancel' }}
+ />
+ </View>
+ </>
+ );
+ } else if (phase.kind === 'joined') {
+ content = (
+ <Notice
+ icon={<CircleCheck size={iconSize.xl} color={colors.textSecondary} />}
+ heading={t('relay.join.joinedTitle')}
+ message={t('relay.join.joinedBody', { name: phase.info.name })}
+ action={{ label: t('relay.join.done'), onPress: () => router.replace('/'), testID: 'relayJoin.done', primary: true }}
+ />
+ );
+ } else {
+ content = (
+ <>
+ {phase.info ? <RelayIdentity info={phase.info} baseUrl={link.baseUrl} /> : null}
+ <Notice
+ icon={phase.info ? null : <CircleAlert size={iconSize.xl} color={colors.textSecondary} />}
+ message={t(errorMessageKey(phase.code, link))}
+ action={phase.retry
+ ? { label: t('relay.join.retry'), onPress: retry, testID: 'relayJoin.retry', primary: true }
+ : { label: t('relay.join.done'), onPress: leave, testID: 'relayJoin.done' }}
+ />
+ </>
+ );
+ }
+
+ return (
+ <SafeAreaView edges={simpleScrollScreenSafeAreaEdges()} style={styles.screen} testID="relayJoin.screen">
+ <SimpleStackHeader
+ scrollEdge
+ title={t('relay.join.title')}
+ backTestID="relayJoin.back"
+ onBack={leave}
+ />
+ <ScrollView {...simpleScrollInsetProps} contentContainerStyle={styles.content}>
+ {content}
+ </ScrollView>
+ </SafeAreaView>
+ );
+}
+
+/** 中转名称与地址:名称来自 relay/info,地址来自加入链接,让用户在点加入前看清连的是谁。 */
+function RelayIdentity({ info, baseUrl }: { info: RelayInfo; baseUrl: string }) {
+ const { colors } = useTheme();
+ const styles = useThemedStyles(makeStyles);
+ return (
+ <View style={styles.identity}>
+ <View style={styles.icon}>
+ <Server size={iconSize.xl} color={colors.textSecondary} />
+ </View>
+ <Text accessibilityRole="header" style={styles.heading}>{info.name}</Text>
+ <Text selectable style={styles.note} testID="relayJoin.address">{baseUrl}</Text>
+ </View>
+ );
+}
+
+function Notice({
+ icon,
+ heading,
+ message,
+ action,
+}: {
+ icon?: ReactNode;
+ heading?: string;
+ message: string;
+ action: { label: string; onPress: () => void; testID: string; primary?: boolean };
+}) {
+ const styles = useThemedStyles(makeStyles);
+ return (
+ <>
+ {icon ? <View style={styles.icon}>{icon}</View> : null}
+ {heading ? <Text accessibilityRole="header" style={styles.heading}>{heading}</Text> : null}
+ <Text accessibilityLiveRegion="polite" style={styles.body}>{message}</Text>
+ <View style={styles.actions}>
+ <MainWindowActionButton
+ action={{
+ label: action.label,
+ tone: action.primary ? 'primary' : 'secondary',
+ onPress: action.onPress,
+ testID: action.testID,
+ }}
+ />
+ </View>
+ </>
+ );
+}
+
+const makeStyles = (colors: ThemeColors) => StyleSheet.create({
+ screen: { backgroundColor: colors.surface, flex: 1 },
+ content: { alignItems: 'flex-start', gap: spacing.md, padding: spacing.lg, paddingTop: spacing.xl },
+ identity: { alignItems: 'flex-start', gap: spacing.xs },
+ icon: {
+ alignItems: 'center',
+ backgroundColor: colors.surfaceElevated,
+ borderColor: colors.border,
+ borderRadius: radius.pill,
+ borderWidth: StyleSheet.hairlineWidth,
+ height: 48,
+ justifyContent: 'center',
+ marginBottom: spacing.xs,
+ width: 48,
+ },
+ // 页面大标题:20/25 600 textPrimary。
+ heading: {
+ color: colors.textPrimary,
+ fontSize: typeScale.title,
+ fontWeight: fontWeight.semibold,
+ lineHeight: lineHeight.title,
+ },
+ // 次级正文:15/20 400 textSecondary。
+ body: {
+ color: colors.textSecondary,
+ fontSize: typeScale.bodySmall,
+ fontWeight: fontWeight.regular,
+ lineHeight: lineHeight.bodySmall,
+ },
+ // 说明 / 提示:13/18 400 textSecondary。
+ note: {
+ color: colors.textSecondary,
+ fontSize: typeScale.footnote,
+ fontWeight: fontWeight.regular,
+ lineHeight: lineHeight.caption,
+ },
+ // 分组小标签:13/18 600 textTertiary。
+ sectionLabel: {
+ color: colors.textTertiary,
+ fontSize: typeScale.footnote,
+ fontWeight: fontWeight.semibold,
+ lineHeight: lineHeight.caption,
+ },
+ codeBlock: {
+ alignSelf: 'stretch',
+ backgroundColor: colors.surfaceElevated,
+ borderColor: colors.border,
+ borderRadius: radius.container,
+ borderWidth: StyleSheet.hairlineWidth,
+ gap: spacing.xs,
+ paddingHorizontal: spacing.lg,
+ paddingVertical: spacing.md,
+ },
+ // 配对码是要和电脑逐位核对的大数字:30/36 600 textPrimary,等宽字体对齐每一位。
+ pairingCode: {
+ color: colors.textPrimary,
+ fontFamily: monoFont,
+ fontSize: typeScale.largeTitle,
+ fontWeight: fontWeight.semibold,
+ letterSpacing: spacing.sm,
+ lineHeight: lineHeight.largeTitle,
+ },
+ loading: { alignItems: 'center', alignSelf: 'stretch', gap: spacing.sm, paddingVertical: spacing.xl },
+ waitingRow: { alignItems: 'center', flexDirection: 'row', gap: spacing.sm },
+ actions: { alignItems: 'flex-start', gap: spacing.sm, marginTop: spacing.sm },
+});
diff --git a/apps/mobile/app/settings.tsx b/apps/mobile/app/settings.tsx
index 36d8819672..c11418b31e 100644
--- a/apps/mobile/app/settings.tsx
+++ b/apps/mobile/app/settings.tsx
@@ -57,6 +57,7 @@ import { LEGAL_LINKS } from '@/config/legalLinks';
import { useDeviceLink } from '@/device-link/DeviceLinkContext';
import { buildMobileDeviceName } from '@/device-link/mobileDeviceIdentity';
import { formatRemoteError } from '@/device-link/remoteStatus';
+import { clearSelfHostedRelay, useSelfHostedRelay } from '@/device-link/selfHostedRelay';
import { buildMobileSettingsOverview } from '@/settings/mobileSettings';
import {
isPushSupported,
@@ -139,7 +140,11 @@ export default function SettingsScreen() {
const { locale, setLocale } = useLocale();
const windowDimensions = useWindowDimensions();
const safeAreaInsets = useSafeAreaInsets();
- const { status } = useDeviceLink();
+ const { status, connectionIssue } = useDeviceLink();
+ // 中转服务:官方中转或自建中转(docs/self-hosted-relay-plan.md §5.3)。
+ const selfHostedRelay = useSelfHostedRelay();
+ const [relaySwitching, setRelaySwitching] = useState(false);
+ const [relayMessage, setRelayMessage] = useState<string | null>(null);
const [loggingOut, setLoggingOut] = useState(false);
const [accountDeletionAvailable, setAccountDeletionAvailable] =
useState(false);
@@ -384,6 +389,43 @@ export default function SettingsScreen() {
router.push('/account-deletion');
}, [router]);
+ // 切回官方中转:先确认(之后要再用这个中转得在电脑上重新加入);删掉本机设置与凭证,
+ // 连接随路由变化重建。不会自动切回,只在用户确认后执行。
+ const switchToOfficialRelay = useCallback(async () => {
+ if (relaySwitching) return;
+ setRelaySwitching(true);
+ setRelayMessage(null);
+ try {
+ await clearSelfHostedRelay();
+ } catch {
+ setRelayMessage(t('relay.settings.switchFailed'));
+ } finally {
+ setRelaySwitching(false);
+ }
+ }, [relaySwitching, t]);
+
+ const requestSwitchToOfficialRelay = useCallback(() => {
+ if (!selfHostedRelay || relaySwitching) return;
+ Alert.alert(
+ t('relay.settings.confirmTitle'),
+ t('relay.settings.confirmBody', { name: selfHostedRelay.name }),
+ [
+ { text: t('devices.common.cancel'), style: 'cancel' },
+ { text: t('relay.settings.confirmAction'), style: 'destructive', onPress: () => void switchToOfficialRelay() },
+ ],
+ );
+ }, [relaySwitching, selfHostedRelay, switchToOfficialRelay, t]);
+
+ // 自建中转下:被主人移出 / 中转停用(4410)或中转凭证被拒(401),以及本机凭证缺失,
+ // 都要在这里给出原因,并配「切回官方中转」。
+ const relayIssueMessage = !selfHostedRelay
+ ? null
+ : selfHostedRelay.credential === null
+ ? t('relay.settings.credentialMissingHint')
+ : status !== 'online' && (connectionIssue?.kind === 'device-removed' || connectionIssue?.kind === 'auth-failed')
+ ? t('relay.settings.removedHint')
+ : null;
+
// 任务完成通知开关:开 → 请求系统权限 + 注册 APNs token 到 device-link server;
// 关 → 注销 token。开关状态本机持久化,server 注册表是唯一发送依据。
useEffect(() => {
@@ -605,6 +647,38 @@ export default function SettingsScreen() {
</View>
</View>
+ {/* 中转服务:当前走官方中转还是自建中转;自建时提供「切回官方中转」。
+ 加入自建中转从电脑上的二维码进入(相机扫码打开加入页),这里不放扫码入口。 */}
+ <SettingsGroup
+ footer={selfHostedRelay
+ ? t('relay.settings.selfHostedHint', { address: selfHostedRelay.baseUrl })
+ : t('relay.settings.officialHint')}
+ messages={[
+ relayIssueMessage ? { text: relayIssueMessage, testID: 'settings.relay.issue' } : null,
+ relayMessage ? { text: relayMessage, testID: 'settings.relay.message' } : null,
+ ]}
+ testID="settings.relay"
+ title={t('relay.settings.sectionTitle')}
+ >
+ <InfoRow
+ key="relay-current"
+ label={t('relay.settings.currentLabel')}
+ testID="settings.relay.current"
+ value={selfHostedRelay ? selfHostedRelay.name : t('relay.settings.official')}
+ />
+ {selfHostedRelay ? (
+ <ActionInfoRow
+ accessibilityLabel={t('relay.settings.switchToOfficial')}
+ chevron={false}
+ disabled={relaySwitching}
+ key="relay-switch-official"
+ label={t('relay.settings.switchToOfficial')}
+ onPress={requestSwitchToOfficialRelay}
+ testID="settings.relay.switchToOfficial"
+ />
+ ) : null}
+ </SettingsGroup>
+
{/* 版本:当前版本 + 统一检查入口(允许整包分发时先查整包,否则直接查热更);
更新方式与检查结果写在分组下方。检查不可用或审核模式时不显示检查行。 */}
<SettingsGroup
@@ -657,7 +731,9 @@ export default function SettingsScreen() {
{/* Notification permission and preview preferences belong to this installation. */}
{isPushSupported() ? (
<SettingsGroup
- footer={t('settings.notifications.taskDoneHint') + (isChatBackgroundSupported() ? ` ${t('settings.notifications.backgroundHint')}` : '')}
+ footer={t('settings.notifications.taskDoneHint')
+ + (isChatBackgroundSupported() ? ` ${t('settings.notifications.backgroundHint')}` : '')
+ + (selfHostedRelay ? ` ${t('relay.settings.pushUnavailable')}` : '')}
messages={[pushMessage ? { text: pushMessage, testID: 'settings.pushMessage' } : null]}
title={t('settings.notifications.sectionTitle')}
>
diff --git a/apps/mobile/src/__tests__/apiClient.test.ts b/apps/mobile/src/__tests__/apiClient.test.ts
index 4754e5be02..392dd23f0e 100644
--- a/apps/mobile/src/__tests__/apiClient.test.ts
+++ b/apps/mobile/src/__tests__/apiClient.test.ts
@@ -7,6 +7,7 @@ import {
apiFetchRaw,
registerAccountUnavailableHandler,
} from '@/api/client';
+import { __testing as relayRoutingTesting, setActiveSelfHostedRelay } from '@/device-link/selfHostedRelayRouting';
// 文案已 i18n 化;固定 zh-CN 让字面量断言与语言环境解耦(全局 mock 默认 en-US)。
beforeAll(async () => {
@@ -283,3 +284,46 @@ describe('apiFetchRaw', () => {
}
});
});
+
+// Self-hosted relay (docs/self-hosted-relay-plan.md §5.3, §8): every device-link REST consumer goes
+// through apiFetchRaw, so this is where the account token must never reach a self-hosted relay and
+// where a relay 401 must lose any meaning for the Cindy account (no refresh code, no sign-out).
+describe('apiFetchRaw with a self-hosted relay', () => {
+ const RELAY = 'https://relay.home.example';
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ relayRoutingTesting.reset();
+ });
+
+ it('sends the relay credential instead of the account token; a relay 401 cannot sign the account out', async () => {
+ setActiveSelfHostedRelay({ relayId: 'relay-1', name: 'Home', baseUrl: RELAY, credential: 'relay-credential', signing: null });
+ const fetchMock = vi.fn(async () => new Response(
+ JSON.stringify({ error: { code: 'ACCOUNT_UNAVAILABLE' } }), { status: 401 },
+ ));
+ vi.stubGlobal('fetch', fetchMock);
+ const terminal = vi.fn();
+ const dispose = registerAccountUnavailableHandler(terminal);
+ try {
+ await expect(apiFetchRaw('/api/device-link/devices', { baseUrl: RELAY, token: 'account-token' }))
+ .rejects.toMatchObject({ code: 'RELAY_CREDENTIAL_INVALID', status: 401 });
+ const headers = (fetchMock.mock.calls[0] as unknown as [string, RequestInit])[1].headers as Record<string, string>;
+ expect(headers.Authorization).toBe('CindyRelay relay-credential');
+ expect(JSON.stringify(headers)).not.toContain('account-token');
+ expect(terminal).not.toHaveBeenCalled();
+ } finally { dispose(); }
+ });
+
+ it('never sends the account token to a known relay without a usable credential', async () => {
+ const fetchMock = vi.fn(async () => new Response('{}'));
+ vi.stubGlobal('fetch', fetchMock);
+ // Credential missing on this phone (e.g. restored backup without THIS_DEVICE_ONLY keychain items).
+ setActiveSelfHostedRelay({ relayId: 'relay-1', name: 'Home', baseUrl: RELAY, credential: null, signing: null });
+ await expect(apiFetchRaw('/api/device-link/devices', { baseUrl: RELAY, token: 'account-token' }))
+ .rejects.toMatchObject({ code: 'RELAY_CREDENTIAL_UNAVAILABLE' });
+ // Switched back to the official relay: a late request still holding the relay address stays blocked.
+ setActiveSelfHostedRelay(null);
+ await expect(apiFetchRaw('/api/device-link/media', { baseUrl: 'https://RELAY.home.example/', token: 'account-token' }))
+ .rejects.toMatchObject({ code: 'RELAY_CREDENTIAL_UNAVAILABLE' });
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/mobile/src/__tests__/clientEndpointStartup.test.ts b/apps/mobile/src/__tests__/clientEndpointStartup.test.ts
index c6ec80cd9c..e248a27d25 100644
--- a/apps/mobile/src/__tests__/clientEndpointStartup.test.ts
+++ b/apps/mobile/src/__tests__/clientEndpointStartup.test.ts
@@ -681,6 +681,28 @@ describe('applyResolvedClientEndpoints', () => {
expect(env.AUTH_API_BASE_URL).toBe('');
});
+ // 自建中转(docs/self-hosted-relay-plan.md §5.3):中转地址必须扛过之后的每一次区域写入,
+ // 而推送注册直接读的 realm 缓存要一直是官方地址(否则会把推送登记发到自建中转)。
+ it('自建中转地址覆盖在区域写入后仍生效,realm 缓存保持官方地址', async () => {
+ const { env, startup } = await freshModules();
+ await expect(
+ startup.runStartupEndpointResolve({ fetchManifest: okFetch(FULL_MANIFEST) }),
+ ).resolves.toEqual({ ok: true, source: 'cdn' });
+ env.setDeviceLinkApiBaseOverride('https://relay.home.example/');
+ expect(env.deviceLinkWsUrl()).toBe('wss://relay.home.example/api/device-link/ws');
+ env.applyResolvedClientEndpoints({
+ deviceLinkApiBaseUrl: 'https://device.override.example.com',
+ });
+ env.activateMobileSessionRealm(env.BUILD_AUTH_REGION);
+ env.resetMobileSessionRealm();
+ expect(env.DEVICE_LINK_API_BASE_URL).toBe('https://relay.home.example');
+ expect(
+ env.getMobileEndpointForRealm(env.BUILD_AUTH_REGION, 'deviceLinkApiBaseUrl'),
+ ).toBe('https://device.override.example.com');
+ env.setDeviceLinkApiBaseOverride(null);
+ expect(env.DEVICE_LINK_API_BASE_URL).toBe('https://device.override.example.com');
+ });
+
it('组织会话切换 token 消费端点,退出后恢复构建区域且不改变更新端点', async () => {
const { env, startup } = await freshModules();
await expect(
diff --git a/apps/mobile/src/__tests__/historyViewProvider.test.tsx b/apps/mobile/src/__tests__/historyViewProvider.test.tsx
index 42588f1e6c..276e1526bb 100644
--- a/apps/mobile/src/__tests__/historyViewProvider.test.tsx
+++ b/apps/mobile/src/__tests__/historyViewProvider.test.tsx
@@ -52,6 +52,7 @@ vi.mock('expo-secure-store', () => ({
getItemAsync: vi.fn(async () => null), setItemAsync: vi.fn(async () => {}), deleteItemAsync: vi.fn(async () => {}),
}));
vi.mock('expo-updates', () => ({ updateId: null, runtimeVersion: null, isEmbeddedLaunch: true }));
+vi.mock('expo-crypto', () => ({ getRandomBytes: (size: number) => new Uint8Array(size) }));
vi.mock('@react-native-async-storage/async-storage', () => ({ default: {
getItem: vi.fn(async () => null), setItem: vi.fn(async () => {}), removeItem: vi.fn(async () => {}),
getAllKeys: vi.fn(async () => []), multiRemove: vi.fn(async () => {}),
diff --git a/apps/mobile/src/__tests__/nativeIntent.test.ts b/apps/mobile/src/__tests__/nativeIntent.test.ts
index c161623194..a4e68d6b15 100644
--- a/apps/mobile/src/__tests__/nativeIntent.test.ts
+++ b/apps/mobile/src/__tests__/nativeIntent.test.ts
@@ -12,6 +12,7 @@ import {
peekProviderShareLinkIntentForTest,
takeProviderShareLinkIntent,
} from '@/device-link/providerShareLinkIntent';
+import { clearRelayJoinIntent, getPendingRelayJoinIntent } from '@/device-link/relayJoinIntent';
import { redirectSystemPath } from '../../app/+native-intent';
const invitation = 'A'.repeat(43);
@@ -19,8 +20,13 @@ const incoming = 'cindy://shared-session?invitation=' + invitation + '&server=ht
const shareInvitation = 'B'.repeat(43);
const shareIncoming = 'cindy://provider-share/join?invitation=' + shareInvitation + '&server=https%3A%2F%2Frelay.example.test%2Fdl';
const shareWebLink = 'https://relay.example.test/dl/provider-share/join#' + shareInvitation;
-beforeEach(() => { vi.useFakeTimers(); clearSharedTaskInvitationIntent(); clearProviderShareLinkIntent(); setMobileAuthOwner(null); });
-afterEach(() => { clearSharedTaskInvitationIntent(); clearProviderShareLinkIntent(); vi.useRealTimers(); });
+const relayCode = 'R'.repeat(43);
+const relayOwnerKey = 'Q'.repeat(43);
+const relayPairSecret = 'S'.repeat(43);
+const relayUnsignedIncoming = 'cindy://relay/join?u=' + encodeURIComponent('https://relay.home.example:47820/') + '&c=' + relayCode;
+const relayIncoming = relayUnsignedIncoming + '&o=' + relayOwnerKey + '&s=' + relayPairSecret;
+beforeEach(() => { vi.useFakeTimers(); clearSharedTaskInvitationIntent(); clearProviderShareLinkIntent(); clearRelayJoinIntent(); setMobileAuthOwner(null); });
+afterEach(() => { clearSharedTaskInvitationIntent(); clearProviderShareLinkIntent(); clearRelayJoinIntent(); vi.useRealTimers(); });
describe('mobile native deep-link redirects', () => {
it('keeps the invitation out of router state, survives login, and clears on an account change', () => {
@@ -97,6 +103,51 @@ describe('mobile native deep-link redirects', () => {
expect(peekProviderShareLinkIntentForTest()).toBeNull();
});
+ // Self-hosted relay join (docs/self-hosted-relay-plan.md §5.1): the one-time join code is a secret,
+ // so the router only ever sees the bare join page; the parsed link lives in memory for that page.
+ it.each([true, false])('routes relay join links to the join page without the join code (initial=%s)', initial => {
+ for (const path of [
+ relayIncoming,
+ relayIncoming.replace('cindy://', 'cindycn://'),
+ relayIncoming.replace('cindy://', 'cindydev://'),
+ relayIncoming.replace('cindy:/', ''),
+ relayIncoming.replace('cindy://', ''),
+ ]) {
+ const route = redirectSystemPath({ path, initial });
+ expect(route).toBe('/relay-join');
+ expect(getPendingRelayJoinIntent()?.link).toEqual({
+ baseUrl: 'https://relay.home.example:47820',
+ code: relayCode,
+ ownerPublicKey: relayOwnerKey,
+ pairSecret: relayPairSecret,
+ });
+ expect(getPendingSharedTaskInvitationIntent()).toBeNull();
+ }
+ });
+
+ it('keeps nothing for malformed relay join links and forgets a valid one after expiry or an account switch', () => {
+ for (const path of [
+ relayIncoming.replace('c=' + relayCode, 'c=short'),
+ // Pre-signature links carry no owner key / pairing secret, so the certificate could never be checked.
+ relayUnsignedIncoming,
+ 'cindy://relay/join?u=' + encodeURIComponent('ftp://relay.home.example') + '&c=' + relayCode,
+ 'xdt-maker://relay/join?u=https%3A%2F%2Frelay.home.example&c=' + relayCode,
+ '/relay?c=' + relayCode,
+ ]) {
+ expect(redirectSystemPath({ path, initial: false })).toBe('/relay-join');
+ expect(getPendingRelayJoinIntent()?.link).toBeNull();
+ }
+ redirectSystemPath({ path: relayIncoming, initial: true });
+ vi.advanceTimersByTime(10 * 60_000);
+ expect(getPendingRelayJoinIntent()).toBeNull();
+
+ redirectSystemPath({ path: relayIncoming, initial: false });
+ setMobileAuthOwner('first'); // the first sign-in claims a link scanned while signed out
+ expect(getPendingRelayJoinIntent()?.link).not.toBeNull();
+ invalidateMobileAuthOwnerForSwitch();
+ expect(getPendingRelayJoinIntent()).toBeNull();
+ });
+
it.each([true, false])('keeps WeChat SDK callbacks out of navigation (initial=%s)', (initial) => {
for (const path of [
'cindycn://oauth?code=test-wechat-code&state=test-state',
diff --git a/apps/mobile/src/__tests__/projectAliasProvider.test.tsx b/apps/mobile/src/__tests__/projectAliasProvider.test.tsx
index 1d152c50ba..29c4731358 100644
--- a/apps/mobile/src/__tests__/projectAliasProvider.test.tsx
+++ b/apps/mobile/src/__tests__/projectAliasProvider.test.tsx
@@ -41,6 +41,7 @@ vi.mock('@react-native-async-storage/async-storage', () => ({ default: {
// Native WebView lifecycle has separate coverage; this suite exercises Provider subscriptions.
vi.mock('@/device-link/DirectLinkTransport', () => ({ DirectLinkTransport: () => null }));
vi.mock('expo-updates', () => ({ updateId: null, runtimeVersion: null, isEmbeddedLaunch: true }));
+vi.mock('expo-crypto', () => ({ getRandomBytes: (size: number) => new Uint8Array(size) }));
vi.mock('@/device-link/rnWebSocket', () => ({ createRnWebSocket: vi.fn() }));
vi.mock('@/debug/mobileDebugLog', () => ({ mobileDebugLog: vi.fn() }));
vi.mock('@/debug/visualMock', () => ({ prepareVisualMockDeviceLinkContext: vi.fn() }));
diff --git a/apps/mobile/src/__tests__/pushNotificationsRealm.test.ts b/apps/mobile/src/__tests__/pushNotificationsRealm.test.ts
index 27d4a90fa4..b7e1235ced 100644
--- a/apps/mobile/src/__tests__/pushNotificationsRealm.test.ts
+++ b/apps/mobile/src/__tests__/pushNotificationsRealm.test.ts
@@ -53,6 +53,7 @@ vi.mock('@/config/env', () => ({
loadMobileEndpointsForRealm: mocks.loadMobileEndpointsForRealm,
getMobileEndpointForRealm: (realm: 'cn' | 'global') =>
envState.endpointByRealm[realm],
+ setDeviceLinkApiBaseOverride: () => {},
}));
vi.mock('@/config/devServerEnvironment', () => ({
@@ -65,6 +66,7 @@ import {
syncPushRegistration,
unregisterPushTokenBestEffort,
} from '@/notifications/pushNotifications';
+import { setActiveSelfHostedRelay } from '@/device-link/selfHostedRelayRouting';
const REGISTERED_KEY = 'cindy.push.registered';
const PENDING_KEY = 'cindy.push.pendingUnregister';
@@ -159,6 +161,25 @@ describe('push notification realm routing', () => {
expect(readStoredRealms(REGISTERED_KEY)).toEqual(['global']);
});
+ // 自建中转不转发系统推送(docs/self-hosted-relay-plan.md §5.3、§7):不在官方 device-link 登记 token
+ // (伙伴消息的 Chat Server 登记不受影响),关闭时仍向官方地址注销以前的登记。
+ it('自建中转下不登记 device-link 推送,注销仍发往官方地址', async () => {
+ setActiveSelfHostedRelay({ relayId: 'relay-1', name: 'Home', baseUrl: 'https://relay.home.example', credential: 'relay-credential', signing: null });
+ try {
+ const apiFetch = vi.fn().mockResolvedValue({});
+ await expect(syncPushRegistration({ enabled: true, apiFetch })).resolves.toBe('registered');
+ expect(apiFetch.mock.calls.map(([path, opts]) => `${opts.method} ${path}`)).toEqual(['PUT /v1/push-token']);
+ apiFetch.mockClear();
+ await expect(syncPushRegistration({ enabled: false, apiFetch })).resolves.toBe('unregistered');
+ expect(apiFetch).toHaveBeenCalledWith('/api/device-link/push-token', expect.objectContaining({
+ baseUrl: 'https://relay.cn.example',
+ method: 'DELETE',
+ }));
+ } finally {
+ setActiveSelfHostedRelay(null);
+ }
+ });
+
it('dev 构建复用 cn 推送构建线向开发环境注册', async () => {
envState.buildRegion = 'dev';
expect((await import('@/config/env')).AUTH_REGION).toBe('dev');
diff --git a/apps/mobile/src/__tests__/selfHostedRelaySignatures.test.ts b/apps/mobile/src/__tests__/selfHostedRelaySignatures.test.ts
new file mode 100644
index 0000000000..b5f3b0ff8b
--- /dev/null
+++ b/apps/mobile/src/__tests__/selfHostedRelaySignatures.test.ts
@@ -0,0 +1,93 @@
+/**
+ * 测试价值
+ * - 生产入口与可观察结果:手机加入流程用的 `mobileRelayAuthCrypto`(@noble)经 `createRelayJoinIdentity` /
+ * `acceptRelayDeviceCert` 加入,DeviceLinkClient 的 `currentSelfHostedRelayFrameAuth()` 给对端帧签名;
+ * 电脑端(node:crypto)核对配对证明、签发证书,并用 `RelayFrameAuthenticator` 判定手机签名的帧为 'ok'、
+ * 篡改内容的帧为 'bad-signature';不是链接里主人签发的证书在手机上被拒(OWNER_MISMATCH);官方中转不签名。
+ * - Bug/规则依据:docs/self-hosted-relay-plan.md §16 设备签名。手机与电脑是两套 Ed25519 / SHA-256 / HMAC /
+ * UTF-8 实现,任何一处字节差异都会让电脑丢弃手机发出的全部消息(自建中转下手机整体不可用)或让手机加入失败。
+ * - 现有覆盖缺口:packages/device-link 的签名测试两端都用 node:crypto,不覆盖 @noble 实现与跨实现兼容。
+ * - 最小失败输入:一条内容含中文与 emoji 的 invoke 帧(纯 JS UTF-8 编码 vs node Buffer 编码)。
+ * - tier:unit(纯计算,node 环境;expo-crypto 的随机数换成 node:crypto)。
+ * - 实测耗时:单独运行 1.8 秒,用例本身 38ms(apps/mobile 下 npx vitest run src/__tests__/selfHostedRelaySignatures.test.ts)。
+ */
+import { randomBytes } from 'node:crypto';
+import { afterEach, expect, it, vi } from 'vitest';
+import {
+ acceptRelayDeviceCert,
+ createRelayJoinIdentity,
+ createRelayPairSecret,
+ createRelaySigningKey,
+ issueRelayDeviceCert,
+ PROTOCOL_VERSION,
+ RelayFrameAuthenticator,
+ verifyRelayPairProof,
+ type Envelope,
+ type RelayJoinLink,
+} from '@cindy/device-link';
+import { nodeRelayAuthCrypto } from '@cindy/device-link/node-relay-crypto';
+
+vi.mock('expo-crypto', () => ({ getRandomBytes: (size: number) => new Uint8Array(randomBytes(size)) }));
+
+import { mobileRelayAuthCrypto } from '@/device-link/relayAuthCrypto';
+import { currentSelfHostedRelayFrameAuth } from '@/device-link/selfHostedRelayFrameAuth';
+import { __testing as relayRouting, setActiveSelfHostedRelay } from '@/device-link/selfHostedRelayRouting';
+
+afterEach(() => relayRouting.reset());
+
+it('phone (@noble) and computer (node:crypto) accept each other’s pairing proof, certificate and frame signatures', () => {
+ const relayId = 'relay-7f3c';
+ const phoneId = 'phone-1';
+ const computerId = 'computer-1';
+ const owner = createRelaySigningKey(nodeRelayAuthCrypto);
+ const link: RelayJoinLink = {
+ baseUrl: 'https://relay.home.example',
+ code: 'C'.repeat(32),
+ ownerPublicKey: owner.publicKey,
+ pairSecret: createRelayPairSecret(nodeRelayAuthCrypto),
+ };
+
+ // 加入:手机生成密钥与配对证明,主人电脑核对后签发证书,手机用链接里的主人公钥核对。
+ const identity = createRelayJoinIdentity(mobileRelayAuthCrypto, link, relayId, phoneId);
+ expect(verifyRelayPairProof(nodeRelayAuthCrypto, link.pairSecret, {
+ relayId, deviceId: phoneId, publicKey: identity.publicKey, proof: identity.proof,
+ })).toBe(true);
+ const certFields = { relayId, deviceId: phoneId, publicKey: identity.publicKey, role: 'member' as const, issuedAt: 1 };
+ const cert = issueRelayDeviceCert(nodeRelayAuthCrypto, owner.seed, certFields);
+ const accept = { relayId, deviceId: phoneId, publicKey: identity.publicKey };
+ expect(acceptRelayDeviceCert(mobileRelayAuthCrypto, link, { ...accept, cert })).toEqual(cert);
+ // 被替换的中转自己签的证书:手机不加入。
+ const forged = issueRelayDeviceCert(nodeRelayAuthCrypto, createRelaySigningKey(nodeRelayAuthCrypto).seed, certFields);
+ expect(() => acceptRelayDeviceCert(mobileRelayAuthCrypto, link, { ...accept, cert: forged }))
+ .toThrow(expect.objectContaining({ code: 'OWNER_MISMATCH' }));
+
+ // 官方中转:不签名。
+ expect(currentSelfHostedRelayFrameAuth()).toBeNull();
+
+ // 自建中转:手机签名,电脑(node:crypto)核对。
+ setActiveSelfHostedRelay({
+ relayId,
+ name: 'Home',
+ baseUrl: link.baseUrl,
+ credential: 'relay-credential',
+ signing: { deviceId: phoneId, ownerPublicKey: owner.publicKey, seed: identity.seed },
+ });
+ const phone = currentSelfHostedRelayFrameAuth()!;
+ const computer = new RelayFrameAuthenticator({
+ crypto: nodeRelayAuthCrypto,
+ relayId,
+ deviceId: computerId,
+ seed: createRelaySigningKey(nodeRelayAuthCrypto).seed,
+ ownerPublicKey: owner.publicKey,
+ });
+ expect(computer.setCertificates([cert])).toEqual({ accepted: 1, rejected: 0 });
+
+ // 手机发出时没有 src,中转转发时填上。
+ const invoke = (args: unknown[]): Envelope => ({
+ v: PROTOCOL_VERSION, kind: 'invoke', id: 'req-1', dst: computerId, payload: { channel: 'maker:send', args },
+ });
+ const delivered = (frame: Envelope) => ({ ...frame, src: phoneId, auth: phone.sign(frame) });
+ expect(computer.verify(delivered(invoke(['继续 👋'])))).toBe('ok');
+ const tampered = delivered(invoke(['继续 👋']));
+ expect(computer.verify({ ...tampered, payload: { channel: 'maker:send', args: ['tampered'] } })).toBe('bad-signature');
+});
diff --git a/apps/mobile/src/__tests__/sharedTaskApiAccountScope.test.ts b/apps/mobile/src/__tests__/sharedTaskApiAccountScope.test.ts
index 15718cb806..b18311b334 100644
--- a/apps/mobile/src/__tests__/sharedTaskApiAccountScope.test.ts
+++ b/apps/mobile/src/__tests__/sharedTaskApiAccountScope.test.ts
@@ -6,12 +6,20 @@ import { ApiError, apiFetchRaw, registerAccountUnavailableHandler, type ApiFetch
import { setMobileAuthOwner } from '@/auth/authOwnerGeneration';
import { SharedTaskScopeChangedError } from '@cindy/device-link';
import { useSharedTaskApi } from '@/device-link/useSharedTaskApi';
+import {
+ __testing as relayRoutingTesting,
+ isSelfHostedRelayBaseUrl,
+ setActiveSelfHostedRelay,
+} from '@/device-link/selfHostedRelayRouting';
type ApiFetch = <T>(path: string, opts: Omit<ApiFetchOptions, 'token'>) => Promise<T>;
const auth = vi.hoisted(() => ({ apiFetch: null as unknown as ApiFetch, accountGeneration: 1 }));
vi.mock('@/auth/AuthContext', () => ({ useAuth: () => auth }));
vi.mock('react', () => ({ useMemo: (factory: () => unknown) => factory() }));
-vi.mock('@/config/env', () => ({ DEVICE_LINK_API_BASE_URL: 'https://relay.example.invalid' }));
+vi.mock('@/config/env', () => ({
+ DEVICE_LINK_API_BASE_URL: 'https://relay.example.invalid',
+ setDeviceLinkApiBaseOverride: () => {},
+}));
// Execute the provider callback with in-memory auth dependencies, without native
// login/storage. The shared-task hook and HTTP transport remain real.
@@ -44,9 +52,9 @@ beforeEach(() => {
refresh.mockResolvedValue('fake-refreshed-a');
fetchMock.mockResolvedValue(response());
vi.stubGlobal('fetch', fetchMock);
- auth.apiFetch = new Function('getAccessToken', 'refresh', 'terminateSession', 'userRef', 'ApiError', 'apiFetchRaw', compiled + '; return request;')(getAccessToken, refresh, terminateSession, { current: { id: 'account-a' } }, ApiError, apiFetchRaw);
+ auth.apiFetch = new Function('getAccessToken', 'refresh', 'terminateSession', 'userRef', 'ApiError', 'apiFetchRaw', 'isSelfHostedRelayBaseUrl', compiled + '; return request;')(getAccessToken, refresh, terminateSession, { current: { id: 'account-a' } }, ApiError, apiFetchRaw, isSelfHostedRelayBaseUrl);
});
-afterEach(() => { vi.unstubAllGlobals(); setMobileAuthOwner(null); });
+afterEach(() => { vi.unstubAllGlobals(); setMobileAuthOwner(null); relayRoutingTesting.reset(); });
describe('shared-task HTTP account fence', () => {
it('sends and refreshes once while the originating account remains current', async () => {
@@ -101,4 +109,17 @@ describe('shared-task HTTP account fence', () => {
await expect(auth.apiFetch('/resource', { baseUrl: 'https://relay.example.invalid' })).resolves.toEqual(closed);
expect(fetchMock).toHaveBeenCalledTimes(2);
});
+ // Self-hosted relay (docs/self-hosted-relay-plan.md §5.3): even a proxy-style 401 (HTTP_401, normally
+ // refreshable) from the relay must not fetch, refresh or send the account token, nor end the session.
+ it('sends self-hosted relay requests with the relay credential only, without refresh or sign-out on 401', async () => {
+ setActiveSelfHostedRelay({ relayId: 'relay-1', name: 'Home', baseUrl: 'https://relay.home.example', credential: 'relay-credential', signing: null });
+ fetchMock.mockResolvedValue({ ok: false, status: 401, json: async () => null } as unknown as Response);
+ await expect(auth.apiFetch('/api/device-link/devices', { baseUrl: 'https://relay.home.example' }))
+ .rejects.toMatchObject({ code: 'RELAY_CREDENTIAL_INVALID', status: 401 });
+ expect(fetchMock).toHaveBeenCalledOnce();
+ expect(fetchMock.mock.calls[0][1].headers.Authorization).toBe('CindyRelay relay-credential');
+ expect(getAccessToken).not.toHaveBeenCalled();
+ expect(refresh).not.toHaveBeenCalled();
+ expect(terminateSession).not.toHaveBeenCalled();
+ });
});
diff --git a/apps/mobile/src/api/client.ts b/apps/mobile/src/api/client.ts
index 9d8a120bed..9b6a419fba 100644
--- a/apps/mobile/src/api/client.ts
+++ b/apps/mobile/src/api/client.ts
@@ -1,5 +1,11 @@
import { i18n } from '@/i18n';
import { mobileDebugLog } from '@/debug/mobileDebugLog';
+import { selfHostedRelayAuthorizationFor } from '@/device-link/selfHostedRelayRouting';
+
+/** 自建中转的 401 统一成这个码:只表示中转凭证失效,不可刷新账号 token,也不触发账号退出。 */
+export const RELAY_CREDENTIAL_INVALID = 'RELAY_CREDENTIAL_INVALID';
+/** 目标是自建中转但本机没有可用凭证:请求不发出。 */
+export const RELAY_CREDENTIAL_UNAVAILABLE = 'RELAY_CREDENTIAL_UNAVAILABLE';
export class ApiError extends Error {
constructor(
@@ -54,8 +60,14 @@ export async function apiFetchRaw<T>(
): Promise<T> {
opts.assertCurrent?.();
if (opts.signal?.aborted) throw requestAborted();
+ // 自建中转(docs/self-hosted-relay-plan.md §5.3):按目标地址换成中转凭证,账号 token 不发过去。
+ const relayAuth = selfHostedRelayAuthorizationFor(opts.baseUrl);
+ if (relayAuth?.kind === 'blocked') {
+ throw new ApiError(RELAY_CREDENTIAL_UNAVAILABLE, 0, i18n.t('relay.errors.credentialUnavailable'));
+ }
const headers: Record<string, string> = { ...opts.headers, 'Content-Type': 'application/json' };
- if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
+ if (relayAuth) headers.Authorization = `CindyRelay ${relayAuth.credential}`;
+ else if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
if (opts.cache === 'no-store') {
// Also tell native HTTP caches not to reuse or store short-lived responses.
headers['Cache-Control'] = 'no-cache, no-store';
@@ -141,7 +153,11 @@ export async function apiFetchRaw<T>(
if (opts.signal?.aborted) throw requestAborted();
if (!response.ok) {
const error = readError(data);
- const code = error.code ?? `HTTP_${response.status}`;
+ // 中转(或它前面的代理)回的任何 401 都只说明中转凭证不对:不能被当成账号 token 过期去刷新,
+ // 更不能凭它自报的 ACCOUNT_UNAVAILABLE 让账号退出。
+ const code = relayAuth && response.status === 401
+ ? RELAY_CREDENTIAL_INVALID
+ : error.code ?? `HTTP_${response.status}`;
if (response.status === 401 && code === 'ACCOUNT_UNAVAILABLE') {
try {
await accountUnavailableHandler?.();
diff --git a/apps/mobile/src/auth/AuthContext.tsx b/apps/mobile/src/auth/AuthContext.tsx
index 8af7cd15c6..5adee4eecb 100644
--- a/apps/mobile/src/auth/AuthContext.tsx
+++ b/apps/mobile/src/auth/AuthContext.tsx
@@ -122,6 +122,7 @@ import { unregisterPushTokenBestEffort } from '@/notifications/pushNotifications
import { resetAgentCapabilitiesCache } from '@/session/agentCapabilitiesCache';
import { resetComposerPaletteCache } from '@/session/composerPaletteCache';
import { clearRemoteResourceCache } from '@/device-link/remoteResourceCache';
+import { isSelfHostedRelayBaseUrl } from '@/device-link/selfHostedRelayRouting';
import { clearCachedHomeListSnapshot } from '@/session/mobileHomeListCache';
import { getMobileAuthOwner, invalidateMobileAuthOwnerForSwitch, setMobileAuthOwner } from '@/auth/authOwnerGeneration';
import { updateCredentialAccessToken } from '@/remote-desktop/credentialIdentity';
@@ -3312,6 +3313,11 @@ export function AuthProvider({ children }: { children: ReactNode }) {
opts: Omit<ApiFetchOptions, 'token'>,
): Promise<T> => {
opts.assertCurrent?.();
+ // 自建中转:中转凭证由 apiFetchRaw 按目标地址附上;账号 token 不取、不发,中转的 401
+ // 只说明中转凭证失效,不刷新也不退出账号(docs/self-hosted-relay-plan.md §5.3)。
+ if (isSelfHostedRelayBaseUrl(opts.baseUrl)) {
+ return apiFetchRaw<T>(path, { ...opts, token: null });
+ }
const token = await getAccessToken();
opts.assertCurrent?.();
if (!token) throw new Error('UNAUTHENTICATED');
diff --git a/apps/mobile/src/auth/secureStorage.ts b/apps/mobile/src/auth/secureStorage.ts
index 56dd2ba584..8aec2acc6a 100644
--- a/apps/mobile/src/auth/secureStorage.ts
+++ b/apps/mobile/src/auth/secureStorage.ts
@@ -8,9 +8,20 @@ export async function getSecureItem(key: string): Promise<string | null> {
return getWebStorage()?.getItem(key) ?? memoryStorage.get(key) ?? null;
}
-export async function setSecureItem(key: string, value: string): Promise<void> {
+export async function setSecureItem(
+ key: string,
+ value: string,
+ /** thisDeviceOnly:只在解锁时可读、不随备份迁移到别的设备(iOS WHEN_UNLOCKED_THIS_DEVICE_ONLY)。 */
+ options?: { thisDeviceOnly?: boolean },
+): Promise<void> {
if (Platform.OS !== 'web') {
- await SecureStore.setItemAsync(key, value);
+ if (options?.thisDeviceOnly) {
+ await SecureStore.setItemAsync(key, value, {
+ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+ });
+ } else {
+ await SecureStore.setItemAsync(key, value);
+ }
return;
}
const storage = getWebStorage();
diff --git a/apps/mobile/src/config/env.ts b/apps/mobile/src/config/env.ts
index 842adf6907..d4042112d3 100644
--- a/apps/mobile/src/config/env.ts
+++ b/apps/mobile/src/config/env.ts
@@ -273,6 +273,27 @@ export let DEVICE_LINK_API_BASE_URL = resolveDeviceLinkApiBaseUrl(
configuredValue('EXPO_PUBLIC_XDT_DEVICE_LINK_API_BASE_URL'),
);
+// 官方中转地址:构建清单 / realm 激活写入的值,也是 realm 缓存里的 deviceLinkApiBaseUrl。
+// 自建中转(docs/self-hosted-relay-plan.md §5.3)只覆盖对外的 DEVICE_LINK_API_BASE_URL,
+// 区域函数之后的每次写入都重新套用覆盖值;推送等直接读 realm 缓存的路径仍拿到官方地址。
+let officialDeviceLinkApiBaseUrl = DEVICE_LINK_API_BASE_URL;
+let deviceLinkApiBaseOverride: string | null = null;
+
+function writeOfficialDeviceLinkApiBaseUrl(value: string): void {
+ officialDeviceLinkApiBaseUrl = value;
+ DEVICE_LINK_API_BASE_URL = deviceLinkApiBaseOverride ?? value;
+}
+
+/**
+ * 自建中转的地址覆盖:非空时所有 device-link 消费者(REST、WebSocket)改连这个地址;
+ * null 恢复官方中转。只由 device-link/selfHostedRelayRouting 调用,凭证与鉴权方案在那里一并切换。
+ */
+export function setDeviceLinkApiBaseOverride(baseUrl: string | null): void {
+ const normalized = baseUrl?.trim().replace(/\/+$/, '') ?? '';
+ deviceLinkApiBaseOverride = normalized || null;
+ DEVICE_LINK_API_BASE_URL = deviceLinkApiBaseOverride ?? officialDeviceLinkApiBaseUrl;
+}
+
/** voice-server 数据面;正式包由启动端点清单回填。 */
export let VOICE_API_BASE_URL = normalizeBaseUrlWithDefault(
configuredValue('EXPO_PUBLIC_CINDY_VOICE_API_BASE_URL'),
@@ -286,7 +307,7 @@ function syncBuildTokenEndpointCache(): void {
...buildEndpointMap,
authApiBaseUrl: AUTH_API_BASE_URL,
oauthBrokerApiBaseUrl: OAUTH_BROKER_API_BASE_URL,
- deviceLinkApiBaseUrl: DEVICE_LINK_API_BASE_URL,
+ deviceLinkApiBaseUrl: officialDeviceLinkApiBaseUrl,
voiceApiBaseUrl: VOICE_API_BASE_URL,
};
realmEndpointCache.set(buildRealm, buildEndpointMap);
@@ -460,7 +481,9 @@ export function applyResolvedClientEndpoints(
);
}
if (resolved.deviceLinkApiBaseUrl !== undefined) {
- DEVICE_LINK_API_BASE_URL = resolved.deviceLinkApiBaseUrl.replace(/\/$/, '');
+ writeOfficialDeviceLinkApiBaseUrl(
+ resolved.deviceLinkApiBaseUrl.replace(/\/$/, ''),
+ );
}
if (resolved.voiceApiBaseUrl !== undefined) {
VOICE_API_BASE_URL = resolved.voiceApiBaseUrl.replace(/\/$/, '');
@@ -566,7 +589,7 @@ export function activateMobileSessionRealm(region: ClientEndpointRegion): void {
activeSessionRealm = region;
AUTH_API_BASE_URL = endpoints.authApiBaseUrl;
OAUTH_BROKER_API_BASE_URL = endpoints.oauthBrokerApiBaseUrl;
- DEVICE_LINK_API_BASE_URL = endpoints.deviceLinkApiBaseUrl;
+ writeOfficialDeviceLinkApiBaseUrl(endpoints.deviceLinkApiBaseUrl);
VOICE_API_BASE_URL = endpoints.voiceApiBaseUrl;
}
@@ -577,7 +600,7 @@ export function resetMobileSessionRealm(): void {
if (!endpoints) return;
AUTH_API_BASE_URL = endpoints.authApiBaseUrl;
OAUTH_BROKER_API_BASE_URL = endpoints.oauthBrokerApiBaseUrl;
- DEVICE_LINK_API_BASE_URL = endpoints.deviceLinkApiBaseUrl;
+ writeOfficialDeviceLinkApiBaseUrl(endpoints.deviceLinkApiBaseUrl);
VOICE_API_BASE_URL = endpoints.voiceApiBaseUrl;
}
diff --git a/apps/mobile/src/device-link/DeviceLinkContext.tsx b/apps/mobile/src/device-link/DeviceLinkContext.tsx
index 5bc015ec99..e358d9619d 100644
--- a/apps/mobile/src/device-link/DeviceLinkContext.tsx
+++ b/apps/mobile/src/device-link/DeviceLinkContext.tsx
@@ -55,6 +55,13 @@ import {
import { deviceLinkWsUrl, DEVICE_LINK_API_BASE_URL } from '@/config/env';
import { MOBILE_VISUAL_MOCK_ENABLED } from '@/config/env';
import { useAuth } from '@/auth/AuthContext';
+import { useSelfHostedRelayRouteGeneration } from './selfHostedRelay';
+import { currentSelfHostedRelayFrameAuth } from './selfHostedRelayFrameAuth';
+import {
+ getActiveSelfHostedRelay,
+ getSelfHostedRelayRouteGeneration,
+ waitForSelfHostedRelayRoute,
+} from './selfHostedRelayRouting';
import { getMobileAuthOwner, isMobileAuthOwnerCurrent } from '@/auth/authOwnerGeneration';
import { useSharedTaskApi } from './useSharedTaskApi';
import {
@@ -401,6 +408,8 @@ export function DeviceLinkProvider({ children }: { children: ReactNode }) {
}
const auth = useAuth();
+ // 官方中转 ↔ 自建中转切换时,与换账号走同一条重建连接的路径(见下方 client effect 依赖)。
+ const relayRouteGeneration = useSelfHostedRelayRouteGeneration();
const [directBridge] = useState(() => createDirectRuntimeBridge());
const sharedTaskApi = useSharedTaskApi();
const currentDataOwnerIdRef = useRef<string | null>(auth.user?.id ?? null);
@@ -1000,10 +1009,31 @@ export function DeviceLinkProvider({ children }: { children: ReactNode }) {
// 新账号/新 client 必须从空的 peer 生命周期表开始;旧连接迟到的恢复结果
// 会被 scheduler generation 丢弃,不能写回新账号。
peerRecoverySchedulerRef.current?.clear();
+ // 旧 client 的连接问题(如被自建中转移除的 4410)属于旧连接;cleanup 先退订再 stop,
+ // 新 client 不会替它清掉,这里显式清空。
+ setConnectionIssue(null);
+ // 这个 client 只服务创建时的那一代路由;路由一变 effect 会重建 client。
+ const clientRelayRoute = getSelfHostedRelayRouteGeneration();
+ const getAccessToken = auth.getAccessToken;
const client = new DeviceLinkClient({
directRuntime: directBridge.runtime,
getWsUrl: () => deviceLinkWsUrl(),
- getToken: auth.getAccessToken,
+ // 自建中转用中转凭证 + CindyRelay,账号 token 绝不发往中转(docs/self-hosted-relay-plan.md §5.2)。
+ // 先等本账号的中转设置读完,避免冷启动先连上官方再切走;取 token 期间路由变了就放弃这一轮,
+ // 不让官方 token 与 CindyRelay 方案、中转地址拼到同一次握手里。
+ getToken: async () => {
+ await waitForSelfHostedRelayRoute();
+ if (getSelfHostedRelayRouteGeneration() !== clientRelayRoute) return null;
+ const relay = getActiveSelfHostedRelay();
+ if (relay) return relay.credential;
+ const token = await getAccessToken();
+ return getSelfHostedRelayRouteGeneration() === clientRelayRoute ? token : null;
+ },
+ authorizationScheme: () => (getActiveSelfHostedRelay() ? 'CindyRelay' : 'Bearer'),
+ // 自建中转的设备签名(docs/self-hosted-relay-plan.md §16);官方中转返回 null。手机只签名、不核对
+ // 收到的消息:Hermes 上纯 JS 的 Ed25519 核对太慢,跟不上推送流。电脑核对所有对端消息,所以被人
+ // 控制的中转最多能在手机上显示伪造的内容,无法让任何一台电脑执行任何操作。
+ frameAuth: currentSelfHostedRelayFrameAuth,
getHello: () => ({
capabilities: [SHARED_TASK_CAPABILITY],
deviceName: mobileDeviceName(),
@@ -1548,6 +1578,7 @@ export function DeviceLinkProvider({ children }: { children: ReactNode }) {
auth.accountGeneration,
auth.getAccessToken,
auth.isAuthenticated,
+ relayRouteGeneration,
clearPerAccountDeviceLinkState,
clearOnePresenceWipeTimer,
clearAllPresenceWipeTimers,
diff --git a/apps/mobile/src/device-link/relayAuthCrypto.ts b/apps/mobile/src/device-link/relayAuthCrypto.ts
new file mode 100644
index 0000000000..c466f208ba
--- /dev/null
+++ b/apps/mobile/src/device-link/relayAuthCrypto.ts
@@ -0,0 +1,29 @@
+/**
+ * 自建中转设备签名的 `RelayAuthCrypto` 手机实现(docs/self-hosted-relay-plan.md §16)。
+ *
+ * 纯 JS 的 @noble 做 Ed25519 / SHA-256 / HMAC,随机数取系统安全随机源(expo-crypto)。
+ * 不提供 `utf8`:Hermes 上没有可靠的 TextEncoder,由共享包的纯 JS 编码器处理。
+ * 与电脑端的 node:crypto 实现逐字节兼容(Ed25519 签名是确定性的)。
+ */
+import { ed25519 } from '@noble/curves/ed25519';
+import { hmac } from '@noble/hashes/hmac';
+import { sha256 } from '@noble/hashes/sha256';
+import { getRandomBytes } from 'expo-crypto';
+import type { RelayAuthCrypto } from '@cindy/device-link';
+
+export const mobileRelayAuthCrypto: RelayAuthCrypto = {
+ sha256: (data) => sha256(data),
+ hmacSha256: (key, data) => hmac(sha256, key, data),
+ ed25519PublicKey: (seed) => ed25519.getPublicKey(seed),
+ ed25519Sign: (seed, message) => ed25519.sign(message, seed),
+ ed25519Verify(publicKey, message, signature) {
+ if (publicKey.length !== 32 || signature.length !== 64) return false;
+ try {
+ // 严格按 RFC 8032 核对(与 node:crypto 一致),不接受 ZIP-215 放宽的写法。
+ return ed25519.verify(signature, message, publicKey, { zip215: false });
+ } catch {
+ return false;
+ }
+ },
+ randomBytes: (size) => getRandomBytes(size),
+};
diff --git a/apps/mobile/src/device-link/relayJoinIntent.ts b/apps/mobile/src/device-link/relayJoinIntent.ts
new file mode 100644
index 0000000000..429cd45259
--- /dev/null
+++ b/apps/mobile/src/device-link/relayJoinIntent.ts
@@ -0,0 +1,99 @@
+/**
+ * 手机收到的「加入中转」链接(`cindy://relay/join?u=<中转地址>&c=<加入码>&o=<主人公钥>&s=<配对秘密>`,
+ * 也接受 cindycn / cindydev 与 Router 去掉 scheme 后的 `/relay/join?...`;见 docs/self-hosted-relay-plan.md
+ * §5.1、§16)。
+ *
+ * 加入码与配对秘密是一次性秘密:不进路由状态、日志或诊断。这里只在内存里留一份解析结果供加入页读取;
+ * 不合法的链接什么都不留。10 分钟(加入码有效期)后丢弃;登录前收到的链接由第一次登录的账号
+ * 接手,换账号即丢弃。
+ */
+import { useSyncExternalStore } from 'react';
+import { parseRelayJoinLink, type RelayJoinLink } from '@cindy/device-link';
+
+import { getMobileAuthOwner, isMobileAuthOwnerCurrent, subscribeMobileAuthOwner } from '@/auth/authOwnerGeneration';
+
+/** 加入页路由;不带任何参数。 */
+export const RELAY_JOIN_ROUTE = '/relay-join';
+const RELAY_JOIN_INTENT_TTL_MS = 10 * 60_000;
+
+export interface RelayJoinIntent {
+ /** 每收到一条链接加一;加入页据此在打开期间换成新链接。 */
+ id: number;
+ /** null = 收到了链接但不合法或已丢弃(加入页显示「链接无效」)。 */
+ link: RelayJoinLink | null;
+}
+
+let pending: RelayJoinIntent | null = null;
+let sequence = 0;
+let expiry: ReturnType<typeof setTimeout> | undefined;
+let stopWatching: (() => void) | undefined;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+ for (const listener of listeners) listener();
+}
+
+function release(): void {
+ pending = null;
+ clearTimeout(expiry);
+ expiry = undefined;
+ stopWatching?.();
+ stopWatching = undefined;
+}
+
+const SCHEME_PREFIX = /^[a-zA-Z][\w+.-]*:\/\//;
+
+/** 去掉 scheme 后统一成以 `/` 开头的路径(Router 给的可能是完整链接,也可能没有前导斜杠)。 */
+function routerPath(path: string): string {
+ const noScheme = path.trim().replace(SCHEME_PREFIX, '/');
+ return noScheme.startsWith('/') ? noScheme : `/${noScheme}`;
+}
+
+/** 这个系统路径是不是加入中转(任意 scheme、相对路径都算,合法与否另说)。 */
+export function isRelayJoinPath(path: string): boolean {
+ const pathname = routerPath(path).split(/[?#]/)[0].replace(/\/+$/, '');
+ return pathname === '/relay' || pathname === '/relay/join';
+}
+
+/**
+ * 收下一条系统链接。是加入中转的路径就返回 true(调用方改路由到加入页,不带参数);
+ * 先丢掉之前留着的链接,再只为合法链接留一份解析结果。
+ */
+export function receiveRelayJoinIntent(path: string): boolean {
+ if (!isRelayJoinPath(path)) return false;
+ release();
+ let owner = getMobileAuthOwner();
+ // 带 scheme 的完整链接交给共享解析器校验 scheme;Router 去掉 scheme 的形态按路径解析。
+ const candidate = SCHEME_PREFIX.test(path.trim()) ? path : routerPath(path);
+ const link = owner.switching ? null : parseRelayJoinLink(candidate);
+ pending = { id: ++sequence, link };
+ if (link) {
+ expiry = setTimeout(clearRelayJoinIntent, RELAY_JOIN_INTENT_TTL_MS);
+ stopWatching = subscribeMobileAuthOwner(() => {
+ const next = getMobileAuthOwner();
+ if (next.switching || (owner.accountKey && !isMobileAuthOwnerCurrent(owner))) clearRelayJoinIntent();
+ else if (next.accountKey) owner = next; // 登录前收到的链接由第一次登录的账号接手。
+ });
+ }
+ notify();
+ return true;
+}
+
+/** 加入码已提交(中转已作废它)、用户放弃或页面换了链接时调用。 */
+export function clearRelayJoinIntent(): void {
+ if (!pending) return;
+ release();
+ notify();
+}
+
+export const getPendingRelayJoinIntent = (): RelayJoinIntent | null => pending;
+
+export function subscribeRelayJoinIntent(listener: () => void): () => void {
+ listeners.add(listener);
+ return () => {
+ listeners.delete(listener);
+ };
+}
+
+export const usePendingRelayJoinIntent = (): RelayJoinIntent | null =>
+ useSyncExternalStore(subscribeRelayJoinIntent, getPendingRelayJoinIntent, getPendingRelayJoinIntent);
diff --git a/apps/mobile/src/device-link/remoteStatus.ts b/apps/mobile/src/device-link/remoteStatus.ts
index 4b7c84926c..2c4230ce49 100644
--- a/apps/mobile/src/device-link/remoteStatus.ts
+++ b/apps/mobile/src/device-link/remoteStatus.ts
@@ -5,6 +5,7 @@ import {
} from '@cindy/maker-shared/device-link-contract';
import type { DeviceLinkConnectionIssue, DeviceLinkConnectionIssueKind, DeviceLinkStatus } from '@cindy/device-link';
import type { LocalNetworkStatus } from '@/device-link/localNetworkStatus';
+import { getActiveSelfHostedRelay } from '@/device-link/selfHostedRelayRouting';
import { i18n } from '@/i18n';
import { parseAgentErrorCode } from '@cindy/maker-shared/error-redaction';
@@ -33,12 +34,22 @@ const CONNECTION_ISSUE_COPY_KEYS: Record<
unstable: { title: 'deviceLink.unstableTitle', hint: 'deviceLink.unstableHint' },
};
+/**
+ * 自建中转下,鉴权失败与 4410 只说明中转凭证失效(被主人移出或中转已停用),与 Cindy 登录无关:
+ * 不能沿用「请重新登录」,改为指向设置里的「切回官方中转」。
+ */
+function isSelfHostedRelayRemoval(kind: DeviceLinkConnectionIssueKind): boolean {
+ return (kind === 'auth-failed' || kind === 'device-removed') && getActiveSelfHostedRelay() !== null;
+}
+
/** Mobile 连接问题标题/提示统一走 i18n,避免同一 banner 混用本地化与中文硬编码。 */
export function connectionIssueTitle(kind: DeviceLinkConnectionIssueKind): string {
+ if (isSelfHostedRelayRemoval(kind)) return i18n.t('relay.issue.removedTitle');
return i18n.t(CONNECTION_ISSUE_COPY_KEYS[kind].title);
}
export function connectionIssueHint(kind: DeviceLinkConnectionIssueKind): string {
+ if (isSelfHostedRelayRemoval(kind)) return i18n.t('relay.issue.removedHint');
return i18n.t(CONNECTION_ISSUE_COPY_KEYS[kind].hint);
}
diff --git a/apps/mobile/src/device-link/selfHostedRelay.ts b/apps/mobile/src/device-link/selfHostedRelay.ts
new file mode 100644
index 0000000000..76b5c8ae3b
--- /dev/null
+++ b/apps/mobile/src/device-link/selfHostedRelay.ts
@@ -0,0 +1,332 @@
+/**
+ * 手机的自建中转设置(docs/self-hosted-relay-plan.md §5.2、§5.3)。
+ *
+ * 按 Cindy 账号保存:
+ * - 非秘密设置在 AsyncStorage `cindy.mobile.self-hosted-relay.v2.<账号 key>`:没有这条 = 官方中转;
+ * 有 = `{ mode: 'self-hosted', relayId, name, baseUrl, role, deviceId, ownerPublicKey }`。
+ * - 中转设备凭证与本机签名密钥种子(§16)作为一个 JSON `{ credential, seed }` 存在安全存储
+ * `cindy.selfHostedRelay.credential.v2.<账号 key 的 SHA-256 前 32 位>`,`WHEN_UNLOCKED_THIS_DEVICE_ONLY`:
+ * 不随备份迁到别的手机,也不进日志与诊断。
+ * - v1(设备签名之前)的条目没有签名密钥,电脑不再接受这台手机发出的未签名消息:读到时按官方中转处理,
+ * 并尽力删除,用户需要重新加入。
+ *
+ * 账号切换时(authOwnerGeneration 同步发布)先清空内存路由,再读新账号的设置;读完之前
+ * device-link 不建连(selfHostedRelayRouting.waitForSelfHostedRelayRoute)。退出登录只清内存路由,
+ * 本机设置留给同一账号下次登录:中转成员资格属于「这台手机 + 这个账号」,重新加入要主人再同意一次。
+ */
+import { useSyncExternalStore } from 'react';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils';
+import { isRelayPublicKey, normalizeRelayBaseUrl, type RelayFetch } from '@cindy/device-link';
+
+import {
+ getMobileAuthOwner,
+ isMobileAuthOwnerCurrent,
+ subscribeMobileAuthOwner,
+ type MobileAuthOwnerGeneration,
+} from '@/auth/authOwnerGeneration';
+import { deleteSecureItem, getSecureItem, setSecureItem } from '@/auth/secureStorage';
+import { mobileDebugLog } from '@/debug/mobileDebugLog';
+
+import {
+ getActiveSelfHostedRelay,
+ getSelfHostedRelayRouteGeneration,
+ setActiveSelfHostedRelay,
+ setSelfHostedRelayLoading,
+ subscribeSelfHostedRelayRoute,
+ type SelfHostedRelayRoute,
+} from './selfHostedRelayRouting';
+
+const CONFIG_PREFIX = 'cindy.mobile.self-hosted-relay.v2.';
+// SecureStore 的 key 只允许 [A-Za-z0-9._-];账号 key 是 JSON,取哈希。
+const SECRETS_PREFIX = 'cindy.selfHostedRelay.credential.v2.';
+const LEGACY_CONFIG_PREFIX = 'cindy.mobile.self-hosted-relay.v1.';
+const LEGACY_CREDENTIAL_PREFIX = 'cindy.selfHostedRelay.credential.v1.';
+const SEED_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const LEAVE_TIMEOUT_MS = 5_000;
+
+interface StoredRelayConfig {
+ version: 2;
+ mode: 'self-hosted';
+ relayId: string;
+ name: string;
+ baseUrl: string;
+ /** 手机只能作为成员加入;主人设备只在电脑上。 */
+ role: 'member';
+ /** 加入时上报、证书里的设备 ID(= 官方登录的设备 ID),签名与退出中转时用。 */
+ deviceId: string;
+ /** 加入链接里的主人公钥。 */
+ ownerPublicKey: string;
+}
+
+/** 安全存储里的一条:凭证与签名种子同存同删,不会只剩一半。 */
+interface StoredRelaySecrets {
+ credential: string;
+ seed: string;
+}
+
+function accountHash(accountKey: string): string {
+ return bytesToHex(sha256(utf8ToBytes(accountKey))).slice(0, 32);
+}
+
+function configKey(accountKey: string): string {
+ return CONFIG_PREFIX + accountKey;
+}
+
+function secretsKey(accountKey: string): string {
+ return SECRETS_PREFIX + accountHash(accountKey);
+}
+
+function parseStoredConfig(raw: string | null): StoredRelayConfig | null {
+ if (!raw) return null;
+ try {
+ const value = JSON.parse(raw) as Partial<StoredRelayConfig>;
+ const baseUrl = typeof value.baseUrl === 'string' ? normalizeRelayBaseUrl(value.baseUrl) : null;
+ if (
+ value.version !== 2 ||
+ value.mode !== 'self-hosted' ||
+ typeof value.relayId !== 'string' ||
+ typeof value.name !== 'string' ||
+ typeof value.deviceId !== 'string' ||
+ !isRelayPublicKey(value.ownerPublicKey) ||
+ !baseUrl
+ ) {
+ return null;
+ }
+ return {
+ version: 2,
+ mode: 'self-hosted',
+ relayId: value.relayId,
+ name: value.name,
+ baseUrl,
+ role: 'member',
+ deviceId: value.deviceId,
+ ownerPublicKey: value.ownerPublicKey,
+ };
+ } catch {
+ return null;
+ }
+}
+
+function parseStoredSecrets(raw: string | null): StoredRelaySecrets | null {
+ if (!raw) return null;
+ try {
+ const value = JSON.parse(raw) as Partial<StoredRelaySecrets>;
+ if (typeof value.credential !== 'string' || !value.credential) return null;
+ if (typeof value.seed !== 'string' || !SEED_PATTERN.test(value.seed)) return null;
+ return { credential: value.credential, seed: value.seed };
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * v1(设备签名之前)的设置与凭证:没有签名密钥,用不了了(电脑会丢弃未签名的消息)。
+ * 尽力删除;删不掉也只是留一条不再读取的旧数据。
+ */
+async function discardLegacyRelay(accountKey: string): Promise<void> {
+ try {
+ if ((await AsyncStorage.getItem(LEGACY_CONFIG_PREFIX + accountKey)) === null) return;
+ await deleteSecureItem(LEGACY_CREDENTIAL_PREFIX + accountHash(accountKey));
+ await AsyncStorage.removeItem(LEGACY_CONFIG_PREFIX + accountKey);
+ mobileDebugLog('info', 'device-link', 'discarded self-hosted relay settings from before device signatures');
+ } catch (error) {
+ mobileDebugLog('warn', 'device-link', 'legacy self-hosted relay cleanup failed',
+ error instanceof Error ? error.name : 'unknown');
+ }
+}
+
+/** 当前账号的设置;只在内存,与路由同步更新。退出中转时要用其中的 deviceId。 */
+let currentConfig: StoredRelayConfig | null = null;
+let loadedAccountKey = '';
+let loadSequence = 0;
+
+function syncOwner(): void {
+ const owner = getMobileAuthOwner();
+ if (owner.switching || !owner.accountKey) {
+ loadSequence += 1;
+ loadedAccountKey = '';
+ currentConfig = null;
+ setActiveSelfHostedRelay(null);
+ setSelfHostedRelayLoading(false);
+ return;
+ }
+ if (owner.accountKey === loadedAccountKey) return;
+ loadedAccountKey = owner.accountKey;
+ const sequence = ++loadSequence;
+ // 上一个账号的中转不能被新账号沿用,哪怕只是读设置的这一小段时间。
+ currentConfig = null;
+ setActiveSelfHostedRelay(null);
+ setSelfHostedRelayLoading(true);
+ void discardLegacyRelay(owner.accountKey);
+ void (async () => {
+ let config: StoredRelayConfig | null = null;
+ let secrets: StoredRelaySecrets | null = null;
+ try {
+ config = parseStoredConfig(await AsyncStorage.getItem(configKey(owner.accountKey)));
+ if (config) secrets = parseStoredSecrets(await getSecureItem(secretsKey(owner.accountKey)));
+ } catch (error) {
+ // 读不到设置时按官方中转处理;读不到凭证时保留自建设置,由设置页提示重新加入或切回。
+ mobileDebugLog('warn', 'device-link', 'self-hosted relay settings unavailable',
+ error instanceof Error ? error.name : 'unknown');
+ }
+ if (sequence !== loadSequence) return;
+ currentConfig = config;
+ setActiveSelfHostedRelay(config ? routeFromConfig(config, secrets) : null);
+ setSelfHostedRelayLoading(false);
+ })();
+}
+
+function routeFromConfig(config: StoredRelayConfig, secrets: StoredRelaySecrets | null): SelfHostedRelayRoute {
+ return {
+ relayId: config.relayId,
+ name: config.name,
+ baseUrl: config.baseUrl,
+ credential: secrets?.credential ?? null,
+ signing: secrets
+ ? { deviceId: config.deviceId, ownerPublicKey: config.ownerPublicKey, seed: secrets.seed }
+ : null,
+ };
+}
+
+subscribeMobileAuthOwner(syncOwner);
+syncOwner();
+
+function assertOwnerCurrent(owner: MobileAuthOwnerGeneration): void {
+ if (!owner.accountKey || owner.switching || !isMobileAuthOwnerCurrent(owner)) {
+ throw new Error('ACCOUNT_CHANGED');
+ }
+}
+
+/**
+ * 加入成功(且证书已核对)后保存并切换到这个中转。凭证只返回一次,先写安全存储再写设置;
+ * 设置写失败时把安全存储恢复成原来的,避免设置与凭证、签名密钥对不上。
+ */
+export async function saveSelfHostedRelay(input: {
+ owner: MobileAuthOwnerGeneration;
+ relayId: string;
+ name: string;
+ baseUrl: string;
+ deviceId: string;
+ ownerPublicKey: string;
+ credential: string;
+ /** 本机签名私钥种子(base64url),见 `createRelayJoinIdentity`。 */
+ seed: string;
+}): Promise<void> {
+ assertOwnerCurrent(input.owner);
+ const baseUrl = normalizeRelayBaseUrl(input.baseUrl);
+ if (!baseUrl || !input.credential || !SEED_PATTERN.test(input.seed) || !isRelayPublicKey(input.ownerPublicKey)) {
+ throw new Error('INVALID_RELAY');
+ }
+ const accountKey = input.owner.accountKey;
+ const previousConfig = currentConfig;
+ const previousRoute = getActiveSelfHostedRelay();
+ const config: StoredRelayConfig = {
+ version: 2,
+ mode: 'self-hosted',
+ relayId: input.relayId,
+ name: input.name,
+ baseUrl,
+ role: 'member',
+ deviceId: input.deviceId,
+ ownerPublicKey: input.ownerPublicKey,
+ };
+ const secrets: StoredRelaySecrets = { credential: input.credential, seed: input.seed };
+ await setSecureItem(secretsKey(accountKey), JSON.stringify(secrets), { thisDeviceOnly: true });
+ try {
+ await AsyncStorage.setItem(configKey(accountKey), JSON.stringify(config));
+ } catch (error) {
+ const previousSecrets: StoredRelaySecrets | null = previousRoute?.credential && previousRoute.signing
+ ? { credential: previousRoute.credential, seed: previousRoute.signing.seed }
+ : null;
+ const restore = previousSecrets
+ ? setSecureItem(secretsKey(accountKey), JSON.stringify(previousSecrets), { thisDeviceOnly: true })
+ : deleteSecureItem(secretsKey(accountKey));
+ await restore.catch(() => undefined);
+ throw error;
+ }
+ // 保存属于发起加入的账号;账号已经切走就不切换当前路由(切回该账号时会读到它)。
+ if (!isMobileAuthOwnerCurrent(input.owner)) return;
+ currentConfig = config;
+ setActiveSelfHostedRelay(routeFromConfig(config, secrets));
+ // 从另一个自建中转换过来:顺手退出旧中转(尽力而为,失败只是在旧中转上留一条设备记录)。
+ if (previousConfig && previousRoute?.credential && previousConfig.baseUrl !== baseUrl) {
+ void leaveRelayBestEffort(previousConfig, previousRoute.credential);
+ }
+}
+
+/** 切回官方中转:删掉设置与凭证,立即恢复官方路由;再尽力让中转删掉这台手机。 */
+export async function clearSelfHostedRelay(): Promise<void> {
+ const owner = getMobileAuthOwner();
+ assertOwnerCurrent(owner);
+ const leavingConfig = currentConfig;
+ const leavingCredential = getActiveSelfHostedRelay()?.credential ?? null;
+ // 设置删不掉就不切:否则下次启动又回到这个中转,和用户看到的不一致。
+ await AsyncStorage.removeItem(configKey(owner.accountKey));
+ await deleteSecureItem(secretsKey(owner.accountKey)).catch((error: unknown) => {
+ mobileDebugLog('warn', 'device-link', 'self-hosted relay credential cleanup failed',
+ error instanceof Error ? error.name : 'unknown');
+ });
+ if (isMobileAuthOwnerCurrent(owner)) {
+ currentConfig = null;
+ setActiveSelfHostedRelay(null);
+ }
+ if (leavingConfig && leavingCredential) void leaveRelayBestEffort(leavingConfig, leavingCredential);
+}
+
+/** 成员可以让自己退出中转(DELETE /devices/<自己>);这里拿的是刚移除的凭证,不经 apiFetch。 */
+async function leaveRelayBestEffort(config: StoredRelayConfig, credential: string): Promise<void> {
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), LEAVE_TIMEOUT_MS);
+ try {
+ await fetch(`${config.baseUrl}/api/device-link/devices/${encodeURIComponent(config.deviceId)}`, {
+ method: 'DELETE',
+ headers: { Authorization: `CindyRelay ${credential}` },
+ signal: controller.signal,
+ });
+ } catch {
+ // 中转已停用或连不上:主人在电脑上仍能移除这台手机。
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+/**
+ * 加入流程用的 fetch:每个请求有自己的超时;调用方的取消信号照常生效
+ * (共享流程据此区分「用户取消」与「连不上」)。
+ */
+export function createRelayJoinFetch(timeoutMs: number): RelayFetch {
+ return async (url, init) => {
+ const controller = new AbortController();
+ const abort = () => controller.abort();
+ const timer = setTimeout(abort, timeoutMs);
+ if (init.signal?.aborted) controller.abort();
+ init.signal?.addEventListener('abort', abort, { once: true });
+ try {
+ return await fetch(url, {
+ method: init.method,
+ headers: init.headers,
+ body: init.body,
+ signal: controller.signal,
+ });
+ } finally {
+ clearTimeout(timer);
+ init.signal?.removeEventListener('abort', abort);
+ }
+ };
+}
+
+/** 界面用:当前账号的中转(null = 官方中转)。credential 为 null 表示本机凭证缺失。 */
+export function useSelfHostedRelay(): SelfHostedRelayRoute | null {
+ return useSyncExternalStore(subscribeSelfHostedRelayRoute, getActiveSelfHostedRelay, getActiveSelfHostedRelay);
+}
+
+/** DeviceLinkProvider 用:路由代次变化时按账号切换同一条路径重建连接。 */
+export function useSelfHostedRelayRouteGeneration(): number {
+ return useSyncExternalStore(
+ subscribeSelfHostedRelayRoute,
+ getSelfHostedRelayRouteGeneration,
+ getSelfHostedRelayRouteGeneration,
+ );
+}
diff --git a/apps/mobile/src/device-link/selfHostedRelayFrameAuth.ts b/apps/mobile/src/device-link/selfHostedRelayFrameAuth.ts
new file mode 100644
index 0000000000..4b8d75b3e1
--- /dev/null
+++ b/apps/mobile/src/device-link/selfHostedRelayFrameAuth.ts
@@ -0,0 +1,43 @@
+/**
+ * 手机的自建中转设备签名(docs/self-hosted-relay-plan.md §16):给 DeviceLinkClient 的 `frameAuth`。
+ * 经中转发出的每条对端消息用本机签名密钥签名;只签名、不核对收到的消息(原因见 DeviceLinkContext
+ * 里 `frameAuth` 处的说明),所以也不需要拉取证书列表。
+ */
+import { RelayFrameAuthenticator, type DeviceLinkFrameAuth } from '@cindy/device-link';
+
+import { mobileDebugLog } from '@/debug/mobileDebugLog';
+
+import { mobileRelayAuthCrypto } from './relayAuthCrypto';
+import { getActiveSelfHostedRelay } from './selfHostedRelayRouting';
+
+/** 本机密钥缺失或损坏:不能签名就不能安全通信。发出的消息不带签名(电脑会丢弃),收到的全部丢弃。 */
+const UNUSABLE: DeviceLinkFrameAuth = { sign: () => undefined, verify: () => false };
+
+let cached: { key: string; frameAuth: DeviceLinkFrameAuth } | null = null;
+
+/** DeviceLinkClient 每帧调用:官方中转返回 null(不签名、不核对,wire 与旧版相同)。 */
+export function currentSelfHostedRelayFrameAuth(): DeviceLinkFrameAuth | null {
+ const relay = getActiveSelfHostedRelay();
+ const signing = relay?.signing;
+ if (!relay || !signing) {
+ cached = null;
+ return relay ? UNUSABLE : null;
+ }
+ // 中转或本机签名身份一变就重建;种子只在内存里比较,不进日志。
+ const key = [relay.relayId, signing.deviceId, signing.ownerPublicKey, signing.seed].join('\n');
+ if (cached?.key === key) return cached.frameAuth;
+ try {
+ const authenticator = new RelayFrameAuthenticator({
+ crypto: mobileRelayAuthCrypto,
+ relayId: relay.relayId,
+ deviceId: signing.deviceId,
+ seed: signing.seed,
+ ownerPublicKey: signing.ownerPublicKey,
+ });
+ cached = { key, frameAuth: { sign: (frame) => authenticator.sign(frame), verify: () => true } };
+ } catch {
+ mobileDebugLog('warn', 'device-link', 'self-hosted relay signing key is unusable');
+ cached = { key, frameAuth: UNUSABLE };
+ }
+ return cached.frameAuth;
+}
diff --git a/apps/mobile/src/device-link/selfHostedRelayRouting.ts b/apps/mobile/src/device-link/selfHostedRelayRouting.ts
new file mode 100644
index 0000000000..fe48e2cf6e
--- /dev/null
+++ b/apps/mobile/src/device-link/selfHostedRelayRouting.ts
@@ -0,0 +1,156 @@
+/**
+ * 自建中转的进程内路由(docs/self-hosted-relay-plan.md §5.2、§5.3)。
+ *
+ * 只放同步可读的内存状态:当前账号是否改走自建中转、中转地址、设备凭证与签名身份。持久化(AsyncStorage +
+ * 安全存储)在 `selfHostedRelay.ts`;这里刻意不引 react-native / expo 原生模块,`api/client` 与
+ * WebSocket 鉴权每次请求都要同步查它。
+ *
+ * 三条约束都在这里收口:
+ * - 地址:切换时同步改写 env 的 DEVICE_LINK_API_BASE_URL 覆盖值,REST 与 WS 消费者调用时读到的
+ * 就是中转地址;
+ * - 凭证:发往当前中转的请求一律带 `CindyRelay <凭证>`,账号 token 不发往任何已知的自建中转地址
+ * (含切走之后迟到、仍拿着旧地址的请求);
+ * - 凭证只在内存里,不进日志、诊断与路由状态。
+ */
+import { setDeviceLinkApiBaseOverride } from '@/config/env';
+
+export interface SelfHostedRelayRoute {
+ relayId: string;
+ name: string;
+ /** 规范化后的中转基础地址(不含 `/api/...`,无末尾斜杠)。 */
+ baseUrl: string;
+ /**
+ * 加入时拿到的设备凭证。null = 配置还在但本机安全存储里读不到凭证(如换机恢复备份,
+ * 钥匙串条目按 THIS_DEVICE_ONLY 不随迁移):此时不发任何请求,界面提示重新加入或切回官方。
+ */
+ credential: string | null;
+ /**
+ * 本机在这个中转上的签名身份(docs/self-hosted-relay-plan.md §16),与凭证同存同取:
+ * 凭证缺失时它也是 null,此时不建连、不签名。种子同凭证一样只在内存,不进日志与诊断。
+ */
+ signing: SelfHostedRelaySigning | null;
+}
+
+export interface SelfHostedRelaySigning {
+ /** 证书里的设备 ID(= 加入时上报的官方设备 ID)。 */
+ deviceId: string;
+ /** 加入链接里的主人公钥。 */
+ ownerPublicKey: string;
+ /** 本机签名私钥种子(base64url)。 */
+ seed: string;
+}
+
+export type SelfHostedRelayAuthorization =
+ | { kind: 'relay'; credential: string }
+ /** 目标是自建中转,但当前没有可用凭证(凭证缺失,或该中转已不是当前中转):不发请求。 */
+ | { kind: 'blocked' };
+
+let active: SelfHostedRelayRoute | null = null;
+let generation = 0;
+let loading = false;
+let loadWaiters: Array<() => void> = [];
+/** 本进程里出现过的自建中转地址:切回官方后,迟到的请求也不能把账号 token 发过去。 */
+const knownRelayBases = new Set<string>();
+const listeners = new Set<() => void>();
+
+/** scheme 与 host 不区分大小写;路径原样保留,去掉末尾斜杠。 */
+export function normalizeSelfHostedRelayBase(url: string): string {
+ const trimmed = url.trim().replace(/\/+$/, '');
+ const match = /^([a-z][a-z0-9+.-]*:\/\/[^/?#]+)(.*)$/i.exec(trimmed);
+ return match ? match[1].toLowerCase() + match[2] : trimmed;
+}
+
+function sameSigning(a: SelfHostedRelaySigning | null, b: SelfHostedRelaySigning | null): boolean {
+ if (!a || !b) return a === b;
+ return a.deviceId === b.deviceId && a.ownerPublicKey === b.ownerPublicKey && a.seed === b.seed;
+}
+
+function sameRoute(a: SelfHostedRelayRoute | null, b: SelfHostedRelayRoute | null): boolean {
+ if (!a || !b) return a === b;
+ return a.relayId === b.relayId && a.name === b.name && a.baseUrl === b.baseUrl && a.credential === b.credential
+ && sameSigning(a.signing, b.signing);
+}
+
+function notify(): void {
+ for (const listener of listeners) listener();
+}
+
+/** 当前生效的自建中转;null = 官方中转。 */
+export function getActiveSelfHostedRelay(): SelfHostedRelayRoute | null {
+ return active;
+}
+
+/**
+ * 路由代次:模式、地址或凭证真正变化时才 +1。DeviceLinkProvider 把它作为重建连接的依赖,
+ * 保证 WebSocket 的地址、token 与鉴权方案总在同一代里取值。
+ */
+export function getSelfHostedRelayRouteGeneration(): number {
+ return generation;
+}
+
+export function subscribeSelfHostedRelayRoute(listener: () => void): () => void {
+ listeners.add(listener);
+ return () => {
+ listeners.delete(listener);
+ };
+}
+
+/** 切换路由:同步改写 device-link 地址覆盖,随后通知订阅者重建连接。 */
+export function setActiveSelfHostedRelay(next: SelfHostedRelayRoute | null): void {
+ const normalized = next ? { ...next, baseUrl: normalizeSelfHostedRelayBase(next.baseUrl) } : null;
+ if (normalized) knownRelayBases.add(normalized.baseUrl);
+ const changed = !sameRoute(active, normalized);
+ const baseChanged = (active?.baseUrl ?? null) !== (normalized?.baseUrl ?? null);
+ active = normalized;
+ // 地址覆盖与路由同步切换(env 初始无覆盖,与 active=null 一致)。
+ if (baseChanged) setDeviceLinkApiBaseOverride(normalized?.baseUrl ?? null);
+ if (!changed) return;
+ generation += 1;
+ notify();
+}
+
+/** 读当前账号的中转设置期间置 true;device-link 首次建连会等它结束,避免先连上官方再切走。 */
+export function setSelfHostedRelayLoading(next: boolean): void {
+ if (loading === next) return;
+ loading = next;
+ if (next) return;
+ const waiters = loadWaiters;
+ loadWaiters = [];
+ for (const resolve of waiters) resolve();
+}
+
+export function waitForSelfHostedRelayRoute(): Promise<void> {
+ if (!loading) return Promise.resolve();
+ return new Promise((resolve) => {
+ loadWaiters.push(resolve);
+ });
+}
+
+/**
+ * 这个地址是否属于自建中转(当前的,或本进程里用过的)。是的话:账号 token 不发、不为它刷新,
+ * 它返回的 401 也不能让账号退出。
+ */
+export function isSelfHostedRelayBaseUrl(baseUrl: string | undefined | null): boolean {
+ if (!baseUrl) return false;
+ if (!active && knownRelayBases.size === 0) return false;
+ return knownRelayBases.has(normalizeSelfHostedRelayBase(baseUrl));
+}
+
+/** 发往这个地址的请求该带什么鉴权;null = 不是自建中转,按原逻辑带账号 token。 */
+export function selfHostedRelayAuthorizationFor(
+ baseUrl: string | undefined | null,
+): SelfHostedRelayAuthorization | null {
+ if (!isSelfHostedRelayBaseUrl(baseUrl)) return null;
+ if (active?.credential && active.baseUrl === normalizeSelfHostedRelayBase(baseUrl!)) {
+ return { kind: 'relay', credential: active.credential };
+ }
+ return { kind: 'blocked' };
+}
+
+export const __testing = {
+ reset(): void {
+ setActiveSelfHostedRelay(null);
+ knownRelayBases.clear();
+ setSelfHostedRelayLoading(false);
+ },
+};
diff --git a/apps/mobile/src/i18n/locales/en/index.ts b/apps/mobile/src/i18n/locales/en/index.ts
index 0c94c70f8f..273517607f 100644
--- a/apps/mobile/src/i18n/locales/en/index.ts
+++ b/apps/mobile/src/i18n/locales/en/index.ts
@@ -21,6 +21,7 @@ import interaction from './interaction.json';
import message from './message.json';
import models from './models.json';
import providerShare from './providerShare.json';
+import relay from './relay.json';
import session from './session.json';
import sharedTask from './sharedTask.json';
import settings from './settings.json';
@@ -45,6 +46,7 @@ export default {
message,
models,
providerShare,
+ relay,
session,
sharedTask,
settings,
diff --git a/apps/mobile/src/i18n/locales/en/relay.json b/apps/mobile/src/i18n/locales/en/relay.json
new file mode 100644
index 0000000000..cf3b52c0d7
--- /dev/null
+++ b/apps/mobile/src/i18n/locales/en/relay.json
@@ -0,0 +1,55 @@
+{
+ "settings": {
+ "sectionTitle": "Relay Service",
+ "currentLabel": "Relay Service",
+ "official": "{{appName}} Official Relay",
+ "switchToOfficial": "Switch Back to Official Relay",
+ "officialHint": "Your devices connect through the {{appName}} official relay. To use your own relay, show its join QR code on the computer running it and scan the code with your phone’s camera.",
+ "selfHostedHint": "Your devices connect through your own relay at {{address}}. Sign-in, models, and other services still use {{appName}}.",
+ "removedHint": "This phone was removed from the relay, or the relay was turned off. Switch back to the official relay, or join again from your computer.",
+ "credentialMissingHint": "The relay credential isn’t on this phone anymore. Join again from your computer, or switch back to the official relay.",
+ "confirmTitle": "Switch Back to Official Relay?",
+ "confirmBody": "This phone will leave “{{name}}” and use the {{appName}} official relay. To use that relay again, join it again from your computer.",
+ "confirmAction": "Switch Back",
+ "switchFailed": "Couldn’t switch back to the official relay. Try again in a moment.",
+ "pushUnavailable": "While you use your own relay, task notifications from your computers aren’t sent to this phone."
+ },
+ "issue": {
+ "removedTitle": "Removed from Relay",
+ "removedHint": "This phone was removed from the relay, or the relay was turned off. You can switch back to the official relay in Settings."
+ },
+ "join": {
+ "title": "Join Relay",
+ "checking": "Connecting to the relay…",
+ "body": "After you join, this phone connects to your computers through this relay. Sign-in, models, and other services still use {{appName}}. While you use your own relay, task notifications from your computers aren’t sent to this phone.",
+ "switchNote": "Joining switches this phone from “{{current}}” to this relay.",
+ "action": "Join",
+ "pairingCodeLabel": "Pairing Code",
+ "verifyHint": "On the computer running the relay, check that it shows these digits, then approve.",
+ "waiting": "Waiting for approval…",
+ "cancel": "Cancel",
+ "joinedTitle": "Joined the Relay",
+ "joinedBody": "This phone now connects to your computers through “{{name}}”.",
+ "done": "Done",
+ "retry": "Try Again",
+ "signedOut": "Sign in to {{appName}} first, then join this relay.",
+ "signIn": "Sign In",
+ "invalidLink": "This join link isn’t valid or has expired. Create a new one on your computer.",
+ "cancelled": "Joining was canceled. To join this relay, create a new join link on your computer."
+ },
+ "errors": {
+ "unreachable": "Can’t reach this relay. Make sure your phone and computer are on the same network, or that your phone can open this address.",
+ "insecureUnreachable": "Can’t reach this relay. Phones can join a relay only over HTTPS. Set up a certificate for the relay on your computer, then create a new join link.",
+ "notRelay": "This address isn’t a {{appName}} relay. Check the join link.",
+ "incompatible": "This relay doesn’t work with this version of {{appName}}. Update both the relay and {{appName}}.",
+ "accountMismatch": "This relay belongs to a different {{appName}} account.",
+ "codeInvalid": "This join link has expired. Create a new one on your computer.",
+ "rateLimited": "Too many attempts. Try again later.",
+ "rejected": "The join request was declined on the computer.",
+ "expired": "The request timed out while waiting for approval. Create a new join link on your computer.",
+ "ownerMismatch": "The relay returned a certificate that the owner in the join link didn’t issue. You may be connected to a fake relay, so joining stopped.",
+ "failed": "Couldn’t join the relay. Try again later.",
+ "saveFailed": "The request was approved, but the relay credential couldn’t be saved on this phone. Create a new join link on your computer and try again.",
+ "credentialUnavailable": "This phone doesn’t have a usable relay credential. Join again, or switch back to the official relay in Settings."
+ }
+}
diff --git a/apps/mobile/src/i18n/locales/ja/index.ts b/apps/mobile/src/i18n/locales/ja/index.ts
index 0c94c70f8f..273517607f 100644
--- a/apps/mobile/src/i18n/locales/ja/index.ts
+++ b/apps/mobile/src/i18n/locales/ja/index.ts
@@ -21,6 +21,7 @@ import interaction from './interaction.json';
import message from './message.json';
import models from './models.json';
import providerShare from './providerShare.json';
+import relay from './relay.json';
import session from './session.json';
import sharedTask from './sharedTask.json';
import settings from './settings.json';
@@ -45,6 +46,7 @@ export default {
message,
models,
providerShare,
+ relay,
session,
sharedTask,
settings,
diff --git a/apps/mobile/src/i18n/locales/ja/relay.json b/apps/mobile/src/i18n/locales/ja/relay.json
new file mode 100644
index 0000000000..2b51e31703
--- /dev/null
+++ b/apps/mobile/src/i18n/locales/ja/relay.json
@@ -0,0 +1,55 @@
+{
+ "settings": {
+ "sectionTitle": "リレーサービス",
+ "currentLabel": "リレーサービス",
+ "official": "{{appName}} 公式リレー",
+ "switchToOfficial": "公式リレーに戻す",
+ "officialHint": "デバイス同士は {{appName}} 公式リレーを経由して接続します。自分のリレーを使うには、リレーを動かしているパソコンで参加用 QR コードを表示し、スマホのカメラで読み取ってください。",
+ "selfHostedHint": "デバイス同士は自分のリレー {{address}} を経由して接続します。ログインやモデルなどは引き続き {{appName}} の公式サービスを使います。",
+ "removedHint": "このスマホはリレーから削除されたか、リレーが停止されています。公式リレーに戻すか、パソコンからもう一度参加してください。",
+ "credentialMissingHint": "このスマホにリレーの認証情報が見つかりません。パソコンからもう一度参加するか、公式リレーに戻してください。",
+ "confirmTitle": "公式リレーに戻しますか?",
+ "confirmBody": "このスマホは「{{name}}」から抜けて、{{appName}} 公式リレーを使います。このリレーをまた使うには、パソコンからもう一度参加してください。",
+ "confirmAction": "戻す",
+ "switchFailed": "公式リレーに戻せませんでした。しばらくしてからもう一度お試しください。",
+ "pushUnavailable": "自分のリレーを使っている間は、パソコンのセッション通知はこのスマホに届きません。"
+ },
+ "issue": {
+ "removedTitle": "リレーから削除されました",
+ "removedHint": "このスマホはリレーから削除されたか、リレーが停止されています。設定で公式リレーに戻せます。"
+ },
+ "join": {
+ "title": "リレーに参加",
+ "checking": "リレーに接続しています…",
+ "body": "参加すると、このスマホはこのリレーを経由してパソコンに接続します。ログインやモデルなどは引き続き {{appName}} の公式サービスを使います。自分のリレーを使っている間は、パソコンのセッション通知はこのスマホに届きません。",
+ "switchNote": "参加すると、「{{current}}」からこのリレーに切り替わります。",
+ "action": "参加",
+ "pairingCodeLabel": "ペアリングコード",
+ "verifyHint": "リレーを動かしているパソコンでこの数字を確認してから、承認してください。",
+ "waiting": "承認を待っています…",
+ "cancel": "キャンセル",
+ "joinedTitle": "リレーに参加しました",
+ "joinedBody": "このスマホは「{{name}}」を経由してパソコンに接続します。",
+ "done": "完了",
+ "retry": "再試行",
+ "signedOut": "先に {{appName}} にログインしてから、このリレーに参加してください。",
+ "signIn": "ログイン",
+ "invalidLink": "参加リンクが無効か、有効期限が切れています。パソコンで新しいリンクを作成してください。",
+ "cancelled": "参加をキャンセルしました。このリレーに参加するには、パソコンで新しい参加リンクを作成してください。"
+ },
+ "errors": {
+ "unreachable": "このリレーに接続できません。スマホとパソコンが同じネットワークにあるか、スマホからこのアドレスにアクセスできるか確認してください。",
+ "insecureUnreachable": "このリレーに接続できません。スマホは https でのみリレーに参加できます。パソコンでリレーに証明書を設定してから、新しい参加リンクを作成してください。",
+ "notRelay": "このアドレスは {{appName}} のリレーではありません。参加リンクを確認してください。",
+ "incompatible": "このリレーは、このバージョンの {{appName}} に対応していません。リレーと {{appName}} を両方とも最新版に更新してください。",
+ "accountMismatch": "このリレーは別の {{appName}} アカウントのものです。",
+ "codeInvalid": "参加リンクの有効期限が切れています。パソコンで新しいリンクを作成してください。",
+ "rateLimited": "試行回数が多すぎます。しばらくしてからもう一度お試しください。",
+ "rejected": "パソコン側で参加が拒否されました。",
+ "expired": "承認待ちの時間が過ぎました。パソコンで新しい参加リンクを作成してください。",
+ "ownerMismatch": "リレーから返された証明書は、参加リンクの所有者が発行したものではありません。偽のリレーに接続している可能性があるため、参加を中止しました。",
+ "failed": "リレーに参加できませんでした。しばらくしてからもう一度お試しください。",
+ "saveFailed": "承認されましたが、このスマホにリレーの認証情報を保存できませんでした。パソコンで新しい参加リンクを作成して、もう一度お試しください。",
+ "credentialUnavailable": "このスマホには使えるリレーの認証情報がありません。もう一度参加するか、設定で公式リレーに戻してください。"
+ }
+}
diff --git a/apps/mobile/src/i18n/locales/ko/index.ts b/apps/mobile/src/i18n/locales/ko/index.ts
index 0c94c70f8f..273517607f 100644
--- a/apps/mobile/src/i18n/locales/ko/index.ts
+++ b/apps/mobile/src/i18n/locales/ko/index.ts
@@ -21,6 +21,7 @@ import interaction from './interaction.json';
import message from './message.json';
import models from './models.json';
import providerShare from './providerShare.json';
+import relay from './relay.json';
import session from './session.json';
import sharedTask from './sharedTask.json';
import settings from './settings.json';
@@ -45,6 +46,7 @@ export default {
message,
models,
providerShare,
+ relay,
session,
sharedTask,
settings,
diff --git a/apps/mobile/src/i18n/locales/ko/relay.json b/apps/mobile/src/i18n/locales/ko/relay.json
new file mode 100644
index 0000000000..b9782d2658
--- /dev/null
+++ b/apps/mobile/src/i18n/locales/ko/relay.json
@@ -0,0 +1,55 @@
+{
+ "settings": {
+ "sectionTitle": "중계 서비스",
+ "currentLabel": "중계 서비스",
+ "official": "{{appName}} 공식 중계",
+ "switchToOfficial": "공식 중계로 돌아가기",
+ "officialHint": "기기 간 연결은 {{appName}} 공식 중계를 거칩니다. 직접 운영하는 중계를 쓰려면 중계가 실행 중인 컴퓨터에서 참여 QR 코드를 띄우고 휴대폰 카메라로 스캔하세요.",
+ "selfHostedHint": "기기 간 연결은 직접 운영하는 중계 {{address}}를 거칩니다. 로그인, 모델 등은 계속 {{appName}} 공식 서비스를 사용합니다.",
+ "removedHint": "이 휴대폰이 중계에서 제거되었거나 중계가 중지되었습니다. 공식 중계로 돌아가거나 컴퓨터에서 다시 참여하세요.",
+ "credentialMissingHint": "이 휴대폰에서 중계 인증 정보를 찾을 수 없습니다. 컴퓨터에서 다시 참여하거나 공식 중계로 돌아가세요.",
+ "confirmTitle": "공식 중계로 돌아갈까요?",
+ "confirmBody": "이 휴대폰은 “{{name}}”에서 나가고 {{appName}} 공식 중계를 사용합니다. 이 중계를 다시 쓰려면 컴퓨터에서 다시 참여해야 합니다.",
+ "confirmAction": "돌아가기",
+ "switchFailed": "공식 중계로 돌아가지 못했습니다. 잠시 후 다시 시도하세요.",
+ "pushUnavailable": "직접 운영하는 중계를 쓰는 동안에는 컴퓨터의 세션 알림이 이 휴대폰으로 전송되지 않습니다."
+ },
+ "issue": {
+ "removedTitle": "중계에서 제거됨",
+ "removedHint": "이 휴대폰이 중계에서 제거되었거나 중계가 중지되었습니다. 설정에서 공식 중계로 돌아갈 수 있습니다."
+ },
+ "join": {
+ "title": "중계에 참여",
+ "checking": "중계에 연결하는 중…",
+ "body": "참여하면 이 휴대폰은 이 중계를 거쳐 컴퓨터에 연결됩니다. 로그인, 모델 등은 계속 {{appName}} 공식 서비스를 사용합니다. 직접 운영하는 중계를 쓰는 동안에는 컴퓨터의 세션 알림이 이 휴대폰으로 전송되지 않습니다.",
+ "switchNote": "참여하면 “{{current}}”에서 이 중계로 전환됩니다.",
+ "action": "참여",
+ "pairingCodeLabel": "페어링 코드",
+ "verifyHint": "중계가 실행 중인 컴퓨터에서 이 숫자를 확인한 뒤 승인하세요.",
+ "waiting": "승인을 기다리는 중…",
+ "cancel": "취소",
+ "joinedTitle": "중계에 참여함",
+ "joinedBody": "이제 이 휴대폰은 “{{name}}”을 거쳐 컴퓨터에 연결됩니다.",
+ "done": "완료",
+ "retry": "다시 시도",
+ "signedOut": "먼저 {{appName}}에 로그인한 다음 이 중계에 참여하세요.",
+ "signIn": "로그인",
+ "invalidLink": "참여 링크가 잘못되었거나 만료되었습니다. 컴퓨터에서 새 링크를 만드세요.",
+ "cancelled": "참여를 취소했습니다. 이 중계에 참여하려면 컴퓨터에서 새 참여 링크를 만드세요."
+ },
+ "errors": {
+ "unreachable": "이 중계에 연결할 수 없습니다. 휴대폰과 컴퓨터가 같은 네트워크에 있는지, 휴대폰에서 이 주소에 접속할 수 있는지 확인하세요.",
+ "insecureUnreachable": "이 중계에 연결할 수 없습니다. 휴대폰은 https로만 중계에 참여할 수 있습니다. 컴퓨터에서 중계에 인증서를 설정한 뒤 새 참여 링크를 만드세요.",
+ "notRelay": "이 주소는 {{appName}} 중계가 아닙니다. 참여 링크를 확인하세요.",
+ "incompatible": "이 중계는 현재 버전의 {{appName}}와 호환되지 않습니다. 중계와 {{appName}}를 모두 최신 버전으로 업데이트하세요.",
+ "accountMismatch": "이 중계는 다른 {{appName}} 계정의 중계입니다.",
+ "codeInvalid": "참여 링크가 만료되었습니다. 컴퓨터에서 새 링크를 만드세요.",
+ "rateLimited": "시도 횟수가 너무 많습니다. 잠시 후 다시 시도하세요.",
+ "rejected": "컴퓨터에서 참여 요청을 거절했습니다.",
+ "expired": "승인 대기 시간이 지났습니다. 컴퓨터에서 새 참여 링크를 만드세요.",
+ "ownerMismatch": "중계가 보낸 인증서를 참여 링크의 소유자가 발급하지 않았습니다. 가짜 중계에 연결되었을 수 있어 참여를 중단했습니다.",
+ "failed": "중계에 참여하지 못했습니다. 잠시 후 다시 시도하세요.",
+ "saveFailed": "승인되었지만 이 휴대폰에 중계 인증 정보를 저장하지 못했습니다. 컴퓨터에서 새 참여 링크를 만든 뒤 다시 시도하세요.",
+ "credentialUnavailable": "이 휴대폰에 사용할 수 있는 중계 인증 정보가 없습니다. 다시 참여하거나 설정에서 공식 중계로 돌아가세요."
+ }
+}
diff --git a/apps/mobile/src/i18n/locales/zh-CN/index.ts b/apps/mobile/src/i18n/locales/zh-CN/index.ts
index 0c94c70f8f..273517607f 100644
--- a/apps/mobile/src/i18n/locales/zh-CN/index.ts
+++ b/apps/mobile/src/i18n/locales/zh-CN/index.ts
@@ -21,6 +21,7 @@ import interaction from './interaction.json';
import message from './message.json';
import models from './models.json';
import providerShare from './providerShare.json';
+import relay from './relay.json';
import session from './session.json';
import sharedTask from './sharedTask.json';
import settings from './settings.json';
@@ -45,6 +46,7 @@ export default {
message,
models,
providerShare,
+ relay,
session,
sharedTask,
settings,
diff --git a/apps/mobile/src/i18n/locales/zh-CN/relay.json b/apps/mobile/src/i18n/locales/zh-CN/relay.json
new file mode 100644
index 0000000000..919207b6fe
--- /dev/null
+++ b/apps/mobile/src/i18n/locales/zh-CN/relay.json
@@ -0,0 +1,55 @@
+{
+ "settings": {
+ "sectionTitle": "中转服务",
+ "currentLabel": "中转服务",
+ "official": "{{appName}} 官方中转",
+ "switchToOfficial": "切回官方中转",
+ "officialHint": "设备之间经 {{appName}} 官方中转连接。要改用自建中转,在中转所在的电脑上显示加入二维码,用手机相机扫码加入。",
+ "selfHostedHint": "设备之间经自建中转 {{address}} 连接;登录、模型等仍使用 {{appName}} 官方服务。",
+ "removedHint": "这台手机已被移出中转,或中转已停用。可以切回官方中转,或在电脑上重新加入。",
+ "credentialMissingHint": "这台手机上找不到中转凭证。请在电脑上重新加入,或切回官方中转。",
+ "confirmTitle": "切回官方中转?",
+ "confirmBody": "这台手机会退出「{{name}}」,改用 {{appName}} 官方中转。之后要再用这个中转,需要在电脑上重新加入。",
+ "confirmAction": "切回",
+ "switchFailed": "没能切回官方中转,请稍后重试。",
+ "pushUnavailable": "使用自建中转时,电脑上的任务通知不会推送到这台手机。"
+ },
+ "issue": {
+ "removedTitle": "已移出中转",
+ "removedHint": "这台手机已被移出中转,或中转已停用。可以在设置里切回官方中转。"
+ },
+ "join": {
+ "title": "加入中转",
+ "checking": "正在连接中转…",
+ "body": "加入后,这台手机经这个中转连接你的电脑;登录、模型等仍使用 {{appName}} 官方服务。使用自建中转时,这台手机收不到电脑上的任务通知。",
+ "switchNote": "加入后会从「{{current}}」切换到这个中转。",
+ "action": "加入",
+ "pairingCodeLabel": "配对码",
+ "verifyHint": "请在中转所在的电脑上核对这串数字并点同意。",
+ "waiting": "正在等待同意…",
+ "cancel": "取消",
+ "joinedTitle": "已加入中转",
+ "joinedBody": "这台手机现在经「{{name}}」连接你的电脑。",
+ "done": "完成",
+ "retry": "重试",
+ "signedOut": "请先登录 {{appName}},再加入这个中转。",
+ "signIn": "去登录",
+ "invalidLink": "加入链接无效或已失效,请在电脑上重新生成。",
+ "cancelled": "已取消加入。要加入这个中转,请在电脑上重新生成加入链接。"
+ },
+ "errors": {
+ "unreachable": "连不上这个中转。请确认手机和电脑在同一网络,或手机能访问这个地址。",
+ "insecureUnreachable": "连不上这个中转。手机只能通过 https 加入中转,请在电脑上为中转配置证书后重新生成加入链接。",
+ "notRelay": "这个地址不是 {{appName}} 中转,请检查加入链接。",
+ "incompatible": "这个中转与当前版本的 {{appName}} 不兼容,请把中转和 {{appName}} 都更新到最新版本。",
+ "accountMismatch": "这个中转属于另一个 {{appName}} 账号。",
+ "codeInvalid": "加入链接已失效,请在电脑上重新生成。",
+ "rateLimited": "尝试次数太多,请稍后再试。",
+ "rejected": "电脑上拒绝了这次加入。",
+ "expired": "等待同意超时,请在电脑上重新生成加入链接。",
+ "ownerMismatch": "中转返回的证书不是加入链接里的主人签发的,可能连到了别人伪造的中转,已停止加入。",
+ "failed": "没能加入中转,请稍后重试。",
+ "saveFailed": "已获同意,但没能在这台手机上保存中转凭证。请在电脑上重新生成加入链接后再试。",
+ "credentialUnavailable": "这台手机没有可用的中转凭证。请重新加入,或在设置里切回官方中转。"
+ }
+}
diff --git a/apps/mobile/src/i18n/locales/zh-TW/index.ts b/apps/mobile/src/i18n/locales/zh-TW/index.ts
index 0c94c70f8f..273517607f 100644
--- a/apps/mobile/src/i18n/locales/zh-TW/index.ts
+++ b/apps/mobile/src/i18n/locales/zh-TW/index.ts
@@ -21,6 +21,7 @@ import interaction from './interaction.json';
import message from './message.json';
import models from './models.json';
import providerShare from './providerShare.json';
+import relay from './relay.json';
import session from './session.json';
import sharedTask from './sharedTask.json';
import settings from './settings.json';
@@ -45,6 +46,7 @@ export default {
message,
models,
providerShare,
+ relay,
session,
sharedTask,
settings,
diff --git a/apps/mobile/src/i18n/locales/zh-TW/relay.json b/apps/mobile/src/i18n/locales/zh-TW/relay.json
new file mode 100644
index 0000000000..0d751b9d43
--- /dev/null
+++ b/apps/mobile/src/i18n/locales/zh-TW/relay.json
@@ -0,0 +1,55 @@
+{
+ "settings": {
+ "sectionTitle": "中繼服務",
+ "currentLabel": "中繼服務",
+ "official": "{{appName}} 官方中繼",
+ "switchToOfficial": "切回官方中繼",
+ "officialHint": "裝置之間經 {{appName}} 官方中繼連線。要改用自建中繼,在中繼所在的電腦上顯示加入 QR 碼,用手機相機掃描加入。",
+ "selfHostedHint": "裝置之間經自建中繼 {{address}} 連線;登入、模型等仍使用 {{appName}} 官方服務。",
+ "removedHint": "這臺手機已被移出中繼,或中繼已停用。可以切回官方中繼,或在電腦上重新加入。",
+ "credentialMissingHint": "這臺手機上找不到中繼憑證。請在電腦上重新加入,或切回官方中繼。",
+ "confirmTitle": "切回官方中繼?",
+ "confirmBody": "這臺手機會退出「{{name}}」,改用 {{appName}} 官方中繼。之後要再用這個中繼,需要在電腦上重新加入。",
+ "confirmAction": "切回",
+ "switchFailed": "未能切回官方中繼,請稍後重試。",
+ "pushUnavailable": "使用自建中繼時,電腦上的任務通知不會推送到這臺手機。"
+ },
+ "issue": {
+ "removedTitle": "已移出中繼",
+ "removedHint": "這臺手機已被移出中繼,或中繼已停用。可以在設定裡切回官方中繼。"
+ },
+ "join": {
+ "title": "加入中繼",
+ "checking": "正在連線中繼…",
+ "body": "加入後,這臺手機經這個中繼連線你的電腦;登入、模型等仍使用 {{appName}} 官方服務。使用自建中繼時,這臺手機收不到電腦上的任務通知。",
+ "switchNote": "加入後會從「{{current}}」切換到這個中繼。",
+ "action": "加入",
+ "pairingCodeLabel": "配對碼",
+ "verifyHint": "請在中繼所在的電腦上核對這串數字並點同意。",
+ "waiting": "正在等待同意…",
+ "cancel": "取消",
+ "joinedTitle": "已加入中繼",
+ "joinedBody": "這臺手機現在經「{{name}}」連線你的電腦。",
+ "done": "完成",
+ "retry": "重試",
+ "signedOut": "請先登入 {{appName}},再加入這個中繼。",
+ "signIn": "去登入",
+ "invalidLink": "加入連結無效或已失效,請在電腦上重新產生。",
+ "cancelled": "已取消加入。要加入這個中繼,請在電腦上重新產生加入連結。"
+ },
+ "errors": {
+ "unreachable": "連不上這個中繼。請確認手機和電腦在同一網路,或手機能存取這個位址。",
+ "insecureUnreachable": "連不上這個中繼。手機只能透過 https 加入中繼,請在電腦上為中繼設定憑證後重新產生加入連結。",
+ "notRelay": "這個位址不是 {{appName}} 中繼,請檢查加入連結。",
+ "incompatible": "這個中繼與目前版本的 {{appName}} 不相容,請把中繼和 {{appName}} 都更新到最新版本。",
+ "accountMismatch": "這個中繼屬於另一個 {{appName}} 帳號。",
+ "codeInvalid": "加入連結已失效,請在電腦上重新產生。",
+ "rateLimited": "嘗試次數太多,請稍後再試。",
+ "rejected": "電腦上拒絕了這次加入。",
+ "expired": "等待同意逾時,請在電腦上重新產生加入連結。",
+ "ownerMismatch": "中繼回傳的憑證不是加入連結裡的主人簽發的,可能連到了別人偽造的中繼,已停止加入。",
+ "failed": "未能加入中繼,請稍後重試。",
+ "saveFailed": "已獲同意,但未能在這臺手機上儲存中繼憑證。請在電腦上重新產生加入連結後再試。",
+ "credentialUnavailable": "這臺手機沒有可用的中繼憑證。請重新加入,或在設定裡切回官方中繼。"
+ }
+}
diff --git a/apps/mobile/src/notifications/PushNotificationsBridge.tsx b/apps/mobile/src/notifications/PushNotificationsBridge.tsx
index cb3a516169..20dee8d29b 100644
--- a/apps/mobile/src/notifications/PushNotificationsBridge.tsx
+++ b/apps/mobile/src/notifications/PushNotificationsBridge.tsx
@@ -2,6 +2,7 @@ import { useGlobalSearchParams, usePathname, useRouter } from 'expo-router';
import { useCallback, useEffect, useRef } from 'react';
import { AppState } from 'react-native';
import { useAuth } from '@/auth/AuthContext';
+import { useSelfHostedRelay } from '@/device-link/selfHostedRelay';
import Notifications from './nativeNotifications';
import { ChatBackgroundBridge } from './ChatBackgroundBridge';
import { notificationRecoveryRoute, parseNotificationResponseDeepLink } from './pushRegistrationModel';
@@ -48,6 +49,8 @@ export function PushNotificationsBridge() {
};
const apiFetchRef = useRef(auth.apiFetch);
apiFetchRef.current = auth.apiFetch;
+ // 自建中转下不登记 device-link 推送;切回官方中转后按本机开关重新同步一次。
+ const selfHostedRelay = useSelfHostedRelay() !== null;
useEffect(() => {
if (!isPushSupported()) return;
@@ -74,7 +77,7 @@ export function PushNotificationsBridge() {
return () => {
cancelled = true;
};
- }, [auth.accountGeneration, auth.initialized, auth.isAuthenticated, auth.user]);
+ }, [auth.accountGeneration, auth.initialized, auth.isAuthenticated, auth.user, selfHostedRelay]);
// APNs token 轮换 → 重新上报(仅开关开启且已登录时)
useEffect(() => {
diff --git a/apps/mobile/src/notifications/pushNotifications.ts b/apps/mobile/src/notifications/pushNotifications.ts
index a293367329..d94665e747 100644
--- a/apps/mobile/src/notifications/pushNotifications.ts
+++ b/apps/mobile/src/notifications/pushNotifications.ts
@@ -14,6 +14,7 @@ import {
getDevServerEnvironment,
type DevServerEnvironment,
} from '@/config/devServerEnvironment';
+import { getActiveSelfHostedRelay } from '@/device-link/selfHostedRelayRouting';
import Notifications from './nativeNotifications';
import { buildPushTokenRegistrationBody, parseNotificationResponseDeepLink } from './pushRegistrationModel';
@@ -191,8 +192,13 @@ function deviceLinkBaseForRealm(realm: ClientEndpointRegion): string {
return getMobileEndpointForRealm(realm, 'deviceLinkApiBaseUrl');
}
-function pushTargets(realm: ClientEndpointRegion) {
- const targets = [{ baseUrl: deviceLinkBaseForRealm(realm), path: PUSH_TOKEN_PATH, optional: false }];
+function pushTargets(realm: ClientEndpointRegion, method: 'PUT' | 'DELETE' = 'DELETE') {
+ // 自建中转不转发系统推送(docs/self-hosted-relay-plan.md §5.3、§7):这时不在官方 device-link
+ // 登记 token;注销仍发往官方地址(realm 缓存,不受中转覆盖),清掉以前的登记。
+ const skipDeviceLink = method === 'PUT' && getActiveSelfHostedRelay() !== null;
+ const targets = skipDeviceLink
+ ? []
+ : [{ baseUrl: deviceLinkBaseForRealm(realm), path: PUSH_TOKEN_PATH, optional: false }];
try {
const baseUrl = getMobileEndpointForRealm(realm, 'chatApiBaseUrl');
if (baseUrl) targets.push({ baseUrl, path: '/v1/push-token', optional: true });
@@ -200,7 +206,7 @@ function pushTargets(realm: ClientEndpointRegion) {
return targets;
}
async function mutatePushTokens(apiFetch: AuthedApiFetch, realm: ClientEndpointRegion, method: 'PUT' | 'DELETE', body?: unknown) {
- const results = await Promise.allSettled(pushTargets(realm).map(async target => {
+ const results = await Promise.allSettled(pushTargets(realm, method).map(async target => {
try { await apiFetch(target.path, { baseUrl: target.baseUrl, method, headers: { 'Accept-Language': i18n.language || 'en' }, ...(body ? { body } : {}) }); }
catch (error) {
// An older chat server can roll forward independently of existing task pushes.
diff --git a/docs/dev-rules/credentials-and-local-storage.md b/docs/dev-rules/credentials-and-local-storage.md
index 2d48ffccef..9640223244 100644
--- a/docs/dev-rules/credentials-and-local-storage.md
+++ b/docs/dev-rules/credentials-and-local-storage.md
@@ -201,6 +201,9 @@ refresh 与 relay 自救节流。在途 refresh 尚未返回时收到的恢复
| Cindy 管理的持久数据 | Desktop 使用 `app.getPath('userData')`,共享 package 由宿主注入等价根目录 |
| 浏览器用户配方与经验 | `userData/browser-recipes/<site>/recipes/<id 的 SHA-256>.json`,每站多个流程,原子替换;兼容旧 `recipe.json`,新文件优先。只保存参数化定义及 candidate/active/suspended 状态、浏览器 profile 范围,不保存试跑 inputs/页面返回值;禁止写入凭据,业务变动值用 inputs。同站 `experience.json` 最多保存 32 种操作形状(动作枚举、次数、时间),不保存 URL 路径/查询、选择器、脚本或输入输出;删除站点目录一并重置。重复形状仅提示当前 Agent 判断,不触发后台模型。试跑凭证与单轮修复预算只在 MCP 会话内存,暂停状态跨重启保留。 |
| 浏览器大结果补读 | MCP 工具会话内存中保留最近四份原始 JSON,每份最多 200 万字符;不落盘、不上传,关闭会话后释放。`readResult` 只能读当前会话生成的引用,沿用原页面实际 profile 的代输入读取限制;切换后端、stop 或读取受保护页面时清除。工具复用宿主现有生命周期与后端对象引用,在下一次访问及异步预检后核对,包括设置/其它任务切换、切走再切回和嵌入后端恢复;切换中的动作仍报告真实结果,但不缓存原文或保存试跑凭证。超过上限明确截断,不能声称完整原文已保存。 |
+| 自建中转服务(Desktop) | `owners/<owner-key>/device-link-relay/`:`config.json` 只存选择、本机中转设置与服务器部署记录(地址、中转 ID、主人公钥,不含秘密);`secrets/<中转ID>.enc` 是本机在该中转上的设备凭证与 Ed25519 签名私钥(本机当主人时即主人密钥),经 safeStorage 加密,Linux 只有 basic_text 时拒绝保存;第 1 版的 `credential.enc` / `owner-credential.enc` 读到旧配置时删除;`host/` 是本机运行中转时的数据(`relay-state.json` 只存各设备凭证的 SHA-256 与档案,0600 原子写入;`media/` 为设备间中转的文件,创建 24 小时后清理)。全部按账号隔离,账号作用域未提交时不读写。见 `device-link/selfHostedRelayConfig.ts`、`packages/device-link-relay` 与 [方案](../self-hosted-relay-plan.md) |
+| 自建中转服务(Mobile) | AsyncStorage `cindy.mobile.self-hosted-relay.v2.<账号>` 只存选择(中转地址、名称、主人公钥、本机设备 ID),不含秘密;设备凭证与 Ed25519 签名私钥合存为 `expo-secure-store` 的 `cindy.selfHostedRelay.credential.v2.<账号哈希>`,仅本机、解锁后可读。没有签名私钥的 v1 记录不再使用,读到时尽力删除。见 `apps/mobile/src/device-link/selfHostedRelay.ts` |
+| 自建中转服务(用户服务器) | 「部署到我的服务器」经 SSH 写入用户自己的服务器:`/opt/cindy-relay`(Node 运行环境与 `relay.mjs`)、`/var/lib/cindy-relay`(属 `cindy-relay` 系统用户、0700:设备凭证哈希与证书档案、Let's Encrypt 账户密钥与 TLS 私钥 0600、`status.json`)、`/etc/systemd/system/cindy-relay.service`。主人凭证明文与主人私钥从不离开主人电脑;卸载时删除以上全部。见 `device-link/selfHostedRelayDeploy.ts` |
| 本机应用 Agent 授权 | `owners/<owner-key>/local-agent/grants.json`,仅含令牌 SHA-256、自报应用资料、账号范围和按授权归属的原生恢复绑定,不存令牌明文、供应商凭据或消息。复用原子写入与恢复 helper;profile 根 `local-agent/host.lock` 复用跨进程锁,保证一个发现端点和写入者。开发连接码从当前服务内存按需生成,不新增公共实例登记或短码映射文件。临时输入与新授权的 Codex 运行历史在同一 owner 下的 `local-agent/clients/<grant-hash>/`;撤权同时关闭执行及工具入口,不允许跨授权恢复。协议与旧版兼容见 [本机应用接入](../local-agent-api.md) |
| 预创建 worktree 的取消标记 | `userData/worktree-cancelled-creations/<sessionId 的 SHA-256>`,空文件原子排他创建;不含路径、草稿或关联密钥。保留以拒绝重启后迟到的创建请求,不按超时删除。只在核实未被任务认领后写入。同路径加 `.lock` 是可释放的跨进程操作锁,复用既有锁协议;同一 profile、同一任务的创建登记与取消回收串行,拿不到锁不得确认回收完成。异步创建完成后、登记前再次核对取消标记 |
| Mobile 已取消创建的草稿 | 复用账号隔离的 durable outbox;持久创建流程先保存草稿、原项目目录和附件,再登记 reservation 和发送远端 worktree 创建;创建回包前暂停发件箱投递。回收确认后,`creation.cancelled` 与原项目目录先持久写入,再忘记回收账本。重建使用新远端 ID,`storageSessionId` 保持原 AsyncStorage 键和附件目录,通过单次记录写入提交;写入失败时原草稿仍可读。编辑页恢复目录时重新探测资格,不沿用旧 worktree 的资格或分支偏好 |
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index c2e3bdab3d..085f49bb3b 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -247,6 +247,62 @@ stream 匹配后才处理;信令不进入业务可靠 FIFO,也不走直连
平台不可用或系统阻止局域网访问时沿用 relay,不能阻断业务。真实跨设备、iOS/Android
前后台及系统网络权限的发布验收必须另记实测证据;浏览器本机 smoke 不等同于真机通过。
+## 自建中转服务(`packages/device-link-relay` 与客户端接入)
+
+方案见 [`docs/self-hosted-relay-plan.md`](../self-hosted-relay-plan.md)。内核实现与官方 relay 相同的 v1 线协议
+(`@cindy/device-link-protocol`),**不改 `PROTOCOL_VERSION`、帧格式或官方 relay / 服务端**。新增内容只存在于自建中转上:
+
+- 认证方案 `Authorization: CindyRelay <设备凭证>`(WebSocket 升级与 REST 共用)。`DeviceLinkClient.authorizationScheme`
+ 增加可选值 `CindyRelay`,现有调用不传时仍为 `Bearer`。自建中转拒绝 `Bearer`;凭证无效时 REST 返回
+ 401 `RELAY_CREDENTIAL_INVALID`,刻意不用 Desktop `serverApiFetch` 会触发刷新/登出 Cindy 账号的三种错误码。
+- hello-ack 的 `capabilities` 为空:客户端据此不发 `notify`、不发 `sharedTask` / `providerShare` 帧;
+ 中转收到带这两种范围的帧回 `BAD_REQUEST`,不转发。`userId` 为主人账号,`deviceId` 由凭证绑定,不信任自报。
+- 官方 REST 同形:`/devices`(GET/PATCH/DELETE)、`/media/presign-put`、`/media/presign-get`、`DELETE /media`。
+ 媒体地址指向中转自身(带签名、短期有效、一次性上传、支持单段 Range);`/ice-servers` 返回 404(客户端退回公共 STUN);
+ `/push-token` 返回 204 不保存;`GET /provider-shares` 返回空列表。
+- 自建中转独有:`/api/device-link/relay/info`、`/relay/pair`(加入)、`/relay/admin/*`(仅主人设备凭证)、
+ `/relay/blob/*`(媒体签名地址)。官方 relay 没有这些路径,客户端只在自建模式下调用。
+
+- 设备签名([方案 §16](../self-hosted-relay-plan.md)):经自建中转转发的对端帧多一个顶层字段
+ `auth: { t, b, c, s }`,中转原样转发、不解析(超过 512 字符或不是对象时回 `BAD_REQUEST`)。
+ - `DeviceLinkClient` 的可选项 `frameAuth` 负责签名与核对,只在 `sendEnvelope` 和 `handleMessage` 两处生效。
+ - 官方中转时它返回 null,wire 与旧版逐字节一致。
+ - 签名覆盖的字段与序列化规则以 `packages/device-link/src/selfHostedRelayAuth.ts` 为准,改动它就是改协议,Desktop、Mobile、中转必须一起改。
+ - 中转新增 `GET /api/device-link/relay/certs`(主人签发的设备证书)。
+ - 加入申请必须带 `publicKey` / `proof`,同意必须带证书;`/relay/info` 的 `features` 声明 `device-signatures-v1`。
+- 加入链接 `<cindy|cindycn|cindydev>://relay/join?u=<中转地址>&c=<一次性加入码>&o=<主人公钥>&s=<配对秘密>` 由 `@cindy/device-link` 的
+ `buildRelayJoinLink` / `parseRelayJoinLink` 生成与解析,Desktop 与 Mobile 共用 `fetchRelayInfo` /
+ `submitRelayPairRequest` / `waitForRelayApproval`。`DeviceLinkClient.authorizationScheme` 也可传函数,每次建连前取值。
+- 客户端:Desktop 的地址与凭证经 `device-link/selfHostedRelayRouting.ts`(零依赖)读取,REST 统一走
+ `deviceLinkApi.ts`(自建中转时带 `CindyRelay`、跳过账号刷新与会话失效);Mobile 见 `apps/mobile/src/device-link/selfHostedRelay*.ts`。
+
+兼容:未选择自建中转时,客户端与官方 relay 的行为不变(没有登记中转来源或使用官方中转时一律回到原路径)。
+旧客户端没有入口;旧版手机无法加入自建中转。互通验证:`pnpm --filter @cindy/device-link-relay run interop`
+(本机起中转、走加入流程,再跑 `scripts/device-link/interop.test.ts`,认证方案由 `CINDY_TEST_AUTH_SCHEME` 指定;
+`CINDY_TEST_FRAME_AUTH` 提供测试签名密钥时全程开启设备签名,主机核对每一条对端消息)。
+
+### 自建中转同步维护
+
+**硬性要求:凡 Device Link 的改动会影响自建中转,必须在同一次改动中完成必要的同步适配、
+兼容处理与验证。缺少这些内容视为未完成,不得只完成官方中转路径后把自建中转留到后续。**
+
+- **触发范围**:共享客户端与协议(`packages/device-link`、`packages/device-link-protocol`)、
+ relay 的握手/帧路由/顶层字段/能力协商、鉴权与设备签名、设备/媒体/ICE 接口,以及
+ Desktop、Mobile 的连接恢复与中转路由。判断以实际行为影响为准,不以修改文件的位置为准。
+- **一起适配**:修改前核对共享客户端、自建中转内核(`packages/device-link-relay`)及两端接入代码。
+ 需要调整的实现、测试和协议说明必须一起更新;能由已有通用转发或共享客户端直接支持的,
+ 不要求制造无意义的服务端改动,但必须说明为何无需修改并提供验证结果。
+- **一起验证**:影响通信兼容或恢复行为时,必须运行共享客户端测试、自建中转测试,以及
+ `pnpm --filter @cindy/device-link-relay run interop`,验证当前生产客户端与真实自建中转的
+ 加入、签名通信和重连。涉及设备、媒体等未被该互通场景覆盖的接口时,补充对应定向验证。
+ 官方中转测试或本地 fixture 通过,不能替代自建中转互通结果。
+- **照顾已部署版本**:服务器上的自建中转不会随客户端自动更新。新增能力遵循可选字段与能力协商,
+ 核对新客户端连接旧中转时的行为;需要更新中转程序时同步维护 `RELAY_VERSION`、分发构建与
+ 升级入口。不兼容变化必须明确支持的版本、升级路径和旧端处理,不能只在两端同时更新时可用。
+- **交付说明**:PR/交付中写明自建中转的影响、同步修改位置及实际验证结果。若只是官方服务内部
+ 扩容、数据库或监控调整,或已有通用转发足够支持本次变化,可以写明无需同步修改的具体依据;
+ 不得仅写「不涉及」或假定官方与自建中转会自动保持一致。
+
## 灵动岛完成卡操作
diff --git a/docs/self-hosted-relay-plan.md b/docs/self-hosted-relay-plan.md
new file mode 100644
index 0000000000..70a2475b07
--- /dev/null
+++ b/docs/self-hosted-relay-plan.md
@@ -0,0 +1,690 @@
+# 自建中转服务:第一期方案
+
+> 状态:方案 v2(2026-10-28)。§11 第 1 步「内核」已实现(`packages/device-link-relay`,见 §15 实施记录),
+> 其余步骤未开始。§13 第 1、2 条按建议执行:方式 A 正式开放前先做设备签名防冒充;服务器上的 Node 由 Cindy 本机校验后上传。
+> v1 以 Tailscale 为主路径,已废弃:Tailscale 的 iOS App 不在中国大陆 App Store
+> ([tailscale/tailscale#19625](https://github.com/tailscale/tailscale/issues/19625)),注册还需要海外账号。
+> 范围:本仓(Desktop、Mobile、共享 packages)。**不改 cindy-server,官方中转的行为不变。**
+> 代码位置基于本仓 `main`(2026-10-28)调研,实施前以当时代码为准。
+> 动手前按 `AGENTS.md` 读以下文档:
+> - `docs/dev-rules/protocol-compatibility.md`
+> - `docs/dev-rules/remote-and-mobile-adaptation.md`
+> - `docs/dev-rules/credentials-and-local-storage.md`
+> - `docs/dev-rules/mobile-development.md`(冷更边界)
+> - `docs/dev-rules/architecture-invariants.md`
+> - `docs/dev-rules/verified-downloads.md`
+> - `docs/product-rules/input-handoff.md`(sudo 密码)
+> - `docs/design-rules/DESIGN.md`
+> - `docs/dev-rules/engineering-conventions.md` §3.2
+
+## 0. 一句话
+
+中转服务只有一个内核(`packages/device-link-relay`),有两种运行方式:
+
+| | A. 部署到公网服务器 | B. 在这台 Cindy 上直接开启 |
+| --- | --- | --- |
+| 适合 | 设备分布在不同网络,需要从公网访问 | 设备之间网络本来就通,或用户自己能打通 |
+| 用户提供 | 一台服务器的 SSH 配置,并在云控制台放行端口 | 让其他设备能访问这台电脑的网络条件 |
+| Cindy 负责 | 安装、配置、申请证书、注册为系统服务、升级、卸载 | 启动内核、显示地址、检测连通、提醒保持唤醒 |
+| 内核运行方式 | 服务器上用 Node 运行,由 systemd 托管 | Cindy 内的独立进程(`utilityProcess`) |
+
+两种方式共用:
+
+- 同一份中转程序和协议。
+- 同一套加入流程:二维码或链接发起,主人确认,设备拿到中转专用凭证。
+- 同一个设置页,同一套客户端切换逻辑。
+
+## 1. 原则与边界
+
+- **一个内核。** A 和 B 只在三件事上不同:怎么启动、证书从哪里来、谁来管理。
+ 协议、认证、加入、设备管理、媒体全部由内核实现,两种方式不能各写一份。
+- **网络连通的责任。**
+ - A:由服务器的公网地址保证。
+ - B:由用户自己保证。同一局域网、路由器端口映射、内网穿透、组网工具都可以。
+ Cindy 只做检测和提示,不安装、不配置任何网络软件。
+- **手机只能用受信任的 `https`/`wss` 连接。** Android 正式包只允许明文访问 `127.0.0.1`,放开要改原生配置,也就是冷更。
+ 所以手机加入时,中转必须有受信任的证书(见 §2.2)。电脑之间不受这个限制。
+- **不碰 Cindy 账号凭证。** Cindy 账号 token 不会发给自建中转;中转返回 401 也不会让 Cindy 账号登出(§5.3)。
+- **官方服务不变。** 官方中转和服务端都不改。自建模式只替换设备之间的中转,登录、模型等服务照旧走官方。
+
+## 2. 内核:`packages/device-link-relay`
+
+### 2.1 功能
+
+起点是 `scripts/device-link/relayFixture.ts`(142 行的测试用中转)。它已经具备握手、presence 广播、按目标转发、
+`DEVICE_OFFLINE`/`REMOTE_DISABLED`、覆写 `src`、4409 顶替。在此基础上需要补:
+
+- **设备协议**(§6.1):
+ - 凭证认证。
+ - 帧校验:单帧上限 2 MiB,超出回 `PAYLOAD_TOO_LARGE`,不断开连接。
+ - 检查目标设备的 `remoteControlEnabled`。
+ - 跨账号的 `sharedTask`/`providerShare` 帧一律拒绝。
+ - 出站缓冲上限,以及 1013 拥塞关闭。
+- **REST**(§6.2):设备列表、改名、移除;媒体上传与下载。
+- **加入与管理**(§6.3):一次性加入码、加入申请、主人审批、移除设备、状态查询。
+- **持久化**:
+ - 设备档案(只存凭证哈希)。
+ - 加入申请。
+ - 媒体文件(24 小时后清理,有总量上限)。
+ - 证书与 ACME 账号。
+ - 配置。
+- **证书**:见 §2.2。
+- hello-ack 的 `capabilities` 为空,即不声明 `notify`、`shared-task-v2`、`provider-share-v1`。
+- 单实例内存路由,不需要 Redis。
+
+依赖只有 `@cindy/device-link-protocol`、`ws` 和一个 ACME 客户端,不依赖 Desktop(`architecture-invariants.md` §1)。
+最终打成一个单文件 bundle:
+
+- 方式 A:服务器上运行 `node relay.mjs --data <目录>`。
+- 方式 B:Desktop 用 `utilityProcess` 运行同一个文件。参考 `localDb/dbSlimmingWorkerClient.ts` 等现有用法;进程崩溃不影响 Cindy 主进程。
+
+### 2.2 证书:三种方式
+
+| 方式 | 做法 | 手机能否加入 | 典型场景 |
+| --- | --- | --- | --- |
+| 自动证书 | 内核用 ACME 向 Let's Encrypt 申请并自动续期。<br>有域名时用域名证书。<br>没有域名时用 **IP 地址证书**:2026-01-15 正式提供,有效期约 6 天,需要自动续期([公告](https://letsencrypt.org/2026/01/15/6day-and-ip-general-availability))。<br>验证方式用 `tls-alpn-01`,只要求公网能访问 443 | 能 | A 的默认方式;B 中有公网 IP 的电脑 |
+| 前置代理提供 | 内核只在 `127.0.0.1` 上明文监听。<br>TLS 由用户自己的 nginx、Caddy、frp、内网穿透服务或 Tailscale serve 等提供 | 取决于前置代理的证书是否受信任 | B 的常见情况;服务器上 443 已被别的网站占用时 |
+| 自签名 + 指纹固定 | 内核生成自签名证书,加入链接里附带证书指纹,电脑端按指纹校验 | **不能**(需要原生改动),界面直接说明 | B,只连自己的几台电脑 |
+
+不提供在网络上明文监听(`ws://` 对外)的方式:否则加入码和凭证会被同一网段的人截获。
+
+IP 证书的注意点:
+
+- 有效期只有约 6 天,内核大约每 3 天续期一次。续期失败时,管理状态里显示证书剩余时间,并提醒主人。
+- 申请证书需要支持 ACME profile(`shortlived`)和 `tls-alpn-01` 的客户端,选型在实现时确定。
+
+### 2.3 管理:主人凭证
+
+- 开启中转(B)或部署中转(A)的那台电脑就是**主人电脑**。
+ - 主人电脑在本机生成自己的设备凭证,交给内核的只有它的哈希;这份凭证同时带管理权限,不另发管理凭证。
+ - A 方式下,这个哈希由 SSH 安装时写进服务器配置(`relay init --owner-credential-hash`)。
+ - 所以两种方式的管理方式完全一样:主人电脑带着自己的凭证调用 §6.3 的管理接口。
+- 加入审批、移除设备、查看状态,都在主人电脑的设置页完成。
+- 主人电脑在显示加入二维码期间轮询待审批的申请,不需要新增协议帧。
+- 第一期只有一台主人电脑。以后要加第二台管理设备,再单独设计。
+
+## 3. 方式 A:部署到公网服务器
+
+入口:设置 → 远程连接 → 中转服务 → 部署到我的服务器。选择一台已配置的 SSH 主机,复用现有 SSH 主机配置与认证
+(`packages/maker-remote-ssh`);没有就先添加。
+
+**支持范围**:Linux x64 / arm64,与现有远程安装一致。
+
+**Cindy 自动完成的步骤**(每一步在界面上显示进度):
+
+1. 探测服务器的系统、架构、是否为 root 或有 sudo 权限、443 端口是否被占用。
+2. 准备运行环境:复用自带 Node 的安装方式(`bootstrap-script.ts` 的 `BUNDLED_NODE_INSTALL_SH`,
+ 安装到 `~/.xdt-server/<ver>/node/`)。下载来源见 §13 第 2 条。
+3. 上传中转程序。同版本重复上传是幂等的,参考 `file-service-installer.ts`。
+4. 写入配置:端口、证书方式、域名(可选)、主人设备凭证的哈希。
+5. 注册为 systemd 服务:开机自启,崩溃自动重启。
+ 以专用的低权限用户运行,只授予绑定低端口的能力(`CAP_NET_BIND_SERVICE`)。
+6. 系统防火墙(ufw、firewalld)开着时,征得用户同意后放行 443。
+7. 申请证书。
+8. 从本机检测能否连上。连不上时,按顺序提示:
+ 1. 去云服务器控制台的安全组放行 TCP 443。
+ 2. 检查服务器上的防火墙。
+ 3. 端口被占用时,改用前置代理方式。
+9. 完成,显示加入二维码。主人电脑自动切换到这个中转。
+
+**权限**:
+
+- 安装 systemd 服务和放行防火墙需要 root 或 sudo。
+- SSH 用户是 root,或者有免密 sudo,就能全自动完成。
+- 需要输入 sudo 密码时,走代输入:密码只交给执行命令的那个进程,不进模型、记录和日志(`input-handoff.md`)。
+- 没有 sudo 权限时,退回用户级运行:使用高位端口,证书只能用前置代理方式,并明确提示这些限制。
+
+**域名**:
+
+- 可选。有域名就填,内核申请域名证书。
+- 服务器在中国大陆时,用域名访问 80/443 需要 ICP 备案。
+- 不填域名就用 IP 证书,不涉及域名备案。各家云厂商会不会拦截按 IP 访问,需要实测(§12)。
+
+**升级与卸载**:
+
+- 主人电脑连接中转时会读到中转版本;版本落后时提示「更新中转」,重新上传并重启。
+- 卸载:停止服务,删除程序。中转数据(设备档案、媒体)可选保留或一并删除。
+
+## 4. 方式 B:在这台 Cindy 上直接开启
+
+入口:设置 → 远程连接 → 中转服务 → 在这台电脑上开启。
+
+**用户需要设置的:**
+
+- 监听端口。
+- 监听范围:仅本机(配合前置代理)或所有网络。
+- 证书方式(§2.2)。
+- 对外地址:其他设备用来连接的地址,会写进加入链接。
+
+**Cindy 负责的:**
+
+- 用 `utilityProcess` 启动内核。崩溃后自动重启,次数有上限。
+- 本机作为一台设备连接自己的中转(`127.0.0.1`)。
+- 列出本机的局域网地址,方便用户填写对外地址。
+- 从本机检测对外地址能否访问。受网络环境限制(比如很多路由器不支持从内网访问自己的公网地址),结果只作参考。
+- 提醒保持唤醒,并自动打开现有的「保持唤醒」设置;笔记本合盖仍会休眠,要写清楚。
+- 监听范围选「所有网络」时,macOS 和 Windows 会弹出系统防火墙确认框;Cindy 先说明原因,再触发。
+
+**用户自己负责的**:其他设备能访问对外地址。界面用一句话说明,并举例:
+
+- 同一局域网。
+- 路由器端口映射。
+- 内网穿透。
+- 组网工具(如 Tailscale、ZeroTier)。
+
+Cindy 不安装、不配置这些工具。
+
+**手机**:只有在「自动证书」或「受信任的前置代理证书」下才能加入;选了自签名时,加入页直接说明手机不支持。
+
+## 5. 加入与切换(A、B 共用)
+
+### 5.1 加入
+
+**加入链接**:`<scheme>://relay/join?u=<对外地址>&c=<加入码>[&k=<证书指纹>]`
+
+- scheme 跟随构建区域:`cindy`、`cindycn` 或 `cindydev`。
+- `k` 只在自签名方式下出现。
+
+**另一台电脑:**
+
+1. 粘贴链接,或直接点链接让 Cindy 打开。
+2. 先请求 `relay/info`,确认地址可达、对方确实是 Cindy 中转;自签名时校验证书指纹。
+3. 发出加入申请。主人电脑弹出确认框,显示设备名、平台和 4 位核对码。
+4. 主人同意后,设备拿到凭证,自动切换到该中转。
+
+**手机:**
+
+1. 用系统相机扫二维码,打开 Cindy 的加入页,复用 `apps/mobile/app/+native-intent.ts` 的深链。
+ 链接里的加入码不进路由状态,也不进诊断信息,处理方式与共享任务邀请相同。
+2. 后续步骤和电脑一样。
+
+App 内不加扫码组件:加一个会改变原生指纹,需要冷更。
+
+**核对码**:与供应商分享的 `Pairing Code` 是同一类东西,只用来核对,不参与鉴权。可以沿用这个术语,需要扩充术语表的说明。
+
+### 5.2 身份与凭证
+
+- **中转凭证**:32 字节随机数,只能用来连这一个中转;中转端只存 SHA-256。
+ - Desktop 存在 `safeStorage`,参照 `secrets/providerSecretStore.ts` 里只在 main 进程读写的键。
+ - Mobile 存在 `expo-secure-store`,用 `WHEN_UNLOCKED_THIS_DEVICE_ONLY`。
+- **握手与 REST 请求头**:`Authorization: CindyRelay <凭证>`。`DeviceLinkClient` 已有 `authorizationScheme`
+ (`packages/device-link/src/client.ts:262`),只需新增一种。
+- **deviceId**:上报与官方登录相同的设备 ID,`hello-ack.deviceId` 原样返回。
+ 这样本机按设备 ID 保存的状态在切换后依然有效,包括撤销记录、设备名、远程任务绑定。
+- **userId**:中转属于主人电脑登录的 Cindy 账号。账号不一致的设备直接拒绝,跨账号场景走共享任务或供应商分享。
+ 这只防误操作,真正的准入关口是主人确认。
+
+### 5.3 客户端切换
+
+设置按账号保存:`{mode:'official'} | {mode:'self-hosted', relayId, name, baseUrl, role:'owner'|'member', certPin?}`,
+凭证另存安全存储。
+
+**Desktop:**
+
+- **地址与凭证统一经新增的 `device-link/relayRouting.ts`**:
+ - `deviceLinkApiBase()`、`wsUrl()`、`getToken`(`main/device-link/index.ts:203-206、681-684、715`)改走它。
+ - `remote-desktop/iceConfig.ts` 也改走它。
+ - 不在 `getClientEndpoint` 做全局覆盖:它还负责区域切换和更新链,影响范围太大。
+- **自建模式下暂停跨账号模块**:`sharedTaskApi.ts`、`providerShareApi.ts`、`providerShareGuest.ts`、`providerShareHost.ts` 不发请求;
+ 对应入口显示「使用自建中转时不可用」。
+- **鉴权失败不能影响官方登录。** 现有两条路径会碰官方登录:
+ - REST 返回 401 时可能登出账号(`main/serverApiClient.ts:142-171`)。
+ - WS 握手 401 会强制刷新官方 token(`index.ts:618-654`)。
+
+ 自建模式下这两条路径都不能碰官方登录。此时 401 或 4410 只表示中转凭证失效,界面提示重新加入,或切回官方中转。
+- **证书校验**:自签名方式下,WebSocket 和 REST 都按指纹校验,不信任系统根证书以外的任何证书。
+- **代理**:设置了代理时,device-link 的 WebSocket 会走代理(见 `dnsFallbackLookup.ts` 顶注)。
+ 自建中转的地址是私有网段或组网地址时,要绕开代理,实测确认。
+
+**Mobile:**
+
+- `DEVICE_LINK_API_BASE_URL`(`src/config/env.ts:272`)会被三个区域函数改写;新增覆盖值,在它们之后重新应用。
+- `src/device-link/DeviceLinkContext.tsx:1005` 的 `getWsUrl` / `getToken` 改走新的 `relayRouting`。
+- `apiFetch`(`src/auth/AuthContext.tsx:3309`)会给任何 `baseUrl` 附上 Cindy token。
+ 自建模式下改用中转凭证,确保官方 token 不会发到自建中转。
+- 推送注册(`src/notifications/pushNotifications.ts:190`)在自建模式下跳过。
+
+**状态与退出:**
+
+- 中转离线时提示,并提供「切回官方中转」。**不会自动切回官方。**
+- 主人可以移除设备:凭证立即失效,对方收到 4410 断开,并看到提示。
+- 主人停用中转(B)或卸载中转(A)前,先用 4410 断开所有设备;各设备提示「中转已停用」,可一键切回官方中转。
+
+## 6. 接口
+
+### 6.1 WebSocket `/api/device-link/ws`
+
+只实现现有客户端已经在用的行为(依据:`packages/device-link-protocol/src/protocol.ts` 与 `packages/device-link/src/client.ts`):
+
+- **握手**:`hello` 必须是第一帧。中转在 15 秒内回 `hello-ack`:`{serverProtocolVersion:1, deviceId, userId, capabilities:[]}`。
+- **心跳**:收到 `ping` 回 `pong`,`pong` 不带 payload。
+- **presence**:收到 `presence-set` 后更新状态,并广播完整的 `PresenceSnapshot`。
+ 初始设备列表靠 `/devices` 获取,与官方行为一致。
+- **转发**:转发 `ROUTED_KINDS` 并回填 `src`。
+ - 目标设备不在线,回 `DEVICE_OFFLINE`。
+ - `CONTROL_KINDS` 的目标关闭了「允许被控」,回 `REMOTE_DISABLED`。
+ - `relay-error` 带回原帧的 `id` 和 `dst`。
+- **关闭码**:
+
+| 关闭码 | 含义 |
+| --- | --- |
+| 4409 | 同一设备有新连接,顶替旧连接 |
+| 4429 | 连接数超限 |
+| 4400 | 版本不符 |
+| 4410 | 设备被移除,或中转已停用;客户端停止重连 |
+| 1013 | 拥塞 |
+
+### 6.2 REST
+
+所有接口以 `/api/device-link` 为前缀,请求头为 `Authorization: CindyRelay`。
+
+| 接口 | 第一期 |
+| --- | --- |
+| `GET /devices`、`PATCH /devices/:id`、`DELETE /devices/:id` | 实现。删除设备等于吊销凭证,并用 4410 断开该设备 |
+| `POST /media/presign-put`、`POST /media/presign-get`、`DELETE /media` | 实现。上传和下载地址都指向中转自身,带签名、短期有效;单文件与总量的上限,实现时对齐客户端现有的上传限制 |
+| `GET /ice-servers` | 不实现,返回 404。远程桌面退回公共 STUN(`remoteDesktopIceConfig.ts:99-136`) |
+| `PUT /push-token`、`DELETE /push-token` | 返回 204,不保存 |
+| `/provider-shares*` | 返回空列表,只作兜底 |
+| `/shared-tasks*`、`/identities*` | 不实现 |
+
+### 6.3 加入与管理(只在自建中转上存在)
+
+**公开接口(不需要凭证):**
+
+- `GET /api/device-link/relay/info` → `{relayId, name, protocolVersion:1, relayVersion, features:['pairing-v1']}`。不返回任何账号信息。
+- `POST /api/device-link/relay/pair` → 请求 `{code, deviceId, deviceName, platform, appVersion, accountUserId}`,
+ 返回 `{requestId, pollToken, verifyCode}`。
+- `GET /api/device-link/relay/pair/:requestId?wait=<秒,≤25>`:长轮询,请求头 `X-Cindy-Relay-Poll-Token` 带提交时拿到的轮询口令。
+ 结果为 `pending`、`approved {credential, deviceId}`、`rejected` 或 `expired`;凭证只返回一次,设备在取回凭证时才写入档案。
+
+**管理接口(需要主人设备的凭证):**
+
+- `POST /relay/admin/join-codes`:生成加入码。一次性、10 分钟有效,用后作废。
+- `GET /relay/admin/pair-requests`:查看待审批申请。
+- `POST /relay/admin/pair-requests/:id/approve`、`.../reject`:同意或拒绝。
+- `GET /relay/admin/status`:版本、证书到期时间、在线设备、媒体占用。
+
+**限制:**
+
+- 同时待处理的申请最多 5 个。
+- 按来源限速。
+- 加入码、凭证、签名地址都不写进日志。
+
+## 7. 自建模式下的功能边界
+
+| 功能 | 第一期 |
+| --- | --- |
+| 远程查看和控制任务、实时输出、审批 | 可用 |
+| 设备列表、改名、移除 | 可用 |
+| 远程文件、图片、语音 | 可用 |
+| 直连(`direct-link-v1`) | 可用,信令经中转透传;只用本机地址候选,能否直连取决于网络环境 |
+| 远程桌面 | 可用。没有 TURN,退回公共 STUN |
+| 手机系统推送 | 不可用:推送凭据绑定在官方 App 上 |
+| 供应商分享、共享任务 | 不可用:它们跨账号,界面上明确说明 |
+| 登录、模型、插件市场等 | 不受影响,仍然使用官方服务 |
+
+## 8. 安全
+
+- **最大风险:冒充。**
+ - 方式 A 天然在公网上;方式 B 也可能被用户映射到公网。
+ - 中转负责回填 `src`,中转所在机器一旦被入侵,攻击者就能冒充控制端,让被控电脑执行远程指令。
+ - **建议在方式 A 正式开放前,先做设备签名防冒充**(§13 第 1 条):
+ - 主人电脑作为信任根,给每台通过审批的设备签发设备证书。
+ - 主人公钥随加入二维码带到新设备,不经过中转。
+ - 设备对每条消息签名,接收方验证签名并检查消息是否新鲜。
+ - 内容加密可以放在下一期。
+- **凭证**:只对这一个中转有效;客户端存在安全存储,中转只存哈希;设备被移除后立即失效。
+- **准入**:三道关:加入码(能看到主人屏幕的人才拿得到)、主人确认、核对码。
+- **账号 token 不外发**:Cindy 账号 token 不发往自建中转。Desktop 的 WS 与 REST、Mobile 的 `apiFetch` 都要覆盖,并补回归测试。
+- **服务器上的运行身份**:专用低权限用户,只授予绑定低端口的能力;数据目录只有该用户可读写。
+- **SSH 凭证与 sudo 密码**:沿用现有 SSH 主机的凭证存储;sudo 密码只走代输入。
+- **媒体**:用带签名的短期地址,过期清理。Desktop 侧的落盘目录登记到 `credentials-and-local-storage.md` 的路径表。
+- **日志**:新增的日志行按 `log-upload-and-redaction.md` 的白名单规则评审。
+
+## 9. 故障半径
+
+按 `remote-and-mobile-adaptation.md` 的故障半径三问:
+
+- **中转不可达**(服务器宕机、电脑休眠、网络断开):
+ - 所有设备按现有退避重连同一个中转;不自动切回官方,界面提示并提供手动切回。
+ - 方式 B 中转进程崩溃时,只重启中转进程,不影响 Cindy 主进程和本机任务。
+- **单台设备被移除**:只影响这一台(4410),其他设备不受影响。
+- **证书过期**(续期失败):所有设备连不上。主人电脑提前提醒,证书剩余时间显示在管理状态里。
+- **切换中转**:只重建本机的 device-link 连接,被远程控制的任务继续运行。
+- **多设备回归用例**:两台控制端加一台被控端,移除其中一台控制端,断言另一台的在途请求与连接不受影响。
+
+## 10. 兼容与发布
+
+- **协议**:中转帧协议不变,仍是 v1。新增内容只存在于自建中转上:`CindyRelay` 认证方案、加入接口、管理接口。官方中转与服务端零改动。
+- **旧客户端**:没有入口,不受影响;旧版手机无法加入,加入页提示升级。
+- **手机**:深链、设置、地址覆盖、安全存储都是 JS 改动,可以热更。
+ 不加相机扫码组件、ATS 或明文例外、本地网络权限文案;用 `@expo/fingerprint` 确认指纹不变。
+- **Desktop**:内核的 bundle 要随 Desktop 打包,供方式 B 使用;方式 A 上传的也是这个文件,两边版本天然一致。
+- **需要更新的规则文档**:
+ - `protocol-compatibility.md`
+ - `remote-and-mobile-adaptation.md`
+ - `credentials-and-local-storage.md` 路径表
+ - 新增产品规则 `docs/product-rules/self-hosted-relay.md`,并在 `AGENTS.md` 加读取入口
+ - `i18n/glossary.json`:登记新术语,状态为 proposed
+
+## 11. 工作拆分(建议的 PR 顺序)
+
+1. **内核** `packages/device-link-relay`:协议、REST、加入与管理、媒体、持久化、三种证书方式。
+ 用 `scripts/device-link/interop.test.ts`(设置 `CINDY_TEST_RELAY_URL`)跑通与现有客户端的互通测试。
+2. **客户端认证与路由**:
+ - `@cindy/device-link` 新增 `CindyRelay` 认证方案。
+ - Desktop 的 `relayRouting`、鉴权失败不影响官方登录、证书指纹校验、跨账号模块暂停。
+3. **方式 B**:Desktop 内置运行与设置界面;同时完成加入流程和主人审批界面。
+4. **方式 A**:SSH 部署器(安装、systemd、证书、防火墙、检测、升级、卸载)。
+5. **Mobile**:加入深链与加入页、地址覆盖、凭证存储、设置项。
+6. **设备签名防冒充**:如果确认要做。建议排在方式 A 正式开放之前。
+7. **文档与术语**。
+
+## 12. 验证
+
+**自动测试:**
+
+- 内核单测:
+ - 认证、路由、错误码。
+ - 加入码:一次性、过期、限速。
+ - 管理权限(只有主人设备)。
+ - 媒体:签名与过期。
+ - 证书:用本地 ACME 测试服务器(如 Pebble)验证申请与续期。
+- 用客户端互通测试跑通新内核。
+- 回归:官方 token 不会发往自建中转。
+- 回归:中转返回 401 不会让官方账号登出。
+- 回归:自签名指纹不匹配时拒绝连接。
+- 多设备故障半径用例(§9)。
+
+测试遵守 `engineering-conventions.md` §3.2 的价值门槛与性能预算。
+
+**真机手动验证:**
+
+- 方式 A:
+ - 中国大陆云服务器(如阿里云、腾讯云),按 IP 访问并使用 IP 证书:确认按 IP 访问会不会被拦截,证书能否申请、续期。
+ - 中国香港或海外服务器。
+ - 有域名的服务器。
+ - root 用户、需要输入 sudo 密码的用户、没有 sudo 权限的用户,各测一遍。
+- 方式 B:
+ - 局域网 + 自签名,只连电脑。
+ - 路由器端口映射 + 自动证书。
+ - 前置代理(frp、nginx 各一种)。
+- 手机:iPhone、Android 通过 IP 证书和域名证书加入,验证远程任务、发图片、远程桌面。
+- 设置了代理的电脑能否连上中转。
+- 界面:Light 与 Dark 两种模式都要目检。
+
+## 13. 待确认
+
+1. **方式 A 正式开放前,是否先做设备签名防冒充?** 建议做(§8)。不做的话,第一期在界面上明确提示公网部署的风险。
+2. **服务器上 Node 从哪里下载?** 现有安装器让服务器自己从 nodejs.org 下载,国内服务器可能很慢或下不到。
+ 建议改为 Cindy 在本机按固定版本和哈希下载(`verified-downloads.md`),再经 SSH 上传。
+3. **界面上的名称**:用「中转服务」,还是别的叫法?
+4. **谁可以移除设备**:任何已加入的设备(与官方一致),还是只有主人电脑?
+5. **是否给 Agent 一个只读的中转状态工具?**
+6. **方式 B 是否保留「检测到 Tailscale 时一键发布」?** 建议第一期不做,只在说明文案里把它列为连通方式之一。
+
+## 14. 后续阶段
+
+- 设备间内容加密(端到端),在设备签名的基础上加密钥协商。可参考插件授权 v3 的设备密钥,以及通讯录同步的加密中转。
+- 多台主人电脑。
+- 中转自带 TURN。
+- 可选的官方推送转发。
+- 公司内网场景:内网服务器 + 公司自己签发的证书。
+
+## 15. 实施记录
+
+### 15.1 第 1 步:内核(2026-10-28)
+
+**已完成**:`packages/device-link-relay`
+
+- 线协议:与官方 relay 对齐的 v1 线协议(§6.1)。
+- REST:与官方同形的 REST(§6.2)。
+- 加入与管理:加入与管理接口(§6.3)。
+- 媒体:中转自带的媒体存储。
+- 持久化:设备档案的持久化。
+- 命令行:`relay init` / `relay serve` / `relay --version`。
+
+**与上文的差异(以此为准):**
+
+- **主人凭证**:主人设备的凭证同时带管理权限,不另发管理凭证(§2.3 已同步)。
+- **移除设备**:主人可以移除任何成员,成员只能让自己退出,主人设备不能被移除。这一项回答了 §13 第 4 条。
+- **加入轮询**:用提交申请时返回的轮询口令,不再复用加入码。
+- **凭证失效的错误码**:REST 返回 401 `RELAY_CREDENTIAL_INVALID`,不用会触发 Desktop 刷新或登出官方账号的错误码。
+- **证书**:本步只提供两种方式。
+ - 明文 HTTP:默认只监听 `127.0.0.1`,用于本机自连、测试,以及由前置代理负责 TLS 的场景。
+ - 用户自带证书文件:`--tls-cert` / `--tls-key`。
+ - **自动证书(ACME / IP 证书)与自签名生成放到下一步内核 PR。** 两者都要新增第三方依赖,需要单独评审。
+- **默认端口**:独立运行时默认 47820。
+- **数据目录**:`relay-state.json` 文件权限 0600,原子写入;媒体放在 `media/` 下。
+
+**验证:**
+
+- **单测**:`pnpm --filter @cindy/device-link-relay test`,9 个用例,单文件约 1.5 秒。
+ - 故意改坏「覆写 src」和「加入码作废」两处,对应用例都会失败。
+- **互通**:`pnpm --filter @cindy/device-link-relay run interop`。
+ - 正式 `DeviceLinkClient` 加上 Mobile 恢复核心,通过 `CindyRelay` 凭证连上中转。
+ - 握手、补订阅、断线后自动重连都通过。
+ - 控制端凭证由真实的加入流程取得。
+- **回归**:`pnpm test:device-link` 10 个用例通过。
+
+**尚未做:**
+
+- 客户端接入(§11 第 2 步起)。
+- 自动证书与自签名证书。
+- 打包成单文件 bundle:随方式 A / B 接入时一起做。
+
+### 15.2 第 2 步:方式 B 与加入流程接入客户端(2026-10-28)
+
+**Desktop**:
+
+- 设置 → 远程连接 → 「中转服务」:显示当前使用的中转,可以在这台电脑上开启中转,也可以加入别的中转或切回官方中转。
+ - 开启中转时可以设置端口、允许谁连接(仅本机 / 所有网络)和对外地址。
+ - 开启后可以「添加设备」:生成二维码和加入链接,在同一处审批申请(显示配对码)。
+- 中转由 Cindy 主进程运行(`device-link/selfHostedRelayRuntime.ts`)。
+ - 开启后本机以主人身份连接 `http://127.0.0.1:<端口>`,并自动打开「保持电脑唤醒」。
+ - 应用启动、登录后,按设置自动拉起中转;登出时停掉。
+- 路由:
+ - device-link 的地址、认证方案与凭证都经零依赖的 `selfHostedRelayRouting.ts` 读取。
+ - REST 统一走 `deviceLinkApi.ts`,覆盖设备列表、媒体预签名和远程桌面 ICE。
+ - 自建中转返回 401 时不会刷新或登出 Cindy 账号,也不会轮换账号 token。
+- 切换中转复用切换区域时的重连流程(`restartDeviceLinkForRelayChange`)。
+
+**Mobile**(纯 JS,不改原生配置):
+
+- 扫码打开 `relay/join` 深链,进入加入页:显示配对码,等待电脑那边同意,然后保存凭证并切换。
+- 设置里可以查看当前中转,并切回官方中转。
+- REST 发往自建中转时只带中转凭证,不带账号 token;推送注册跳过官方 device-link。
+
+**与上文的差异:**
+
+- 方式 B 的中转目前运行在 **Electron 主进程**里,不是 `utilityProcess`:它是纯 Node 网络服务、负载很小,先保证可用;崩溃隔离留给后续步骤。
+- 4 位数字统一沿用术语表的「配对码 / Pairing code」,§2.2 与 §5.1 里写的「核对码」都按此理解。
+- 手机端的共享任务入口在自建模式下没有隐藏,打开会因中转不提供 `/shared-tasks` 而报错,后续再处理。
+
+**验证:**
+
+- Desktop typecheck、Mobile typecheck 通过。
+- 以下测试通过:
+ - `@cindy/device-link-relay` 11 例,其中新增「共享加入函数 + 真实中转」与「停用时成员收到 4410」。
+ - `@cindy/device-link` 加入链接解析 8 例。
+ - Desktop `deviceLinkApi.test.ts`:账号 token 不外发,中转 401 不登出。
+ - `mediaTransfer.test.ts`、`remoteControlDevicesDeepLink.test.tsx`。
+ - Mobile 相关 13 个文件。
+- 互通测试已改用与客户端相同的加入函数,通过。
+
+**未在真机或界面上走通**:两台电脑加一部手机的完整体验需要用户实测,步骤见交付说明。
+
+### 15.3 第 3 步:设备签名、一键部署到服务器、远程管理(2026-10-28)
+
+**设备签名**(见 §16):
+
+- 共享协议:`packages/device-link/src/selfHostedRelayAuth.ts`,加密实现由宿主注入。
+ - Desktop 与中转用 `@cindy/device-link/node-relay-crypto`(node:crypto)。
+ - Mobile 用 `@noble/curves` / `@noble/hashes` 与 `expo-crypto`。
+- `DeviceLinkClient` 新增 `frameAuth` 选项,只有两处钩子:
+ - `sendEnvelope` 给经中转转发的对端帧附上 `auth`;
+ - `handleMessage` 在任何解码与分发之前核对签名。
+ - 官方中转返回 null,wire 行为与旧版完全相同。
+- 中转:
+ - `relay-state.json` 升到 schema 2,保存主人公钥与每台设备的证书;
+ - 新增 `GET /api/device-link/relay/certs`;
+ - 加入申请必须带公钥与配对证明,同意必须附主人签发、发给申请里那把公钥的证书;
+ - 帧里的 `auth` 原样转发。
+- Desktop:
+ - 主人密钥与设备签名密钥按中转 ID 存在 `secrets/<中转ID>.enc`(safeStorage 加密);
+ - 审批时用加入链接里的配对秘密核对证明,对不上只能拒绝;
+ - 电脑核对所有对端消息(`selfHostedRelayFrameAuth.ts`)。
+- Mobile:加入时生成签名密钥并核对证书;发出的消息都签名,不核对收到的消息(理由见 §16.4)。
+
+**一键部署到服务器**(方式 A 的落地形态):
+
+- 内核新增自动证书(`acme.ts`、`csr.ts`、`certificates.ts`)。
+ - 自己实现了最小 ACME 客户端(http-01)与 CSR 编码,没有引入第三方库。
+ - 填 IP 时用 Let's Encrypt `shortlived` 配置申请 6 天有效的 IP 证书;填域名时用常规证书。
+ - 剩余有效期不足 1/3 时自动续期,续期后热替换证书,不断开现有连接。
+ - 证书状态写进数据目录的 `status.json`,部署方据此报告进度与失败原因。
+- `relay serve --acme-identifier <IP或域名>`:先在 80 端口提供验证,拿到证书后才开始提供 443。
+ - 首次申请失败按 1 / 5 / 15 / 30 / 60 分钟退避重试(Let's Encrypt 对失败验证有限额)。
+- 单文件:`packages/device-link-relay/build.mjs` 打出 `dist/relay.mjs`(约 210 KB)。
+ - 由 `apps/desktop/scripts/build-remote-bundles.mjs` 放进 `resources/device-link-relay/`,随安装包分发。
+- 部署器 `apps/desktop/src/main/device-link/selfHostedRelayDeploy.ts`:走「远程」里已配置的 SSH 主机。
+ - 需要 root 或免密 sudo;没有就停下来提示,不索要密码。
+ - 步骤:连接 → 检查系统和 80/443 端口 → 安装 Node → 上传并核对 SHA-256 → 建系统用户、初始化、写 systemd 服务、开放 ufw / firewalld → 等证书 → 从这台电脑访问 `https://<地址>/api/device-link/relay/info` 核对中转 ID。
+ - Node 24.22.1 的 SHA-256 写死在代码里。国内区域先试 npmmirror,其他区域先试 nodejs.org;校验不符视为下载失败。
+ - 服务器有 IPv6 时监听 `::`(双栈),否则 `0.0.0.0`。Let's Encrypt 会优先通过 IPv6 验证有 AAAA 记录的域名。
+ - systemd 服务以 `cindy-relay` 用户运行,只放行绑定低端口的权限;`ProtectSystem=strict`,只能写数据目录。
+ - 主人身份(中转 ID、主人凭证、主人密钥)只在这台电脑生成;服务器只拿到凭证哈希、主人公钥和主人证书。
+ - 身份在动服务器之前就记进部署记录:中途失败重试,用的还是同一份身份,不会和服务器上已初始化的数据冲突。
+- 服务器上已有不属于这台电脑的中转时停下(`RELAY_MISMATCH`),由用户选择清掉重新部署。
+
+**远程管理**(设置 → 远程连接 → 中转服务):
+
+- 部署表单:选择 SSH 主机,访问地址默认取 SSH 主机地址(IP 或域名),可以修改。
+- 部署进度逐步显示。
+- 失败时给出原因与处理办法,例如安全组没放行 80 / 443、端口被占、没有 root。
+- 可以重试,也可以清掉旧中转重新部署。
+- 「我的服务器中转」:
+ - 版本;
+ - 升级(Cindy 带的中转版本不同时);
+ - 从服务器卸载(连同设备档案);
+ - 只在本机移除;
+ - 改用这个中转。
+- 作为服务器中转的主人时,「添加设备」与审批直接对 `https://<地址>` 调管理接口,与本机中转共用同一套界面。
+- 切回官方中转时,服务器上的中转继续运行,可以随时改回来。
+
+**与上文的差异:**
+
+- §2.2 原计划的自签名证书不再需要:手机只信任公开 CA 的证书,IP 证书已覆盖「没有域名」的场景。
+- §3 原计划由用户自己执行安装命令,现在由 Cindy 经 SSH 一键完成;不支持 SSH 的服务器仍可手动运行同一个 `relay.mjs`。
+- 中转版本升到 0.2.0(加入签名与证书,wire 行为变化);第 2 步留下的本机中转数据(schema 1)不能使用,开启时会自动重建,已加入的设备需要重新加入。
+
+**验证:**
+
+- `@cindy/device-link-relay` 12 例通过,新增两项:
+ - 同意时证书对不上申请(没有证书、证书发给别的公钥)被拒;
+ - 加入链接里的主人公钥与中转不符时 `OWNER_MISMATCH`。
+- `@cindy/device-link` 54 个文件 1081 例通过,新增两项:
+ - 客户端签名用例:未签名、他人密钥、签名后改内容、原样重放的帧都在分发前被丢弃,本机发出的帧带有效签名;
+ - 加入链接缺主人公钥或配对秘密时拒绝。
+- 互通:`pnpm --filter @cindy/device-link-relay run interop` 全程开启设备签名,主机核对每一条对端消息,通过。
+ - 故意把控制端换成错误的签名密钥,主机丢帧、测试失败,说明签名确实在生效。
+- ACME:用 Let's Encrypt 官方测试 CA Pebble 在本机实测内核单文件。
+ - IP 证书(6 天)与域名证书(90 天)都签发成功,HTTPS 正常提供;
+ - 重启后复用已保存证书,不重复申请;
+ - 失败原因(80 端口连不上)原样写进状态文件。
+ - Pebble 需要单独下载,没有放进 CI。
+- Desktop:typecheck 通过;`src/main/device-link/__tests__` 88 个文件 1811 例通过。
+
+**尚未验证:**
+
+- 真实云服务器上的部署:Let's Encrypt 生产环境、云厂商安全组、不同发行版的 sudo / useradd / ufw。
+- 界面实机操作与手机真机。
+
+### 15.4 收尾验证与体验入口(2026-10-28)
+
+部署等待期间换账号时,旧工作不能继续取新账号的 SSH 主机、写入新账号的配置或覆盖新部署进度。
+部署、升级、卸载及切换中转的异步步骤核对发起时的账号代次;旧账号的本机中转迟到启动成功时立即关闭。
+已送到服务器的命令不能撤回,但旧任务不再继续后续 SSH 步骤;切回原账号后可用原部署记录重试。
+实现见 `selfHostedRelayRuntime.ts`、`selfHostedRelayDeploy.ts`,回归从实际注册的 IPC 入口验证。
+
+本次补验:
+
+- Desktop、Mobile 与中转内核类型检查通过;中转单文件构建通过。
+- 共享通信库 54 个文件、1081 例通过;真实 WebSocket 断线恢复 10 例通过。
+- 中转内核 12 例及开启设备签名的互通测试通过。
+- 手机签名、加入深链、API 路由、账号隔离与通知的定向测试 6 个文件、101 例通过。
+- Desktop 部署器 7 例、运行时账号切换 6 例、账号 token 隔离 2 例通过。
+- 部署表单、部署进度、部署完成三个真实组件场景,Light/Dark × 中文/英文/日文共 18 个截图场景通过并目检。
+ SSH 列表和部署状态为模拟数据,不代表真实服务器已部署。
+ `ui:check --changed --theme all` 因公共语言资源选入大量无关页面,已主动中止,不计作通过;上述结果来自部署页定向验证。
+- i18n、术语表、测试卫生和开发文档检查通过。
+
+体验步骤:
+
+1. 使用含本次代码的桌面开发版,在「设置 → 远程」配置自己的 Linux SSH 主机。
+2. 打开「设置 → 远程连接 → 中转服务 → 部署到我的服务器」,选主机、核对访问地址,开始部署。
+ 主机需支持 systemd,并具备 root 或免密 sudo;80/443 端口不能被其他服务占用,云安全组需放行这两个端口。
+3. 等待部署完成并自动切换后,点击「添加设备」。另一台新版电脑粘贴链接,手机用含本次 JS 改动的开发版扫码。
+ 在主人电脑核对配对码并同意,再测试设备列表、远程消息、图片和断线重连。
+4. 切回官方中转,核对原有连接恢复,服务器中转仍继续运行;可以再点击「改用这个中转」。
+
+真实云服务器部署、生产 CA 签发与续期、手机真机仍待体验验证;本轮未操作用户的云服务器,也未提交或发布。
+
+## 16. 设备签名:中转无法冒充你的设备
+
+### 16.1 要防什么
+
+中转部署在云服务器上之后,服务器被入侵(或云厂商、托管方能动它)就等于中转被人控制。没有签名时,控制了中转的人可以:
+
+- 冒充手机给电脑发 `invoke` / `link-open`,让电脑执行任务、读写文件;
+- 冒充电脑给其他电脑推送插件同步、词典、通讯录等会写入状态的消息;
+- 重放之前的消息。
+
+签名之后,中转仍然能看到经它转发的内容,也能断开、丢弃消息(它本来就能),但**不能让任何一台电脑执行没有经过你自己设备签名的请求**。端到端加密不在本期范围。
+
+### 16.2 密钥与证书
+
+- **主人密钥**:开启或部署中转的那台电脑生成(Ed25519),私钥只在它的 safeStorage 里。主人电脑自己的设备签名也用这把密钥。
+- **设备证书**:主人密钥对「中转 ID + 设备 ID + 设备公钥 + 角色 + 签发时间」的签名。
+ - 中转保存证书并提供给所有设备,但伪造不了。
+ - 每台设备用主人公钥逐个核对证书。
+- **主人公钥从哪来**:
+ - 主人电脑自己知道;
+ - 其他设备从加入链接 `o=` 参数取得。链接经二维码或复制粘贴交给新设备,不经中转。
+- **新设备的公钥怎么不被中转替换**:
+ - 加入链接里还有一次性配对秘密 `s=`,同样不经中转。
+ - 新设备生成签名密钥,用 `HMAC-SHA256(s, [中转ID, 设备ID, 公钥])` 证明这把公钥是拿着链接的设备生成的。
+ - 主人电脑审批时核对证明,对不上只能拒绝。
+ - 4 位配对码仍保留,给人眼再核对一次。
+- **加入时核对证书**:新设备拿到中转转交的证书后,必须核对它出自链接里的主人、发给自己这把公钥。否则视为中转被替换,停止加入(`OWNER_MISMATCH`)。
+
+### 16.3 每条消息的签名
+
+经中转转发的对端帧(`ROUTED_KINDS`)都带 `auth: { t, b, c, s }`:
+
+- `t`:发送时刻(毫秒),收到时与本机时钟相差超过 10 分钟即拒绝。
+- `b`:本次启动的随机标识;`c`:本次启动内严格递增的计数。收到方按「发送设备 + 启动标识」记下最大计数,不大于它的一律视为重放。启动标识的最后一条消息也过期后清理记录,内存不随消息量增长。
+- `s`:Ed25519 签名。签名对象是以下内容的 SHA-256:
+ - `JSON.stringify(["cindy-relay-frame/1", 中转ID, 发送设备, 收件设备, kind, id, t, b, c])`;
+ - 换行;
+ - `JSON.stringify(payload)`。
+ - 中转转发时会重新序列化帧,JSON 解析再序列化在 V8 与 Hermes 上都保持不变。
+- 收件设备还核对 `dst` 就是自己:签给别的设备的消息不能转投给它。
+- 可靠传输重发、分片都会重新签名(签名发生在每次真正写入 WebSocket 时)。
+- 直连通道上的帧不签名:直连的 DTLS 指纹经已签名的信令交换,电脑只接受签名有效的信令,因此直连的对端身份同样可信。
+- 遇到证书列表里还没有的设备,先丢弃这条消息并刷新证书(5 秒节流);可靠传输的重发会在刷新后送达。
+
+### 16.4 手机只签名、不核对
+
+- 手机会签名发出的每条消息(主要是 `invoke` / `link-open` / ACK,体积小)。
+- 手机**不核对**收到的消息:Hermes 上纯 JS 的 Ed25519 验签对推送流来说太慢。
+- 电脑核对全部对端消息,因此控制了中转的人最多能让手机显示伪造的内容,不能让任何电脑执行请求。
+- 后续如果手机端引入原生加密模块,可以补上核对。
+
+### 16.5 兼容
+
+- 官方中转完全不受影响:`frameAuth` 返回 null,不签名、不核对,wire 与旧版逐字节一致。
+- 自建中转从 0.2.0 起要求签名。
+ - 旧格式的加入链接(没有 `o` / `s`)会被拒绝;
+ - 不支持 `device-signatures-v1` 的中转不能加入。
+- 自建中转从未发布过,不存在需要迁移的用户数据。第 2 步开发期间留下的本机配置会被忽略并清掉旧凭证文件。
diff --git a/i18n/GLOSSARY.md b/i18n/GLOSSARY.md
index f4772211e5..480b44c5e5 100644
--- a/i18n/GLOSSARY.md
+++ b/i18n/GLOSSARY.md
@@ -627,6 +627,10 @@ Orca Worker 创建卡上的命名字段。它只是派活用的名字,不改
2026-10-26 用户指定截图功能统一称为滚动截图,突出滚动操作,不再使用长截图作为功能名称。
+### Relay service
+
+远程连接设置里选择设备之间经 Cindy 官方中转,还是用户自己的中转(这台电脑当中转 / 加入别的中转)。官方一侧称「Cindy 官方中转」(Cindy relay)。方案见 docs/self-hosted-relay-plan.md。
+
### Mute notifications
任务右键菜单里的通知开关,是普通句子不是品牌词,故 checkCase 为 false。开关两态成对出现:未静音时显示「消息免打扰」(点了就静音),已静音时显示「允许消息通知」(点了就恢复);英文对为 Mute notifications / Allow notifications。与设置里的全局通知开关(ccAgent.settings.notifications)区分:这个是单个任务的。中文不用「免打扰模式」「静音」。「允许消息通知」是反面文案,未列入 translations,待五语用例变多后一并裁决。
diff --git a/i18n/glossary.json b/i18n/glossary.json
index 5d92b87c8a..4e635033fb 100644
--- a/i18n/glossary.json
+++ b/i18n/glossary.json
@@ -256,6 +256,18 @@
},
"note": "远程桌面传输状态,桌面端沿用手机端现有用语。表示画面不经过中转服务器;直连也可能穿过公网 NAT,不能据此标成内网直连。"
},
+ {
+ "id": "self-hosted-relay-service",
+ "status": "proposed",
+ "en": "Relay service",
+ "translations": {
+ "zh-CN": "中转服务",
+ "zh-TW": "中繼服務",
+ "ja": "リレーサービス",
+ "ko": "중계 서비스"
+ },
+ "note": "远程连接设置里选择设备之间经 Cindy 官方中转,还是用户自己的中转(这台电脑当中转 / 加入别的中转)。官方一侧称「Cindy 官方中转」(Cindy relay)。方案见 docs/self-hosted-relay-plan.md。"
+ },
{
"id": "remote-desktop-video-relay",
"status": "proposed",
diff --git a/packages/device-link-relay/build.mjs b/packages/device-link-relay/build.mjs
new file mode 100644
index 0000000000..9f2a857247
--- /dev/null
+++ b/packages/device-link-relay/build.mjs
@@ -0,0 +1,37 @@
+// 把中转命令行入口(src/cli.ts)打成一个自包含的 ESM 文件 dist/relay.mjs,部署时经 SSH 传到用户的
+// 服务器、用 Node 运行。与 remote-file-service/build.mjs 同款管线(含跨平台 EOL 归一,保证 Win/mac
+// 构建产物一致);产物由 apps/desktop/scripts/build-remote-bundles.mjs 在 dev/prepackage 阶段交给 desktop。
+
+import * as esbuild from 'esbuild';
+import { readFile } from 'node:fs/promises';
+
+const normalizeEolPlugin = {
+ name: 'normalize-eol-lf',
+ setup(build) {
+ build.onLoad({ filter: /\.(ts|js|mjs|cjs|json)$/ }, async (args) => {
+ const raw = await readFile(args.path, 'utf8');
+ const normalized = raw.replace(/\r\n/g, '\n');
+ const ext = args.path.slice(args.path.lastIndexOf('.') + 1);
+ const loader = ext === 'ts' ? 'ts' : ext === 'json' ? 'json' : 'js';
+ return { contents: normalized, loader };
+ });
+ },
+};
+
+await esbuild.build({
+ entryPoints: ['src/cli.ts'],
+ bundle: true,
+ platform: 'node',
+ target: 'node20',
+ format: 'esm',
+ outfile: 'dist/relay.mjs',
+ // ws 是 CommonJS,可选的原生加速模块(bufferutil / utf-8-validate)不打包:没有时 ws 自动退回纯 JS。
+ banner: { js: "#!/usr/bin/env node\nimport { createRequire as __cindyCreateRequire } from 'node:module';\nconst require = __cindyCreateRequire(import.meta.url);" },
+ external: ['bufferutil', 'utf-8-validate'],
+ legalComments: 'none',
+ minify: false, // 远端日志里的堆栈保持可读
+ sourcemap: false,
+ plugins: [normalizeEolPlugin],
+});
+
+console.log('built dist/relay.mjs');
diff --git a/packages/device-link-relay/package.json b/packages/device-link-relay/package.json
new file mode 100644
index 0000000000..164d6c9646
--- /dev/null
+++ b/packages/device-link-relay/package.json
@@ -0,0 +1,37 @@
+{
+ "name": "@cindy/device-link-relay",
+ "version": "0.0.0",
+ "private": true,
+ "description": "自建 device-link 中转服务内核:与官方 relay 线协议兼容的 WebSocket 中转、设备档案、配对与管理接口、媒体中转。同一份代码既可在 Cindy 内运行,也可在服务器上用 Node 独立运行。零 Electron 依赖。",
+ "type": "module",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "scripts": {
+ "build": "tsc --noEmit",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run",
+ "interop": "tsx scripts/run-interop.ts",
+ "bundle": "node build.mjs"
+ },
+ "author": {
+ "name": "XD Inc.",
+ "email": "[email protected]"
+ },
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@cindy/device-link": "workspace:*",
+ "@cindy/device-link-protocol": "workspace:*",
+ "ws": "^8.18.3"
+ },
+ "devDependencies": {
+ "@types/node": "*",
+ "@types/ws": "^8.18.1",
+ "esbuild": "^0.28.1",
+ "tsx": "^4.19.0",
+ "typescript": "^5.7.0",
+ "vitest": "^3.2.4"
+ }
+}
diff --git a/packages/device-link-relay/scripts/run-interop.ts b/packages/device-link-relay/scripts/run-interop.ts
new file mode 100644
index 0000000000..0119074396
--- /dev/null
+++ b/packages/device-link-relay/scripts/run-interop.ts
@@ -0,0 +1,151 @@
+/**
+ * 用现有的 device-link 互通测试(`pnpm test:device-link --interop`)验证自建中转:
+ *
+ * 1. 在临时目录初始化一个中转,主人电脑凭证在本进程生成;
+ * 2. 在本机回环地址启动中转;
+ * 3. 走真实的加入流程(加入码 → 申请 → 主人同意 → 取回凭证)拿到第二台设备的凭证;
+ * 4. 以 `CindyRelay` 方案把两份凭证交给互通测试,由正式 DeviceLinkClient 与 Mobile 恢复核心连接;
+ * 同时交出两台设备的签名密钥与中转上的证书,互通测试全程开启设备签名(主机核对每一条对端消息);
+ * 5. 结束后关闭中转、删除临时目录。
+ *
+ * 凭证只经子进程环境变量传递,不打印。
+ */
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+ acceptRelayDeviceCert,
+ buildRelayJoinLink,
+ createRelayJoinIdentity,
+ createRelayPairSecret,
+ createRelaySigningKey,
+ issueRelayDeviceCert,
+ parseRelayJoinLink,
+ submitRelayPairRequest,
+ verifyRelayPairProof,
+ waitForRelayApproval,
+ type RelayFetch,
+} from '@cindy/device-link';
+import { nodeRelayAuthCrypto as crypto } from '@cindy/device-link/node-relay-crypto';
+import { createDeviceCredential, initializeRelay, startRelayServer } from '../src/index';
+
+const repoRoot = fileURLToPath(new URL('../../../', import.meta.url));
+const OWNER_USER = 'interop-account';
+
+async function call(base: string, method: string, pathname: string, init: { credential?: string; body?: unknown; pollToken?: string } = {}) {
+ const headers: Record<string, string> = {};
+ if (init.credential) headers.authorization = `CindyRelay ${init.credential}`;
+ if (init.pollToken) headers['x-cindy-relay-poll-token'] = init.pollToken;
+ if (init.body !== undefined) headers['content-type'] = 'application/json';
+ const res = await fetch(`${base}${pathname}`, {
+ method,
+ headers,
+ body: init.body === undefined ? undefined : JSON.stringify(init.body),
+ });
+ const json = (await res.json()) as Record<string, any>;
+ if (!res.ok) throw new Error(`${method} ${pathname} failed: ${res.status} ${json.error?.code ?? ''}`);
+ return json;
+}
+
+async function main(): Promise<number> {
+ const dataDir = await mkdtemp(path.join(os.tmpdir(), 'cindy-relay-interop-'));
+ const owner = createDeviceCredential();
+ const ownerKey = createRelaySigningKey(crypto);
+ const relayId = randomUUID();
+ await initializeRelay({
+ dataDir,
+ name: 'Interop relay',
+ ownerUserId: OWNER_USER,
+ ownerDeviceId: 'interop-owner-desktop',
+ ownerDeviceName: 'Interop host',
+ ownerCredentialHash: owner.credentialHash,
+ relayId,
+ ownerPublicKey: ownerKey.publicKey,
+ ownerCert: issueRelayDeviceCert(crypto, ownerKey.seed, {
+ relayId,
+ deviceId: 'interop-owner-desktop',
+ publicKey: ownerKey.publicKey,
+ role: 'owner',
+ issuedAt: Date.now(),
+ }),
+ });
+ const relay = await startRelayServer({ dataDir, port: 0 });
+ try {
+ const base = relay.localUrl;
+ // 与 Desktop / Mobile 相同的加入路径:主人生成加入链接,新设备解析链接、申请、等主人同意。
+ const { code } = await call(base, 'POST', '/api/device-link/relay/admin/join-codes', { credential: owner.credential });
+ const pairSecret = createRelayPairSecret(crypto);
+ const link = parseRelayJoinLink(
+ buildRelayJoinLink({ baseUrl: base, code, ownerPublicKey: ownerKey.publicKey, pairSecret, app: 'cindy' }),
+ )!;
+ const relayFetch: RelayFetch = (url, init) => fetch(url, init);
+ const deviceId = 'interop-controller-phone';
+ const identity = createRelayJoinIdentity(crypto, link, relayId, deviceId);
+ const request = await submitRelayPairRequest(relayFetch, link, {
+ deviceId,
+ deviceName: 'Interop controller',
+ platform: 'ios',
+ appVersion: '0.0.0-test',
+ accountUserId: OWNER_USER,
+ publicKey: identity.publicKey,
+ proof: identity.proof,
+ });
+ const approval = waitForRelayApproval(relayFetch, link, request, { deadlineMs: 30_000 });
+ // 主人电脑:核对配对证明后签发证书并同意。
+ const { requests } = await call(base, 'GET', '/api/device-link/relay/admin/pair-requests', { credential: owner.credential });
+ const pending = (requests as Array<Record<string, string>>).find((r) => r.requestId === request.requestId)!;
+ if (!verifyRelayPairProof(crypto, pairSecret, { relayId, deviceId, publicKey: pending.publicKey, proof: pending.proof })) {
+ throw new Error('pairing proof mismatch');
+ }
+ await call(base, 'POST', `/api/device-link/relay/admin/pair-requests/${request.requestId}/approve`, {
+ credential: owner.credential,
+ body: {
+ cert: issueRelayDeviceCert(crypto, ownerKey.seed, { relayId, deviceId, publicKey: pending.publicKey, role: 'member', issuedAt: Date.now() }),
+ },
+ });
+ const admitted = await approval;
+ acceptRelayDeviceCert(crypto, link, { relayId, deviceId, publicKey: identity.publicKey, cert: admitted.cert });
+ console.log('[relay-interop] relay started on loopback; controller paired through the join flow');
+
+ const { certs } = await call(base, 'GET', '/api/device-link/relay/certs', { credential: owner.credential });
+
+ return await new Promise<number>((resolve) => {
+ const child = spawn(process.execPath, ['apps/mobile/scripts/device-link-reconnect-smoke.mjs', '--interop'], {
+ cwd: repoRoot,
+ stdio: 'inherit',
+ env: {
+ ...process.env,
+ CINDY_TEST_RELAY_URL: `${base.replace(/^http/, 'ws')}/api/device-link/ws`,
+ CINDY_TEST_HOST_TOKEN: owner.credential,
+ CINDY_TEST_CONTROLLER_TOKEN: admitted.credential,
+ CINDY_TEST_AUTH_SCHEME: 'CindyRelay',
+ CINDY_TEST_FRAME_AUTH: JSON.stringify({
+ relayId,
+ ownerPublicKey: ownerKey.publicKey,
+ certs,
+ host: { deviceId: 'interop-owner-desktop', seed: ownerKey.seed },
+ controller: { deviceId, seed: identity.seed },
+ }),
+ },
+ });
+ child.on('exit', (exitCode, signal) => resolve(exitCode ?? (signal ? 1 : 0)));
+ child.on('error', () => resolve(1));
+ });
+ } finally {
+ await relay.close();
+ await rm(dataDir, { recursive: true, force: true });
+ }
+}
+
+main().then(
+ (exitCode) => {
+ process.exitCode = exitCode;
+ },
+ (error: unknown) => {
+ console.error(`[relay-interop] ${error instanceof Error ? error.message : 'failed'}`);
+ process.exitCode = 1;
+ },
+);
diff --git a/packages/device-link-relay/src/__tests__/relay.test.ts b/packages/device-link-relay/src/__tests__/relay.test.ts
new file mode 100644
index 0000000000..8fc3a2fc71
--- /dev/null
+++ b/packages/device-link-relay/src/__tests__/relay.test.ts
@@ -0,0 +1,518 @@
+/**
+ * 测试价值
+ * - 生产入口与可观察结果:`initializeRelay` + `startRelayServer` 起真实的本机 HTTP/WebSocket 服务,
+ * 用真实 ws 客户端与 fetch 断言设备能看到的协议结果(hello-ack、转发帧、relay-error、关闭码、
+ * REST 状态码与响应体、持久化后的凭证与名字)。
+ * - Bug/规则依据:docs/self-hosted-relay-plan.md §5.2、§6(线协议必须与官方 relay 对齐,客户端才能
+ * 不改协议直接连);§8 安全(凭证认证、加入码一次性、主人才能管理、媒体签名地址)。
+ * - 现有覆盖缺口:新包,此前没有中转服务端实现;scripts/device-link/relayFixture.ts 只是测试用假中转。
+ * - 最小失败输入:每条用例各对应一个结果分支,例如伪造 src、重复使用加入码、成员调用管理接口、
+ * 篡改媒体签名、上传超过声明大小、同意时附的证书不是发给申请里那把公钥、加入链接里的主人公钥与中转不符。
+ * - tier:unit。只用本机回环端口与临时目录,无外部服务;过期用注入时钟,不做真实等待。
+ * - 实测耗时:见 PR 描述(单文件本机运行)。
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, readdir, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {
+ acceptRelayDeviceCert,
+ buildRelayJoinLink,
+ computeRelayPairProof,
+ createRelayJoinIdentity,
+ createRelayPairSecret,
+ createRelaySigningKey,
+ fetchRelayCertificates,
+ fetchRelayInfo,
+ issueRelayDeviceCert,
+ parseRelayJoinLink,
+ RelayJoinError,
+ submitRelayPairRequest,
+ waitForRelayApproval,
+ type RelayFetch,
+} from '@cindy/device-link';
+import { nodeRelayAuthCrypto as crypto } from '@cindy/device-link/node-relay-crypto';
+import type { Envelope } from '@cindy/device-link-protocol';
+import { afterEach, describe, expect, it } from 'vitest';
+import WebSocket from 'ws';
+import { createDeviceCredential, initializeRelay, startRelayServer, type RelayServerHandle } from '../index';
+
+const OWNER_USER = 'user-owner';
+const OWNER_DEVICE = 'owner-desktop';
+const HOUR = 60 * 60 * 1000;
+
+interface Harness {
+ base: string;
+ relayId: string;
+ ownerCredential: string;
+ ownerKey: { seed: string; publicKey: string };
+ dataDir: string;
+ clock: { now: number };
+ handle: RelayServerHandle;
+ restart(): Promise<void>;
+}
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+ for (const cleanup of cleanups.splice(0).reverse()) await cleanup();
+});
+
+async function setup(): Promise<Harness> {
+ const dataDir = await mkdtemp(path.join(os.tmpdir(), 'cindy-relay-test-'));
+ const owner = createDeviceCredential();
+ const ownerKey = createRelaySigningKey(crypto);
+ const relayId = randomUUID();
+ await initializeRelay({
+ dataDir,
+ name: 'Test relay',
+ ownerUserId: OWNER_USER,
+ ownerDeviceId: OWNER_DEVICE,
+ ownerDeviceName: 'Owner Mac',
+ ownerCredentialHash: owner.credentialHash,
+ relayId,
+ ownerPublicKey: ownerKey.publicKey,
+ ownerCert: issueRelayDeviceCert(crypto, ownerKey.seed, {
+ relayId,
+ deviceId: OWNER_DEVICE,
+ publicKey: ownerKey.publicKey,
+ role: 'owner',
+ issuedAt: 1,
+ }),
+ });
+ const clock = { now: Date.UTC(2026, 9, 28) };
+ const start = () => startRelayServer({ dataDir, port: 0, now: () => clock.now });
+ const harness: Harness = {
+ base: '',
+ relayId,
+ ownerCredential: owner.credential,
+ ownerKey,
+ dataDir,
+ clock,
+ handle: await start(),
+ async restart() {
+ await harness.handle.close();
+ harness.handle = await start();
+ harness.base = harness.handle.localUrl;
+ },
+ };
+ harness.base = harness.handle.localUrl;
+ cleanups.push(async () => {
+ await harness.handle.close();
+ await rm(dataDir, { recursive: true, force: true });
+ });
+ return harness;
+}
+
+async function api(
+ base: string,
+ method: string,
+ pathname: string,
+ options: { credential?: string; body?: unknown; headers?: Record<string, string> } = {},
+): Promise<{ status: number; json: any }> {
+ const headers: Record<string, string> = { ...options.headers };
+ if (options.credential) headers.authorization = `CindyRelay ${options.credential}`;
+ if (options.body !== undefined) headers['content-type'] = 'application/json';
+ const res = await fetch(`${base}${pathname}`, {
+ method,
+ headers,
+ body: options.body === undefined ? undefined : JSON.stringify(options.body),
+ });
+ const text = await res.text();
+ return { status: res.status, json: text ? JSON.parse(text) : null };
+}
+
+/** 新设备的签名公钥与配对证明(加入申请必带)。 */
+function deviceKeys(h: Harness, deviceId: string) {
+ const key = createRelaySigningKey(crypto);
+ const proof = computeRelayPairProof(crypto, createRelayPairSecret(crypto), { relayId: h.relayId, deviceId, publicKey: key.publicKey });
+ return { publicKey: key.publicKey, proof };
+}
+
+/** 主人为申请里的公钥签发成员证书。 */
+function memberCert(h: Harness, deviceId: string, publicKey: string) {
+ return issueRelayDeviceCert(crypto, h.ownerKey.seed, { relayId: h.relayId, deviceId, publicKey, role: 'member', issuedAt: 2 });
+}
+
+/** 走完整加入流程,返回新设备的凭证。 */
+async function pair(h: Harness, deviceId: string): Promise<string> {
+ const code = await api(h.base, 'POST', '/api/device-link/relay/admin/join-codes', { credential: h.ownerCredential });
+ const keys = deviceKeys(h, deviceId);
+ const submitted = await api(h.base, 'POST', '/api/device-link/relay/pair', {
+ body: { code: code.json.code, deviceId, deviceName: deviceId, platform: 'ios', appVersion: '1.0.0', accountUserId: OWNER_USER, ...keys },
+ });
+ expect(submitted.status).toBe(200);
+ await api(h.base, 'POST', `/api/device-link/relay/admin/pair-requests/${submitted.json.requestId}/approve`, {
+ credential: h.ownerCredential,
+ body: { cert: memberCert(h, deviceId, keys.publicKey) },
+ });
+ const polled = await api(h.base, 'GET', `/api/device-link/relay/pair/${submitted.json.requestId}`, {
+ headers: { 'x-cindy-relay-poll-token': submitted.json.pollToken },
+ });
+ expect(polled.json.status).toBe('approved');
+ return polled.json.credential as string;
+}
+
+interface Peer {
+ ws: WebSocket;
+ frames: Envelope[];
+ waitFor(match: (env: Envelope) => boolean): Promise<Envelope>;
+ closed: Promise<{ code: number; reason: string }>;
+ send(env: Record<string, unknown>): void;
+}
+
+function openSocket(base: string, authorization?: string): { ws: WebSocket; peer: Peer } {
+ const ws = new WebSocket(`${base.replace(/^http/, 'ws')}/api/device-link/ws`, {
+ headers: authorization ? { authorization } : {},
+ });
+ ws.on('error', () => undefined);
+ const frames: Envelope[] = [];
+ const waiters: Array<{ match: (env: Envelope) => boolean; resolve: (env: Envelope) => void }> = [];
+ ws.on('message', (data) => {
+ const env = JSON.parse(String(data)) as Envelope;
+ frames.push(env);
+ for (const waiter of [...waiters]) {
+ if (!waiter.match(env)) continue;
+ waiters.splice(waiters.indexOf(waiter), 1);
+ waiter.resolve(env);
+ }
+ });
+ const closed = new Promise<{ code: number; reason: string }>((resolve) => {
+ ws.on('close', (code, reason) => resolve({ code, reason: reason.toString() }));
+ });
+ cleanups.push(async () => {
+ ws.terminate();
+ });
+ const peer: Peer = {
+ ws,
+ frames,
+ closed,
+ waitFor(match) {
+ const existing = frames.find(match);
+ if (existing) return Promise.resolve(existing);
+ return new Promise((resolve) => waiters.push({ match, resolve }));
+ },
+ send(env) {
+ ws.send(JSON.stringify(env));
+ },
+ };
+ return { ws, peer };
+}
+
+async function connect(h: Harness, credential: string, remoteControlEnabled: boolean): Promise<Peer> {
+ const { ws, peer } = openSocket(h.base, `CindyRelay ${credential}`);
+ await new Promise<void>((resolve, reject) => {
+ ws.once('open', () => resolve());
+ ws.once('unexpected-response', (_req, res) => reject(new Error(`upgrade rejected ${res.statusCode}`)));
+ });
+ peer.send({
+ v: 1,
+ kind: 'hello',
+ payload: { deviceName: 'Device', platform: 'darwin', appVersion: '0.0.0-test', remoteControlEnabled, busy: false },
+ });
+ await peer.waitFor((env) => env.kind === 'hello-ack');
+ return peer;
+}
+
+function upgradeStatus(base: string, authorization?: string): Promise<number> {
+ const { ws } = openSocket(base, authorization);
+ return new Promise((resolve) => {
+ ws.once('unexpected-response', (_req, res) => resolve(res.statusCode ?? 0));
+ ws.once('open', () => resolve(101));
+ });
+}
+
+describe('device-link relay wire contract', () => {
+ it('authenticates with CindyRelay credentials only and binds identity to the credential', async () => {
+ const h = await setup();
+ // 没有凭证、凭证错误、用 Bearer 方案(可能是误发的账号 token)都在升级阶段 401。
+ expect(await upgradeStatus(h.base)).toBe(401);
+ expect(await upgradeStatus(h.base, `CindyRelay ${'x'.repeat(43)}`)).toBe(401);
+ expect(await upgradeStatus(h.base, `Bearer ${h.ownerCredential}`)).toBe(401);
+
+ const owner = await connect(h, h.ownerCredential, true);
+ const ack = owner.frames.find((env) => env.kind === 'hello-ack')!;
+ expect(ack.payload).toEqual({
+ serverProtocolVersion: 1,
+ deviceId: OWNER_DEVICE,
+ userId: OWNER_USER,
+ capabilities: [],
+ });
+ // REST 401 用专属错误码,不能是会触发 Desktop 刷新/登出 Cindy 账号的 UNAUTHORIZED 等。
+ const rest = await api(h.base, 'GET', '/api/device-link/devices', { credential: 'y'.repeat(43) });
+ expect(rest.status).toBe(401);
+ expect(rest.json.error.code).toBe('RELAY_CREDENTIAL_INVALID');
+ });
+
+ it('routes tunnel frames with a relay-assigned src and reports routing failures', async () => {
+ const h = await setup();
+ const phoneCredential = await pair(h, 'phone-1');
+ const host = await connect(h, h.ownerCredential, true);
+ const phone = await connect(h, phoneCredential, false);
+
+ const auth = { t: 1, b: 'boot-id-0123456789', c: 1, s: 'sig' };
+ phone.send({ v: 1, kind: 'invoke', id: 'req-1', src: 'forged-device', dst: OWNER_DEVICE, payload: { channel: 'x', args: [] }, auth });
+ const delivered = await host.waitFor((env) => env.kind === 'invoke' && env.id === 'req-1');
+ expect(delivered.src).toBe('phone-1');
+ expect(delivered.payload).toEqual({ channel: 'x', args: [] });
+ // 设备签名原样交给收件设备核对。
+ expect((delivered as Envelope & { auth?: unknown }).auth).toEqual(auth);
+
+ const cases: Array<{ frame: Record<string, unknown>; code: string }> = [
+ { frame: { v: 1, kind: 'invoke', id: 'req-2', dst: 'nobody', payload: {} }, code: 'DEVICE_OFFLINE' },
+ // 手机没开「允许被控」:控制类帧被拒,回程帧照常送达。
+ { frame: { v: 1, kind: 'link-open', id: 'req-3', dst: 'phone-1', payload: {} }, code: 'REMOTE_DISABLED' },
+ {
+ frame: { v: 1, kind: 'invoke', id: 'req-4', dst: OWNER_DEVICE, sharedTask: { taskId: 't' }, payload: {} },
+ code: 'BAD_REQUEST',
+ },
+ { frame: { v: 1, kind: 'invoke', id: 'req-5', dst: OWNER_DEVICE, payload: {}, auth: 'not-an-object' }, code: 'BAD_REQUEST' },
+ ];
+ for (const { frame, code } of cases) {
+ const sender = frame.dst === 'phone-1' ? host : phone;
+ sender.send(frame);
+ const error = await sender.waitFor((env) => env.kind === 'relay-error' && env.id === frame.id);
+ expect((error.payload as { code: string }).code).toBe(code);
+ }
+ host.send({ v: 1, kind: 'push', id: 'push-1', dst: 'phone-1', payload: { channel: 'evt' } });
+ expect((await phone.waitFor((env) => env.kind === 'push' && env.id === 'push-1')).src).toBe(OWNER_DEVICE);
+ expect(host.frames.some((env) => env.kind === 'invoke' && env.id === 'req-4')).toBe(false);
+ });
+
+ it('closes on protocol version mismatch with a reason clients classify as version', async () => {
+ const h = await setup();
+ const { ws, peer } = openSocket(h.base, `CindyRelay ${h.ownerCredential}`);
+ await new Promise((resolve) => ws.once('open', resolve));
+ peer.send({ v: 2, kind: 'hello', payload: {} });
+ const closed = await peer.closed;
+ expect(closed.code).toBe(4400);
+ expect(closed.reason).toContain('version');
+ });
+});
+
+describe('pairing and administration', () => {
+ it('admits a device only through a one-time join code and the owner approval', async () => {
+ const h = await setup();
+ const code = (await api(h.base, 'POST', '/api/device-link/relay/admin/join-codes', { credential: h.ownerCredential })).json.code;
+ const keys = deviceKeys(h, 'laptop-2');
+ const request = { code, deviceId: 'laptop-2', deviceName: 'Laptop', platform: 'win32', appVersion: '1.0.0', ...keys };
+
+ // 账号不一致被拒,但加入码保留给正确的设备。
+ const wrongAccount = await api(h.base, 'POST', '/api/device-link/relay/pair', { body: { ...request, accountUserId: 'someone-else' } });
+ expect(wrongAccount.json.error.code).toBe('ACCOUNT_MISMATCH');
+ const submitted = await api(h.base, 'POST', '/api/device-link/relay/pair', { body: { ...request, accountUserId: OWNER_USER } });
+ expect(submitted.status).toBe(200);
+ expect(submitted.json.verifyCode).toMatch(/^\d{4}$/);
+ const reused = await api(h.base, 'POST', '/api/device-link/relay/pair', { body: { ...request, accountUserId: OWNER_USER } });
+ expect(reused.status).toBe(403);
+
+ const pollPath = `/api/device-link/relay/pair/${submitted.json.requestId}`;
+ const pollHeaders = { 'x-cindy-relay-poll-token': submitted.json.pollToken };
+ expect((await api(h.base, 'GET', pollPath, { headers: pollHeaders })).json).toEqual({ status: 'pending' });
+ expect((await api(h.base, 'GET', pollPath, { headers: { 'x-cindy-relay-poll-token': 'wrong' } })).status).toBe(403);
+
+ const pending = await api(h.base, 'GET', '/api/device-link/relay/admin/pair-requests', { credential: h.ownerCredential });
+ expect(pending.json.requests).toMatchObject([{ deviceId: 'laptop-2', verifyCode: submitted.json.verifyCode, ...keys }]);
+ // 同意必须附主人为申请里这把公钥签发的证书:没有证书、证书发给别的公钥都不算同意。
+ const approvePath = `/api/device-link/relay/admin/pair-requests/${submitted.json.requestId}/approve`;
+ expect((await api(h.base, 'POST', approvePath, { credential: h.ownerCredential, body: {} })).status).toBe(400);
+ const otherKey = createRelaySigningKey(crypto).publicKey;
+ expect(
+ (await api(h.base, 'POST', approvePath, { credential: h.ownerCredential, body: { cert: memberCert(h, 'laptop-2', otherKey) } })).status,
+ ).toBe(400);
+ expect((await api(h.base, 'GET', pollPath, { headers: pollHeaders })).json).toEqual({ status: 'pending' });
+ await api(h.base, 'POST', approvePath, { credential: h.ownerCredential, body: { cert: memberCert(h, 'laptop-2', keys.publicKey) } });
+ const approved = await api(h.base, 'GET', pollPath, { headers: pollHeaders });
+ expect(approved.json.status).toBe('approved');
+ expect(approved.json.cert).toMatchObject({ deviceId: 'laptop-2', publicKey: keys.publicKey, role: 'member' });
+ // 凭证只给一次。
+ expect((await api(h.base, 'GET', pollPath, { headers: pollHeaders })).json).toEqual({ status: 'expired' });
+ const devices = await api(h.base, 'GET', '/api/device-link/devices', { credential: approved.json.credential });
+ expect(devices.json.devices.map((d: { deviceId: string; isSelf: boolean }) => [d.deviceId, d.isSelf])).toEqual([
+ [OWNER_DEVICE, false],
+ ['laptop-2', true],
+ ]);
+ });
+
+ it('gives nothing for rejected requests and expired join codes', async () => {
+ const h = await setup();
+ const codes = [];
+ for (let i = 0; i < 2; i++) {
+ codes.push((await api(h.base, 'POST', '/api/device-link/relay/admin/join-codes', { credential: h.ownerCredential })).json.code);
+ }
+ const body = { deviceId: 'phone-x', deviceName: 'Phone', accountUserId: OWNER_USER, ...deviceKeys(h, 'phone-x') };
+ const submitted = await api(h.base, 'POST', '/api/device-link/relay/pair', { body: { ...body, code: codes[0] } });
+ await api(h.base, 'POST', `/api/device-link/relay/admin/pair-requests/${submitted.json.requestId}/reject`, {
+ credential: h.ownerCredential,
+ });
+ const polled = await api(h.base, 'GET', `/api/device-link/relay/pair/${submitted.json.requestId}`, {
+ headers: { 'x-cindy-relay-poll-token': submitted.json.pollToken },
+ });
+ expect(polled.json).toEqual({ status: 'rejected' });
+
+ h.clock.now += 11 * 60 * 1000;
+ const expired = await api(h.base, 'POST', '/api/device-link/relay/pair', { body: { ...body, code: codes[1] } });
+ expect(expired.status).toBe(403);
+ const devices = await api(h.base, 'GET', '/api/device-link/devices', { credential: h.ownerCredential });
+ expect(devices.json.devices).toHaveLength(1);
+ });
+
+ it('lets only the owner manage the relay and disconnects removed devices for good', async () => {
+ const h = await setup();
+ const memberA = await pair(h, 'member-a');
+ const memberB = await pair(h, 'member-b');
+ for (const [method, pathname] of [
+ ['POST', '/api/device-link/relay/admin/join-codes'],
+ ['GET', '/api/device-link/relay/admin/pair-requests'],
+ ['GET', '/api/device-link/relay/admin/status'],
+ ['DELETE', '/api/device-link/devices/member-b'],
+ ['DELETE', `/api/device-link/devices/${OWNER_DEVICE}`],
+ ]) {
+ expect((await api(h.base, method, pathname, { credential: memberA })).status).toBe(403);
+ }
+
+ const socketB = await connect(h, memberB, false);
+ const removed = await api(h.base, 'DELETE', '/api/device-link/devices/member-b', { credential: h.ownerCredential });
+ expect(removed.json).toEqual({ deviceId: 'member-b', deleted: true });
+ expect((await socketB.closed).code).toBe(4410);
+ expect(await upgradeStatus(h.base, `CindyRelay ${memberB}`)).toBe(401);
+ // 成员可以让自己退出。
+ expect((await api(h.base, 'DELETE', '/api/device-link/devices/member-a', { credential: memberA })).status).toBe(200);
+ });
+
+ it('keeps credentials and device names across a restart', async () => {
+ const h = await setup();
+ const member = await pair(h, 'member-p');
+ await api(h.base, 'PATCH', '/api/device-link/devices/member-p', { credential: h.ownerCredential, body: { name: 'Work phone' } });
+ await h.restart();
+ const devices = await api(h.base, 'GET', '/api/device-link/devices', { credential: member });
+ expect(devices.status).toBe(200);
+ expect(devices.json.devices.find((d: { deviceId: string }) => d.deviceId === 'member-p').name).toBe('Work phone');
+ });
+});
+
+describe('joining through the shared client helpers (Desktop / Mobile path)', () => {
+ const relayFetch: RelayFetch = (url, init) => fetch(url, init);
+ const device = { deviceId: 'phone-j', deviceName: 'Phone', platform: 'ios', appVersion: '1.0.0', accountUserId: OWNER_USER };
+
+ async function joinLink(h: Harness, ownerPublicKey = h.ownerKey.publicKey) {
+ const code = (await api(h.base, 'POST', '/api/device-link/relay/admin/join-codes', { credential: h.ownerCredential })).json.code;
+ const pairSecret = createRelayPairSecret(crypto);
+ return parseRelayJoinLink(buildRelayJoinLink({ baseUrl: h.base, code, ownerPublicKey, pairSecret, app: 'cindycn' }))!;
+ }
+
+ /** 主人电脑的同意动作:签发证书并同意。 */
+ async function approveAsOwner(h: Harness, requestId: string, deviceId: string) {
+ const pending = await api(h.base, 'GET', '/api/device-link/relay/admin/pair-requests', { credential: h.ownerCredential });
+ const request = pending.json.requests.find((r: { requestId: string }) => r.requestId === requestId);
+ await api(h.base, 'POST', `/api/device-link/relay/admin/pair-requests/${requestId}/approve`, {
+ credential: h.ownerCredential,
+ body: { cert: memberCert(h, deviceId, request.publicKey) },
+ });
+ }
+
+ it('joins after approval, reports typed errors, and tells members when the relay is retired', async () => {
+ const h = await setup();
+ const info = await fetchRelayInfo(relayFetch, h.base);
+ expect(info.name).toBe('Test relay');
+
+ const link = await joinLink(h);
+ const identity = createRelayJoinIdentity(crypto, link, info.relayId, device.deviceId);
+ const signed = { ...device, publicKey: identity.publicKey, proof: identity.proof };
+ await expect(submitRelayPairRequest(relayFetch, link, { ...signed, accountUserId: 'other' })).rejects.toMatchObject({
+ code: 'ACCOUNT_MISMATCH',
+ });
+ const request = await submitRelayPairRequest(relayFetch, link, signed);
+ const approval = waitForRelayApproval(relayFetch, link, request);
+ await approveAsOwner(h, request.requestId, device.deviceId);
+ const result = await approval;
+ expect(result.deviceId).toBe('phone-j');
+ const cert = acceptRelayDeviceCert(crypto, link, { relayId: info.relayId, deviceId: 'phone-j', publicKey: identity.publicKey, cert: result.cert });
+ const certs = await fetchRelayCertificates(relayFetch, h.base, result.credential);
+ expect(certs).toContainEqual(cert);
+ await expect(submitRelayPairRequest(relayFetch, link, signed)).rejects.toMatchObject({ code: 'CODE_INVALID' });
+
+ const declinedLink = await joinLink(h);
+ const declined = await submitRelayPairRequest(relayFetch, declinedLink, { ...signed, deviceId: 'phone-k' });
+ const declinedWait = waitForRelayApproval(relayFetch, declinedLink, declined);
+ await api(h.base, 'POST', `/api/device-link/relay/admin/pair-requests/${declined.requestId}/reject`, { credential: h.ownerCredential });
+ await expect(declinedWait).rejects.toBeInstanceOf(RelayJoinError);
+ await expect(declinedWait).rejects.toMatchObject({ code: 'REJECTED' });
+
+ // 主人停用中转:成员收到 4410(客户端据此停止重连并提示「中转已停用」)。
+ const member = await connect(h, result.credential, false);
+ await h.handle.close({ retire: true });
+ expect((await member.closed).code).toBe(4410);
+ });
+
+ it('refuses a certificate from an owner other than the one in the join link', async () => {
+ // 链接里的主人公钥与中转实际的主人不符(例如中转被换成别人的):证书核对失败,不能加入。
+ const h = await setup();
+ const info = await fetchRelayInfo(relayFetch, h.base);
+ const link = await joinLink(h, createRelaySigningKey(crypto).publicKey);
+ const identity = createRelayJoinIdentity(crypto, link, info.relayId, device.deviceId);
+ const request = await submitRelayPairRequest(relayFetch, link, { ...device, publicKey: identity.publicKey, proof: identity.proof });
+ const approval = waitForRelayApproval(relayFetch, link, request);
+ await approveAsOwner(h, request.requestId, device.deviceId);
+ const result = await approval;
+ expect(() =>
+ acceptRelayDeviceCert(crypto, link, { relayId: info.relayId, deviceId: device.deviceId, publicKey: identity.publicKey, cert: result.cert }),
+ ).toThrow(expect.objectContaining({ code: 'OWNER_MISMATCH' }));
+ });
+
+ it('reports an unreachable address without hanging', async () => {
+ const h = await setup();
+ const port = h.handle.port;
+ await h.handle.close();
+ await expect(fetchRelayInfo(relayFetch, `http://127.0.0.1:${port}`)).rejects.toMatchObject({ code: 'UNREACHABLE' });
+ });
+});
+
+describe('media relay', () => {
+ it('stores uploads behind signed links and serves byte ranges', async () => {
+ const h = await setup();
+ const bytes = Buffer.from('hello self-hosted relay');
+ const put = await api(h.base, 'POST', '/api/device-link/media/presign-put', {
+ credential: h.ownerCredential,
+ body: { size: bytes.length, ext: 'txt', contentType: 'text/plain' },
+ });
+ expect(put.status).toBe(200);
+ const uploaded = await fetch(put.json.putUrl, {
+ method: 'PUT',
+ headers: { 'Content-Type': 'text/plain', 'x-oss-object-acl': 'private' },
+ body: bytes,
+ });
+ expect(uploaded.status).toBe(200);
+ // 签名地址只能上传一次。
+ expect((await fetch(put.json.putUrl, { method: 'PUT', body: bytes })).status).toBe(409);
+
+ const get = await api(h.base, 'POST', '/api/device-link/media/presign-get', { credential: h.ownerCredential, body: { key: put.json.key } });
+ const full = await fetch(get.json.getUrl);
+ expect(full.headers.get('content-type')).toBe('text/plain');
+ expect(await full.text()).toBe('hello self-hosted relay');
+ const ranged = await fetch(get.json.getUrl, { headers: { Range: 'bytes=6-9' } });
+ expect(ranged.status).toBe(206);
+ expect(ranged.headers.get('content-range')).toBe(`bytes 6-9/${bytes.length}`);
+ expect(await ranged.text()).toBe('self');
+
+ const tampered = new URL(get.json.getUrl);
+ tampered.searchParams.set('sig', '0'.repeat(64));
+ expect((await fetch(tampered)).status).toBe(403);
+ h.clock.now += 2 * HOUR;
+ expect((await fetch(get.json.getUrl)).status).toBe(403);
+ });
+
+ it('rejects uploads larger than the presigned size without keeping a partial object', async () => {
+ const h = await setup();
+ const put = await api(h.base, 'POST', '/api/device-link/media/presign-put', {
+ credential: h.ownerCredential,
+ body: { size: 4, ext: 'bin', contentType: 'application/octet-stream' },
+ });
+ const res = await fetch(put.json.putUrl, { method: 'PUT', body: Buffer.alloc(16) });
+ expect(res.status).toBe(413);
+ const stored = (await readdir(path.join(h.dataDir, 'media'))).filter((name) => !name.startsWith('.'));
+ expect(stored).toEqual([]);
+ const get = await api(h.base, 'POST', '/api/device-link/media/presign-get', { credential: h.ownerCredential, body: { key: put.json.key } });
+ expect(get.status).toBe(404);
+ });
+});
diff --git a/packages/device-link-relay/src/acme.ts b/packages/device-link-relay/src/acme.ts
new file mode 100644
index 0000000000..2e63ba6c0d
--- /dev/null
+++ b/packages/device-link-relay/src/acme.ts
@@ -0,0 +1,239 @@
+/**
+ * 最小 ACME 客户端(RFC 8555),只做中转需要的一件事:用 http-01 验证给一个域名或 IP 申请证书。
+ *
+ * - 账户密钥 ECDSA P-256(ES256);证书私钥每次新生成,不复用。
+ * - IP 证书使用 Let's Encrypt 的 `shortlived` 配置(有效期约 6 天,由证书管理定时续期);
+ * 域名证书用 CA 默认配置。
+ * - 验证文件由调用方经 80 端口提供(`challenges`:token → key authorization)。
+ */
+import { createHash, generateKeyPairSync, sign, X509Certificate, type KeyObject } from 'node:crypto';
+import { buildCsr, type CertificateIdentifier } from './csr';
+
+export const LETS_ENCRYPT_DIRECTORY = 'https://acme-v02.api.letsencrypt.org/directory';
+
+const VALIDATION_TIMEOUT_MS = 3 * 60 * 1000;
+const POLL_INTERVAL_MS = 2_000;
+
+export class AcmeError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = 'AcmeError';
+ }
+}
+
+interface Directory {
+ newNonce: string;
+ newAccount: string;
+ newOrder: string;
+ meta?: { profiles?: Record<string, unknown> };
+}
+
+interface AcmeResponse {
+ status: number;
+ headers: Headers;
+ body: Record<string, any> | null;
+ text: string;
+}
+
+export interface IssuedCertificate {
+ certPem: string;
+ keyPem: string;
+ notBefore: number;
+ notAfter: number;
+}
+
+export interface AcmeClientOptions {
+ directoryUrl: string;
+ accountKey: KeyObject;
+ /** 上次注册得到的账户地址;没有时自动注册(同一密钥重复注册会拿回同一账户)。 */
+ accountUrl?: string | null;
+ fetchImpl?: typeof fetch;
+ sleep?: (ms: number) => Promise<void>;
+ log?: (message: string) => void;
+}
+
+function b64url(data: Buffer | string): string {
+ return Buffer.from(data).toString('base64url');
+}
+
+function problem(body: Record<string, any> | null, fallback: string): string {
+ if (!body) return fallback;
+ const subproblems = Array.isArray(body.subproblems)
+ ? body.subproblems.map((p: Record<string, unknown>) => p.detail).filter(Boolean).join('; ')
+ : '';
+ return [body.type, body.detail, subproblems].filter(Boolean).join(': ') || fallback;
+}
+
+export function firstCertificate(pemChain: string): string {
+ const match = /-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/.exec(pemChain);
+ if (!match) throw new AcmeError('the CA returned no certificate');
+ return match[0];
+}
+
+export function certificateValidity(pemChain: string): { notBefore: number; notAfter: number } {
+ const cert = new X509Certificate(firstCertificate(pemChain));
+ return { notBefore: Date.parse(cert.validFrom), notAfter: Date.parse(cert.validTo) };
+}
+
+export function createAccountKey(): KeyObject {
+ return generateKeyPairSync('ec', { namedCurve: 'P-256' }).privateKey;
+}
+
+export class AcmeClient {
+ private readonly fetchImpl: typeof fetch;
+ private readonly sleep: (ms: number) => Promise<void>;
+ private readonly log: (message: string) => void;
+ private readonly jwk: { crv: string; kty: string; x: string; y: string };
+ private directory: Directory | null = null;
+ private nonce: string | null = null;
+ private kid: string | null;
+
+ constructor(private readonly options: AcmeClientOptions) {
+ this.fetchImpl = options.fetchImpl ?? fetch;
+ this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+ this.log = options.log ?? (() => undefined);
+ const jwk = options.accountKey.export({ format: 'jwk' }) as { crv: string; kty: string; x: string; y: string };
+ this.jwk = { crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y };
+ this.kid = options.accountUrl ?? null;
+ }
+
+ get accountUrl(): string | null {
+ return this.kid;
+ }
+
+ /** RFC 7638 JWK 指纹:验证文件内容 = token + "." + 指纹。 */
+ get thumbprint(): string {
+ const { crv, kty, x, y } = this.jwk;
+ return b64url(createHash('sha256').update(JSON.stringify({ crv, kty, x, y })).digest());
+ }
+
+ private async getDirectory(): Promise<Directory> {
+ if (this.directory) return this.directory;
+ const res = await this.fetchImpl(this.options.directoryUrl);
+ const body = (await res.json().catch(() => null)) as Directory | null;
+ if (!res.ok || !body?.newNonce || !body.newAccount || !body.newOrder) {
+ throw new AcmeError(`certificate authority directory unavailable (${res.status})`);
+ }
+ this.directory = body;
+ return body;
+ }
+
+ private async getNonce(): Promise<string> {
+ if (this.nonce) {
+ const nonce = this.nonce;
+ this.nonce = null;
+ return nonce;
+ }
+ const res = await this.fetchImpl((await this.getDirectory()).newNonce, { method: 'HEAD' });
+ const nonce = res.headers.get('replay-nonce');
+ if (!nonce) throw new AcmeError('certificate authority returned no nonce');
+ return nonce;
+ }
+
+ /** 带 JWS 签名的 POST;payload 为 undefined 时是 POST-as-GET。 */
+ private async post(url: string, payload: unknown, options: { useJwk?: boolean; accept?: string } = {}): Promise<AcmeResponse> {
+ for (let attempt = 0; attempt < 3; attempt++) {
+ const header = {
+ alg: 'ES256',
+ nonce: await this.getNonce(),
+ url,
+ ...(options.useJwk || !this.kid ? { jwk: this.jwk } : { kid: this.kid }),
+ };
+ const protectedPart = b64url(JSON.stringify(header));
+ const payloadPart = payload === undefined ? '' : b64url(JSON.stringify(payload));
+ const signature = sign('sha256', Buffer.from(`${protectedPart}.${payloadPart}`), {
+ key: this.options.accountKey,
+ dsaEncoding: 'ieee-p1363',
+ });
+ const res = await this.fetchImpl(url, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/jose+json', ...(options.accept ? { Accept: options.accept } : {}) },
+ body: JSON.stringify({ protected: protectedPart, payload: payloadPart, signature: b64url(signature) }),
+ });
+ this.nonce = res.headers.get('replay-nonce');
+ const text = await res.text();
+ let body: Record<string, any> | null = null;
+ try {
+ body = JSON.parse(text) as Record<string, any>;
+ } catch {
+ body = null;
+ }
+ if (res.status === 400 && body?.type === 'urn:ietf:params:acme:error:badNonce') continue;
+ return { status: res.status, headers: res.headers, body, text };
+ }
+ throw new AcmeError('certificate authority kept rejecting nonces');
+ }
+
+ private async ensureAccount(): Promise<void> {
+ if (this.kid) return;
+ const directory = await this.getDirectory();
+ const res = await this.post(directory.newAccount, { termsOfServiceAgreed: true }, { useJwk: true });
+ const location = res.headers.get('location');
+ if ((res.status !== 200 && res.status !== 201) || !location) {
+ throw new AcmeError(`account registration failed: ${problem(res.body, String(res.status))}`);
+ }
+ this.kid = location;
+ }
+
+ private async pollUntil(url: string, done: (body: Record<string, any>) => boolean, what: string): Promise<Record<string, any>> {
+ const deadline = Date.now() + VALIDATION_TIMEOUT_MS;
+ for (;;) {
+ const res = await this.post(url, undefined);
+ if (res.status >= 400 || !res.body) throw new AcmeError(`${what} failed: ${problem(res.body, String(res.status))}`);
+ if (res.body.status === 'invalid') {
+ const failed = Array.isArray(res.body.challenges)
+ ? res.body.challenges.find((c: Record<string, any>) => c.error)?.error
+ : res.body.error;
+ throw new AcmeError(`${what} failed: ${problem(failed ?? null, 'invalid')}`);
+ }
+ if (done(res.body)) return res.body;
+ if (Date.now() > deadline) throw new AcmeError(`${what} timed out`);
+ const retryAfter = Number(res.headers.get('retry-after'));
+ await this.sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 10) * 1000 : POLL_INTERVAL_MS);
+ }
+ }
+
+ async obtainCertificate(identifier: CertificateIdentifier, challenges: Map<string, string>): Promise<IssuedCertificate> {
+ const directory = await this.getDirectory();
+ await this.ensureAccount();
+ const profiles = directory.meta?.profiles ?? {};
+ const profile = identifier.type === 'ip' && 'shortlived' in profiles ? 'shortlived' : undefined;
+ this.log(`requesting a certificate for ${identifier.type} ${identifier.value}${profile ? ` (profile ${profile})` : ''}`);
+ const order = await this.post(directory.newOrder, { identifiers: [identifier], ...(profile ? { profile } : {}) });
+ const orderUrl = order.headers.get('location');
+ if (order.status !== 201 || !order.body || !orderUrl) {
+ throw new AcmeError(`order failed: ${problem(order.body, String(order.status))}`);
+ }
+
+ for (const authzUrl of order.body.authorizations as string[]) {
+ const authz = await this.post(authzUrl, undefined);
+ if (authz.body?.status === 'valid') continue;
+ const challenge = (authz.body?.challenges as Array<Record<string, string>> | undefined)?.find((c) => c.type === 'http-01');
+ if (!challenge) throw new AcmeError('the certificate authority offered no http-01 validation');
+ challenges.set(challenge.token, `${challenge.token}.${this.thumbprint}`);
+ try {
+ const triggered = await this.post(challenge.url, {});
+ if (triggered.status >= 400) throw new AcmeError(`validation failed: ${problem(triggered.body, String(triggered.status))}`);
+ await this.pollUntil(authzUrl, (body) => body.status === 'valid', 'validation');
+ } finally {
+ challenges.delete(challenge.token);
+ }
+ }
+
+ await this.pollUntil(orderUrl, (body) => body.status === 'ready' || body.status === 'valid', 'order');
+ const certKey = generateKeyPairSync('ec', { namedCurve: 'P-256' }).privateKey;
+ const finalized = await this.post(order.body.finalize as string, { csr: b64url(buildCsr(certKey, identifier)) });
+ if (finalized.status >= 400) throw new AcmeError(`finalize failed: ${problem(finalized.body, String(finalized.status))}`);
+ const ready = await this.pollUntil(orderUrl, (body) => body.status === 'valid' && Boolean(body.certificate), 'issuance');
+ const download = await this.post(ready.certificate as string, undefined, { accept: 'application/pem-certificate-chain' });
+ if (download.status !== 200 || !download.text.includes('BEGIN CERTIFICATE')) {
+ throw new AcmeError(`certificate download failed (${download.status})`);
+ }
+ const certPem = download.text;
+ return {
+ certPem,
+ keyPem: certKey.export({ type: 'pkcs8', format: 'pem' }) as string,
+ ...certificateValidity(certPem),
+ };
+ }
+}
diff --git a/packages/device-link-relay/src/certificates.ts b/packages/device-link-relay/src/certificates.ts
new file mode 100644
index 0000000000..39bd87ea90
--- /dev/null
+++ b/packages/device-link-relay/src/certificates.ts
@@ -0,0 +1,197 @@
+/**
+ * 服务器上独立运行时的自动证书:申请、保存、到期前续期,并在 80 端口提供验证文件。
+ *
+ * - 证书与私钥存在数据目录 `tls/`(权限 0600);ACME 账户密钥存在 `acme/`。
+ * - 剩余有效期不足总时长的 1/3 就续期(6 天的 IP 证书约剩 2 天时续,90 天的域名证书约剩 30 天时续)。
+ * - 当前状态写进 `status.json`,部署方经 SSH 读取它报告进度与失败原因(不含任何秘密)。
+ */
+import { createPrivateKey, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { createServer, type Server } from 'node:http';
+import path from 'node:path';
+import { AcmeClient, certificateValidity, createAccountKey, LETS_ENCRYPT_DIRECTORY, type IssuedCertificate } from './acme';
+import type { CertificateIdentifier } from './csr';
+import type { RelayLogger } from './logger';
+
+export const STATUS_FILE = 'status.json';
+const CHALLENGE_PREFIX = '/.well-known/acme-challenge/';
+
+export interface TlsMaterial {
+ cert: string;
+ key: string;
+ notBefore: number;
+ notAfter: number;
+}
+
+export type CertificateState = 'requesting' | 'ready' | 'failed';
+
+export interface CertificateManagerOptions {
+ dataDir: string;
+ identifier: CertificateIdentifier;
+ directoryUrl?: string;
+ logger: RelayLogger;
+ now?: () => number;
+ fetchImpl?: typeof fetch;
+}
+
+async function writeFileAtomically(file: string, content: string, mode: number): Promise<void> {
+ await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+ const tmp = `${file}.${randomUUID()}.tmp`;
+ try {
+ await writeFile(tmp, content, { mode, flag: 'wx' });
+ await rename(tmp, file);
+ } catch (error) {
+ await rm(tmp, { force: true }).catch(() => undefined);
+ throw error;
+ }
+}
+
+async function readOptional(file: string): Promise<string | null> {
+ try {
+ return await readFile(file, 'utf8');
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+ throw error;
+ }
+}
+
+export class CertificateManager {
+ /** 当前待验证的 token → key authorization,由 80 端口服务读取。 */
+ readonly challenges = new Map<string, string>();
+ private readonly now: () => number;
+ private readonly directoryUrl: string;
+
+ constructor(private readonly options: CertificateManagerOptions) {
+ this.now = options.now ?? Date.now;
+ this.directoryUrl = options.directoryUrl ?? LETS_ENCRYPT_DIRECTORY;
+ }
+
+ private file(...parts: string[]): string {
+ return path.join(this.options.dataDir, ...parts);
+ }
+
+ /** 读取已保存的证书;名字不符或已过期时返回 null。 */
+ async load(): Promise<TlsMaterial | null> {
+ const [cert, key, metaText] = await Promise.all([
+ readOptional(this.file('tls', 'cert.pem')),
+ readOptional(this.file('tls', 'key.pem')),
+ readOptional(this.file('tls', 'meta.json')),
+ ]);
+ if (!cert || !key || !metaText) return null;
+ try {
+ const meta = JSON.parse(metaText) as { identifier?: CertificateIdentifier };
+ if (meta.identifier?.type !== this.options.identifier.type || meta.identifier.value !== this.options.identifier.value) {
+ return null;
+ }
+ createPrivateKey(key);
+ const validity = certificateValidity(cert);
+ if (validity.notAfter <= this.now()) return null;
+ return { cert, key, ...validity };
+ } catch {
+ return null;
+ }
+ }
+
+ needsRenewal(material: TlsMaterial): boolean {
+ const lifetime = material.notAfter - material.notBefore;
+ return material.notAfter - this.now() < lifetime / 3;
+ }
+
+ /** 走一遍 ACME 申请新证书并保存;失败时写入状态再抛出。 */
+ async obtain(): Promise<TlsMaterial> {
+ await this.writeStatus('requesting');
+ try {
+ const issued = await this.issue();
+ await writeFileAtomically(this.file('tls', 'key.pem'), issued.keyPem, 0o600);
+ await writeFileAtomically(this.file('tls', 'cert.pem'), issued.certPem, 0o600);
+ await writeFileAtomically(
+ this.file('tls', 'meta.json'),
+ JSON.stringify({ identifier: this.options.identifier, directoryUrl: this.directoryUrl }),
+ 0o600,
+ );
+ await this.writeStatus('ready', { notAfter: new Date(issued.notAfter).toISOString() });
+ this.options.logger.info('certificate issued', { notAfter: new Date(issued.notAfter).toISOString() });
+ return { cert: issued.certPem, key: issued.keyPem, notBefore: issued.notBefore, notAfter: issued.notAfter };
+ } catch (error) {
+ const message = error instanceof Error ? error.message : 'unknown error';
+ await this.writeStatus('failed', { error: message.slice(0, 500) });
+ this.options.logger.error('certificate request failed', { reason: message.slice(0, 500) });
+ throw error;
+ }
+ }
+
+ private async issue(): Promise<IssuedCertificate> {
+ const keyFile = this.file('acme', 'account-key.pem');
+ const accountFile = this.file('acme', 'account.json');
+ let keyPem = await readOptional(keyFile);
+ if (!keyPem) {
+ keyPem = createAccountKey().export({ type: 'pkcs8', format: 'pem' }) as string;
+ await writeFileAtomically(keyFile, keyPem, 0o600);
+ }
+ let accountUrl: string | null = null;
+ try {
+ const saved = JSON.parse((await readOptional(accountFile)) ?? '{}') as { directoryUrl?: string; accountUrl?: string };
+ if (saved.directoryUrl === this.directoryUrl && typeof saved.accountUrl === 'string') accountUrl = saved.accountUrl;
+ } catch {
+ accountUrl = null;
+ }
+ const client = new AcmeClient({
+ directoryUrl: this.directoryUrl,
+ accountKey: createPrivateKey(keyPem),
+ accountUrl,
+ fetchImpl: this.options.fetchImpl,
+ log: (message) => this.options.logger.info(message),
+ });
+ try {
+ return await client.obtainCertificate(this.options.identifier, this.challenges);
+ } finally {
+ if (client.accountUrl && client.accountUrl !== accountUrl) {
+ await writeFileAtomically(accountFile, JSON.stringify({ directoryUrl: this.directoryUrl, accountUrl: client.accountUrl }), 0o600);
+ }
+ }
+ }
+
+ async writeStatus(state: CertificateState, extra: { notAfter?: string; error?: string } = {}): Promise<void> {
+ const status = {
+ certificate: { state, identifier: this.options.identifier.value, ...extra, updatedAt: new Date(this.now()).toISOString() },
+ };
+ await writeFileAtomically(this.file(STATUS_FILE), JSON.stringify(status), 0o600).catch(() => undefined);
+ }
+}
+
+/** 80 端口:只回答 ACME 验证文件,其余请求提示使用 https。 */
+export async function startChallengeServer(options: {
+ host: string;
+ port: number;
+ challenges: Map<string, string>;
+}): Promise<{ close(): Promise<void> }> {
+ const server: Server = createServer((req, res) => {
+ const pathname = new URL(req.url ?? '/', 'http://relay.invalid').pathname;
+ if (req.method === 'GET' && pathname.startsWith(CHALLENGE_PREFIX)) {
+ const answer = options.challenges.get(pathname.slice(CHALLENGE_PREFIX.length));
+ if (answer) {
+ res.writeHead(200, { 'Content-Type': 'text/plain', 'Content-Length': String(Buffer.byteLength(answer)) });
+ res.end(answer);
+ return;
+ }
+ }
+ res.writeHead(404, { 'Content-Type': 'text/plain' });
+ res.end('This is a Cindy relay. Use https.\n');
+ });
+ server.headersTimeout = 10_000;
+ server.requestTimeout = 10_000;
+ await new Promise<void>((resolve, reject) => {
+ server.once('error', reject);
+ server.listen(options.port, options.host, () => {
+ server.off('error', reject);
+ resolve();
+ });
+ });
+ return {
+ close: () =>
+ new Promise<void>((resolve) => {
+ server.close(() => resolve());
+ server.closeAllConnections?.();
+ }),
+ };
+}
diff --git a/packages/device-link-relay/src/cli.ts b/packages/device-link-relay/src/cli.ts
new file mode 100644
index 0000000000..95c7544848
--- /dev/null
+++ b/packages/device-link-relay/src/cli.ts
@@ -0,0 +1,203 @@
+/**
+ * 独立运行入口(服务器部署与本机调试共用):
+ *
+ * relay init --data <目录> --name <中转名> --owner-user <账号ID> --owner-device <设备ID>
+ * --owner-device-name <设备名> --owner-credential-hash <SHA-256>
+ * --relay-id <UUID> --owner-public-key <公钥> --owner-cert <证书 JSON 的 base64url>
+ * relay serve --data <目录> [--host 127.0.0.1] [--port 47820]
+ * [--tls-cert <PEM> --tls-key <PEM>] [--public-url <https://...>] [--trust-proxy]
+ * [--acme-identifier <域名或IP> [--acme-http-port 80] [--acme-directory <URL>]]
+ *
+ * `--acme-identifier`:自动向 Let's Encrypt 申请并续期证书(http-01 验证走 `--acme-http-port`),
+ * 拿到证书后才开始提供 HTTPS;申请失败按退避重试,状态写进数据目录的 status.json。
+ * relay --version
+ *
+ * stdout 每行一个 JSON 事件(initialized / listening / error),供部署器解析;
+ * 日志写 stderr,不含凭证、加入码与签名地址。
+ */
+import { CertificateManager, startChallengeServer, type TlsMaterial } from './certificates';
+import { identifierFor } from './csr';
+import { RelayError } from './errors';
+import type { RelayLogger } from './logger';
+import { readTlsFiles, startRelayServer } from './server';
+import { initializeRelay } from './store';
+import { RELAY_VERSION } from './version';
+
+const BOOLEAN_FLAGS = new Set(['trust-proxy']);
+/** 首次申请证书失败后的重试间隔(Let's Encrypt 对同一名字每小时只允许几次失败验证)。 */
+const ACME_RETRY_DELAYS_MS = [60_000, 5 * 60_000, 15 * 60_000, 30 * 60_000, 60 * 60_000];
+const RENEWAL_CHECK_MS = 60 * 60 * 1000;
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function parsePort(value: string | undefined, fallback: number, name: string): number {
+ const port = value === undefined ? fallback : Number(value);
+ if (!Number.isInteger(port) || port < 0 || port > 65535) throw new RelayError('BAD_REQUEST', `invalid --${name}`);
+ return port;
+}
+
+/** 自动证书:先在 80 端口提供验证,拿到(或读到)有效证书后返回;之后由调用方定时续期。 */
+async function prepareAcme(flags: Map<string, string>, dataDir: string, host: string) {
+ const identifier = identifierFor(required(flags, 'acme-identifier'));
+ const manager = new CertificateManager({
+ dataDir,
+ identifier,
+ directoryUrl: flags.get('acme-directory'),
+ logger: stderrLogger,
+ });
+ await startChallengeServer({ host, port: parsePort(flags.get('acme-http-port'), 80, 'acme-http-port'), challenges: manager.challenges });
+ let material: TlsMaterial | null = await manager.load();
+ if (material && manager.needsRenewal(material)) material = null;
+ for (let attempt = 0; !material; attempt++) {
+ emit({ event: 'certificate', status: 'requesting', identifier: identifier.value });
+ try {
+ material = await manager.obtain();
+ } catch (error) {
+ const delay = ACME_RETRY_DELAYS_MS[Math.min(attempt, ACME_RETRY_DELAYS_MS.length - 1)];
+ emit({ event: 'certificate', status: 'failed', retryInMs: delay, message: error instanceof Error ? error.message : 'unknown' });
+ // 证书还没到手但旧证书仍有效:先用旧的服务,后台继续申请。
+ const previous = await manager.load();
+ if (previous) {
+ material = previous;
+ break;
+ }
+ await sleep(delay);
+ }
+ }
+ await manager.writeStatus('ready', { notAfter: new Date(material.notAfter).toISOString() });
+ return { manager, material };
+}
+
+function parseArgs(argv: string[]): { command: string | undefined; flags: Map<string, string> } {
+ const flags = new Map<string, string>();
+ let command: string | undefined;
+ for (let i = 0; i < argv.length; i++) {
+ const arg = argv[i];
+ if (!arg.startsWith('--')) {
+ if (command) throw new RelayError('BAD_REQUEST', `unexpected argument: ${arg}`);
+ command = arg;
+ continue;
+ }
+ const name = arg.slice(2);
+ if (name === 'version' || BOOLEAN_FLAGS.has(name)) {
+ flags.set(name, 'true');
+ continue;
+ }
+ const value = argv[i + 1];
+ if (value === undefined || value.startsWith('--')) throw new RelayError('BAD_REQUEST', `missing value for --${name}`);
+ flags.set(name, value);
+ i++;
+ }
+ return { command, flags };
+}
+
+function required(flags: Map<string, string>, name: string): string {
+ const value = flags.get(name);
+ if (!value) throw new RelayError('BAD_REQUEST', `--${name} is required`);
+ return value;
+}
+
+/** JSON 参数以 base64url 传入,避免经 SSH 拼命令时的引号转义。 */
+function parseJsonArg(value: string, name: string): unknown {
+ try {
+ return JSON.parse(Buffer.from(value, 'base64url').toString('utf8')) as unknown;
+ } catch {
+ throw new RelayError('BAD_REQUEST', `--${name} must be base64url-encoded JSON`);
+ }
+}
+
+function emit(event: Record<string, unknown>): void {
+ process.stdout.write(`${JSON.stringify(event)}\n`);
+}
+
+const stderrLogger: RelayLogger = {
+ info: (message, fields) => process.stderr.write(`${JSON.stringify({ level: 'info', message, ...fields })}\n`),
+ warn: (message, fields) => process.stderr.write(`${JSON.stringify({ level: 'warn', message, ...fields })}\n`),
+ error: (message, fields) => process.stderr.write(`${JSON.stringify({ level: 'error', message, ...fields })}\n`),
+};
+
+async function main(): Promise<void> {
+ const { command, flags } = parseArgs(process.argv.slice(2));
+ if (flags.has('version')) {
+ emit({ event: 'version', relayVersion: RELAY_VERSION });
+ return;
+ }
+ if (command === 'init') {
+ const { relayId } = await initializeRelay({
+ dataDir: required(flags, 'data'),
+ name: required(flags, 'name'),
+ ownerUserId: required(flags, 'owner-user'),
+ ownerDeviceId: required(flags, 'owner-device'),
+ ownerDeviceName: required(flags, 'owner-device-name'),
+ ownerCredentialHash: required(flags, 'owner-credential-hash'),
+ relayId: required(flags, 'relay-id'),
+ ownerPublicKey: required(flags, 'owner-public-key'),
+ ownerCert: parseJsonArg(required(flags, 'owner-cert'), 'owner-cert'),
+ });
+ emit({ event: 'initialized', relayId });
+ return;
+ }
+ if (command === 'serve') {
+ const certPath = flags.get('tls-cert');
+ const keyPath = flags.get('tls-key');
+ if (Boolean(certPath) !== Boolean(keyPath)) {
+ throw new RelayError('BAD_REQUEST', '--tls-cert and --tls-key must be given together');
+ }
+ if (flags.has('acme-identifier') && certPath) {
+ throw new RelayError('BAD_REQUEST', '--acme-identifier cannot be combined with --tls-cert');
+ }
+ const port = parsePort(flags.get('port'), 47820, 'port');
+ const dataDir = required(flags, 'data');
+ const host = flags.get('host') ?? '127.0.0.1';
+ const acme = flags.has('acme-identifier') ? await prepareAcme(flags, dataDir, host) : null;
+ let material = acme?.material ?? null;
+ const handle = await startRelayServer({
+ dataDir,
+ host,
+ port,
+ tls: material ? { cert: material.cert, key: material.key } : certPath && keyPath ? await readTlsFiles(certPath, keyPath) : undefined,
+ publicUrl: flags.get('public-url'),
+ trustProxyHeaders: flags.has('trust-proxy'),
+ logger: stderrLogger,
+ certificateExpiresAt: () => (material ? new Date(material.notAfter).toISOString() : null),
+ });
+ emit({ event: 'listening', relayId: handle.relayId, url: handle.localUrl, port: handle.port });
+ if (acme) {
+ let renewing = false;
+ const timer = setInterval(() => {
+ if (renewing || !material || !acme.manager.needsRenewal(material)) return;
+ renewing = true;
+ void acme.manager
+ .obtain()
+ .then((next) => {
+ material = next;
+ handle.updateTls({ cert: next.cert, key: next.key });
+ })
+ .catch(() => {
+ // 已记录;旧证书仍有效时下个小时再试。
+ })
+ .finally(() => {
+ renewing = false;
+ });
+ }, RENEWAL_CHECK_MS);
+ timer.unref?.();
+ }
+ const shutdown = () => {
+ void handle.close().then(() => process.exit(0));
+ };
+ process.once('SIGINT', shutdown);
+ process.once('SIGTERM', shutdown);
+ return;
+ }
+ throw new RelayError('BAD_REQUEST', 'usage: relay <init|serve> [options] | relay --version');
+}
+
+main().catch((error: unknown) => {
+ const relayError = error instanceof RelayError ? error : null;
+ emit({
+ event: 'error',
+ code: relayError?.code ?? 'INTERNAL',
+ message: relayError?.message ?? (error instanceof Error ? error.message : 'unknown error'),
+ });
+ process.exitCode = 1;
+});
diff --git a/packages/device-link-relay/src/credentials.ts b/packages/device-link-relay/src/credentials.ts
new file mode 100644
index 0000000000..ce65cf3a08
--- /dev/null
+++ b/packages/device-link-relay/src/credentials.ts
@@ -0,0 +1,51 @@
+/**
+ * 中转凭证与一次性秘密。
+ *
+ * - 设备凭证只用于连接这一个自建中转,与 Cindy 账号 token 无关;中转只保存 SHA-256。
+ * - 主人电脑在本机生成自己的凭证,交给中转的只有哈希(Cindy 内运行与 SSH 部署两种方式一致)。
+ * - 握手与 REST 都用 `Authorization: CindyRelay <凭证>`;不接受 `Bearer`,避免客户端误把账号
+ * token 发过来时被当成可用凭证继续流转。
+ */
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+export const RELAY_AUTH_SCHEME = 'CindyRelay';
+
+/** 32 字节随机数,base64url。设备凭证、加入码、轮询口令、签名密钥共用同一生成方式。 */
+export function createSecret(bytes = 32): string {
+ return randomBytes(bytes).toString('base64url');
+}
+
+export function hashSecret(secret: string): string {
+ return createHash('sha256').update(secret, 'utf8').digest('hex');
+}
+
+/** 供主人电脑 / 测试生成一份设备凭证:明文只留在调用方,哈希交给中转。 */
+export function createDeviceCredential(): { credential: string; credentialHash: string } {
+ const credential = createSecret();
+ return { credential, credentialHash: hashSecret(credential) };
+}
+
+/** 解析 `Authorization: CindyRelay <凭证>`;其它方案或格式一律视为未认证。 */
+export function parseRelayAuthorization(header: string | string[] | undefined): string | null {
+ if (typeof header !== 'string') return null;
+ const match = /^CindyRelay ([A-Za-z0-9_-]{16,256})$/.exec(header.trim());
+ return match ? match[1] : null;
+}
+
+export function isSha256Hex(value: unknown): value is string {
+ return typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
+}
+
+export function hmacHex(key: string, message: string): string {
+ return createHmac('sha256', key).update(message, 'utf8').digest('hex');
+}
+
+export function safeEqualHex(a: string, b: string): boolean {
+ if (a.length !== b.length || !/^[0-9a-f]*$/.test(a) || !/^[0-9a-f]*$/.test(b)) return false;
+ return timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+}
+
+/** 4 位核对码:只供主人与申请设备肉眼核对,不参与鉴权。 */
+export function createVerifyCode(): string {
+ return String(randomBytes(2).readUInt16BE(0) % 10_000).padStart(4, '0');
+}
diff --git a/packages/device-link-relay/src/csr.ts b/packages/device-link-relay/src/csr.ts
new file mode 100644
index 0000000000..2df0aa9fdb
--- /dev/null
+++ b/packages/device-link-relay/src/csr.ts
@@ -0,0 +1,77 @@
+/**
+ * 证书签名请求(PKCS#10 CSR)的最小 DER 编码:只含一个名字(域名或 IP)与 ECDSA P-256 公钥。
+ * node:crypto 能生成密钥和签名,但不能生成 CSR;为一个结构引入整套 ASN.1 库不值得。
+ */
+import { createPublicKey, sign, type KeyObject } from 'node:crypto';
+import { isIP, isIPv4, isIPv6 } from 'node:net';
+
+export interface CertificateIdentifier {
+ type: 'ip' | 'dns';
+ value: string;
+}
+
+/** 访问地址是 IP 时签 IP 证书,否则签域名证书。 */
+export function identifierFor(address: string): CertificateIdentifier {
+ return isIP(address) ? { type: 'ip', value: address } : { type: 'dns', value: address.toLowerCase() };
+}
+
+function encodeLength(length: number): Buffer {
+ if (length < 0x80) return Buffer.from([length]);
+ const bytes: number[] = [];
+ for (let n = length; n > 0; n >>= 8) bytes.unshift(n & 0xff);
+ return Buffer.from([0x80 | bytes.length, ...bytes]);
+}
+
+function tlv(tag: number, ...parts: Buffer[]): Buffer {
+ const content = Buffer.concat(parts);
+ return Buffer.concat([Buffer.from([tag]), encodeLength(content.length), content]);
+}
+
+const sequence = (...parts: Buffer[]) => tlv(0x30, ...parts);
+const set = (...parts: Buffer[]) => tlv(0x31, ...parts);
+
+function objectId(dotted: string): Buffer {
+ const [first, second, ...rest] = dotted.split('.').map(Number);
+ const bytes = [first * 40 + second];
+ for (const value of rest) {
+ const chunk: number[] = [value & 0x7f];
+ for (let n = value >> 7; n > 0; n >>= 7) chunk.unshift(0x80 | (n & 0x7f));
+ bytes.push(...chunk);
+ }
+ return tlv(0x06, Buffer.from(bytes));
+}
+
+function ipBytes(address: string): Buffer {
+ if (isIPv4(address)) return Buffer.from(address.split('.').map(Number));
+ if (!isIPv6(address)) throw new Error('invalid IP address');
+ const [head, tail] = address.includes('::') ? address.split('::') : [address, undefined];
+ const headParts = head ? head.split(':') : [];
+ const tailParts = tail ? tail.split(':') : [];
+ const missing = 8 - headParts.length - tailParts.length;
+ const groups = [...headParts, ...Array<string>(tail === undefined ? 0 : missing).fill('0'), ...tailParts];
+ const out = Buffer.alloc(16);
+ groups.forEach((group, index) => out.writeUInt16BE(parseInt(group || '0', 16), index * 2));
+ return out;
+}
+
+const OID_COMMON_NAME = '2.5.4.3';
+const OID_SUBJECT_ALT_NAME = '2.5.29.17';
+const OID_EXTENSION_REQUEST = '1.2.840.113549.1.9.14';
+const OID_ECDSA_WITH_SHA256 = '1.2.840.10045.4.3.2';
+
+/** 用证书私钥(ECDSA P-256)签出 DER 编码的 CSR。 */
+export function buildCsr(privateKey: KeyObject, identifier: CertificateIdentifier): Buffer {
+ const spki = createPublicKey(privateKey).export({ type: 'spki', format: 'der' });
+ // IP 证书不带 CN(CA 会忽略或拒绝);域名证书 CN 与 SAN 一致。
+ const subject =
+ identifier.type === 'dns'
+ ? sequence(set(sequence(objectId(OID_COMMON_NAME), tlv(0x0c, Buffer.from(identifier.value, 'utf8')))))
+ : sequence();
+ const generalName =
+ identifier.type === 'ip' ? tlv(0x87, ipBytes(identifier.value)) : tlv(0x82, Buffer.from(identifier.value, 'ascii'));
+ const subjectAltName = sequence(objectId(OID_SUBJECT_ALT_NAME), tlv(0x04, sequence(generalName)));
+ const extensionRequest = sequence(objectId(OID_EXTENSION_REQUEST), set(sequence(subjectAltName)));
+ const info = sequence(tlv(0x02, Buffer.from([0])), subject, spki, tlv(0xa0, extensionRequest));
+ const signature = sign('sha256', info, privateKey);
+ return sequence(info, sequence(objectId(OID_ECDSA_WITH_SHA256)), tlv(0x03, Buffer.from([0]), signature));
+}
diff --git a/packages/device-link-relay/src/errors.ts b/packages/device-link-relay/src/errors.ts
new file mode 100644
index 0000000000..b7b3db7248
--- /dev/null
+++ b/packages/device-link-relay/src/errors.ts
@@ -0,0 +1,53 @@
+/**
+ * REST 错误:响应体沿用官方 relay 的 `{error:{code,message}}`。
+ *
+ * 凭证无效用专属的 `RELAY_CREDENTIAL_INVALID`,刻意不用 `UNAUTHORIZED` / `INVALID_TOKEN` /
+ * `TOKEN_EXPIRED`:Desktop `serverApiFetch` 收到这三种 401 会刷新并可能登出 Cindy 账号,
+ * 自建中转的凭证失效不能牵连官方登录态。
+ */
+export type RelayErrorCode =
+ | 'BAD_REQUEST'
+ | 'RELAY_CREDENTIAL_INVALID'
+ | 'FORBIDDEN'
+ | 'NOT_FOUND'
+ | 'CONFLICT'
+ | 'PAYLOAD_TOO_LARGE'
+ | 'RATE_LIMITED'
+ | 'NOT_SUPPORTED'
+ | 'ACCOUNT_MISMATCH'
+ | 'QUOTA_EXCEEDED'
+ | 'ALREADY_INITIALIZED'
+ | 'NOT_INITIALIZED'
+ | 'STATE_INVALID'
+ | 'INTERNAL';
+
+const HTTP_STATUS: Record<RelayErrorCode, number> = {
+ BAD_REQUEST: 400,
+ RELAY_CREDENTIAL_INVALID: 401,
+ FORBIDDEN: 403,
+ NOT_FOUND: 404,
+ CONFLICT: 409,
+ PAYLOAD_TOO_LARGE: 413,
+ RATE_LIMITED: 429,
+ NOT_SUPPORTED: 501,
+ ACCOUNT_MISMATCH: 403,
+ QUOTA_EXCEEDED: 507,
+ ALREADY_INITIALIZED: 409,
+ NOT_INITIALIZED: 500,
+ STATE_INVALID: 500,
+ INTERNAL: 500,
+};
+
+export class RelayError extends Error {
+ constructor(
+ readonly code: RelayErrorCode,
+ message: string,
+ ) {
+ super(message);
+ this.name = 'RelayError';
+ }
+
+ get status(): number {
+ return HTTP_STATUS[this.code];
+ }
+}
diff --git a/packages/device-link-relay/src/hub.ts b/packages/device-link-relay/src/hub.ts
new file mode 100644
index 0000000000..cd82371d50
--- /dev/null
+++ b/packages/device-link-relay/src/hub.ts
@@ -0,0 +1,378 @@
+/**
+ * WebSocket 中转:与官方 relay 相同的线协议(`@cindy/device-link-protocol` v1)。
+ *
+ * 只理解连接层帧与路由头;隧道层 payload(invoke 的 channel/args、push 内容)原样转发,不解析。
+ * 与官方行为对齐的要点:
+ * - `hello` 必须是第一帧;回 `hello-ack`,deviceId 来自凭证绑定的设备,不信任客户端自报。
+ * - 转发时覆写 `src`;目标不在线回 `DEVICE_OFFLINE`,发起控制但目标关闭了「允许被控」回 `REMOTE_DISABLED`。
+ * - 单帧超过 2 MiB 回 `PAYLOAD_TOO_LARGE`,不断开;协议版本不符用 4400 关闭(reason 含 version)。
+ * - 同一设备新连接顶替旧连接(4409);设备被移除用 4410(客户端停止重连);接收方积压过多用 1013。
+ * - hello-ack 不声明任何能力:不收 notify,不转发跨账号(sharedTask / providerShare)帧。
+ * - 设备签名 `auth` 原样转发;中转无法伪造它(收件设备用主人签发的证书核对)。
+ */
+import {
+ CONTROL_KINDS,
+ MAX_FRAME_BYTES,
+ PROTOCOL_VERSION,
+ ROUTED_KINDS,
+ type DeviceInfo,
+ type Envelope,
+ type HelloAckPayload,
+ type PresenceSnapshot,
+ type RelayErrorCode,
+} from '@cindy/device-link-protocol';
+import WebSocket from 'ws';
+import type { RelayLogger } from './logger';
+import type { RelayStore, StoredDevice } from './store';
+
+export const CLOSE_VERSION_MISMATCH = 4400;
+export const CLOSE_HELLO_REQUIRED = 4401;
+export const CLOSE_REPLACED = 4409;
+export const CLOSE_DEVICE_REMOVED = 4410;
+export const CLOSE_TOO_MANY_CONNECTIONS = 4429;
+export const CLOSE_CONGESTED = 1013;
+/** 设备签名字段的长度上限(正常约 160 字符)。 */
+const MAX_AUTH_CHARS = 512;
+
+export interface HubLimits {
+ helloTimeoutMs: number;
+ idleTimeoutMs: number;
+ maxConnections: number;
+ maxConnectionsPerDevice: number;
+ maxBufferedBytes: number;
+}
+
+export const DEFAULT_HUB_LIMITS: HubLimits = {
+ helloTimeoutMs: 15_000,
+ idleTimeoutMs: 90_000,
+ maxConnections: 256,
+ maxConnectionsPerDevice: 4,
+ maxBufferedBytes: 16 * 1024 * 1024,
+};
+
+interface Connection {
+ ws: WebSocket;
+ deviceId: string;
+ ready: boolean;
+ remoteControlEnabled: boolean;
+ busy: boolean;
+ lastInboundAt: number;
+ helloTimer: ReturnType<typeof setTimeout> | null;
+}
+
+function displayName(device: StoredDevice): string {
+ return device.customName ?? device.reportedName;
+}
+
+function boundedString(value: unknown, max: number): string | null {
+ if (typeof value !== 'string') return null;
+ const trimmed = value.trim();
+ return trimmed && trimmed.length <= max ? trimmed : null;
+}
+
+function sanitizeDeviceInfo(value: unknown): DeviceInfo | null {
+ if (!value || typeof value !== 'object') return null;
+ const raw = value as Record<string, unknown>;
+ const info: DeviceInfo = {};
+ const cpuLabel = boundedString(raw.cpuLabel, 128);
+ const osVersion = boundedString(raw.osVersion, 128);
+ const modelLabel = boundedString(raw.modelLabel, 128);
+ if (cpuLabel) info.cpuLabel = cpuLabel;
+ if (osVersion) info.osVersion = osVersion;
+ if (modelLabel) info.modelLabel = modelLabel;
+ if (typeof raw.memoryGb === 'number' && Number.isFinite(raw.memoryGb) && raw.memoryGb >= 0) {
+ info.memoryGb = raw.memoryGb;
+ }
+ return Object.keys(info).length > 0 ? info : null;
+}
+
+export class Hub {
+ private readonly active = new Map<string, Connection>();
+ private readonly connections = new Set<Connection>();
+ private readonly idleTimer: ReturnType<typeof setInterval>;
+
+ constructor(
+ private readonly store: RelayStore,
+ private readonly ownerUserId: string,
+ private readonly now: () => number,
+ private readonly logger: RelayLogger,
+ private readonly limits: HubLimits = DEFAULT_HUB_LIMITS,
+ ) {
+ this.idleTimer = setInterval(() => this.closeIdle(), Math.min(30_000, limits.idleTimeoutMs));
+ this.idleTimer.unref?.();
+ }
+
+ get onlineCount(): number {
+ return this.active.size;
+ }
+
+ isOnline(deviceId: string): boolean {
+ return this.active.has(deviceId);
+ }
+
+ connectionCountFor(deviceId: string): number {
+ let count = 0;
+ for (const conn of this.connections) if (conn.deviceId === deviceId) count++;
+ return count;
+ }
+
+ /** 接管一条已通过凭证认证的 WebSocket。 */
+ attach(ws: WebSocket, device: StoredDevice): void {
+ if (
+ this.connections.size >= this.limits.maxConnections ||
+ this.connectionCountFor(device.deviceId) >= this.limits.maxConnectionsPerDevice
+ ) {
+ ws.close(CLOSE_TOO_MANY_CONNECTIONS, 'too many connections');
+ return;
+ }
+ const conn: Connection = {
+ ws,
+ deviceId: device.deviceId,
+ ready: false,
+ remoteControlEnabled: false,
+ busy: false,
+ lastInboundAt: this.now(),
+ helloTimer: null,
+ };
+ conn.helloTimer = setTimeout(() => {
+ if (!conn.ready) ws.close(CLOSE_HELLO_REQUIRED, 'hello required');
+ }, this.limits.helloTimeoutMs);
+ conn.helloTimer.unref?.();
+ this.connections.add(conn);
+ ws.on('error', () => undefined);
+ ws.on('message', (data, isBinary) => {
+ conn.lastInboundAt = this.now();
+ const buffer = Array.isArray(data)
+ ? Buffer.concat(data)
+ : Buffer.isBuffer(data)
+ ? data
+ : Buffer.from(data);
+ if (isBinary) {
+ this.sendError(conn, undefined, 'BAD_REQUEST', 'binary frames are not supported');
+ return;
+ }
+ this.handleFrame(conn, buffer);
+ });
+ ws.on('close', () => this.detach(conn));
+ }
+
+ private detach(conn: Connection): void {
+ if (conn.helloTimer) clearTimeout(conn.helloTimer);
+ this.connections.delete(conn);
+ if (this.active.get(conn.deviceId) !== conn) return;
+ this.active.delete(conn.deviceId);
+ const device = this.store.update(conn.deviceId, { lastSeenAt: this.now() });
+ if (device) this.broadcast(this.presenceOf(device));
+ }
+
+ private handleFrame(conn: Connection, buffer: Buffer): void {
+ let env: Envelope;
+ try {
+ const parsed = JSON.parse(buffer.toString('utf8')) as unknown;
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not an object');
+ env = parsed as Envelope;
+ } catch {
+ this.sendError(conn, undefined, 'BAD_REQUEST', 'frame is not a JSON object');
+ return;
+ }
+ const id = typeof env.id === 'string' ? env.id : undefined;
+ if (buffer.byteLength > MAX_FRAME_BYTES) {
+ this.sendError(conn, id, 'PAYLOAD_TOO_LARGE', 'frame exceeds the size limit', env.dst);
+ return;
+ }
+ if (env.v !== PROTOCOL_VERSION) {
+ conn.ws.close(CLOSE_VERSION_MISMATCH, 'protocol version mismatch');
+ return;
+ }
+ if (!conn.ready) {
+ if (env.kind === 'hello') this.handleHello(conn, env.payload);
+ else conn.ws.close(CLOSE_HELLO_REQUIRED, 'hello required');
+ return;
+ }
+ switch (env.kind) {
+ case 'ping':
+ this.send(conn, { v: PROTOCOL_VERSION, kind: 'pong' });
+ return;
+ case 'presence-set':
+ this.handlePresenceSet(conn, env.payload);
+ return;
+ case 'notify':
+ // 未声明 notify 能力:与旧版官方 relay 一致,静默丢弃。
+ return;
+ default:
+ if (ROUTED_KINDS.has(env.kind)) this.route(conn, env, id);
+ else this.sendError(conn, id, 'BAD_REQUEST', 'unexpected frame kind');
+ }
+ }
+
+ private handleHello(conn: Connection, payload: unknown): void {
+ const device = this.store.get(conn.deviceId);
+ const hello = payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : null;
+ const deviceName = boundedString(hello?.deviceName, 256);
+ const platform = boundedString(hello?.platform, 32);
+ const appVersion = boundedString(hello?.appVersion, 64);
+ if (!device || !hello || !deviceName || !platform || !appVersion ||
+ typeof hello.remoteControlEnabled !== 'boolean' || typeof hello.busy !== 'boolean') {
+ conn.ws.close(CLOSE_VERSION_MISMATCH, 'invalid hello');
+ return;
+ }
+ if (conn.helloTimer) clearTimeout(conn.helloTimer);
+ conn.helloTimer = null;
+ const previous = this.active.get(conn.deviceId);
+ if (previous && previous !== conn) {
+ // 先摘掉旧连接,它的 close 回调不能把新连接的在线状态改成离线。
+ this.active.delete(conn.deviceId);
+ previous.ws.close(CLOSE_REPLACED, 'replaced by a newer connection');
+ }
+ conn.ready = true;
+ conn.remoteControlEnabled = hello.remoteControlEnabled;
+ conn.busy = hello.busy;
+ this.active.set(conn.deviceId, conn);
+ const updated = this.store.update(conn.deviceId, {
+ reportedName: deviceName,
+ platform,
+ appVersion,
+ deviceInfo: sanitizeDeviceInfo(hello.deviceInfo),
+ lastSeenAt: this.now(),
+ })!;
+ const ack: HelloAckPayload = {
+ serverProtocolVersion: PROTOCOL_VERSION,
+ deviceId: conn.deviceId,
+ userId: this.ownerUserId,
+ capabilities: [],
+ };
+ this.send(conn, { v: PROTOCOL_VERSION, kind: 'hello-ack', payload: ack });
+ for (const [deviceId] of this.active) {
+ if (deviceId === conn.deviceId) continue;
+ const other = this.store.get(deviceId);
+ if (other) this.send(conn, { v: PROTOCOL_VERSION, kind: 'presence-changed', payload: this.presenceOf(other) });
+ }
+ this.broadcast(this.presenceOf(updated));
+ }
+
+ private handlePresenceSet(conn: Connection, payload: unknown): void {
+ const patch = payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : {};
+ if (typeof patch.remoteControlEnabled === 'boolean') conn.remoteControlEnabled = patch.remoteControlEnabled;
+ if (typeof patch.busy === 'boolean') conn.busy = patch.busy;
+ const device = this.store.get(conn.deviceId);
+ if (device) this.broadcast(this.presenceOf(device));
+ }
+
+ private route(conn: Connection, env: Envelope, id: string | undefined): void {
+ if (env.sharedTask !== undefined || env.providerShare !== undefined) {
+ this.sendError(conn, id, 'BAD_REQUEST', 'cross-account frames are not available on a self-hosted relay', env.dst);
+ return;
+ }
+ const dst = typeof env.dst === 'string' ? env.dst : undefined;
+ const target = dst ? this.active.get(dst) : undefined;
+ if (!target) {
+ this.sendError(conn, id, 'DEVICE_OFFLINE', 'target device is offline', dst);
+ return;
+ }
+ if (CONTROL_KINDS.has(env.kind) && !target.remoteControlEnabled) {
+ this.sendError(conn, id, 'REMOTE_DISABLED', 'target device does not allow remote control', dst);
+ return;
+ }
+ const forwarded: Envelope & { auth?: unknown } = { v: PROTOCOL_VERSION, kind: env.kind, src: conn.deviceId, dst };
+ if (id !== undefined) forwarded.id = id;
+ if (env.payload !== undefined) forwarded.payload = env.payload;
+ // 设备签名(docs/self-hosted-relay-plan.md §16)原样转给收件设备,由它核对;中转不解析。
+ const auth = (env as Envelope & { auth?: unknown }).auth;
+ if (auth !== undefined) {
+ if (!auth || typeof auth !== 'object' || Array.isArray(auth) || JSON.stringify(auth).length > MAX_AUTH_CHARS) {
+ this.sendError(conn, id, 'BAD_REQUEST', 'invalid frame signature field', dst);
+ return;
+ }
+ forwarded.auth = auth;
+ }
+ if (!this.send(target, forwarded)) {
+ this.sendError(conn, id, 'DEVICE_OFFLINE', 'target device is not accepting frames', dst);
+ }
+ }
+
+ presenceOf(device: StoredDevice): PresenceSnapshot {
+ const conn = this.active.get(device.deviceId);
+ return {
+ deviceId: device.deviceId,
+ online: Boolean(conn),
+ deviceName: displayName(device),
+ selfName: device.reportedName,
+ deviceInfo: device.deviceInfo,
+ platform: device.platform ?? '',
+ appVersion: device.appVersion ?? '',
+ lastSeenAt: conn ? this.now() : device.lastSeenAt ?? 0,
+ remoteControlEnabled: conn?.remoteControlEnabled ?? false,
+ busy: conn?.busy ?? false,
+ };
+ }
+
+ /** REST `/devices` 的设备视图(与官方 `DeviceView` 同形)。 */
+ deviceView(device: StoredDevice, selfId: string) {
+ const conn = this.active.get(device.deviceId);
+ const lastSeenAt = conn ? this.now() : device.lastSeenAt;
+ return {
+ deviceId: device.deviceId,
+ name: displayName(device),
+ selfName: device.reportedName,
+ deviceInfo: device.deviceInfo,
+ platform: device.platform,
+ appVersion: device.appVersion,
+ lastSeenAt: lastSeenAt === null ? null : new Date(lastSeenAt).toISOString(),
+ online: Boolean(conn),
+ busy: conn?.busy ?? false,
+ remoteControlEnabled: conn?.remoteControlEnabled ?? false,
+ isSelf: device.deviceId === selfId,
+ };
+ }
+
+ /** 设备档案变化(改名)后通知所有在线设备。 */
+ announce(device: StoredDevice): void {
+ this.broadcast(this.presenceOf(device));
+ }
+
+ /** 移除设备:断开它的所有连接,并广播离线。 */
+ disconnectDevice(device: StoredDevice, code: number, reason: string): void {
+ for (const conn of [...this.connections]) {
+ if (conn.deviceId !== device.deviceId) continue;
+ if (this.active.get(conn.deviceId) === conn) this.active.delete(conn.deviceId);
+ conn.ws.close(code, reason);
+ }
+ this.broadcast({ ...this.presenceOf(device), online: false, remoteControlEnabled: false, busy: false });
+ }
+
+ closeAll(code: number, reason: string): void {
+ clearInterval(this.idleTimer);
+ for (const conn of [...this.connections]) conn.ws.close(code, reason);
+ }
+
+ private closeIdle(): void {
+ const now = this.now();
+ for (const conn of this.connections) {
+ if (now - conn.lastInboundAt > this.limits.idleTimeoutMs) conn.ws.terminate();
+ }
+ }
+
+ private broadcast(snapshot: PresenceSnapshot): void {
+ for (const conn of this.active.values()) {
+ this.send(conn, { v: PROTOCOL_VERSION, kind: 'presence-changed', payload: snapshot });
+ }
+ }
+
+ private sendError(conn: Connection, id: string | undefined, code: RelayErrorCode, message: string, dst?: string): void {
+ const frame: Envelope = { v: PROTOCOL_VERSION, kind: 'relay-error', payload: { code, message, ...(dst ? { dst } : {}) } };
+ if (id !== undefined) frame.id = id;
+ this.send(conn, frame);
+ }
+
+ /** 发送失败或接收方积压过多时返回 false;积压的连接用 1013 关闭,由客户端退避重连。 */
+ private send(conn: Connection, frame: Envelope): boolean {
+ if (conn.ws.readyState !== WebSocket.OPEN) return false;
+ if (conn.ws.bufferedAmount > this.limits.maxBufferedBytes) {
+ this.logger.warn('closing congested connection');
+ conn.ws.close(CLOSE_CONGESTED, 'relay congested');
+ return false;
+ }
+ conn.ws.send(JSON.stringify(frame));
+ return true;
+ }
+}
diff --git a/packages/device-link-relay/src/index.ts b/packages/device-link-relay/src/index.ts
new file mode 100644
index 0000000000..2b6b4f2bde
--- /dev/null
+++ b/packages/device-link-relay/src/index.ts
@@ -0,0 +1,11 @@
+/**
+ * @cindy/device-link-relay
+ * ---------------------------------------------------------------------------
+ * 自建中转服务内核。方案见 docs/self-hosted-relay-plan.md。
+ */
+export { createDeviceCredential, hashSecret, RELAY_AUTH_SCHEME } from './credentials';
+export { RelayError, type RelayErrorCode } from './errors';
+export type { RelayLogger } from './logger';
+export { initializeRelay, type InitializeRelayInput } from './store';
+export { readTlsFiles, startRelayServer, type RelayServerHandle, type RelayServerOptions } from './server';
+export { RELAY_VERSION } from './version';
diff --git a/packages/device-link-relay/src/logger.ts b/packages/device-link-relay/src/logger.ts
new file mode 100644
index 0000000000..02cf3de2df
--- /dev/null
+++ b/packages/device-link-relay/src/logger.ts
@@ -0,0 +1,15 @@
+/**
+ * 中转日志接口。调用方只传固定的事件描述和非敏感字段:
+ * 不写凭证、加入码、轮询口令、签名地址、帧内容或设备名以外的用户数据。
+ */
+export interface RelayLogger {
+ info(message: string, fields?: Record<string, string | number | boolean>): void;
+ warn(message: string, fields?: Record<string, string | number | boolean>): void;
+ error(message: string, fields?: Record<string, string | number | boolean>): void;
+}
+
+export const silentLogger: RelayLogger = {
+ info() {},
+ warn() {},
+ error() {},
+};
diff --git a/packages/device-link-relay/src/media.ts b/packages/device-link-relay/src/media.ts
new file mode 100644
index 0000000000..a3833defa0
--- /dev/null
+++ b/packages/device-link-relay/src/media.ts
@@ -0,0 +1,314 @@
+/**
+ * 中转自带的媒体存储,替代官方 relay 的 OSS 预签名。
+ *
+ * 客户端契约(Desktop `device-link/mediaTransfer.ts`、Mobile 附件上传)不变:
+ * - `presign-put` 返回 `putUrl`,客户端对它 `PUT` 原始字节(带 Content-Type,可能带 OSS 专用头,忽略即可);
+ * - `presign-get` 返回 `getUrl`,客户端 `GET`,可带单段 `Range`,期望 200/206 与 Content-Range;
+ * - 两种地址都是带签名、短期有效的地址,不需要再带凭证。
+ *
+ * 文件放在中转数据目录下,创建 24 小时后清理;单对象与总量都有上限。上传在声明大小内流式写入
+ * 临时文件,完整后原子改名,中途失败不留半个对象。
+ */
+import { randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Transform } from 'node:stream';
+import { hmacHex, safeEqualHex } from './credentials';
+import { RelayError } from './errors';
+
+export const BLOB_PATH_PREFIX = '/api/device-link/relay/blob/';
+
+const KEY_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.[a-z0-9]{1,16}$/;
+const EXT_PATTERN = /^[a-z0-9]{1,16}$/;
+const META_SUFFIX = '.meta.json';
+const PART_PREFIX = '.part-';
+
+export interface MediaLimits {
+ /** 单对象上限,与客户端 `MAX_MEDIA_BYTES`(2 GiB)一致。 */
+ maxObjectBytes: number;
+ /** 所有对象加上已签发未完成的上传的总量上限。 */
+ maxTotalBytes: number;
+ /** 对象保留时长。 */
+ objectTtlMs: number;
+ /** 预签名地址有效期。 */
+ urlTtlMs: number;
+}
+
+export const DEFAULT_MEDIA_LIMITS: MediaLimits = {
+ maxObjectBytes: 2 * 1024 * 1024 * 1024,
+ maxTotalBytes: 10 * 1024 * 1024 * 1024,
+ objectTtlMs: 24 * 60 * 60 * 1000,
+ urlTtlMs: 60 * 60 * 1000,
+};
+
+interface ObjectMeta {
+ size: number;
+ contentType: string;
+ createdAt: number;
+}
+
+interface Reservation {
+ size: number;
+ contentType: string;
+ expiresAt: number;
+}
+
+export interface PresignPutInput {
+ size?: unknown;
+ ext?: unknown;
+ contentType?: unknown;
+ sharedTaskId?: unknown;
+}
+
+function normalizeContentType(value: unknown): string | null {
+ if (typeof value !== 'string') return null;
+ const trimmed = value.trim();
+ if (!trimmed || trimmed.length > 255 || /[\r\n]/.test(trimmed)) return null;
+ return trimmed;
+}
+
+type ByteRange = { start: number; end: number };
+
+/** 单段 Range;多段或无法解析时返回 'ignore'(按整文件 200 返回),越界返回 'unsatisfiable'。 */
+function parseRange(header: string | undefined, size: number): ByteRange | 'ignore' | 'unsatisfiable' {
+ if (!header) return 'ignore';
+ const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+ if (!match) return 'ignore';
+ const [, rawStart, rawEnd] = match;
+ if (!rawStart && !rawEnd) return 'ignore';
+ if (size === 0) return 'unsatisfiable';
+ if (!rawStart) {
+ const suffix = Number(rawEnd);
+ if (suffix === 0) return 'unsatisfiable';
+ return { start: Math.max(0, size - suffix), end: size - 1 };
+ }
+ const start = Number(rawStart);
+ const end = rawEnd ? Math.min(Number(rawEnd), size - 1) : size - 1;
+ if (start >= size || end < start) return 'unsatisfiable';
+ return { start, end };
+}
+
+export class MediaStore {
+ private usedBytes = 0;
+ private readonly reservations = new Map<string, Reservation>();
+
+ constructor(
+ private readonly dir: string,
+ private readonly signingKey: string,
+ private readonly limits: MediaLimits,
+ private readonly now: () => number,
+ ) {}
+
+ async init(): Promise<void> {
+ await mkdir(this.dir, { recursive: true, mode: 0o700 });
+ this.usedBytes = 0;
+ for (const name of await readdir(this.dir)) {
+ if (!name.endsWith(META_SUFFIX)) continue;
+ const meta = await this.readMeta(name.slice(0, -META_SUFFIX.length));
+ if (meta) this.usedBytes += meta.size;
+ }
+ await this.sweep();
+ }
+
+ get stats(): { usedBytes: number; reservedBytes: number } {
+ let reservedBytes = 0;
+ for (const reservation of this.reservations.values()) reservedBytes += reservation.size;
+ return { usedBytes: this.usedBytes, reservedBytes };
+ }
+
+ private sign(op: 'put' | 'get', key: string, exp: number): string {
+ return hmacHex(this.signingKey, `${op}\n${key}\n${exp}`);
+ }
+
+ private signedUrl(baseUrl: string, op: 'put' | 'get', key: string, exp: number): string {
+ const params = new URLSearchParams({ op, exp: String(exp), sig: this.sign(op, key, exp) });
+ return `${baseUrl}${BLOB_PATH_PREFIX}${key}?${params.toString()}`;
+ }
+
+ presignPut(input: PresignPutInput, baseUrl: string): { putUrl: string; key: string; expiresAt: string } {
+ if (input.sharedTaskId !== undefined) {
+ throw new RelayError('NOT_SUPPORTED', 'shared task media is not available on a self-hosted relay');
+ }
+ const size = input.size;
+ if (typeof size !== 'number' || !Number.isSafeInteger(size) || size < 1) {
+ throw new RelayError('BAD_REQUEST', 'size must be a positive integer');
+ }
+ if (size > this.limits.maxObjectBytes) throw new RelayError('PAYLOAD_TOO_LARGE', 'media object is too large');
+ if (typeof input.ext !== 'string' || !EXT_PATTERN.test(input.ext)) {
+ throw new RelayError('BAD_REQUEST', 'invalid extension');
+ }
+ const contentType = normalizeContentType(input.contentType);
+ if (!contentType) throw new RelayError('BAD_REQUEST', 'invalid content type');
+ this.expireReservations();
+ const { usedBytes, reservedBytes } = this.stats;
+ if (usedBytes + reservedBytes + size > this.limits.maxTotalBytes) {
+ throw new RelayError('QUOTA_EXCEEDED', 'relay media storage is full');
+ }
+ const key = `${randomUUID()}.${input.ext}`;
+ const expiresAt = this.now() + this.limits.urlTtlMs;
+ this.reservations.set(key, { size, contentType, expiresAt });
+ return { putUrl: this.signedUrl(baseUrl, 'put', key, expiresAt), key, expiresAt: new Date(expiresAt).toISOString() };
+ }
+
+ async presignGet(key: unknown, baseUrl: string): Promise<{ getUrl: string; expiresAt: string }> {
+ if (typeof key !== 'string' || !KEY_PATTERN.test(key)) throw new RelayError('BAD_REQUEST', 'invalid key');
+ if (!(await this.readMeta(key))) throw new RelayError('NOT_FOUND', 'media object not found');
+ const expiresAt = this.now() + this.limits.urlTtlMs;
+ return { getUrl: this.signedUrl(baseUrl, 'get', key, expiresAt), expiresAt: new Date(expiresAt).toISOString() };
+ }
+
+ async delete(key: unknown): Promise<void> {
+ if (typeof key !== 'string' || !KEY_PATTERN.test(key)) throw new RelayError('BAD_REQUEST', 'invalid key');
+ this.reservations.delete(key);
+ await this.removeObject(key);
+ }
+
+ /** 处理签名地址上的 PUT / GET / HEAD。签名、有效期或 key 不对一律 403,不区分原因。 */
+ async handleBlobRequest(req: IncomingMessage, res: ServerResponse, url: URL): Promise<void> {
+ const key = decodeURIComponent(url.pathname.slice(BLOB_PATH_PREFIX.length));
+ const op = url.searchParams.get('op');
+ const exp = Number(url.searchParams.get('exp'));
+ const sig = url.searchParams.get('sig') ?? '';
+ const method = req.method ?? 'GET';
+ const expectedOp = method === 'PUT' ? 'put' : method === 'GET' || method === 'HEAD' ? 'get' : null;
+ if (
+ !expectedOp ||
+ op !== expectedOp ||
+ !KEY_PATTERN.test(key) ||
+ !Number.isSafeInteger(exp) ||
+ exp < this.now() ||
+ !safeEqualHex(sig, this.sign(expectedOp, key, exp))
+ ) {
+ throw new RelayError('FORBIDDEN', 'invalid or expired media link');
+ }
+ if (expectedOp === 'put') await this.receive(req, res, key);
+ else await this.serve(req, res, key, method === 'HEAD');
+ }
+
+ private async receive(req: IncomingMessage, res: ServerResponse, key: string): Promise<void> {
+ const reservation = this.reservations.get(key);
+ if (!reservation || reservation.expiresAt < this.now()) {
+ throw new RelayError('CONFLICT', 'media link was already used or has expired');
+ }
+ // 一个签名地址只能上传一次:先摘掉预留,失败时也不复用。
+ this.reservations.delete(key);
+ const declared = Number(req.headers['content-length']);
+ if (Number.isFinite(declared) && declared > reservation.size) {
+ throw new RelayError('PAYLOAD_TOO_LARGE', 'upload is larger than the presigned size');
+ }
+ const partPath = path.join(this.dir, `${PART_PREFIX}${key}-${randomUUID()}`);
+ let received = 0;
+ const limiter = new Transform({
+ transform(chunk: Buffer, _encoding, callback) {
+ received += chunk.length;
+ if (received > reservation.size) {
+ callback(new RelayError('PAYLOAD_TOO_LARGE', 'upload is larger than the presigned size'));
+ return;
+ }
+ callback(null, chunk);
+ },
+ });
+ try {
+ await pipeline(req, limiter, createWriteStream(partPath, { flags: 'wx', mode: 0o600 }));
+ if (received === 0) throw new RelayError('BAD_REQUEST', 'empty upload');
+ // 先把数据改名到位,再写 meta:有 meta 才算对象存在,没有 meta 的数据由 sweep 清理。
+ await rename(partPath, this.dataPath(key));
+ const meta: ObjectMeta = { size: received, contentType: reservation.contentType, createdAt: this.now() };
+ await writeFile(this.metaPath(key), JSON.stringify(meta), { mode: 0o600, flag: 'wx' });
+ this.usedBytes += received;
+ } catch (error) {
+ await rm(partPath, { force: true }).catch(() => undefined);
+ await rm(this.dataPath(key), { force: true }).catch(() => undefined);
+ if (error instanceof RelayError) throw error;
+ throw new RelayError('INTERNAL', 'failed to store media object');
+ }
+ res.writeHead(200, { 'Content-Length': '0' });
+ res.end();
+ }
+
+ private async serve(req: IncomingMessage, res: ServerResponse, key: string, headOnly: boolean): Promise<void> {
+ const meta = await this.readMeta(key);
+ if (!meta) throw new RelayError('NOT_FOUND', 'media object not found');
+ const range = parseRange(req.headers.range, meta.size);
+ if (range === 'unsatisfiable') {
+ res.writeHead(416, { 'Content-Range': `bytes */${meta.size}` });
+ res.end();
+ return;
+ }
+ const headers: Record<string, string> = {
+ 'Content-Type': meta.contentType,
+ 'Accept-Ranges': 'bytes',
+ 'Cache-Control': 'private, no-store',
+ };
+ const start = range === 'ignore' ? 0 : range.start;
+ const end = range === 'ignore' ? meta.size - 1 : range.end;
+ headers['Content-Length'] = String(end - start + 1);
+ if (range !== 'ignore') headers['Content-Range'] = `bytes ${start}-${end}/${meta.size}`;
+ res.writeHead(range === 'ignore' ? 200 : 206, headers);
+ if (headOnly) {
+ res.end();
+ return;
+ }
+ await pipeline(createReadStream(this.dataPath(key), { start, end }), res);
+ }
+
+ private expireReservations(): void {
+ const now = this.now();
+ for (const [key, reservation] of this.reservations) {
+ if (reservation.expiresAt < now) this.reservations.delete(key);
+ }
+ }
+
+ /** 清理过期对象与遗留的临时文件。 */
+ async sweep(): Promise<void> {
+ this.expireReservations();
+ const now = this.now();
+ const names = new Set(await readdir(this.dir));
+ for (const name of names) {
+ const full = path.join(this.dir, name);
+ if (name.endsWith(META_SUFFIX)) {
+ const key = name.slice(0, -META_SUFFIX.length);
+ const meta = await this.readMeta(key);
+ if (!meta || now - meta.createdAt > this.limits.objectTtlMs) await this.removeObject(key);
+ continue;
+ }
+ // 上传中的临时文件,以及改名后没来得及写 meta 的数据:超过地址有效期仍无 meta 才清理。
+ const orphanData = KEY_PATTERN.test(name) && !names.has(`${name}${META_SUFFIX}`);
+ if (!name.startsWith(PART_PREFIX) && !orphanData) continue;
+ const info = await stat(full).catch(() => null);
+ if (info && now - info.mtimeMs > this.limits.urlTtlMs) await rm(full, { force: true }).catch(() => undefined);
+ }
+ }
+
+ private dataPath(key: string): string {
+ return path.join(this.dir, key);
+ }
+
+ private metaPath(key: string): string {
+ return path.join(this.dir, `${key}${META_SUFFIX}`);
+ }
+
+ private async readMeta(key: string): Promise<ObjectMeta | null> {
+ try {
+ const meta = JSON.parse(await readFile(this.metaPath(key), 'utf8')) as Partial<ObjectMeta>;
+ if (typeof meta.size !== 'number' || typeof meta.contentType !== 'string' || typeof meta.createdAt !== 'number') {
+ return null;
+ }
+ // meta 在数据改名到位后才写;数据已被删除时视为不存在。
+ const info = await stat(this.dataPath(key)).catch(() => null);
+ return info ? (meta as ObjectMeta) : null;
+ } catch {
+ return null;
+ }
+ }
+
+ private async removeObject(key: string): Promise<void> {
+ const meta = await this.readMeta(key);
+ await rm(this.dataPath(key), { force: true }).catch(() => undefined);
+ await rm(this.metaPath(key), { force: true }).catch(() => undefined);
+ if (meta) this.usedBytes = Math.max(0, this.usedBytes - meta.size);
+ }
+}
diff --git a/packages/device-link-relay/src/pairing.ts b/packages/device-link-relay/src/pairing.ts
new file mode 100644
index 0000000000..9cd72f2759
--- /dev/null
+++ b/packages/device-link-relay/src/pairing.ts
@@ -0,0 +1,271 @@
+/**
+ * 加入流程:主人生成一次性加入码 → 新设备凭加入码提交申请 → 主人在自己的电脑上核对并同意 →
+ * 新设备凭申请时拿到的轮询口令取回凭证(只给一次)。
+ *
+ * - 加入码 256 位随机,只存哈希,10 分钟有效,提交一次即作废。
+ * - 账号不一致直接拒绝(跨账号走共享任务 / 供应商分享);这只防误操作,准入关口是主人同意。
+ * - 设备在取回凭证的那一刻才写入设备档案:同意后没人来取,就不会留下一个没人持有凭证的设备。
+ * - 申请带新设备的签名公钥与配对证明(用加入链接里的配对秘密算出,中转拿不到秘密);主人电脑核对证明后
+ * 签发证书随同意一起交给中转,中转只核对证书确实出自主人、发给的就是申请里这把公钥。
+ * - 全部状态在内存里;中转重启后未完成的申请作废,重新生成加入码即可。
+ */
+import { randomUUID } from 'node:crypto';
+import {
+ createDeviceCredential,
+ createSecret,
+ createVerifyCode,
+ hashSecret,
+ safeEqualHex,
+} from './credentials';
+import { nodeRelayAuthCrypto } from '@cindy/device-link/node-relay-crypto';
+import { isRelayPublicKey, verifyRelayDeviceCert, type RelayDeviceCert } from '@cindy/device-link/relay-auth';
+import { RelayError } from './errors';
+import { DEVICE_ID_PATTERN, normalizeName, type RelayStore, type StoredDevice } from './store';
+
+export const JOIN_CODE_TTL_MS = 10 * 60 * 1000;
+const PAIR_REQUEST_TTL_MS = 10 * 60 * 1000;
+const MAX_ACTIVE_JOIN_CODES = 5;
+const MAX_PENDING_REQUESTS = 5;
+const SUBMIT_WINDOW_MS = 10 * 60 * 1000;
+const MAX_SUBMITS_PER_SOURCE = 20;
+const PROOF_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+
+type PairStatus = 'pending' | 'approved' | 'rejected';
+
+interface PairRequest {
+ requestId: string;
+ pollTokenHash: string;
+ deviceId: string;
+ deviceName: string;
+ platform: string | null;
+ appVersion: string | null;
+ publicKey: string;
+ proof: string;
+ verifyCode: string;
+ createdAt: number;
+ expiresAt: number;
+ status: PairStatus;
+ cert?: RelayDeviceCert;
+}
+
+export interface PairRequestView {
+ requestId: string;
+ deviceId: string;
+ deviceName: string;
+ platform: string | null;
+ appVersion: string | null;
+ /** 新设备的签名公钥与配对证明:主人电脑用加入链接里的配对秘密核对,通过才签发证书。 */
+ publicKey: string;
+ proof: string;
+ verifyCode: string;
+ createdAt: string;
+ expiresAt: string;
+ /** 同一设备之前已加入过(例如重装),同意后旧凭证失效。 */
+ replacesExisting: boolean;
+}
+
+export type PollResult =
+ | { status: 'pending' }
+ | { status: 'rejected' }
+ | { status: 'expired' }
+ | { status: 'approved'; credential: string; deviceId: string; cert: RelayDeviceCert };
+
+function optionalShortString(value: unknown, max: number): string | null {
+ if (value === undefined || value === null) return null;
+ if (typeof value !== 'string' || value.length > max) throw new RelayError('BAD_REQUEST', 'invalid field');
+ return value;
+}
+
+export class Pairing {
+ private readonly joinCodes = new Map<string, number>();
+ private readonly requests = new Map<string, PairRequest>();
+ private readonly waiters = new Map<string, Set<() => void>>();
+ private readonly submitsBySource = new Map<string, number[]>();
+
+ constructor(
+ private readonly store: RelayStore,
+ private readonly now: () => number,
+ private readonly onAdmitted: (device: StoredDevice) => void,
+ ) {}
+
+ createJoinCode(): { code: string; expiresAt: string } {
+ this.expire();
+ if (this.joinCodes.size >= MAX_ACTIVE_JOIN_CODES) {
+ throw new RelayError('RATE_LIMITED', 'too many active join codes');
+ }
+ const code = createSecret();
+ const expiresAt = this.now() + JOIN_CODE_TTL_MS;
+ this.joinCodes.set(hashSecret(code), expiresAt);
+ return { code, expiresAt: new Date(expiresAt).toISOString() };
+ }
+
+ submit(body: Record<string, unknown>, source: string): { requestId: string; pollToken: string; verifyCode: string } {
+ this.expire();
+ this.limitSource(source);
+ const { code, deviceId, accountUserId } = body;
+ const deviceName = normalizeName(body.deviceName);
+ if (typeof code !== 'string' || typeof deviceId !== 'string' || !DEVICE_ID_PATTERN.test(deviceId) || !deviceName) {
+ throw new RelayError('BAD_REQUEST', 'invalid pairing request');
+ }
+ if (!isRelayPublicKey(body.publicKey) || typeof body.proof !== 'string' || !PROOF_PATTERN.test(body.proof)) {
+ throw new RelayError('BAD_REQUEST', 'this Cindy version is too old to join a signed relay');
+ }
+ const platform = optionalShortString(body.platform, 32);
+ const appVersion = optionalShortString(body.appVersion, 64);
+ const codeHash = hashSecret(code);
+ const codeExpiresAt = this.joinCodes.get(codeHash);
+ if (codeExpiresAt === undefined || codeExpiresAt < this.now()) {
+ throw new RelayError('FORBIDDEN', 'invalid or expired join code');
+ }
+ // 账号不对时保留加入码,让正确的设备还能用。
+ if (accountUserId !== this.store.ownerUserId) {
+ throw new RelayError('ACCOUNT_MISMATCH', 'this relay belongs to another Cindy account');
+ }
+ if (this.store.get(deviceId)?.role === 'owner') {
+ throw new RelayError('FORBIDDEN', 'the owner device is already part of this relay');
+ }
+ const pending = [...this.requests.values()].filter((request) => request.status === 'pending');
+ if (pending.length >= MAX_PENDING_REQUESTS) throw new RelayError('RATE_LIMITED', 'too many pending requests');
+
+ this.joinCodes.delete(codeHash);
+ const pollToken = createSecret();
+ const createdAt = this.now();
+ const request: PairRequest = {
+ requestId: randomUUID(),
+ pollTokenHash: hashSecret(pollToken),
+ deviceId,
+ deviceName,
+ platform,
+ appVersion,
+ publicKey: body.publicKey,
+ proof: body.proof,
+ verifyCode: createVerifyCode(),
+ createdAt,
+ expiresAt: createdAt + PAIR_REQUEST_TTL_MS,
+ status: 'pending',
+ };
+ this.requests.set(request.requestId, request);
+ return { requestId: request.requestId, pollToken, verifyCode: request.verifyCode };
+ }
+
+ listPending(): PairRequestView[] {
+ this.expire();
+ return [...this.requests.values()]
+ .filter((request) => request.status === 'pending')
+ .map((request) => ({
+ requestId: request.requestId,
+ deviceId: request.deviceId,
+ deviceName: request.deviceName,
+ platform: request.platform,
+ appVersion: request.appVersion,
+ publicKey: request.publicKey,
+ proof: request.proof,
+ verifyCode: request.verifyCode,
+ createdAt: new Date(request.createdAt).toISOString(),
+ expiresAt: new Date(request.expiresAt).toISOString(),
+ replacesExisting: this.store.get(request.deviceId) !== undefined,
+ }));
+ }
+
+ /** 同意时必须附主人为申请里这把公钥签发的证书。 */
+ decide(requestId: string, approve: boolean, rawCert?: unknown): void {
+ this.expire();
+ const request = this.requests.get(requestId);
+ if (!request || request.status !== 'pending') throw new RelayError('NOT_FOUND', 'pairing request not found');
+ if (approve) {
+ const cert = verifyRelayDeviceCert(nodeRelayAuthCrypto, this.store.ownerPublicKey, this.store.relayId, rawCert);
+ if (!cert || cert.deviceId !== request.deviceId || cert.publicKey !== request.publicKey || cert.role !== 'member') {
+ throw new RelayError('BAD_REQUEST', 'approval requires a certificate for the requesting device');
+ }
+ request.cert = cert;
+ }
+ request.status = approve ? 'approved' : 'rejected';
+ // 同意后给取回留一个完整的有效期,避免主人刚好在快过期时点同意。
+ request.expiresAt = this.now() + PAIR_REQUEST_TTL_MS;
+ this.wake(requestId);
+ }
+
+ /** 长轮询:等到主人决定或超时。凭证只返回一次,随后申请即被删除。 */
+ async poll(requestId: string, pollToken: unknown, waitMs: number): Promise<PollResult> {
+ const request = this.authorizePoll(requestId, pollToken);
+ if (!request) return { status: 'expired' };
+ if (request.status === 'pending' && waitMs > 0) {
+ await new Promise<void>((resolve) => {
+ const timer = setTimeout(done, waitMs);
+ const set = this.waiters.get(requestId) ?? new Set();
+ this.waiters.set(requestId, set);
+ function done() {
+ clearTimeout(timer);
+ set.delete(done);
+ resolve();
+ }
+ set.add(done);
+ });
+ }
+ this.expire();
+ const current = this.requests.get(requestId);
+ if (!current) return { status: 'expired' };
+ if (current.status === 'pending') return { status: 'pending' };
+ this.requests.delete(requestId);
+ if (current.status === 'rejected') return { status: 'rejected' };
+ const { credential, credentialHash } = createDeviceCredential();
+ const device = this.store.admitMember({
+ deviceId: current.deviceId,
+ credentialHash,
+ cert: current.cert!,
+ reportedName: current.deviceName,
+ platform: current.platform,
+ appVersion: current.appVersion,
+ now: this.now(),
+ });
+ this.onAdmitted(device);
+ return { status: 'approved', credential, deviceId: device.deviceId, cert: device.cert };
+ }
+
+ /** 关闭中转时唤醒所有长轮询,让它们按当前状态返回。 */
+ wakeAll(): void {
+ for (const requestId of [...this.waiters.keys()]) this.wake(requestId);
+ }
+
+ private authorizePoll(requestId: string, pollToken: unknown): PairRequest | null {
+ this.expire();
+ const request = this.requests.get(requestId);
+ if (!request) return null;
+ if (typeof pollToken !== 'string' || !safeEqualHex(hashSecret(pollToken), request.pollTokenHash)) {
+ throw new RelayError('FORBIDDEN', 'invalid poll token');
+ }
+ return request;
+ }
+
+ private wake(requestId: string): void {
+ const set = this.waiters.get(requestId);
+ if (!set) return;
+ this.waiters.delete(requestId);
+ for (const done of [...set]) done();
+ }
+
+ private limitSource(source: string): void {
+ const now = this.now();
+ const recent = (this.submitsBySource.get(source) ?? []).filter((at) => now - at < SUBMIT_WINDOW_MS);
+ if (recent.length >= MAX_SUBMITS_PER_SOURCE) {
+ this.submitsBySource.set(source, recent);
+ throw new RelayError('RATE_LIMITED', 'too many pairing attempts');
+ }
+ recent.push(now);
+ this.submitsBySource.set(source, recent);
+ }
+
+ private expire(): void {
+ const now = this.now();
+ for (const [hash, expiresAt] of this.joinCodes) if (expiresAt < now) this.joinCodes.delete(hash);
+ for (const [requestId, request] of this.requests) {
+ if (request.expiresAt < now) {
+ this.requests.delete(requestId);
+ this.wake(requestId);
+ }
+ }
+ for (const [source, times] of this.submitsBySource) {
+ if (times.every((at) => now - at >= SUBMIT_WINDOW_MS)) this.submitsBySource.delete(source);
+ }
+ }
+}
diff --git a/packages/device-link-relay/src/server.ts b/packages/device-link-relay/src/server.ts
new file mode 100644
index 0000000000..ca3dcbcc2d
--- /dev/null
+++ b/packages/device-link-relay/src/server.ts
@@ -0,0 +1,401 @@
+/**
+ * 中转服务入口:一个 HTTP(S) 服务同时承载
+ * - `/api/device-link/ws`:设备 WebSocket(握手时校验 `CindyRelay` 凭证);
+ * - `/api/device-link/*`:与官方 relay 同形的 REST(设备、媒体);
+ * - `/api/device-link/relay/*`:自建中转独有的加入与管理接口、媒体签名地址。
+ *
+ * Cindy 内运行与服务器上独立运行用的都是这一个入口。证书:传入 `tls` 时直接提供 HTTPS;
+ * 不传时只提供 HTTP,用于本机自连、测试,以及由前置代理(nginx / frp / Tailscale serve 等)负责 TLS 的场景。
+ */
+import { readFile } from 'node:fs/promises';
+import { createServer as createHttpServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { createServer as createHttpsServer } from 'node:https';
+import type { AddressInfo, Socket } from 'node:net';
+import path from 'node:path';
+import { PROTOCOL_VERSION, WS_MAX_PAYLOAD_BYTES } from '@cindy/device-link-protocol';
+import { WebSocketServer } from 'ws';
+import { parseRelayAuthorization } from './credentials';
+import { RelayError } from './errors';
+import { CLOSE_DEVICE_REMOVED, DEFAULT_HUB_LIMITS, Hub, type HubLimits } from './hub';
+import { silentLogger, type RelayLogger } from './logger';
+import { BLOB_PATH_PREFIX, DEFAULT_MEDIA_LIMITS, MediaStore, type MediaLimits } from './media';
+import { Pairing } from './pairing';
+import { normalizeName, RelayStore, type StoredDevice } from './store';
+import { RELAY_VERSION } from './version';
+
+const API_PREFIX = '/api/device-link';
+const WS_PATH = `${API_PREFIX}/ws`;
+const MAX_JSON_BODY_BYTES = 64 * 1024;
+const MAX_POLL_WAIT_MS = 25_000;
+const POLL_TOKEN_HEADER = 'x-cindy-relay-poll-token';
+
+export interface RelayServerOptions {
+ /** 中转数据目录,须先用 `initializeRelay` 初始化。 */
+ dataDir: string;
+ /** 监听地址,默认只监听本机 `127.0.0.1`。 */
+ host?: string;
+ /** 监听端口,默认 0(随机)。 */
+ port?: number;
+ /** PEM 证书与私钥;提供时直接以 HTTPS/WSS 服务。 */
+ tls?: { cert: string | Buffer; key: string | Buffer };
+ /** 其他设备访问中转用的地址(如 https://1.2.3.4),用于生成媒体签名地址;不填时按请求推断。 */
+ publicUrl?: string;
+ /** 中转在前置代理之后时,按 X-Forwarded-Proto / X-Forwarded-Host 推断外部地址。默认 false。 */
+ trustProxyHeaders?: boolean;
+ media?: Partial<MediaLimits>;
+ hub?: Partial<HubLimits>;
+ now?: () => number;
+ logger?: RelayLogger;
+ /** 媒体过期清理间隔,默认 10 分钟。 */
+ sweepIntervalMs?: number;
+ /** 当前证书到期时间(自动证书时由证书管理提供),主人在状态接口里看到。 */
+ certificateExpiresAt?: () => string | null;
+}
+
+export interface RelayServerHandle {
+ readonly relayId: string;
+ /** 本机可直接访问的基础地址(按监听地址生成),如 http://127.0.0.1:47820 */
+ readonly localUrl: string;
+ readonly port: number;
+ /** 换上续期后的证书,已建立的连接不受影响(仅 HTTPS)。 */
+ updateTls(tls: { cert: string | Buffer; key: string | Buffer }): void;
+ /**
+ * 关闭中转。`retire: true` 表示主人停用了中转:用 4410 断开所有设备,客户端不再重连、
+ * 提示「中转已停用」;缺省为暂时关闭(1001),设备按退避重连,中转回来后自动恢复。
+ */
+ close(options?: { retire?: boolean }): Promise<void>;
+}
+
+type Route = (ctx: RequestContext) => Promise<void>;
+
+interface RequestContext {
+ req: IncomingMessage;
+ res: ServerResponse;
+ url: URL;
+ params: string[];
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+ const text = JSON.stringify(body);
+ res.writeHead(status, {
+ 'Content-Type': 'application/json; charset=utf-8',
+ 'Content-Length': String(Buffer.byteLength(text)),
+ 'Cache-Control': 'no-store',
+ });
+ res.end(text);
+}
+
+function sendEmpty(res: ServerResponse, status: number): void {
+ res.writeHead(status, { 'Cache-Control': 'no-store' });
+ res.end();
+}
+
+async function readJson(req: IncomingMessage): Promise<Record<string, unknown>> {
+ const chunks: Buffer[] = [];
+ let size = 0;
+ for await (const chunk of req) {
+ size += (chunk as Buffer).length;
+ if (size > MAX_JSON_BODY_BYTES) throw new RelayError('PAYLOAD_TOO_LARGE', 'request body is too large');
+ chunks.push(chunk as Buffer);
+ }
+ if (size === 0) return {};
+ try {
+ const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown;
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not an object');
+ return parsed as Record<string, unknown>;
+ } catch {
+ throw new RelayError('BAD_REQUEST', 'request body must be a JSON object');
+ }
+}
+
+function headerValue(value: string | string[] | undefined): string | undefined {
+ return Array.isArray(value) ? value[0] : value;
+}
+
+const HOST_PATTERN = /^[A-Za-z0-9.-]+(:\d{1,5})?$|^\[[0-9A-Fa-f:.]+\](:\d{1,5})?$/;
+
+export async function startRelayServer(options: RelayServerOptions): Promise<RelayServerHandle> {
+ const now = options.now ?? Date.now;
+ const logger = options.logger ?? silentLogger;
+ const host = options.host ?? '127.0.0.1';
+ const store = await RelayStore.open(options.dataDir, (error) => {
+ logger.error('failed to save relay state', { reason: error instanceof Error ? error.name : 'unknown' });
+ });
+ const media = new MediaStore(
+ path.join(options.dataDir, 'media'),
+ store.mediaSigningKey,
+ { ...DEFAULT_MEDIA_LIMITS, ...options.media },
+ now,
+ );
+ await media.init();
+ const hub = new Hub(store, store.ownerUserId, now, logger, { ...DEFAULT_HUB_LIMITS, ...options.hub });
+ const pairing = new Pairing(store, now, (device) => {
+ logger.info('device admitted', { platform: device.platform ?? 'unknown' });
+ hub.announce(device);
+ });
+ const publicUrl = options.publicUrl?.replace(/\/+$/, '');
+
+ function externalBase(req: IncomingMessage): string {
+ if (publicUrl) return publicUrl;
+ const forwardedProto = options.trustProxyHeaders ? headerValue(req.headers['x-forwarded-proto']) : undefined;
+ const forwardedHost = options.trustProxyHeaders ? headerValue(req.headers['x-forwarded-host']) : undefined;
+ const proto = options.tls ? 'https' : forwardedProto === 'https' ? 'https' : 'http';
+ const hostHeader = forwardedHost ?? headerValue(req.headers.host);
+ const safeHost = hostHeader && HOST_PATTERN.test(hostHeader) ? hostHeader : `${host}:${boundPort}`;
+ return `${proto}://${safeHost}`;
+ }
+
+ function authenticate(req: IncomingMessage): StoredDevice {
+ const credential = parseRelayAuthorization(req.headers.authorization);
+ const device = credential ? store.findByCredential(credential) : undefined;
+ if (!device) throw new RelayError('RELAY_CREDENTIAL_INVALID', 'missing or invalid relay credential');
+ return device;
+ }
+
+ function requireOwner(req: IncomingMessage): StoredDevice {
+ const device = authenticate(req);
+ if (device.role !== 'owner') throw new RelayError('FORBIDDEN', 'only the owner device can manage this relay');
+ return device;
+ }
+
+ const routes: Array<{ method: string; pattern: RegExp; handler: Route }> = [];
+ const route = (method: string, pattern: RegExp, handler: Route) => routes.push({ method, pattern, handler });
+
+ // ── 公开:加入前探测与加入申请 ────────────────────────────────────────────
+ route('GET', /^\/api\/device-link\/relay\/info$/, async ({ res }) => {
+ sendJson(res, 200, {
+ relayId: store.relayId,
+ name: store.relayName,
+ protocolVersion: PROTOCOL_VERSION,
+ relayVersion: RELAY_VERSION,
+ features: ['pairing-v1', 'device-signatures-v1'],
+ // 仅供展示与主人核对;加入的设备只信任加入链接里的主人公钥。
+ ownerPublicKey: store.ownerPublicKey,
+ });
+ });
+ route('POST', /^\/api\/device-link\/relay\/pair$/, async ({ req, res }) => {
+ const body = await readJson(req);
+ sendJson(res, 200, pairing.submit(body, req.socket.remoteAddress ?? 'unknown'));
+ });
+ route('GET', /^\/api\/device-link\/relay\/pair\/([0-9a-f-]{36})$/, async ({ req, res, url, params }) => {
+ const wait = Math.min(Math.max(Number(url.searchParams.get('wait') ?? 0) * 1000, 0), MAX_POLL_WAIT_MS);
+ const result = await pairing.poll(params[0], headerValue(req.headers[POLL_TOKEN_HEADER]), Number.isFinite(wait) ? wait : 0);
+ sendJson(res, 200, result);
+ });
+
+ // ── 设备(与官方 relay 同形)─────────────────────────────────────────────
+ route('GET', /^\/api\/device-link\/devices$/, async ({ req, res }) => {
+ const self = authenticate(req);
+ sendJson(res, 200, { devices: store.list().map((device) => hub.deviceView(device, self.deviceId)) });
+ });
+ route('PATCH', /^\/api\/device-link\/devices\/([^/]+)$/, async ({ req, res, params }) => {
+ authenticate(req);
+ const body = await readJson(req);
+ const deviceId = decodeURIComponent(params[0]);
+ if (!store.get(deviceId)) throw new RelayError('NOT_FOUND', 'device not found');
+ let customName: string | null = null;
+ if (body.name !== null) {
+ customName = normalizeName(body.name);
+ if (!customName) throw new RelayError('BAD_REQUEST', 'invalid device name');
+ }
+ const device = store.update(deviceId, { customName })!;
+ hub.announce(device);
+ sendJson(res, 200, { deviceId, name: device.customName ?? device.reportedName });
+ });
+ route('DELETE', /^\/api\/device-link\/devices\/([^/]+)$/, async ({ req, res, params }) => {
+ const self = authenticate(req);
+ const deviceId = decodeURIComponent(params[0]);
+ const target = store.get(deviceId);
+ if (!target) throw new RelayError('NOT_FOUND', 'device not found');
+ if (target.role === 'owner') throw new RelayError('FORBIDDEN', 'the owner device cannot be removed');
+ // 主人可以移除任何成员;成员只能让自己退出。
+ if (self.role !== 'owner' && self.deviceId !== deviceId) {
+ throw new RelayError('FORBIDDEN', 'only the owner device can remove other devices');
+ }
+ store.remove(deviceId);
+ hub.disconnectDevice(target, CLOSE_DEVICE_REMOVED, 'device removed');
+ logger.info('device removed', { bySelf: self.deviceId === deviceId });
+ sendJson(res, 200, { deviceId, deleted: true });
+ });
+
+ // 设备证书:每台设备据此核对其他设备发来的消息(证书由主人签名,中转只负责保存与转交)。
+ route('GET', /^\/api\/device-link\/relay\/certs$/, async ({ req, res }) => {
+ authenticate(req);
+ sendJson(res, 200, { ownerPublicKey: store.ownerPublicKey, certs: store.certificates() });
+ });
+
+ // ── 媒体 ─────────────────────────────────────────────────────────────────
+ route('POST', /^\/api\/device-link\/media\/presign-put$/, async ({ req, res }) => {
+ authenticate(req);
+ sendJson(res, 200, media.presignPut(await readJson(req), externalBase(req)));
+ });
+ route('POST', /^\/api\/device-link\/media\/presign-get$/, async ({ req, res }) => {
+ authenticate(req);
+ const body = await readJson(req);
+ sendJson(res, 200, await media.presignGet(body.key, externalBase(req)));
+ });
+ route('DELETE', /^\/api\/device-link\/media$/, async ({ req, res }) => {
+ authenticate(req);
+ const body = await readJson(req);
+ await media.delete(body.key);
+ sendJson(res, 200, { deleted: true });
+ });
+
+ // ── 自建中转不提供的官方能力:给出客户端能平稳处理的响应 ─────────────────
+ // ICE:404 让远程桌面按现有逻辑退回公共 STUN。
+ route('GET', /^\/api\/device-link\/ice-servers$/, async ({ req }) => {
+ authenticate(req);
+ throw new RelayError('NOT_FOUND', 'no ICE configuration on a self-hosted relay');
+ });
+ // 手机推送:推送凭据绑定官方 App,自建中转不保存 token,也不声明 notify 能力。
+ route('PUT', /^\/api\/device-link\/push-token$/, async ({ req, res }) => {
+ authenticate(req);
+ sendEmpty(res, 204);
+ });
+ route('DELETE', /^\/api\/device-link\/push-token$/, async ({ req, res }) => {
+ authenticate(req);
+ sendEmpty(res, 204);
+ });
+ // 供应商分享跨账号,自建中转上始终为空。
+ route('GET', /^\/api\/device-link\/provider-shares$/, async ({ req, res }) => {
+ authenticate(req);
+ sendJson(res, 200, { shares: [] });
+ });
+
+ // ── 管理(仅主人电脑)─────────────────────────────────────────────────────
+ route('POST', /^\/api\/device-link\/relay\/admin\/join-codes$/, async ({ req, res }) => {
+ requireOwner(req);
+ sendJson(res, 200, pairing.createJoinCode());
+ });
+ route('GET', /^\/api\/device-link\/relay\/admin\/pair-requests$/, async ({ req, res }) => {
+ requireOwner(req);
+ sendJson(res, 200, { requests: pairing.listPending() });
+ });
+ route('POST', /^\/api\/device-link\/relay\/admin\/pair-requests\/([0-9a-f-]{36})\/(approve|reject)$/, async ({ req, res, params }) => {
+ requireOwner(req);
+ const approve = params[1] === 'approve';
+ const body = approve ? await readJson(req) : {};
+ pairing.decide(params[0], approve, body.cert);
+ sendJson(res, 200, { requestId: params[0], status: params[1] === 'approve' ? 'approved' : 'rejected' });
+ });
+ route('GET', /^\/api\/device-link\/relay\/admin\/status$/, async ({ req, res }) => {
+ requireOwner(req);
+ sendJson(res, 200, {
+ relayId: store.relayId,
+ name: store.relayName,
+ relayVersion: RELAY_VERSION,
+ protocolVersion: PROTOCOL_VERSION,
+ devices: store.list().length,
+ online: hub.onlineCount,
+ media: media.stats,
+ tls: options.tls ? 'certificate' : 'none',
+ certificateExpiresAt: options.certificateExpiresAt?.() ?? null,
+ });
+ });
+
+ async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+ const url = new URL(req.url ?? '/', 'http://relay.invalid');
+ try {
+ if (url.pathname.startsWith(BLOB_PATH_PREFIX)) {
+ await media.handleBlobRequest(req, res, url);
+ return;
+ }
+ if (!url.pathname.startsWith(`${API_PREFIX}/`)) throw new RelayError('NOT_FOUND', 'not found');
+ for (const entry of routes) {
+ const match = entry.pattern.exec(url.pathname);
+ if (!match) continue;
+ if (entry.method !== req.method) continue;
+ await entry.handler({ req, res, url, params: match.slice(1) });
+ return;
+ }
+ const pathExists = routes.some((entry) => entry.pattern.test(url.pathname));
+ throw pathExists ? new RelayError('BAD_REQUEST', 'method not allowed') : new RelayError('NOT_FOUND', 'not found');
+ } catch (error) {
+ const relayError =
+ error instanceof RelayError ? error : new RelayError('INTERNAL', 'internal relay error');
+ if (!(error instanceof RelayError)) logger.error('request failed', { path: url.pathname.split('/').slice(0, 4).join('/') });
+ if (res.headersSent) {
+ res.destroy();
+ return;
+ }
+ // 上传被拒时请求体可能还没读完;回完错误后关闭连接,不在拒绝的上传上继续读数据。
+ if (req.method === 'PUT' && !req.complete) res.setHeader('Connection', 'close');
+ sendJson(res, relayError.status, { error: { code: relayError.code, message: relayError.message } });
+ }
+ }
+
+ const server: Server = options.tls
+ ? createHttpsServer({ cert: options.tls.cert, key: options.tls.key }, (req, res) => void handleRequest(req, res))
+ : createHttpServer((req, res) => void handleRequest(req, res));
+ // 长轮询最长 25 秒;大文件上传不能被整体请求超时打断,只限制请求头。
+ server.requestTimeout = 0;
+ server.headersTimeout = 30_000;
+
+ const wss = new WebSocketServer({ noServer: true, maxPayload: WS_MAX_PAYLOAD_BYTES });
+ server.on('upgrade', (req: IncomingMessage, socket: Socket, head: Buffer) => {
+ socket.on('error', () => undefined);
+ const url = new URL(req.url ?? '/', 'http://relay.invalid');
+ const credential = parseRelayAuthorization(req.headers.authorization);
+ const device = credential ? store.findByCredential(credential) : undefined;
+ if (url.pathname !== WS_PATH || !device) {
+ const status = url.pathname !== WS_PATH ? '404 Not Found' : '401 Unauthorized';
+ socket.end(`HTTP/1.1 ${status}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+ return;
+ }
+ wss.handleUpgrade(req, socket, head, (ws) => hub.attach(ws, device));
+ });
+
+ let boundPort = 0;
+ await new Promise<void>((resolve, reject) => {
+ server.once('error', reject);
+ server.listen(options.port ?? 0, host, () => {
+ server.off('error', reject);
+ resolve();
+ });
+ });
+ boundPort = (server.address() as AddressInfo).port;
+
+ const sweepTimer = setInterval(() => {
+ void media.sweep().catch(() => logger.warn('media sweep failed'));
+ }, options.sweepIntervalMs ?? 10 * 60 * 1000);
+ sweepTimer.unref?.();
+
+ const scheme = options.tls ? 'https' : 'http';
+ const urlHost = host.includes(':') ? `[${host}]` : host;
+ logger.info('relay listening', { port: boundPort, tls: Boolean(options.tls) });
+
+ let closing: Promise<void> | null = null;
+ return {
+ relayId: store.relayId,
+ localUrl: `${scheme}://${urlHost}:${boundPort}`,
+ port: boundPort,
+ updateTls(tls) {
+ if (!options.tls) throw new Error('relay is not serving HTTPS');
+ (server as import('node:https').Server).setSecureContext({ cert: tls.cert, key: tls.key });
+ logger.info('certificate updated');
+ },
+ close(closeOptions) {
+ closing ??= (async () => {
+ clearInterval(sweepTimer);
+ pairing.wakeAll();
+ if (closeOptions?.retire) hub.closeAll(CLOSE_DEVICE_REMOVED, 'relay retired');
+ else hub.closeAll(1001, 'relay shutting down');
+ await new Promise<void>((resolve) => {
+ wss.close(() => resolve());
+ });
+ await new Promise<void>((resolve) => {
+ server.close(() => resolve());
+ server.closeAllConnections?.();
+ });
+ await store.flush();
+ })();
+ return closing;
+ },
+ };
+}
+
+/** 从文件读取 PEM 证书与私钥(独立运行时由命令行参数指定)。 */
+export async function readTlsFiles(certPath: string, keyPath: string): Promise<{ cert: Buffer; key: Buffer }> {
+ const [cert, key] = await Promise.all([readFile(certPath), readFile(keyPath)]);
+ return { cert, key };
+}
diff --git a/packages/device-link-relay/src/store.ts b/packages/device-link-relay/src/store.ts
new file mode 100644
index 0000000000..c4244fb760
--- /dev/null
+++ b/packages/device-link-relay/src/store.ts
@@ -0,0 +1,364 @@
+/**
+ * 中转的持久状态:中转身份、主人账号与主人公钥、设备档案(只存凭证哈希,另存主人签发的设备证书)、
+ * 媒体签名密钥。
+ *
+ * 单个 JSON 文件,原子写入(临时文件 + rename,权限 0600)。结构变化(加入、移除、改名、
+ * 自报信息变化)立即排队保存;lastSeenAt 只在断开时更新,避免每次心跳写盘。
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { DeviceInfo } from '@cindy/device-link-protocol';
+import { nodeRelayAuthCrypto } from '@cindy/device-link/node-relay-crypto';
+import { isRelayPublicKey, verifyRelayDeviceCert, type RelayDeviceCert } from '@cindy/device-link/relay-auth';
+import { createSecret, hashSecret, isSha256Hex } from './credentials';
+import { RelayError } from './errors';
+
+export const STATE_FILE = 'relay-state.json';
+/** 2:加入设备签名(主人公钥 + 每台设备的证书)。schema 1 的数据不再接受,需重新开启中转。 */
+const STATE_SCHEMA = 2;
+
+export const DEVICE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+export const RELAY_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export const MAX_NAME_LENGTH = 64;
+const MAX_USER_ID_LENGTH = 128;
+
+export type DeviceRole = 'owner' | 'member';
+
+export interface StoredDevice {
+ deviceId: string;
+ role: DeviceRole;
+ credentialHash: string;
+ /** 主人签发的设备证书:其他设备据此核对这台设备发出的消息。 */
+ cert: RelayDeviceCert;
+ /** 设备在 hello 里自报的名字。 */
+ reportedName: string;
+ /** 用户改过的名字;null = 用自报名。 */
+ customName: string | null;
+ platform: string | null;
+ appVersion: string | null;
+ deviceInfo: DeviceInfo | null;
+ pairedAt: number;
+ lastSeenAt: number | null;
+}
+
+interface RelayStateFile {
+ schema: typeof STATE_SCHEMA;
+ relayId: string;
+ name: string;
+ ownerUserId: string;
+ ownerPublicKey: string;
+ mediaSigningKey: string;
+ devices: StoredDevice[];
+}
+
+export interface InitializeRelayInput {
+ dataDir: string;
+ /** 中转的展示名,加入页与设置页显示。 */
+ name: string;
+ /** 主人电脑登录的 Cindy 账号 ID;hello-ack.userId 原样返回,加入时用于防误操作。 */
+ ownerUserId: string;
+ /** 主人电脑与官方登录相同的设备 ID。 */
+ ownerDeviceId: string;
+ ownerDeviceName: string;
+ /** 主人电脑凭证的 SHA-256;明文只留在主人电脑。 */
+ ownerCredentialHash: string;
+ /** 中转 ID 由主人电脑生成(UUID):主人证书要签进这个 ID。 */
+ relayId: string;
+ /** 主人公钥;私钥只留在主人电脑。 */
+ ownerPublicKey: string;
+ /** 主人给自己签发的设备证书。 */
+ ownerCert: unknown;
+ now?: number;
+}
+
+export function normalizeName(value: unknown): string | null {
+ if (typeof value !== 'string') return null;
+ const trimmed = value.trim();
+ if (!trimmed || trimmed.length > MAX_NAME_LENGTH) return null;
+ return trimmed;
+}
+
+function isValidUserId(value: unknown): value is string {
+ return typeof value === 'string' && value.length > 0 && value.length <= MAX_USER_ID_LENGTH;
+}
+
+/** 首次创建中转状态。已存在时拒绝,避免覆盖已有设备档案。 */
+export async function initializeRelay(input: InitializeRelayInput): Promise<{ relayId: string }> {
+ const name = normalizeName(input.name);
+ const ownerDeviceName = normalizeName(input.ownerDeviceName);
+ if (!name || !ownerDeviceName) throw new RelayError('BAD_REQUEST', 'invalid relay or device name');
+ if (!isValidUserId(input.ownerUserId)) throw new RelayError('BAD_REQUEST', 'invalid owner account');
+ if (!DEVICE_ID_PATTERN.test(input.ownerDeviceId)) throw new RelayError('BAD_REQUEST', 'invalid owner device id');
+ if (!isSha256Hex(input.ownerCredentialHash)) throw new RelayError('BAD_REQUEST', 'invalid owner credential hash');
+ if (!RELAY_ID_PATTERN.test(input.relayId)) throw new RelayError('BAD_REQUEST', 'invalid relay id');
+ if (!isRelayPublicKey(input.ownerPublicKey)) throw new RelayError('BAD_REQUEST', 'invalid owner public key');
+ const ownerCert = verifyRelayDeviceCert(nodeRelayAuthCrypto, input.ownerPublicKey, input.relayId, input.ownerCert);
+ if (!ownerCert || ownerCert.role !== 'owner' || ownerCert.deviceId !== input.ownerDeviceId) {
+ throw new RelayError('BAD_REQUEST', 'invalid owner certificate');
+ }
+
+ await mkdir(input.dataDir, { recursive: true, mode: 0o700 });
+ const file = path.join(input.dataDir, STATE_FILE);
+ const existing = await readFile(file, 'utf8').catch((error: NodeJS.ErrnoException) => {
+ if (error.code === 'ENOENT') return null;
+ throw error;
+ });
+ if (existing !== null) throw new RelayError('ALREADY_INITIALIZED', 'relay data directory is already initialized');
+
+ const state: RelayStateFile = {
+ schema: STATE_SCHEMA,
+ relayId: input.relayId,
+ name,
+ ownerUserId: input.ownerUserId,
+ ownerPublicKey: input.ownerPublicKey,
+ mediaSigningKey: createSecret(),
+ devices: [
+ {
+ deviceId: input.ownerDeviceId,
+ role: 'owner',
+ credentialHash: input.ownerCredentialHash,
+ cert: ownerCert,
+ reportedName: ownerDeviceName,
+ customName: null,
+ platform: null,
+ appVersion: null,
+ deviceInfo: null,
+ pairedAt: input.now ?? Date.now(),
+ lastSeenAt: null,
+ },
+ ],
+ };
+ await writeStateAtomically(input.dataDir, state);
+ return { relayId: state.relayId };
+}
+
+async function writeStateAtomically(dataDir: string, state: RelayStateFile): Promise<void> {
+ const file = path.join(dataDir, STATE_FILE);
+ const tmp = `${file}.${randomUUID()}.tmp`;
+ try {
+ await writeFile(tmp, JSON.stringify(state, null, 2), { mode: 0o600, flag: 'wx' });
+ await rename(tmp, file);
+ } catch (error) {
+ await rm(tmp, { force: true }).catch(() => undefined);
+ throw error;
+ }
+}
+
+function parseStoredDevice(raw: unknown, relayId: string, ownerPublicKey: string): StoredDevice | null {
+ if (!raw || typeof raw !== 'object') return null;
+ const d = raw as Record<string, unknown>;
+ if (typeof d.deviceId !== 'string' || !DEVICE_ID_PATTERN.test(d.deviceId)) return null;
+ if (d.role !== 'owner' && d.role !== 'member') return null;
+ if (!isSha256Hex(d.credentialHash)) return null;
+ const cert = verifyRelayDeviceCert(nodeRelayAuthCrypto, ownerPublicKey, relayId, d.cert);
+ if (!cert || cert.deviceId !== d.deviceId || cert.role !== d.role) return null;
+ if (typeof d.reportedName !== 'string') return null;
+ if (typeof d.pairedAt !== 'number') return null;
+ return {
+ deviceId: d.deviceId,
+ role: d.role,
+ credentialHash: d.credentialHash,
+ cert,
+ reportedName: d.reportedName,
+ customName: typeof d.customName === 'string' ? d.customName : null,
+ platform: typeof d.platform === 'string' ? d.platform : null,
+ appVersion: typeof d.appVersion === 'string' ? d.appVersion : null,
+ deviceInfo: d.deviceInfo && typeof d.deviceInfo === 'object' ? (d.deviceInfo as DeviceInfo) : null,
+ pairedAt: d.pairedAt,
+ lastSeenAt: typeof d.lastSeenAt === 'number' ? d.lastSeenAt : null,
+ };
+}
+
+export class RelayStore {
+ readonly relayId: string;
+ readonly ownerUserId: string;
+ readonly ownerPublicKey: string;
+ readonly mediaSigningKey: string;
+ private name: string;
+ private readonly devices = new Map<string, StoredDevice>();
+ private readonly deviceIdByHash = new Map<string, string>();
+ private saveTimer: ReturnType<typeof setTimeout> | null = null;
+ private saving: Promise<void> = Promise.resolve();
+ private dirty = false;
+
+ private constructor(
+ private readonly dataDir: string,
+ state: RelayStateFile,
+ private readonly onSaveError: (error: unknown) => void,
+ ) {
+ this.relayId = state.relayId;
+ this.ownerUserId = state.ownerUserId;
+ this.ownerPublicKey = state.ownerPublicKey;
+ this.mediaSigningKey = state.mediaSigningKey;
+ this.name = state.name;
+ for (const device of state.devices) this.index(device);
+ }
+
+ /** 读取已初始化的状态;缺失或损坏时明确失败,不自动重建(重建会让所有已加入设备失效)。 */
+ static async open(dataDir: string, onSaveError: (error: unknown) => void): Promise<RelayStore> {
+ const file = path.join(dataDir, STATE_FILE);
+ let text: string;
+ try {
+ text = await readFile(file, 'utf8');
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+ throw new RelayError('NOT_INITIALIZED', 'relay data directory is not initialized');
+ }
+ throw error;
+ }
+ let raw: Record<string, unknown>;
+ try {
+ raw = JSON.parse(text) as Record<string, unknown>;
+ } catch {
+ throw new RelayError('STATE_INVALID', 'relay state file is not valid JSON');
+ }
+ if (raw.schema !== STATE_SCHEMA) {
+ throw new RelayError('STATE_INVALID', `relay state schema ${String(raw.schema)} is not supported`);
+ }
+ const relayId = typeof raw.relayId === 'string' ? raw.relayId : '';
+ const ownerPublicKey = isRelayPublicKey(raw.ownerPublicKey) ? raw.ownerPublicKey : '';
+ const devices = Array.isArray(raw.devices) && relayId && ownerPublicKey
+ ? raw.devices.map((device) => parseStoredDevice(device, relayId, ownerPublicKey))
+ : null;
+ if (
+ typeof raw.relayId !== 'string' ||
+ typeof raw.name !== 'string' ||
+ !isValidUserId(raw.ownerUserId) ||
+ typeof raw.mediaSigningKey !== 'string' ||
+ raw.mediaSigningKey.length < 32 ||
+ !devices ||
+ devices.some((device) => device === null) ||
+ devices.filter((device) => device!.role === 'owner').length !== 1
+ ) {
+ throw new RelayError('STATE_INVALID', 'relay state file has an unexpected shape');
+ }
+ return new RelayStore(
+ dataDir,
+ {
+ schema: STATE_SCHEMA,
+ relayId: raw.relayId,
+ name: raw.name,
+ ownerUserId: raw.ownerUserId,
+ ownerPublicKey,
+ mediaSigningKey: raw.mediaSigningKey,
+ devices: devices as StoredDevice[],
+ },
+ onSaveError,
+ );
+ }
+
+ get relayName(): string {
+ return this.name;
+ }
+
+ private index(device: StoredDevice): void {
+ this.devices.set(device.deviceId, device);
+ this.deviceIdByHash.set(device.credentialHash, device.deviceId);
+ }
+
+ findByCredential(credential: string): StoredDevice | undefined {
+ const deviceId = this.deviceIdByHash.get(hashSecret(credential));
+ return deviceId ? this.devices.get(deviceId) : undefined;
+ }
+
+ get(deviceId: string): StoredDevice | undefined {
+ return this.devices.get(deviceId);
+ }
+
+ list(): StoredDevice[] {
+ return [...this.devices.values()];
+ }
+
+ /** 全部设备证书(由主人私钥签名,中转无法伪造)。 */
+ certificates(): RelayDeviceCert[] {
+ return this.list().map((device) => device.cert);
+ }
+
+ /** 加入审批通过:新设备入档,或同一设备重新加入时替换凭证(旧凭证立即失效)。 */
+ admitMember(input: {
+ deviceId: string;
+ credentialHash: string;
+ cert: RelayDeviceCert;
+ reportedName: string;
+ platform: string | null;
+ appVersion: string | null;
+ now: number;
+ }): StoredDevice {
+ const existing = this.devices.get(input.deviceId);
+ if (existing?.role === 'owner') throw new RelayError('FORBIDDEN', 'owner device cannot re-pair');
+ if (existing) this.deviceIdByHash.delete(existing.credentialHash);
+ const device: StoredDevice = {
+ deviceId: input.deviceId,
+ role: 'member',
+ credentialHash: input.credentialHash,
+ cert: input.cert,
+ reportedName: input.reportedName,
+ customName: existing?.customName ?? null,
+ platform: input.platform,
+ appVersion: input.appVersion,
+ deviceInfo: existing?.deviceInfo ?? null,
+ pairedAt: input.now,
+ lastSeenAt: existing?.lastSeenAt ?? null,
+ };
+ this.index(device);
+ this.markDirty();
+ return device;
+ }
+
+ remove(deviceId: string): StoredDevice | undefined {
+ const device = this.devices.get(deviceId);
+ if (!device) return undefined;
+ this.devices.delete(deviceId);
+ this.deviceIdByHash.delete(device.credentialHash);
+ this.markDirty();
+ return device;
+ }
+
+ update(
+ deviceId: string,
+ patch: Partial<Pick<StoredDevice, 'reportedName' | 'customName' | 'platform' | 'appVersion' | 'deviceInfo' | 'lastSeenAt'>>,
+ ): StoredDevice | undefined {
+ const device = this.devices.get(deviceId);
+ if (!device) return undefined;
+ Object.assign(device, patch);
+ this.markDirty();
+ return device;
+ }
+
+ private markDirty(): void {
+ this.dirty = true;
+ if (this.saveTimer) return;
+ this.saveTimer = setTimeout(() => {
+ this.saveTimer = null;
+ void this.flush();
+ }, 200);
+ this.saveTimer.unref?.();
+ }
+
+ /** 把挂起的修改写盘;串行执行,保证后写覆盖先写。 */
+ flush(): Promise<void> {
+ if (this.saveTimer) {
+ clearTimeout(this.saveTimer);
+ this.saveTimer = null;
+ }
+ if (!this.dirty) return this.saving;
+ this.dirty = false;
+ const snapshot: RelayStateFile = {
+ schema: STATE_SCHEMA,
+ relayId: this.relayId,
+ name: this.name,
+ ownerUserId: this.ownerUserId,
+ ownerPublicKey: this.ownerPublicKey,
+ mediaSigningKey: this.mediaSigningKey,
+ devices: this.list().map((device) => ({ ...device })),
+ };
+ this.saving = this.saving
+ .then(() => writeStateAtomically(this.dataDir, snapshot))
+ .catch((error) => {
+ this.dirty = true;
+ this.onSaveError(error);
+ });
+ return this.saving;
+ }
+}
diff --git a/packages/device-link-relay/src/version.ts b/packages/device-link-relay/src/version.ts
new file mode 100644
index 0000000000..0f6ebb75a1
--- /dev/null
+++ b/packages/device-link-relay/src/version.ts
@@ -0,0 +1,2 @@
+/** 中转程序版本:主人电脑据此提示升级服务器上的中转。改动 wire 行为时递增。 */
+export const RELAY_VERSION = '0.2.0';
diff --git a/packages/device-link-relay/tsconfig.json b/packages/device-link-relay/tsconfig.json
new file mode 100644
index 0000000000..44b677a6ac
--- /dev/null
+++ b/packages/device-link-relay/tsconfig.json
@@ -0,0 +1,17 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "noEmit": true,
+ "lib": ["ES2022"],
+ "types": ["node"]
+ },
+ "include": ["src/**/*", "scripts/**/*"]
+}
diff --git a/packages/device-link/TESTING.md b/packages/device-link/TESTING.md
index 4af4838936..b523ea5cd6 100644
--- a/packages/device-link/TESTING.md
+++ b/packages/device-link/TESTING.md
@@ -66,6 +66,21 @@ pnpm test:device-link --interop
不会静默 skip、回退本地 fixture,也不尝试旧开发登录接口。身份从 hello-ack 获取,
不硬编码服务端 deviceId。输出不打印 URL/token/鉴权头。
+可选 `CINDY_TEST_AUTH_SCHEME` 指定认证方案:缺省 `Bearer`(官方 relay 的账号 access token);
+`CindyRelay` 用于自建中转的设备凭证。自建中转的互通由一条命令完成,不需要外部环境:
+
+```bash
+pnpm --filter @cindy/device-link-relay run interop
+```
+
+它在本机回环地址初始化并启动 `packages/device-link-relay`,走真实加入流程拿到第二台设备的凭证,
+再以 `CindyRelay` 运行上面的互通用例;结束后关闭中转并删除临时目录。这验证的是自建中转与
+当前客户端的线协议兼容,不代表官方 relay 的互操作已验收。
+
+这条命令还会通过 `CINDY_TEST_FRAME_AUTH` 交出两台设备的测试签名密钥与中转上的证书,互通用例因此全程开启
+设备签名:主机像电脑一样核对每一条对端消息,控制端像手机一样只签名。任何绕过签名的发送路径都会让主机丢帧、
+恢复流程超时(见 docs/self-hosted-relay-plan.md §16)。不设这个变量时行为与官方 relay 的互通完全相同。
+
仅使用**专用隔离测试环境**签发的两台测试设备身份,不能使用日常账号或正在连接的设备:
用例会注册一个允许被控的内存 host,并主动断开自己创建的 socket。脚本不启动、停止、
清库或修改外部服务,测试环境创建和销毁由其所有者负责。
diff --git a/packages/device-link/package.json b/packages/device-link/package.json
index 9826e5315d..47c99dc2b8 100644
--- a/packages/device-link/package.json
+++ b/packages/device-link/package.json
@@ -8,7 +8,9 @@
"types": "./src/index.ts",
"exports": {
".": "./src/index.ts",
- "./node-compression": "./src/nodeCompression.ts"
+ "./node-compression": "./src/nodeCompression.ts",
+ "./node-relay-crypto": "./src/nodeRelayCrypto.ts",
+ "./relay-auth": "./src/selfHostedRelayAuth.ts"
},
"scripts": {
"build": "tsc --noEmit",
diff --git a/packages/device-link/src/__tests__/client.test.ts b/packages/device-link/src/__tests__/client.test.ts
index abd1f7104b..7f4e279b71 100644
--- a/packages/device-link/src/__tests__/client.test.ts
+++ b/packages/device-link/src/__tests__/client.test.ts
@@ -41,6 +41,8 @@ import { resolveRemoteInvokeTimeoutMs } from '../invokePolicy.js';
import { SESSION_ACTIVITY_CHANNEL } from '../topics.js';
import { resolveDesktopIceServers, REMOTE_DESKTOP_ICE_CONFIG_TIMEOUT_MS } from '../remoteDesktopIceConfig.js';
import { REMOTE_DESKTOP_ICE_SERVERS } from '../remoteDesktopIce.js';
+import { nodeRelayAuthCrypto } from '../nodeRelayCrypto.js';
+import { createRelaySigningKey, issueRelayDeviceCert, RelayFrameAuthenticator } from '../selfHostedRelayAuth.js';
import {
DIRECT_PATH_HIGH_WATER_BYTES,
type DeviceLinkDirectChannel,
@@ -105,6 +107,7 @@ function makeHarness(opts?: {
peerFailurePolicy?: ConstructorParameters<typeof DeviceLinkClient>[0]['peerFailurePolicy'];
peerResetReadRetry?: ConstructorParameters<typeof DeviceLinkClient>[0]['peerResetReadRetry'];
invokeMetrics?: ConstructorParameters<typeof DeviceLinkClient>[0]['invokeMetrics'];
+ frameAuth?: ConstructorParameters<typeof DeviceLinkClient>[0]['frameAuth'];
}): Harness {
const sockets: FakeWs[] = [];
const client = new DeviceLinkClient({
@@ -126,6 +129,7 @@ function makeHarness(opts?: {
peerFailurePolicy: opts?.peerFailurePolicy,
peerResetReadRetry: opts?.peerResetReadRetry,
invokeMetrics: opts?.invokeMetrics,
+ frameAuth: opts?.frameAuth,
timing: {
reconnectBaseMs: 5,
reconnectMaxMs: 40,
@@ -386,6 +390,58 @@ describe('outbound invoke admission', () => {
});
});
+/**
+ * 自建中转的设备签名(docs/self-hosted-relay-plan.md §16):被控电脑收到的每条对端消息都必须带发送设备的
+ * 有效签名,中转(哪怕被人控制)伪造、篡改或重放的消息在分发前丢弃;本机发出的对端消息都带签名。
+ * 最小失败输入:未签名 / 他人密钥签名 / 签名后改内容 / 原样重放的同一条 push。
+ */
+describe('self-hosted relay device signatures', () => {
+ it('signs outbound peer frames and drops forged, tampered or replayed inbound frames', async () => {
+ const relayId = '0b7a4a52-8f6a-4d55-9a53-3f1f6f2c9e10';
+ const owner = createRelaySigningKey(nodeRelayAuthCrypto);
+ const selfKey = createRelaySigningKey(nodeRelayAuthCrypto);
+ const peerKey = createRelaySigningKey(nodeRelayAuthCrypto);
+ const certs = [
+ ['dev-self', selfKey.publicKey],
+ ['dev-b', peerKey.publicKey],
+ ].map(([deviceId, publicKey]) => issueRelayDeviceCert(nodeRelayAuthCrypto, owner.seed, {
+ relayId, deviceId, publicKey, role: 'member', issuedAt: 1,
+ }));
+ const authenticator = (deviceId: string, seed: string) => {
+ const auth = new RelayFrameAuthenticator({ crypto: nodeRelayAuthCrypto, relayId, deviceId, seed, ownerPublicKey: owner.publicKey });
+ auth.setCertificates(certs);
+ return auth;
+ };
+ const self = authenticator('dev-self', selfKey.seed);
+ const peer = authenticator('dev-b', peerKey.seed);
+ const h = makeHarness({
+ timing: { pingIntervalMs: 60_000 },
+ frameAuth: () => ({ sign: (frame) => self.sign(frame), verify: (frame) => self.verify(frame) === 'ok' }),
+ });
+ h.client.start(); await tick(); h.current().ack();
+ const received: unknown[] = [];
+ h.client.onFrame((frame) => { if (frame.kind === 'push' && frame.src === 'dev-b') received.push(frame.payload); });
+
+ void h.client.openLink('dev-b', { controllerName: 'Test', protocolVersion: 1, appVersion: '1' }).catch(() => undefined);
+ const linkOpen = h.current().sent.find((env) => env.kind === 'link-open')!;
+ // 中转覆写 src 后交给对端,对端用本机证书核对通过。
+ expect(peer.verify({ ...linkOpen, src: 'dev-self' })).toBe('ok');
+
+ const frame = (payload: unknown): Envelope => ({ v: PROTOCOL_VERSION, kind: 'push', src: 'dev-b', dst: 'dev-self', payload });
+ const signed = (env: Envelope) => ({ ...env, auth: peer.sign(env) }) as Envelope;
+ const genuine = signed(frame({ channel: 'evt', payload: { n: 1 } }));
+ const forger = authenticator('dev-b', createRelaySigningKey(nodeRelayAuthCrypto).seed);
+ h.current().push(frame({ channel: 'evt', payload: { n: 0 } }));
+ h.current().push({ ...frame({ channel: 'evt', payload: { n: 0 } }), auth: forger.sign(frame({})) } as Envelope);
+ h.current().push({ ...genuine, payload: { channel: 'evt', payload: { n: 2 } } });
+ h.current().push(genuine);
+ h.current().push(genuine);
+ await tick();
+ expect(received).toEqual([{ channel: 'evt', payload: { n: 1 } }]);
+ h.client.stop();
+ });
+});
+
describe('verified outbound stream notification', () => {
it('notifies before business delivery and keeps two peers independent across restart', async () => {
const h = makeHarness({ timing: { pingIntervalMs: 60_000 } });
diff --git a/packages/device-link/src/__tests__/selfHostedRelay.test.ts b/packages/device-link/src/__tests__/selfHostedRelay.test.ts
new file mode 100644
index 0000000000..2413450b2c
--- /dev/null
+++ b/packages/device-link/src/__tests__/selfHostedRelay.test.ts
@@ -0,0 +1,50 @@
+/**
+ * 测试价值
+ * - 生产入口与可观察结果:`parseRelayJoinLink` / `buildRelayJoinLink` —— 扫码或粘贴的加入链接在这里变成
+ * Desktop / Mobile 要连接的中转地址与一次性加入码。
+ * - Bug/规则依据:docs/self-hosted-relay-plan.md §5.1(加入链接格式)、§8(只接受 http(s)、不带账号密码,
+ * 加入码不能被拼进别的参数)。
+ * - 现有覆盖缺口:新增解析器;relay 包的加入流程测试只覆盖合法链接。
+ * - 最小失败输入:见下方表格每一行(非 http 协议、URL 带凭据、未知 App、加入码过短、指向 /api 路径、
+ * 缺主人公钥或配对秘密——旧格式链接加入不了需要设备签名的中转)。
+ * - tier:unit,纯函数,无 IO。
+ */
+import { describe, expect, it } from 'vitest';
+import { buildRelayJoinLink, parseRelayJoinLink } from '../selfHostedRelay';
+
+const CODE = 'A'.repeat(43);
+const OWNER = 'Q'.repeat(43);
+const SECRET = 'C'.repeat(43);
+const keys = { ownerPublicKey: OWNER, pairSecret: SECRET };
+const keyQuery = `&o=${OWNER}&s=${SECRET}`;
+
+describe('relay join links', () => {
+ it('round-trips through every app scheme and the router path form', () => {
+ for (const app of ['cindy', 'cindycn', 'cindydev'] as const) {
+ const link = buildRelayJoinLink({ baseUrl: 'http://192.168.1.20:47820/', code: CODE, ...keys, app });
+ expect(link.startsWith(`${app}://relay/join?`)).toBe(true);
+ expect(parseRelayJoinLink(link)).toEqual({ baseUrl: 'http://192.168.1.20:47820', code: CODE, ...keys });
+ // Expo Router native intent 只给路径部分。
+ expect(parseRelayJoinLink(link.slice(link.indexOf('/relay/join')))).toEqual({
+ baseUrl: 'http://192.168.1.20:47820',
+ code: CODE,
+ ...keys,
+ });
+ }
+ expect(parseRelayJoinLink(buildRelayJoinLink({ baseUrl: 'https://relay.example.com/cindy', code: CODE, ...keys, app: 'cindy' })))
+ .toEqual({ baseUrl: 'https://relay.example.com/cindy', code: CODE, ...keys });
+ });
+
+ it.each([
+ ['non-http relay address', `cindy://relay/join?u=${encodeURIComponent('file:///etc/passwd')}&c=${CODE}${keyQuery}`],
+ ['credentials embedded in the address', `cindy://relay/join?u=${encodeURIComponent('http://user:[email protected]')}&c=${CODE}${keyQuery}`],
+ ['address pointing inside the API', `cindy://relay/join?u=${encodeURIComponent('http://10.0.0.2/api/device-link')}&c=${CODE}${keyQuery}`],
+ ['unknown app scheme', `evil://relay/join?u=${encodeURIComponent('http://10.0.0.2')}&c=${CODE}${keyQuery}`],
+ ['join code too short', `cindy://relay/join?u=${encodeURIComponent('http://10.0.0.2')}&c=short${keyQuery}`],
+ ['missing join code', `cindy://relay/join?u=${encodeURIComponent('http://10.0.0.2')}${keyQuery}`],
+ ['missing owner key and pairing secret', `cindy://relay/join?u=${encodeURIComponent('http://10.0.0.2')}&c=${CODE}`],
+ ['other deep link', `cindy://provider-share/join?u=${encodeURIComponent('http://10.0.0.2')}&c=${CODE}${keyQuery}`],
+ ])('rejects %s', (_label, link) => {
+ expect(parseRelayJoinLink(link)).toBeNull();
+ });
+});
diff --git a/packages/device-link/src/client.ts b/packages/device-link/src/client.ts
index f3155b660b..6e887b737c 100644
--- a/packages/device-link/src/client.ts
+++ b/packages/device-link/src/client.ts
@@ -248,6 +248,18 @@ export interface DeviceLinkLogger {
error(...args: unknown[]): void;
}
+/** WebSocket 升级的认证方案,见 `DeviceLinkClientOptions.authorizationScheme`。 */
+export type DeviceLinkAuthorizationScheme = 'Bearer' | 'ProviderShareGuest' | 'CindyRelay';
+
+/**
+ * 自建中转的设备签名钩子(docs/self-hosted-relay-plan.md §16,实现见 selfHostedRelayAuth.ts)。
+ * `sign` 返回要附在经中转转发的对端帧上的 `auth`;`verify` 返回 false 的入站对端帧直接丢弃。
+ */
+export interface DeviceLinkFrameAuth {
+ sign(frame: Readonly<Envelope>): unknown;
+ verify(frame: Readonly<Record<string, unknown>>): boolean;
+}
+
export interface DeviceLinkClientOptions {
/** Host WebRTC adapter. Both peers must opt in; unavailable/old hosts keep using relay. */
directRuntime?: DirectRuntime;
@@ -257,9 +269,16 @@ export interface DeviceLinkClientOptions {
getToken(): Promise<string | null>;
/**
* WebSocket 升级的认证方案。默认 `Bearer`(账号 Access Token);供应商分享的跨区域受邀者
- * 连接对方区域时用 `ProviderShareGuest`(只限分享的凭证,契约 §6.3)。
+ * 连接对方区域时用 `ProviderShareGuest`(只限分享的凭证,契约 §6.3);连接自建中转用
+ * `CindyRelay`(加入中转时拿到的设备凭证,绝不发送账号 token,见 docs/self-hosted-relay-plan.md §5.2)。
+ * 传函数时每次建连前取值:host 在官方中转与自建中转之间切换时,方案与 getToken 必须同一轮一致。
*/
- authorizationScheme?: 'Bearer' | 'ProviderShareGuest';
+ authorizationScheme?: DeviceLinkAuthorizationScheme | (() => DeviceLinkAuthorizationScheme);
+ /**
+ * 自建中转的设备签名。每帧取值:返回 null(官方中转)时不签名也不核对,wire 行为与旧版完全相同。
+ * host 在官方与自建中转之间切换时与 `getToken` / `authorizationScheme` 同一轮生效。
+ */
+ frameAuth?: () => DeviceLinkFrameAuth | null;
/** 每次(重)连时的 hello payload(host 持有 deviceName / 开关 / busy 的真相) */
getHello(): HelloPayload;
createWebSocket: WsFactory;
@@ -2056,8 +2075,11 @@ export class DeviceLinkClient {
let ws: WsLike;
try {
+ const scheme = typeof this.opts.authorizationScheme === 'function'
+ ? this.opts.authorizationScheme()
+ : this.opts.authorizationScheme;
ws = await this.opts.createWebSocket(this.opts.getWsUrl(), {
- authorization: `${this.opts.authorizationScheme ?? 'Bearer'} ${token}`,
+ authorization: `${scheme ?? 'Bearer'} ${token}`,
});
} catch (err) {
// 异步工厂可能在更新的一轮 connect 已经起来之后才 reject —— 那是过期尝试的失败,
@@ -2378,6 +2400,14 @@ export class DeviceLinkClient {
this.log.warn('dropping invalid device-link frame');
return;
}
+ // 自建中转:对端帧必须带发送设备的有效签名(在任何解码与分发之前核对,中转改不了内容)。
+ if (typeof parsed.src === 'string' && ROUTED_KINDS.has(parsed.kind)) {
+ const frameAuth = this.opts.frameAuth?.();
+ if (frameAuth && !frameAuth.verify(parsed as unknown as Record<string, unknown>)) {
+ this.noteRejectedSignature(parsed.src, parsed.kind);
+ return;
+ }
+ }
const env = decodeScopedEnvelope(parsed, this.scopeSupport());
if (!env) { this.log.warn('dropping invalid device-link routing scope'); return; }
const validForHeartbeat = isValidInboundEnvelope(env);
@@ -3720,10 +3750,30 @@ export class DeviceLinkClient {
return Math.max(originalBytes, skipBytes);
}
+ private rejectedSignatureLogAt = 0;
+ private rejectedSignatureCount = 0;
+
+ /** 签名不对的帧可能成批出现(时钟不准、证书未同步),日志按分钟汇总。 */
+ private noteRejectedSignature(src: string, kind: string): void {
+ this.rejectedSignatureCount++;
+ const now = Date.now();
+ if (now - this.rejectedSignatureLogAt < 60_000) return;
+ this.log.warn(
+ `dropping device-link frame without a valid device signature src=${src.slice(0, 8)} kind=${kind} count=${this.rejectedSignatureCount}`,
+ );
+ this.rejectedSignatureLogAt = now;
+ this.rejectedSignatureCount = 0;
+ }
+
private sendEnvelope(env: Envelope): void {
const ws = this.ws;
if (!ws) throw new DeviceLinkError('NOT_CONNECTED', 'no active connection');
- const text = JSON.stringify(encodeScopedEnvelope(env, this.scopeSupport()));
+ let wire = encodeScopedEnvelope(env, this.scopeSupport());
+ if (wire.dst && ROUTED_KINDS.has(wire.kind)) {
+ const auth = this.opts.frameAuth?.()?.sign(wire);
+ if (auth !== undefined) wire = { ...wire, auth } as Envelope;
+ }
+ const text = JSON.stringify(wire);
// 按 UTF-8 字节数判定,与服务端 MAX_FRAME_BYTES(Buffer.byteLength)一致。
// 用 text.length(UTF-16 码元)会与服务端不符:CJK 等多字节内容客户端自检通过、
// 服务端却 PAYLOAD_TOO_LARGE 丢帧,invoke 只能等 30s 超时而非快速失败。
diff --git a/packages/device-link/src/index.ts b/packages/device-link/src/index.ts
index 42e34ad313..ff8f1e0941 100644
--- a/packages/device-link/src/index.ts
+++ b/packages/device-link/src/index.ts
@@ -62,6 +62,9 @@ export * from "./clipboardSync.js";
export * from "./clipboardSyncFailure.js";
export * from "./clipboardTransfer.js";
+export * from "./selfHostedRelay.js";
+export * from "./selfHostedRelayAuth.js";
+
export * from "./pluginOauth.js";
export * from "./pluginSettings.js";
export * from "./pluginAuthorization.js";
diff --git a/packages/device-link/src/nodeRelayCrypto.ts b/packages/device-link/src/nodeRelayCrypto.ts
new file mode 100644
index 0000000000..235b1447de
--- /dev/null
+++ b/packages/device-link/src/nodeRelayCrypto.ts
@@ -0,0 +1,48 @@
+/**
+ * `RelayAuthCrypto` 的 node:crypto 实现(Desktop 主进程、自建中转与测试使用)。
+ * 只经子路径 `@cindy/device-link/node-relay-crypto` 导出,Mobile 不会打包它。
+ */
+import { createHash, createHmac, createPrivateKey, createPublicKey, randomBytes, sign, verify, type KeyObject } from 'node:crypto';
+import type { RelayAuthCrypto } from './selfHostedRelayAuth.js';
+
+// Ed25519 原始 32 字节密钥外面的固定 DER 头(PKCS#8 私钥 / SPKI 公钥)。
+const PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const MAX_CACHED_KEYS = 256;
+
+const privateKeys = new Map<string, KeyObject>();
+const publicKeys = new Map<string, KeyObject>();
+
+function remember(cache: Map<string, KeyObject>, id: string, key: KeyObject): KeyObject {
+ if (cache.size >= MAX_CACHED_KEYS) cache.delete(cache.keys().next().value!);
+ cache.set(id, key);
+ return key;
+}
+
+function privateKeyOf(seed: Uint8Array): KeyObject {
+ const id = Buffer.from(seed).toString('base64');
+ return privateKeys.get(id)
+ ?? remember(privateKeys, id, createPrivateKey({ key: Buffer.concat([PKCS8_PREFIX, seed]), format: 'der', type: 'pkcs8' }));
+}
+
+function publicKeyOf(raw: Uint8Array): KeyObject {
+ const id = Buffer.from(raw).toString('base64');
+ return publicKeys.get(id)
+ ?? remember(publicKeys, id, createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: 'der', type: 'spki' }));
+}
+
+export const nodeRelayAuthCrypto: RelayAuthCrypto = {
+ sha256: (data) => createHash('sha256').update(data).digest(),
+ hmacSha256: (key, data) => createHmac('sha256', key).update(data).digest(),
+ ed25519PublicKey(seed) {
+ const der = createPublicKey(privateKeyOf(seed)).export({ format: 'der', type: 'spki' });
+ return new Uint8Array(der.subarray(der.length - 32));
+ },
+ ed25519Sign: (seed, message) => sign(null, message, privateKeyOf(seed)),
+ ed25519Verify(publicKey, message, signature) {
+ if (publicKey.length !== 32 || signature.length !== 64) return false;
+ return verify(null, message, publicKeyOf(publicKey), signature);
+ },
+ randomBytes: (size) => randomBytes(size),
+ utf8: (text) => Buffer.from(text, 'utf8'),
+};
diff --git a/packages/device-link/src/selfHostedRelay.ts b/packages/device-link/src/selfHostedRelay.ts
new file mode 100644
index 0000000000..2844d2eaab
--- /dev/null
+++ b/packages/device-link/src/selfHostedRelay.ts
@@ -0,0 +1,339 @@
+/**
+ * 自建中转:加入链接与加入流程(Desktop / Mobile 共用,fetch 由宿主注入)。
+ *
+ * 加入链接 `<app>://relay/join?u=<中转地址>&c=<一次性加入码>&o=<主人公钥>&s=<配对秘密>`:主人电脑生成,
+ * 另一台电脑粘贴,手机用系统相机扫二维码打开。加入码只能用一次、10 分钟有效;拿到它还要主人在自己的电脑上
+ * 同意,新设备才会拿到只对这个中转有效的凭证(`Authorization: CindyRelay <凭证>`),从不发送账号 token。
+ *
+ * `o` 与 `s` 只在链接里,不发给中转:新设备用 `s` 证明自己的签名公钥(主人核对后签发证书),
+ * 用 `o` 核对中转转交的证书确实出自主人。设备签名见 selfHostedRelayAuth.ts。
+ *
+ * 中转端契约见 `packages/device-link-relay`(`/api/device-link/relay/*`)与 docs/self-hosted-relay-plan.md §6.3。
+ */
+import type { SharedTaskInvitationApp } from './sharedTaskInvitation.js';
+import {
+ computeRelayPairProof,
+ createRelaySigningKey,
+ isRelayPublicKey,
+ verifyRelayDeviceCert,
+ type RelayAuthCrypto,
+ type RelayDeviceCert,
+} from './selfHostedRelayAuth.js';
+
+export const RELAY_JOIN_HOST = 'relay';
+export const RELAY_JOIN_PATH = '/join';
+const RELAY_APPS: ReadonlySet<string> = new Set(['cindy', 'cindycn', 'cindydev']);
+const MAX_LINK_LENGTH = 2048;
+const JOIN_CODE_PATTERN = /^[A-Za-z0-9_-]{16,256}$/;
+const PAIR_SECRET_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+/** 支持设备签名的中转在 `/relay/info` 里声明的能力。 */
+export const RELAY_SIGNATURES_FEATURE = 'device-signatures-v1';
+const API_PREFIX = '/api/device-link';
+
+export interface RelayJoinLink {
+ /** 中转的基础地址(不含 `/api/...`),如 `http://192.168.1.20:47820`。 */
+ baseUrl: string;
+ code: string;
+ /** 主人公钥(base64url):核对中转转交的设备证书。 */
+ ownerPublicKey: string;
+ /** 一次性配对秘密(base64url):新设备用它证明自己的公钥。 */
+ pairSecret: string;
+}
+
+/** 规范化中转地址:只接受 http(s)、不带账号密码 / 查询 / 片段;去掉末尾斜杠。 */
+export function normalizeRelayBaseUrl(value: string): string | null {
+ let url: URL;
+ try {
+ url = new URL(value.trim());
+ } catch {
+ return null;
+ }
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+ if (url.username || url.password || url.search || url.hash || !url.hostname) return null;
+ const pathname = url.pathname.replace(/\/+$/, '');
+ if (pathname.startsWith(API_PREFIX)) return null;
+ return `${url.protocol}//${url.host}${pathname}`;
+}
+
+export function buildRelayJoinLink(input: {
+ baseUrl: string;
+ code: string;
+ ownerPublicKey: string;
+ pairSecret: string;
+ app: SharedTaskInvitationApp;
+}): string {
+ const baseUrl = normalizeRelayBaseUrl(input.baseUrl);
+ if (
+ !baseUrl ||
+ !JOIN_CODE_PATTERN.test(input.code) ||
+ !isRelayPublicKey(input.ownerPublicKey) ||
+ !PAIR_SECRET_PATTERN.test(input.pairSecret) ||
+ !RELAY_APPS.has(input.app)
+ ) {
+ throw new Error('Invalid relay join link');
+ }
+ const query = new URLSearchParams({ u: baseUrl, c: input.code, o: input.ownerPublicKey, s: input.pairSecret });
+ return `${input.app}://${RELAY_JOIN_HOST}${RELAY_JOIN_PATH}?${query.toString()}`;
+}
+
+/**
+ * 解析加入链接。同时接受完整链接 `cindy://relay/join?...` 与路由层收到的路径形态 `/relay/join?...`
+ * (Expo Router 的 native intent 只给 path)。不合法一律返回 null。
+ */
+export function parseRelayJoinLink(value: string): RelayJoinLink | null {
+ const trimmed = value.trim();
+ if (!trimmed || trimmed.length > MAX_LINK_LENGTH) return null;
+ const match = /^(?:([a-z]+):\/\/relay|\/relay)\/join\/?\?(.*)$/i.exec(trimmed);
+ if (!match) return null;
+ if (match[1] && !RELAY_APPS.has(match[1].toLowerCase())) return null;
+ const params = new URLSearchParams(match[2]);
+ const rawBase = params.get('u');
+ const code = params.get('c');
+ const ownerPublicKey = params.get('o');
+ const pairSecret = params.get('s');
+ if (!rawBase || !code || !JOIN_CODE_PATTERN.test(code)) return null;
+ if (!isRelayPublicKey(ownerPublicKey) || !pairSecret || !PAIR_SECRET_PATTERN.test(pairSecret)) return null;
+ const baseUrl = normalizeRelayBaseUrl(rawBase);
+ return baseUrl ? { baseUrl, code, ownerPublicKey, pairSecret } : null;
+}
+
+// ─── 加入流程 ────────────────────────────────────────────────────────────────
+
+export interface RelayFetchResponse {
+ ok: boolean;
+ status: number;
+ json(): Promise<unknown>;
+}
+
+export type RelayFetch = (
+ url: string,
+ init: { method: string; headers?: Record<string, string>; body?: string; signal?: AbortSignal },
+) => Promise<RelayFetchResponse>;
+
+export type RelayJoinErrorCode =
+ /** 连不上这个地址(网络不通、地址写错、中转没开)。 */
+ | 'UNREACHABLE'
+ /** 地址能访问,但不是 Cindy 中转。 */
+ | 'NOT_A_RELAY'
+ /** 中转的协议版本与本机不兼容。 */
+ | 'INCOMPATIBLE'
+ /** 中转属于另一个 Cindy 账号。 */
+ | 'ACCOUNT_MISMATCH'
+ /** 加入码无效、已用过或已过期。 */
+ | 'CODE_INVALID'
+ | 'RATE_LIMITED'
+ /** 主人拒绝了这次加入。 */
+ | 'REJECTED'
+ /** 等待主人同意超时。 */
+ | 'EXPIRED'
+ /** 中转转交的证书不是加入链接里那位主人签发的:中转可能被人替换,不要加入。 */
+ | 'OWNER_MISMATCH'
+ | 'CANCELLED'
+ | 'FAILED';
+
+export class RelayJoinError extends Error {
+ constructor(
+ readonly code: RelayJoinErrorCode,
+ message: string,
+ ) {
+ super(message);
+ this.name = 'RelayJoinError';
+ }
+}
+
+export interface RelayInfo {
+ relayId: string;
+ name: string;
+ protocolVersion: number;
+ relayVersion: string;
+}
+
+export interface RelayPairRequest {
+ requestId: string;
+ pollToken: string;
+ /** 4 位核对码:与主人电脑上显示的一致才应同意。 */
+ verifyCode: string;
+}
+
+export interface RelayPairResult {
+ credential: string;
+ deviceId: string;
+ /** 主人签发的设备证书(未核对,用 `acceptRelayDeviceCert` 核对)。 */
+ cert: unknown;
+}
+
+async function call(
+ fetchFn: RelayFetch,
+ url: string,
+ init: { method: string; headers?: Record<string, string>; body?: string; signal?: AbortSignal },
+): Promise<{ status: number; ok: boolean; body: Record<string, unknown> | null }> {
+ let res: RelayFetchResponse;
+ try {
+ res = await fetchFn(url, init);
+ } catch (error) {
+ if (init.signal?.aborted) throw new RelayJoinError('CANCELLED', 'cancelled');
+ throw new RelayJoinError('UNREACHABLE', error instanceof Error ? error.message : 'request failed');
+ }
+ let body: Record<string, unknown> | null = null;
+ try {
+ const parsed = await res.json();
+ body = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+ } catch {
+ body = null;
+ }
+ return { status: res.status, ok: res.ok, body };
+}
+
+function errorCodeOf(body: Record<string, unknown> | null): string | undefined {
+ const error = body?.error as { code?: unknown } | undefined;
+ return typeof error?.code === 'string' ? error.code : undefined;
+}
+
+/** 加入前探测:地址可达、确实是 Cindy 中转、协议版本兼容。 */
+export async function fetchRelayInfo(fetchFn: RelayFetch, baseUrl: string, signal?: AbortSignal): Promise<RelayInfo> {
+ const { ok, body } = await call(fetchFn, `${baseUrl}${API_PREFIX}/relay/info`, { method: 'GET', signal });
+ if (!ok || !body || typeof body.relayId !== 'string' || typeof body.name !== 'string') {
+ throw new RelayJoinError('NOT_A_RELAY', 'address is not a Cindy relay');
+ }
+ if (
+ body.protocolVersion !== 1 ||
+ !Array.isArray(body.features) ||
+ !body.features.includes('pairing-v1') ||
+ !body.features.includes(RELAY_SIGNATURES_FEATURE)
+ ) {
+ throw new RelayJoinError('INCOMPATIBLE', 'relay protocol is not supported');
+ }
+ return {
+ relayId: body.relayId,
+ name: body.name,
+ protocolVersion: body.protocolVersion,
+ relayVersion: typeof body.relayVersion === 'string' ? body.relayVersion : '',
+ };
+}
+
+export async function submitRelayPairRequest(
+ fetchFn: RelayFetch,
+ link: RelayJoinLink,
+ device: {
+ deviceId: string;
+ deviceName: string;
+ platform: string;
+ appVersion: string;
+ accountUserId: string;
+ /** 新设备的签名公钥与配对证明,见 `createRelayJoinIdentity`。 */
+ publicKey: string;
+ proof: string;
+ },
+ signal?: AbortSignal,
+): Promise<RelayPairRequest> {
+ const { ok, status, body } = await call(fetchFn, `${link.baseUrl}${API_PREFIX}/relay/pair`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ code: link.code, ...device, deviceName: device.deviceName.slice(0, 64) }),
+ signal,
+ });
+ if (ok && body && typeof body.requestId === 'string' && typeof body.pollToken === 'string' && typeof body.verifyCode === 'string') {
+ return { requestId: body.requestId, pollToken: body.pollToken, verifyCode: body.verifyCode };
+ }
+ const code = errorCodeOf(body);
+ if (code === 'ACCOUNT_MISMATCH') throw new RelayJoinError('ACCOUNT_MISMATCH', 'relay belongs to another account');
+ if (status === 429) throw new RelayJoinError('RATE_LIMITED', 'too many attempts');
+ if (status === 403) throw new RelayJoinError('CODE_INVALID', 'join code is invalid or expired');
+ throw new RelayJoinError('FAILED', `pairing request failed (${status})`);
+}
+
+/**
+ * 等主人同意:反复长轮询直到同意、拒绝、过期或超过 `deadlineMs`。
+ * 凭证只返回一次;拿到后调用方必须立即保存到安全存储。
+ */
+export async function waitForRelayApproval(
+ fetchFn: RelayFetch,
+ link: RelayJoinLink,
+ request: RelayPairRequest,
+ options: { signal?: AbortSignal; deadlineMs?: number; now?: () => number } = {},
+): Promise<RelayPairResult> {
+ const now = options.now ?? Date.now;
+ const deadline = now() + (options.deadlineMs ?? 10 * 60 * 1000);
+ let failures = 0;
+ while (now() < deadline) {
+ if (options.signal?.aborted) throw new RelayJoinError('CANCELLED', 'cancelled');
+ let result: Awaited<ReturnType<typeof call>>;
+ try {
+ result = await call(
+ fetchFn,
+ `${link.baseUrl}${API_PREFIX}/relay/pair/${encodeURIComponent(request.requestId)}?wait=20`,
+ { method: 'GET', headers: { 'X-Cindy-Relay-Poll-Token': request.pollToken }, signal: options.signal },
+ );
+ } catch (error) {
+ // 等待期间网络抖一下不算失败;连续多次连不上才放弃。
+ if (error instanceof RelayJoinError && error.code === 'UNREACHABLE' && ++failures < 5) {
+ await new Promise((resolve) => setTimeout(resolve, 2_000));
+ continue;
+ }
+ throw error;
+ }
+ failures = 0;
+ const status = result.body?.status;
+ if (status === 'approved' && typeof result.body?.credential === 'string' && typeof result.body?.deviceId === 'string') {
+ return { credential: result.body.credential, deviceId: result.body.deviceId, cert: result.body.cert };
+ }
+ if (status === 'rejected') throw new RelayJoinError('REJECTED', 'the owner rejected this device');
+ if (status === 'expired') throw new RelayJoinError('EXPIRED', 'the request expired');
+ if (status !== 'pending') throw new RelayJoinError('FAILED', `unexpected pairing state (${result.status})`);
+ }
+ throw new RelayJoinError('EXPIRED', 'timed out waiting for approval');
+}
+
+// ─── 设备签名相关 ────────────────────────────────────────────────────────────
+
+export interface RelayJoinIdentity {
+ /** 本机签名私钥种子(base64url),加入成功后存进安全存储。 */
+ seed: string;
+ publicKey: string;
+ /** 用链接里的配对秘密对公钥做的证明,随申请提交。 */
+ proof: string;
+}
+
+/** 为这次加入生成本机签名密钥,并用链接里的配对秘密做公钥证明。 */
+export function createRelayJoinIdentity(
+ crypto: RelayAuthCrypto,
+ link: RelayJoinLink,
+ relayId: string,
+ deviceId: string,
+): RelayJoinIdentity {
+ const key = createRelaySigningKey(crypto);
+ return {
+ seed: key.seed,
+ publicKey: key.publicKey,
+ proof: computeRelayPairProof(crypto, link.pairSecret, { relayId, deviceId, publicKey: key.publicKey }),
+ };
+}
+
+/** 核对主人签发的证书:必须出自链接里的主人、发给本机这把公钥。 */
+export function acceptRelayDeviceCert(
+ crypto: RelayAuthCrypto,
+ link: RelayJoinLink,
+ input: { relayId: string; deviceId: string; publicKey: string; cert: unknown },
+): RelayDeviceCert {
+ const cert = verifyRelayDeviceCert(crypto, link.ownerPublicKey, input.relayId, input.cert);
+ if (!cert || cert.deviceId !== input.deviceId || cert.publicKey !== input.publicKey || cert.role !== 'member') {
+ throw new RelayJoinError('OWNER_MISMATCH', 'the relay returned a certificate the owner did not issue');
+ }
+ return cert;
+}
+
+/** 取中转上全部设备证书(未核对;交给 `RelayFrameAuthenticator.setCertificates` 用主人公钥逐个核对)。 */
+export async function fetchRelayCertificates(
+ fetchFn: RelayFetch,
+ baseUrl: string,
+ credential: string,
+ signal?: AbortSignal,
+): Promise<unknown[]> {
+ const { ok, status, body } = await call(fetchFn, `${baseUrl}${API_PREFIX}/relay/certs`, {
+ method: 'GET',
+ headers: { Authorization: `CindyRelay ${credential}` },
+ signal,
+ });
+ if (!ok || !body || !Array.isArray(body.certs)) throw new RelayJoinError('FAILED', `certificate list unavailable (${status})`);
+ return body.certs;
+}
diff --git a/packages/device-link/src/selfHostedRelayAuth.ts b/packages/device-link/src/selfHostedRelayAuth.ts
new file mode 100644
index 0000000000..a5686fa437
--- /dev/null
+++ b/packages/device-link/src/selfHostedRelayAuth.ts
@@ -0,0 +1,444 @@
+/**
+ * 自建中转的设备签名:让中转(哪怕所在服务器被人控制)无法冒充你的设备发消息。
+ *
+ * - 每台设备有自己的 Ed25519 签名密钥;主人电脑用「主人密钥」给每台设备签发证书
+ * (中转 ID + 设备 ID + 设备公钥)。主人公钥随加入链接 / 二维码交给新设备,不经中转。
+ * - 加入时新设备用链接里的一次性配对秘密(同样不经中转)对自己的公钥做 HMAC,主人电脑核对后
+ * 才签发证书:中转换不掉新设备的公钥。
+ * - 经中转转发的每条对端消息都带 `auth`:时间戳 + 本次启动标识 + 递增计数 + 签名,签名覆盖
+ * 中转 ID、收发设备、类型、请求 ID 与完整内容。收到方核对证书、签名、时间与计数,任一不符即丢弃。
+ *
+ * 本模块不依赖任何加密库:Desktop 注入 node:crypto,Mobile 注入 @noble。方案见
+ * docs/self-hosted-relay-plan.md §16。
+ */
+
+export const RELAY_CERT_VERSION = 1;
+/** 时间戳允许的误差:设备时钟差太多时消息会被拒绝。 */
+export const RELAY_FRAME_MAX_SKEW_MS = 10 * 60 * 1000;
+
+const CERT_CONTEXT = 'cindy-relay-cert/1';
+const FRAME_CONTEXT = 'cindy-relay-frame/1';
+const PAIR_CONTEXT = 'cindy-relay-pair/1';
+const KEY_32_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const SIGNATURE_PATTERN = /^[A-Za-z0-9_-]{86}$/;
+const BOOT_PATTERN = /^[A-Za-z0-9_-]{16,32}$/;
+const MAX_ID_LENGTH = 256;
+
+export interface RelayAuthCrypto {
+ sha256(data: Uint8Array): Uint8Array;
+ hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array;
+ /** 由 32 字节私钥种子推出公钥。 */
+ ed25519PublicKey(seed: Uint8Array): Uint8Array;
+ ed25519Sign(seed: Uint8Array, message: Uint8Array): Uint8Array;
+ ed25519Verify(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
+ randomBytes(size: number): Uint8Array;
+ /** 可选的原生 UTF-8 编码(Node 的 Buffer 更快);缺省用纯 JS 实现。 */
+ utf8?(text: string): Uint8Array;
+}
+
+export type RelayDeviceRole = 'owner' | 'member';
+
+export interface RelayDeviceCert {
+ v: typeof RELAY_CERT_VERSION;
+ relayId: string;
+ deviceId: string;
+ /** Ed25519 公钥,base64url(32 字节)。 */
+ publicKey: string;
+ role: RelayDeviceRole;
+ issuedAt: number;
+ /** 主人密钥对以上字段的签名,base64url(64 字节)。 */
+ signature: string;
+}
+
+export interface RelayFrameAuth {
+ /** 发送时刻(毫秒)。 */
+ t: number;
+ /** 本次启动的随机标识。 */
+ b: string;
+ /** 本次启动内严格递增的计数。 */
+ c: number;
+ /** 签名,base64url。 */
+ s: string;
+}
+
+// ─── 编码 ────────────────────────────────────────────────────────────────────
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const ALPHABET_INDEX = new Int16Array(128).fill(-1);
+for (let i = 0; i < ALPHABET.length; i++) ALPHABET_INDEX[ALPHABET.charCodeAt(i)] = i;
+
+export function encodeBase64Url(bytes: Uint8Array): string {
+ let out = '';
+ for (let i = 0; i < bytes.length; i += 3) {
+ const a = bytes[i];
+ const b = bytes[i + 1];
+ const c = bytes[i + 2];
+ out += ALPHABET[a >> 2] + ALPHABET[((a & 3) << 4) | ((b ?? 0) >> 4)];
+ if (b !== undefined) out += ALPHABET[((b & 15) << 2) | ((c ?? 0) >> 6)];
+ if (c !== undefined) out += ALPHABET[c & 63];
+ }
+ return out;
+}
+
+export function decodeBase64Url(value: string): Uint8Array | null {
+ if (value.length % 4 === 1) return null;
+ const out = new Uint8Array(Math.floor((value.length * 3) / 4));
+ let bits = 0;
+ let acc = 0;
+ let index = 0;
+ for (let i = 0; i < value.length; i++) {
+ const code = value.charCodeAt(i);
+ const digit = code < 128 ? ALPHABET_INDEX[code] : -1;
+ if (digit < 0) return null;
+ acc = (acc << 6) | digit;
+ bits += 6;
+ if (bits >= 8) {
+ bits -= 8;
+ out[index++] = (acc >> bits) & 0xff;
+ }
+ }
+ // 拒绝非规范编码(末尾多余的位不为 0),保证同一字节串只有一种写法。
+ if ((acc & ((1 << bits) - 1)) !== 0) return null;
+ return out;
+}
+
+export function utf8Bytes(text: string): Uint8Array {
+ const out: number[] = [];
+ for (let i = 0; i < text.length; i++) {
+ let code = text.charCodeAt(i);
+ if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+ const next = text.charCodeAt(i + 1);
+ if (next >= 0xdc00 && next <= 0xdfff) {
+ code = 0x10000 + ((code - 0xd800) << 10) + (next - 0xdc00);
+ i++;
+ }
+ }
+ if (code >= 0xd800 && code <= 0xdfff) code = 0xfffd;
+ if (code < 0x80) out.push(code);
+ else if (code < 0x800) out.push(0xc0 | (code >> 6), 0x80 | (code & 63));
+ else if (code < 0x10000) out.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+ else out.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 63), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+ }
+ return Uint8Array.from(out);
+}
+
+function encodeText(crypto: RelayAuthCrypto, text: string): Uint8Array {
+ return crypto.utf8 ? crypto.utf8(text) : utf8Bytes(text);
+}
+
+function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+ if (a.length !== b.length) return false;
+ let diff = 0;
+ for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+ return diff === 0;
+}
+
+function isShortId(value: unknown): value is string {
+ return typeof value === 'string' && value.length > 0 && value.length <= MAX_ID_LENGTH;
+}
+
+// ─── 密钥 ────────────────────────────────────────────────────────────────────
+
+export interface RelaySigningKey {
+ /** 32 字节私钥种子,base64url。只存安全存储。 */
+ seed: string;
+ publicKey: string;
+}
+
+export function createRelaySigningKey(crypto: RelayAuthCrypto): RelaySigningKey {
+ const seed = crypto.randomBytes(32);
+ return { seed: encodeBase64Url(seed), publicKey: encodeBase64Url(crypto.ed25519PublicKey(seed)) };
+}
+
+export function relayPublicKeyOf(crypto: RelayAuthCrypto, seed: string): string | null {
+ const bytes = KEY_32_PATTERN.test(seed) ? decodeBase64Url(seed) : null;
+ return bytes ? encodeBase64Url(crypto.ed25519PublicKey(bytes)) : null;
+}
+
+export function isRelayPublicKey(value: unknown): value is string {
+ return typeof value === 'string' && KEY_32_PATTERN.test(value) && decodeBase64Url(value) !== null;
+}
+
+/** 一次性配对秘密:只写进加入链接,不发给中转。 */
+export function createRelayPairSecret(crypto: RelayAuthCrypto): string {
+ return encodeBase64Url(crypto.randomBytes(32));
+}
+
+// ─── 加入时的公钥绑定 ─────────────────────────────────────────────────────────
+
+/** 新设备证明「这把公钥是拿着加入链接的那台设备生成的」。 */
+export function computeRelayPairProof(
+ crypto: RelayAuthCrypto,
+ pairSecret: string,
+ input: { relayId: string; deviceId: string; publicKey: string },
+): string {
+ const key = decodeBase64Url(pairSecret);
+ if (!key || key.length !== 32) throw new Error('invalid pairing secret');
+ const message = JSON.stringify([PAIR_CONTEXT, input.relayId, input.deviceId, input.publicKey]);
+ return encodeBase64Url(crypto.hmacSha256(key, encodeText(crypto, message)));
+}
+
+export function verifyRelayPairProof(
+ crypto: RelayAuthCrypto,
+ pairSecret: string,
+ input: { relayId: string; deviceId: string; publicKey: string; proof: unknown },
+): boolean {
+ if (typeof input.proof !== 'string') return false;
+ const actual = decodeBase64Url(input.proof);
+ if (!actual) return false;
+ let expected: Uint8Array;
+ try {
+ expected = decodeBase64Url(computeRelayPairProof(crypto, pairSecret, input))!;
+ } catch {
+ return false;
+ }
+ return constantTimeEqual(actual, expected);
+}
+
+// ─── 设备证书 ────────────────────────────────────────────────────────────────
+
+function certMessage(crypto: RelayAuthCrypto, cert: Omit<RelayDeviceCert, 'signature' | 'v'>): Uint8Array {
+ return encodeText(
+ crypto,
+ JSON.stringify([CERT_CONTEXT, cert.relayId, cert.deviceId, cert.publicKey, cert.role, cert.issuedAt]),
+ );
+}
+
+export function issueRelayDeviceCert(
+ crypto: RelayAuthCrypto,
+ ownerSeed: string,
+ input: { relayId: string; deviceId: string; publicKey: string; role: RelayDeviceRole; issuedAt: number },
+): RelayDeviceCert {
+ const seed = decodeBase64Url(ownerSeed);
+ if (!seed || seed.length !== 32) throw new Error('invalid owner key');
+ if (!isShortId(input.relayId) || !isShortId(input.deviceId) || !isRelayPublicKey(input.publicKey)) {
+ throw new Error('invalid certificate fields');
+ }
+ const body = {
+ relayId: input.relayId,
+ deviceId: input.deviceId,
+ publicKey: input.publicKey,
+ role: input.role,
+ issuedAt: input.issuedAt,
+ };
+ return {
+ v: RELAY_CERT_VERSION,
+ ...body,
+ signature: encodeBase64Url(crypto.ed25519Sign(seed, certMessage(crypto, body))),
+ };
+}
+
+/** 形状正确时返回证书对象;不校验签名(中转只做这一步)。 */
+export function parseRelayDeviceCert(value: unknown): RelayDeviceCert | null {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+ const v = value as Record<string, unknown>;
+ if (
+ v.v !== RELAY_CERT_VERSION ||
+ !isShortId(v.relayId) ||
+ !isShortId(v.deviceId) ||
+ !isRelayPublicKey(v.publicKey) ||
+ (v.role !== 'owner' && v.role !== 'member') ||
+ typeof v.issuedAt !== 'number' ||
+ !Number.isSafeInteger(v.issuedAt) ||
+ typeof v.signature !== 'string' ||
+ !SIGNATURE_PATTERN.test(v.signature)
+ ) {
+ return null;
+ }
+ return {
+ v: RELAY_CERT_VERSION,
+ relayId: v.relayId,
+ deviceId: v.deviceId,
+ publicKey: v.publicKey,
+ role: v.role,
+ issuedAt: v.issuedAt,
+ signature: v.signature,
+ };
+}
+
+/** 用主人公钥核对证书;不属于这个中转或签名不对时返回 null。 */
+export function verifyRelayDeviceCert(
+ crypto: RelayAuthCrypto,
+ ownerPublicKey: string,
+ relayId: string,
+ value: unknown,
+): RelayDeviceCert | null {
+ const cert = parseRelayDeviceCert(value);
+ if (!cert || cert.relayId !== relayId) return null;
+ const owner = decodeBase64Url(ownerPublicKey);
+ const signature = decodeBase64Url(cert.signature);
+ if (!owner || owner.length !== 32 || !signature) return null;
+ try {
+ return crypto.ed25519Verify(owner, certMessage(crypto, cert), signature) ? cert : null;
+ } catch {
+ return null;
+ }
+}
+
+// ─── 消息签名 ────────────────────────────────────────────────────────────────
+
+/** 经中转转发的帧里参与签名的字段(与 wire envelope 同名)。 */
+export interface RelaySignableFrame {
+ kind: string;
+ id?: string;
+ src?: string;
+ dst?: string;
+ payload?: unknown;
+}
+
+export type RelayFrameVerdict =
+ | 'ok'
+ | 'unsigned'
+ | 'malformed'
+ | 'wrong-target'
+ | 'unknown-signer'
+ | 'stale'
+ | 'replayed'
+ | 'bad-signature';
+
+interface BootWindow {
+ lastCounter: number;
+ lastSentAt: number;
+}
+
+export interface RelayFrameAuthenticatorOptions {
+ crypto: RelayAuthCrypto;
+ relayId: string;
+ /** 本机在这个中转上的设备 ID(证书里的 deviceId)。 */
+ deviceId: string;
+ /** 本机签名密钥种子。 */
+ seed: string;
+ /** 加入时从链接取得(或本机即主人)的主人公钥;所有证书都用它核对。 */
+ ownerPublicKey: string;
+ now?: () => number;
+ /** 收到不认识的设备发来的消息时调用,宿主据此刷新证书列表。 */
+ onUnknownSigner?: (deviceId: string) => void;
+}
+
+export class RelayFrameAuthenticator {
+ readonly relayId: string;
+ readonly deviceId: string;
+ readonly ownerPublicKey: string;
+ private readonly crypto: RelayAuthCrypto;
+ private readonly seed: Uint8Array;
+ private readonly now: () => number;
+ private readonly onUnknownSigner?: (deviceId: string) => void;
+ private readonly bootId: string;
+ private counter = 0;
+ private signers = new Map<string, { publicKey: Uint8Array; cert: RelayDeviceCert }>();
+ private readonly windows = new Map<string, Map<string, BootWindow>>();
+ private verifiedSinceSweep = 0;
+
+ constructor(options: RelayFrameAuthenticatorOptions) {
+ const seed = decodeBase64Url(options.seed);
+ if (!seed || seed.length !== 32) throw new Error('invalid signing key');
+ if (!isRelayPublicKey(options.ownerPublicKey)) throw new Error('invalid owner public key');
+ this.crypto = options.crypto;
+ this.relayId = options.relayId;
+ this.deviceId = options.deviceId;
+ this.ownerPublicKey = options.ownerPublicKey;
+ this.seed = seed;
+ this.now = options.now ?? Date.now;
+ this.onUnknownSigner = options.onUnknownSigner;
+ this.bootId = encodeBase64Url(options.crypto.randomBytes(12));
+ }
+
+ /** 用主人公钥逐个核对后替换证书列表;返回被拒绝的数量。 */
+ setCertificates(certs: readonly unknown[]): { accepted: number; rejected: number } {
+ const next = new Map<string, { publicKey: Uint8Array; cert: RelayDeviceCert }>();
+ let rejected = 0;
+ for (const raw of certs) {
+ const cert = verifyRelayDeviceCert(this.crypto, this.ownerPublicKey, this.relayId, raw);
+ const publicKey = cert ? decodeBase64Url(cert.publicKey) : null;
+ if (!cert || !publicKey) {
+ rejected++;
+ continue;
+ }
+ next.set(cert.deviceId, { publicKey, cert });
+ }
+ this.signers = next;
+ return { accepted: next.size, rejected };
+ }
+
+ hasSigner(deviceId: string): boolean {
+ return this.signers.has(deviceId);
+ }
+
+ sign(frame: RelaySignableFrame): RelayFrameAuth {
+ const t = this.now();
+ const c = ++this.counter;
+ const digest = this.digest(frame, this.deviceId, frame.dst ?? '', t, this.bootId, c);
+ return { t, b: this.bootId, c, s: encodeBase64Url(this.crypto.ed25519Sign(this.seed, digest)) };
+ }
+
+ /** 入参是刚解析出的 wire 帧(任意形状),字段类型在这里逐个核对。 */
+ verify(frame: Readonly<Record<string, unknown>>): RelayFrameVerdict {
+ const src = frame.src;
+ const kind = frame.kind;
+ const id = frame.id;
+ if (!isShortId(src) || typeof kind !== 'string' || (id !== undefined && typeof id !== 'string')) return 'malformed';
+ // 自建中转上没有跨账号范围的帧;出现即视为伪造。
+ if (frame.sharedTask !== undefined || frame.providerShare !== undefined) return 'unsigned';
+ const auth = frame.auth as Partial<RelayFrameAuth> | undefined;
+ if (!auth || typeof auth !== 'object') return 'unsigned';
+ if (
+ typeof auth.t !== 'number' ||
+ !Number.isSafeInteger(auth.t) ||
+ typeof auth.b !== 'string' ||
+ !BOOT_PATTERN.test(auth.b) ||
+ typeof auth.c !== 'number' ||
+ !Number.isSafeInteger(auth.c) ||
+ auth.c <= 0 ||
+ typeof auth.s !== 'string' ||
+ !SIGNATURE_PATTERN.test(auth.s)
+ ) {
+ return 'malformed';
+ }
+ if (frame.dst !== this.deviceId) return 'wrong-target';
+ const signer = this.signers.get(src);
+ if (!signer) {
+ this.onUnknownSigner?.(src);
+ return 'unknown-signer';
+ }
+ const now = this.now();
+ if (Math.abs(now - auth.t) > RELAY_FRAME_MAX_SKEW_MS) return 'stale';
+ const boots = this.windows.get(src);
+ const window = boots?.get(auth.b);
+ if (window && auth.c <= window.lastCounter) return 'replayed';
+ const signature = decodeBase64Url(auth.s);
+ if (!signature) return 'malformed';
+ let valid = false;
+ try {
+ valid = this.crypto.ed25519Verify(
+ signer.publicKey,
+ this.digest({ kind, id, payload: frame.payload }, src, this.deviceId, auth.t, auth.b, auth.c),
+ signature,
+ );
+ } catch {
+ valid = false;
+ }
+ if (!valid) return 'bad-signature';
+ const perSource = boots ?? new Map<string, BootWindow>();
+ perSource.set(auth.b, { lastCounter: auth.c, lastSentAt: Math.max(window?.lastSentAt ?? 0, auth.t) });
+ this.windows.set(src, perSource);
+ if (++this.verifiedSinceSweep >= 1000) this.sweep(now);
+ return 'ok';
+ }
+
+ /** 一次启动的最后一条消息也过期后,它的计数窗口就不再需要:之后的重放都会因过期被拒。 */
+ private sweep(now: number): void {
+ this.verifiedSinceSweep = 0;
+ for (const [src, boots] of this.windows) {
+ for (const [boot, window] of boots) {
+ if (now - window.lastSentAt > 2 * RELAY_FRAME_MAX_SKEW_MS) boots.delete(boot);
+ }
+ if (boots.size === 0) this.windows.delete(src);
+ }
+ }
+
+ private digest(frame: RelaySignableFrame, src: string, dst: string, t: number, b: string, c: number): Uint8Array {
+ const header = JSON.stringify([FRAME_CONTEXT, this.relayId, src, dst, frame.kind, frame.id ?? null, t, b, c]);
+ const body = frame.payload === undefined ? '' : JSON.stringify(frame.payload);
+ return this.crypto.sha256(encodeText(this.crypto, `${header}\n${body}`));
+ }
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1de5721f12..7c8fad3263 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -119,6 +119,9 @@ importers:
'@cindy/device-link':
specifier: workspace:*
version: link:../../packages/device-link
+ '@cindy/device-link-relay':
+ specifier: workspace:*
+ version: link:../../packages/device-link-relay
'@cindy/embedding-client':
specifier: workspace:*
version: link:../../packages/embedding-client
@@ -1031,6 +1034,37 @@ importers:
specifier: ^5.7.0
version: 5.9.3
+ packages/device-link-relay:
+ dependencies:
+ '@cindy/device-link':
+ specifier: workspace:*
+ version: link:../device-link
+ '@cindy/device-link-protocol':
+ specifier: workspace:*
+ version: link:../device-link-protocol
+ ws:
+ specifier: ^8.18.3
+ version: 8.21.1
+ devDependencies:
+ '@types/node':
+ specifier: '*'
+ version: 25.9.5
+ '@types/ws':
+ specifier: ^8.18.1
+ version: 8.18.1
+ esbuild:
+ specifier: ^0.28.1
+ version: 0.28.1
+ tsx:
+ specifier: ^4.19.0
+ version: 4.23.1
+ typescript:
+ specifier: ^5.7.0
+ version: 5.9.3
+ vitest:
+ specifier: ^3.2.4
+
packages/embedding-client:
devDependencies:
'@types/node':
diff --git a/scripts/device-link/clientHarness.ts b/scripts/device-link/clientHarness.ts
index ed663daca9..8b45b8d83d 100644
--- a/scripts/device-link/clientHarness.ts
+++ b/scripts/device-link/clientHarness.ts
@@ -4,6 +4,7 @@ import {
PeerRecoveryScheduler,
DeviceLinkError,
PROTOCOL_VERSION,
+ type DeviceLinkFrameAuth,
type DeviceLinkTiming,
type Envelope,
type InvokePayload,
@@ -21,8 +22,11 @@ export function createClient(
host = false,
options: {
token?: string;
+ authorizationScheme?: "Bearer" | "CindyRelay";
timing?: Partial<DeviceLinkTiming>;
desktop?: boolean;
+ /** 自建中转的设备签名钩子(与 Desktop / Mobile 传给 DeviceLinkClient 的同一选项)。 */
+ frameAuth?: () => DeviceLinkFrameAuth | null;
} = {},
) {
const sockets: WebSocket[] = [];
@@ -31,6 +35,8 @@ export function createClient(
const client = new DeviceLinkClient({
getWsUrl: () => url,
getToken: async () => options.token ?? `fixture-${id}`,
+ authorizationScheme: options.authorizationScheme,
+ frameAuth: options.frameAuth,
getHello: () => ({
deviceName: `Integration ${id}`,
platform: host || options.desktop ? "darwin" : "ios",
diff --git a/scripts/device-link/interop.test.ts b/scripts/device-link/interop.test.ts
index 4eb647cf1e..50404d3c2f 100644
--- a/scripts/device-link/interop.test.ts
+++ b/scripts/device-link/interop.test.ts
@@ -1,10 +1,44 @@
import { expect, it, vi } from "vitest";
+import { nodeRelayAuthCrypto } from "../../packages/device-link/src/nodeRelayCrypto";
+import { RelayFrameAuthenticator } from "../../packages/device-link/src/selfHostedRelayAuth";
import {
createClient,
createHost,
createMobileRecovery,
} from "./clientHarness";
+interface FrameAuthSpec {
+ relayId: string;
+ ownerPublicKey: string;
+ certs: unknown[];
+ host: { deviceId: string; seed: string };
+ controller: { deviceId: string; seed: string };
+}
+
+/**
+ * 自建中转的设备签名(可选,由 run-interop 提供测试密钥):主机像电脑一样核对全部对端帧,
+ * 控制端像手机一样只签名。任何绕过签名的发送路径都会让主机丢帧、恢复流程超时。
+ */
+function frameAuthFor(spec: FrameAuthSpec, role: "host" | "controller", rejected: string[]) {
+ const auth = new RelayFrameAuthenticator({
+ crypto: nodeRelayAuthCrypto,
+ relayId: spec.relayId,
+ deviceId: spec[role].deviceId,
+ seed: spec[role].seed,
+ ownerPublicKey: spec.ownerPublicKey,
+ });
+ auth.setCertificates(spec.certs);
+ return () => ({
+ sign: (frame: Parameters<RelayFrameAuthenticator["sign"]>[0]) => auth.sign(frame),
+ verify: (frame: Readonly<Record<string, unknown>>) => {
+ if (role === "controller") return true;
+ const verdict = auth.verify(frame);
+ if (verdict !== "ok") rejected.push(`${String(frame.kind)}:${verdict}`);
+ return verdict === "ok";
+ },
+ });
+}
+
it("interoperates with an explicitly provisioned isolated relay and automatically reconnects", async () => {
const url = process.env.CINDY_TEST_RELAY_URL;
const hostToken = process.env.CINDY_TEST_HOST_TOKEN;
@@ -31,6 +65,11 @@ it("interoperates with an explicitly provisioned isolated relay and automaticall
"Test relay URL must be ws(s), without credentials, query or fragment.",
);
}
+ // 官方测试 relay 用账号 access token(Bearer);自建中转用加入时拿到的设备凭证(CindyRelay)。
+ const scheme = process.env.CINDY_TEST_AUTH_SCHEME ?? "Bearer";
+ if (scheme !== "Bearer" && scheme !== "CindyRelay") {
+ throw new Error("CINDY_TEST_AUTH_SCHEME must be Bearer or CindyRelay.");
+ }
const timing = {
requestTimeoutMs: 10_000,
pingIntervalMs: 5_000,
@@ -38,13 +77,21 @@ it("interoperates with an explicitly provisioned isolated relay and automaticall
reconnectBaseMs: 500,
reconnectMaxMs: 2_000,
};
+ const frameAuthSpec = process.env.CINDY_TEST_FRAME_AUTH
+ ? (JSON.parse(process.env.CINDY_TEST_FRAME_AUTH) as FrameAuthSpec)
+ : null;
+ const rejected: string[] = [];
const host = createClient(url, "interop-host", true, {
token: hostToken,
+ authorizationScheme: scheme,
timing,
+ frameAuth: frameAuthSpec ? frameAuthFor(frameAuthSpec, "host", rejected) : undefined,
});
const controller = createClient(url, "interop-controller", false, {
token: controllerToken,
+ authorizationScheme: scheme,
timing,
+ frameAuth: frameAuthSpec ? frameAuthFor(frameAuthSpec, "controller", rejected) : undefined,
});
const data = createHost(host.client);
let recovery: ReturnType<typeof createMobileRecovery> | undefined;
@@ -74,6 +121,7 @@ it("interoperates with an explicitly provisioned isolated relay and automaticall
"interop-gap",
]);
expect(controller.sockets.length).toBeGreaterThan(1);
+ expect(rejected).toEqual([]);
} finally {
recovery?.close();
data.close();
diff --git a/scripts/test-workspaces.config.mjs b/scripts/test-workspaces.config.mjs
index 7c3520d129..430f24a423 100644
--- a/scripts/test-workspaces.config.mjs
+++ b/scripts/test-workspaces.config.mjs
@@ -514,6 +514,7 @@ export default {
requiredUnitWorkspace('@cindy/browser-control-runtime', 'packages/browser-control-runtime'),
requiredUnitWorkspace('cindy-tools', 'packages/cindy-tools'),
requiredUnitWorkspace('@cindy/device-link', 'packages/device-link'),
+ requiredUnitWorkspace('@cindy/device-link-relay', 'packages/device-link-relay'),
noCollectableWorkspace('@cindy/embedding-client', 'packages/embedding-client'),
requiredUnitWorkspace('@cindy/file-browser-core', 'packages/file-browser-core'),
noCollectableWorkspace('@cindy/github-client', 'packages/github-client'),