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。

fix(device-link): bind relay frames to the receiver lifetime

MagicLiziaa00d858f2f7
diff --git a/apps/desktop/src/main/device-link/__tests__/selfHostedRelayFrameAuth.test.ts b/apps/desktop/src/main/device-link/__tests__/selfHostedRelayFrameAuth.test.ts
index e4f5399181..8f42febd0b 100644
--- a/apps/desktop/src/main/device-link/__tests__/selfHostedRelayFrameAuth.test.ts
+++ b/apps/desktop/src/main/device-link/__tests__/selfHostedRelayFrameAuth.test.ts
@@ -8,7 +8,7 @@
* - 单文件实测:1.04 秒(1 例,测试体 9ms,Windows)。
*/
import { afterEach, expect, it, vi } from 'vitest';
-import { createRelaySigningKey, issueRelayDeviceCert, RelayFrameAuthenticator } from '@cindy/device-link';
+import { createRelaySigningKey, issueRelayDeviceCert, RELAY_AUTH_CHANNEL, RelayFrameAuthenticator, type Envelope } from '@cindy/device-link';
import { nodeRelayAuthCrypto as crypto } from '@cindy/device-link/node-relay-crypto';
import { setSelfHostedRelaySource } from '../selfHostedRelayRouting';
@@ -42,6 +42,12 @@ it('refreshes a rejoined device key with throttling while rejecting its first un
const auth = currentRelayFrameAuth()!;
await vi.advanceTimersByTimeAsync(0);
const signer = new RelayFrameAuthenticator({ crypto, relayId, deviceId: 'peer', seed: peer.seed, ownerPublicKey: owner.publicKey });
+ signer.setCertificates([issueRelayDeviceCert(crypto, owner.seed, {
+ relayId, deviceId: 'self', publicKey: self.publicKey, role: 'member', issuedAt: 1,
+ })]);
+ const challenge: Envelope = { v: 1, kind: 'push', id: 'auth-1', src: 'self', dst: 'peer',
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'request' } } };
+ expect(signer.verify({ ...challenge, auth: auth.sign(challenge) })).toBe('ok');
const frame = { kind: 'push', src: 'peer', dst: 'self', payload: { value: 1 } };
const signed = () => ({ ...frame, auth: signer.sign(frame) });
const pending = signed();
diff --git a/apps/desktop/src/main/device-link/selfHostedRelayFrameAuth.ts b/apps/desktop/src/main/device-link/selfHostedRelayFrameAuth.ts
index a7a155ac15..f22ed24164 100644
--- a/apps/desktop/src/main/device-link/selfHostedRelayFrameAuth.ts
+++ b/apps/desktop/src/main/device-link/selfHostedRelayFrameAuth.ts
@@ -90,6 +90,7 @@ function create(relay: ActiveSelfHostedRelay): Current {
relay,
authenticator,
frameAuth: {
+ peerChallenge: { session: authenticator, state: deviceId => authenticator.peerChallenge(deviceId) },
sign: (frame) => authenticator.sign(frame),
verify: (frame) => {
const verdict = authenticator.verify(frame);
diff --git a/apps/mobile/src/__tests__/selfHostedRelaySignatures.test.ts b/apps/mobile/src/__tests__/selfHostedRelaySignatures.test.ts
index 908812f8af..cea8e39af6 100644
--- a/apps/mobile/src/__tests__/selfHostedRelaySignatures.test.ts
+++ b/apps/mobile/src/__tests__/selfHostedRelaySignatures.test.ts
@@ -21,6 +21,7 @@ import {
DeviceLinkClient,
issueRelayDeviceCert,
PROTOCOL_VERSION,
+ RELAY_AUTH_CHANNEL,
RelayFrameAuthenticator,
verifyRelayPairProof,
type Envelope,
@@ -45,7 +46,7 @@ afterEach(() => {
vi.useRealTimers();
});
-it('phone (@noble) and computer (node:crypto) accept each other’s pairing proof, certificate and frame signatures', () => {
+it('phone (@noble) and computer (node:crypto) accept each other’s pairing proof, certificate and frame signatures', async () => {
const relayId = 'relay-7f3c';
const phoneId = 'phone-1';
const computerId = 'computer-1';
@@ -82,15 +83,26 @@ it('phone (@noble) and computer (node:crypto) accept each other’s pairing proo
credential: 'relay-credential',
signing: { deviceId: phoneId, ownerPublicKey: owner.publicKey, seed: identity.seed },
});
+ const computerKey = createRelaySigningKey(nodeRelayAuthCrypto);
+ const computerCert = issueRelayDeviceCert(nodeRelayAuthCrypto, owner.seed, {
+ relayId, deviceId: computerId, publicKey: computerKey.publicKey, role: 'member', issuedAt: 1,
+ });
+ vi.mocked(fetch).mockResolvedValue(new Response(JSON.stringify({ certs: [computerCert] }), { status: 200 }));
const phone = currentSelfHostedRelayFrameAuth()!;
const computer = new RelayFrameAuthenticator({
crypto: nodeRelayAuthCrypto,
relayId,
deviceId: computerId,
- seed: createRelaySigningKey(nodeRelayAuthCrypto).seed,
+ seed: computerKey.seed,
ownerPublicKey: owner.publicKey,
});
expect(computer.setCertificates([cert])).toEqual({ accepted: 1, rejected: 0 });
+ const challenge: Envelope = { v: PROTOCOL_VERSION, kind: 'push', id: 'auth-1', src: phoneId, dst: computerId,
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'request' } } };
+ expect(computer.verify({ ...challenge, auth: phone.sign(challenge) })).toBe('ok');
+ const response: Envelope = { ...challenge, src: computerId, dst: phoneId,
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'response' } } };
+ await vi.waitFor(() => expect(phone.verify({ ...response, auth: computer.sign(response) })).toBe(true));
// 手机发出时没有 src,中转转发时填上。
const invoke = (args: unknown[]): Envelope => ({
@@ -126,9 +138,18 @@ function incomingFixture() {
const cert = (publicKey: string, signerSeed = owner.seed) => issueRelayDeviceCert(nodeRelayAuthCrypto, signerSeed, {
relayId: route.relayId, deviceId: 'computer-1', publicKey, role: 'member', issuedAt: 1,
});
- const sender = (seed = peer.seed) => new RelayFrameAuthenticator({
- crypto: nodeRelayAuthCrypto, relayId: route.relayId, deviceId: 'computer-1', seed, ownerPublicKey: owner.publicKey,
- });
+ const sender = (seed = peer.seed) => {
+ const auth = new RelayFrameAuthenticator({
+ crypto: nodeRelayAuthCrypto, relayId: route.relayId, deviceId: 'computer-1', seed, ownerPublicKey: owner.publicKey,
+ });
+ auth.setCertificates([issueRelayDeviceCert(nodeRelayAuthCrypto, owner.seed, {
+ relayId: route.relayId, deviceId: 'phone-1', publicKey: phone.publicKey, role: 'member', issuedAt: 1,
+ })]);
+ const challenge: Envelope = { v: PROTOCOL_VERSION, kind: 'push', id: 'auth-1', src: 'phone-1', dst: 'computer-1',
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'request' } } };
+ auth.verify({ ...challenge, auth: currentSelfHostedRelayFrameAuth()!.sign(challenge) });
+ return auth;
+ };
const signed = (auth: RelayFrameAuthenticator, payload: unknown): Envelope => {
const frame = { v: PROTOCOL_VERSION, kind: 'push' as const, src: 'computer-1', dst: 'phone-1', payload };
return { ...frame, auth: auth.sign(frame) } as Envelope;
diff --git a/apps/mobile/src/device-link/selfHostedRelayFrameAuth.ts b/apps/mobile/src/device-link/selfHostedRelayFrameAuth.ts
index 613c90bf7b..cfe40396e0 100644
--- a/apps/mobile/src/device-link/selfHostedRelayFrameAuth.ts
+++ b/apps/mobile/src/device-link/selfHostedRelayFrameAuth.ts
@@ -99,6 +99,7 @@ export function currentSelfHostedRelayFrameAuth(): DeviceLinkFrameAuth | null {
key, baseUrl: relay.baseUrl, credential: relay.credential, authenticator,
refreshing: null, controller: null, lastRefreshAt: -Infinity,
frameAuth: {
+ peerChallenge: { session: authenticator, state: deviceId => authenticator.peerChallenge(deviceId) },
sign: frame => cached === target ? authenticator.sign(frame) : undefined,
verify: frame => {
if (cached !== target) return false;
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index f96ef5a640..731e65a177 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -264,13 +264,18 @@ stream 匹配后才处理;信令不进入业务可靠 FIFO,也不走直连
`/relay/blob/*`(媒体签名地址)。官方 relay 没有这些路径,客户端只在自建模式下调用。
- 设备签名([方案 §16](../self-hosted-relay-plan.md)):经自建中转转发的对端帧多一个顶层字段
- `auth: { t, b, c, s }`,中转原样转发、不解析(超过 512 字符或不是对象时回 `BAD_REQUEST`)。
+ `auth: { t, b, r, 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`(主人签发的设备证书)。
- Desktop 与 Mobile 都在分发前核对入站帧,包含权限请求文案;证书未就绪时拒绝当前帧,
未知设备或已知设备签名不符时有界刷新,不重连共享链路。Mobile 复用已有纯 JS 加密实现。
+ - 签名上下文 `cindy-relay-frame/2` 包含接收端启动挑战 `r`,避免接收端重启后旧请求再次执行。
+ 共享客户端消费保留的 `device-link:relay-auth` push 请求/响应;仅认证请求允许空挑战,
+ 不进入业务分发、不建立控制链路、不改变远控开关。待发队列按稳定签名身份和设备隔离,超时/断线/换身份后不发送旧请求。
+ 中转已有 push 与 opaque auth 转发足够支持,无需新增协议 kind 或修改路由;互通同时覆盖关闭远控的手机接收插件同步与未建链查询。
+ 此自建功能尚未发布,开发期间旧的无 `r` 签名客户端需同步更新;官方客户端路径无此交换。
- 加入申请必须带 `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` /
diff --git a/docs/self-hosted-relay-plan.md b/docs/self-hosted-relay-plan.md
index f311b494ac..a5389f0ac2 100644
--- a/docs/self-hosted-relay-plan.md
+++ b/docs/self-hosted-relay-plan.md
@@ -660,12 +660,17 @@ App 内不加扫码组件:加一个会改变原生指纹,需要冷更。
### 16.3 每条消息的签名
-经中转转发的对端帧(`ROUTED_KINDS`)都带 `auth: { t, b, c, s }`:
+经中转转发的对端帧(`ROUTED_KINDS`)都带 `auth: { t, b, r, c, s }`:
- `t`:发送时刻(毫秒),收到时与本机时钟相差超过 10 分钟即拒绝。
- `b`:本次启动的随机标识;`c`:本次启动内严格递增的计数。收到方按「发送设备 + 启动标识」记下最大计数,不大于它的一律视为重放。启动标识的最后一条消息也过期后清理记录,内存不随消息量增长。
+- `r`:收件设备本次启动的随机挑战,签名必须绑定它。重启后挑战变化,即使计数窗口已经清空,旧建链或写请求也不能再次执行。
+ 双方先在保留的 `device-link:relay-auth` push 通道交换已签名的 request / response;仅完整的认证 request 允许空挑战,
+ 接收端验签后直接消费认证消息,不进入业务 handler、不建立远控链路,也不改变开关、订阅或权限。
+ 因而关闭远控的手机仍能接收插件同步;未建链的允许查询沿用原有权限边界。
+ 首次业务消息在客户端按设备有界排队,认证重试不重连共享 socket;超时、断线或签名身份变化后不再发送旧请求。
- `s`:Ed25519 签名。签名对象是以下内容的 SHA-256:
- - `JSON.stringify(["cindy-relay-frame/1", 中转ID, 发送设备, 收件设备, kind, id, t, b, c])`;
+ - `JSON.stringify(["cindy-relay-frame/2", 中转ID, 发送设备, 收件设备, kind, id, t, b, r, c])`;
- 换行;
- `JSON.stringify(payload)`。
- 中转转发时会重新序列化帧,JSON 解析再序列化在 V8 与 Hermes 上都保持不变。
@@ -691,3 +696,5 @@ App 内不加扫码组件:加一个会改变原生指纹,需要冷更。
- 旧格式的加入链接(没有 `o` / `s`)会被拒绝;
- 不支持 `device-signatures-v1` 的中转不能加入。
- 自建中转从未发布过,不存在需要迁移的用户数据。第 2 步开发期间留下的本机配置会被忽略并清掉旧凭证文件。
+- 开发期间不含接收端挑战的旧签名客户端不兼容本次签名格式,需同步更新 Desktop / Mobile;
+ 中转仅原样转发 `auth` 与已有 push,无需更改已实现的服务端路由。
diff --git a/packages/device-link/TESTING.md b/packages/device-link/TESTING.md
index 1587256ab3..b478068e12 100644
--- a/packages/device-link/TESTING.md
+++ b/packages/device-link/TESTING.md
@@ -80,6 +80,8 @@ pnpm --filter @cindy/device-link-relay run interop
这条命令还会通过 `CINDY_TEST_FRAME_AUTH` 交出两台设备的测试签名密钥与中转上的证书,互通用例因此全程开启
设备签名:主机与控制端都像正式 Desktop / Mobile 一样核对每一条对端消息。任何绕过签名的发送路径都会让接收端丢帧、
恢复流程超时(见 docs/self-hosted-relay-plan.md §16)。不设这个变量时行为与官方 relay 的互通完全相同。
+开启设备签名时,还先验证关闭远控的控制端可通过独立认证挑战接收插件同步,以及未建链的允许查询;
+认证 push 不进入业务分发。共享客户端单测另验证重启后旧写请求拒绝、认证期间超时/换身份不再发送及另一设备不受影响。
仅使用**专用隔离测试环境**签发的两台测试设备身份,不能使用日常账号或正在连接的设备:
用例会注册一个允许被控的内存 host,并主动断开自己创建的 socket。脚本不启动、停止、
diff --git a/packages/device-link/src/__tests__/client.test.ts b/packages/device-link/src/__tests__/client.test.ts
index 7f4e279b71..413d927e17 100644
--- a/packages/device-link/src/__tests__/client.test.ts
+++ b/packages/device-link/src/__tests__/client.test.ts
@@ -42,7 +42,7 @@ 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 { createRelaySigningKey, issueRelayDeviceCert, RELAY_AUTH_CHANNEL, RelayFrameAuthenticator } from '../selfHostedRelayAuth.js';
import {
DIRECT_PATH_HIGH_WATER_BYTES,
type DeviceLinkDirectChannel,
@@ -396,6 +396,175 @@ describe('outbound invoke admission', () => {
* 最小失败输入:未签名 / 他人密钥签名 / 签名后改内容 / 原样重放的同一条 push。
*/
describe('self-hosted relay device signatures', () => {
+ function signingPeers(ids: string[]) {
+ const owner = createRelaySigningKey(nodeRelayAuthCrypto);
+ const keys = new Map(ids.map(id => [id, createRelaySigningKey(nodeRelayAuthCrypto)]));
+ const certs = [...keys].map(([deviceId, key]) => issueRelayDeviceCert(nodeRelayAuthCrypto, owner.seed, {
+ relayId: 'test-relay', deviceId, publicKey: key.publicKey, role: 'member', issuedAt: 1,
+ }));
+ return (deviceId: string) => {
+ const auth = new RelayFrameAuthenticator({ crypto: nodeRelayAuthCrypto, relayId: 'test-relay', deviceId,
+ seed: keys.get(deviceId)!.seed, ownerPublicKey: owner.publicKey });
+ auth.setCertificates(certs);
+ return auth;
+ };
+ }
+
+ function frameAuth(auth: RelayFrameAuthenticator) {
+ return { sign: (env: Readonly<Envelope>) => auth.sign(env),
+ verify: (env: Readonly<Record<string, unknown>>) => auth.verify(env) === 'ok',
+ peerChallenge: { session: auth, state: (peer: string) => auth.peerChallenge(peer) } };
+ }
+
+ // 认证只交换签名挑战,不能隐式调用 openLink;未建链查询与手机关闭远控时的插件同步必须继续可用。
+ // 生产 DeviceLinkClient + 双端真实密钥,经 MemoryRelay 验证业务分发结果,tier: unit。
+ it('authenticates unlinked queries and plugin pushes without opening a control link', async () => {
+ vi.useFakeTimers();
+ const relay = new MemoryRelay();
+ const signer = signingPeers(['host', 'phone']);
+ const signerHost = signer('host'), signerPhone = signer('phone');
+ const host = makeRelayClient(relay, 'host', undefined, { frameAuth: () => frameAuth(signerHost) });
+ const phone = makeRelayClient(relay, 'phone', undefined, { frameAuth: () => frameAuth(signerPhone), remoteControlEnabled: false });
+ const received: Envelope[] = [];
+ const pump = () => relay.settle(async () => { await vi.advanceTimersByTimeAsync(0); });
+ host.onFrame(env => {
+ received.push(env);
+ if (env.kind === 'invoke') host.sendInvokeResult(env.src!, env.id!, { ok: true, result: ['visible'] });
+ });
+ phone.onFrame(env => received.push(env));
+ try {
+ host.start(); phone.start(); await pump();
+ host.sendPush('phone', PLUGIN_SYNC_CHANNEL, { version: 1, type: 'snapshot' });
+ await pump();
+ expect(received.filter(env => env.kind === 'push').map(env => env.payload))
+ .toEqual([{ channel: PLUGIN_SYNC_CHANNEL, payload: { version: 1, type: 'snapshot' } }]);
+ const query = phone.invoke('host', { channel: 'local-db:sessions:list', args: [] });
+ await pump();
+ await expect(query).resolves.toEqual({ ok: true, result: ['visible'] });
+ const delivered = [...relay.deliveredTo.values()].flat();
+ expect(delivered.some(env => env.kind === 'link-open' || env.kind === 'link-accept')).toBe(false);
+ expect(delivered.some(env => (env.payload as { channel?: string })?.channel === RELAY_AUTH_CHANNEL)).toBe(true);
+ expect(received.some(env => (env.payload as { channel?: string })?.channel === RELAY_AUTH_CHANNEL)).toBe(false);
+ } finally { host.stop(); phone.stop(); vi.useRealTimers(); }
+ });
+
+ // 首发在挑战完成前排队;过期或身份切换后,迟到的认证回复不能让旧写操作执行。
+ it.each(['expired', 'identity-changed', 'closed'] as const)('never sends a queued write after it is %s while another peer remains usable', async mode => {
+ vi.useFakeTimers();
+ const signer = signingPeers(['dev-self', 'blocked', 'healthy']);
+ let self = signer('dev-self');
+ const blocked = signer('blocked'), healthy = signer('healthy');
+ const h = makeHarness({ timing: { pingIntervalMs: 60_000, requestTimeoutMs: 10_000 },
+ frameAuth: () => frameAuth(self) });
+ const answerChallenge = (peer: RelayFrameAuthenticator) => {
+ const request = h.current().sent.filter(env => env.dst === peer.deviceId &&
+ (env.payload as { channel?: string })?.channel === RELAY_AUTH_CHANNEL).at(-1)!;
+ expect(peer.verify({ ...request, src: 'dev-self' })).toBe('ok');
+ const response: Envelope = { v: 1, kind: 'push', id: request.id, src: peer.deviceId, dst: 'dev-self',
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'response' } } };
+ h.current().push({ ...response, auth: peer.sign(response) } as Envelope);
+ };
+ try {
+ h.client.start(); await vi.advanceTimersByTimeAsync(0); h.current().ack();
+ const write = h.client.invoke('blocked', { channel: 'maker:create-session', args: [] }, 20).catch(error => error);
+ if (mode === 'expired') await vi.advanceTimersByTimeAsync(21);
+ else if (mode === 'identity-changed') self = signer('dev-self');
+ else h.client.closeLink('blocked', 'user');
+ answerChallenge(blocked);
+ expect(h.current().sent.some(env => env.kind === 'invoke' && env.dst === 'blocked')).toBe(false);
+ if (mode === 'identity-changed') await vi.advanceTimersByTimeAsync(1_000);
+ expect(await write).toMatchObject({ code: mode === 'expired' ? 'BACKPRESSURE'
+ : mode === 'closed' ? 'LINK_NOT_OPEN' : 'NOT_CONNECTED', inFlight: false });
+ const read = h.client.invoke('healthy', { channel: 'local-db:sessions:list', args: [] });
+ answerChallenge(healthy);
+ const request = h.current().sent.find(env => env.kind === 'invoke' && env.dst === 'healthy')!;
+ const result: Envelope = { v: 1, kind: 'invoke-result', id: request.id, src: 'healthy', dst: 'dev-self',
+ payload: { ok: true, result: [] } };
+ h.current().push({ ...result, auth: healthy.sign(result) } as Envelope);
+ await expect(read).resolves.toEqual({ ok: true, result: [] });
+ expect(h.sockets).toHaveLength(1);
+ } finally { h.client.stop(); vi.useRealTimers(); }
+ });
+
+ // 已协商可靠流后认证器更新,完整大请求必须仍由可靠层分片;认证等待不能计作已写 socket。
+ it('keeps a fragmented request in the reliable stream until fresh authentication completes', async () => {
+ vi.useFakeTimers();
+ const relay = new MemoryRelay();
+ const signer = signingPeers(['host', 'phone']);
+ const hostAuth = signer('host');
+ let phoneAuth = signer('phone');
+ const host = makeRelayClient(relay, 'host', undefined, { frameAuth: () => frameAuth(hostAuth) });
+ const phone = makeRelayClient(relay, 'phone', undefined, { frameAuth: () => frameAuth(phoneAuth) });
+ const executed: unknown[] = [];
+ const pump = () => relay.settle(async () => { await vi.advanceTimersByTimeAsync(0); });
+ host.onFrame(env => {
+ if (env.kind === 'link-open') host.sendLinkAccept(env.src!, env.id!, { appVersion: '1', allowlistHash: 'hash' });
+ if (env.kind === 'invoke') {
+ executed.push(env.payload);
+ host.sendInvokeResult(env.src!, env.id!, { ok: true, result: 'complete' });
+ }
+ });
+ try {
+ host.start(); phone.start(); await pump();
+ const opening = phone.openLink('host', { controllerName: 'Phone', protocolVersion: 1, appVersion: '1' });
+ await pump(); await opening;
+ phoneAuth = signer('phone');
+ const payload = { channel: 'maker:send', args: ['x'.repeat(2 * MAX_TRANSPORT_CHUNK_BYTES)] };
+ const request = phone.invoke('host', payload);
+ expect(executed).toEqual([]);
+ await pump();
+ await expect(request).resolves.toEqual({ ok: true, result: 'complete' });
+ expect(executed).toEqual([payload]);
+ const fragments = (relay.deliveredTo.get('host') ?? []).filter(env => env.kind === 'invoke');
+ expect(fragments.length).toBeGreaterThan(1);
+ } finally { host.stop(); phone.stop(); vi.useRealTimers(); }
+ });
+
+ // #7722 discussion_r4403285988:内存计数在接收端重启后消失,旧写请求不能在十分钟内再次执行。
+ // 真实认证器公开握手/验签入口;重放建链和invoke,并验证新的握手仍能恢复正常写请求。tier: unit。
+ it('binds requests to the receiver boot so a restart cannot replay an executed write', () => {
+ const owner = createRelaySigningKey(nodeRelayAuthCrypto);
+ const keys = { host: createRelaySigningKey(nodeRelayAuthCrypto), peer: createRelaySigningKey(nodeRelayAuthCrypto) };
+ const certs = Object.entries(keys).map(([deviceId, key]) => issueRelayDeviceCert(nodeRelayAuthCrypto, owner.seed, {
+ relayId: 'restart-relay', deviceId, publicKey: key.publicKey, role: 'member', issuedAt: 1,
+ }));
+ const create = (deviceId: 'host' | 'peer') => {
+ const auth = new RelayFrameAuthenticator({
+ crypto: nodeRelayAuthCrypto, relayId: 'restart-relay', deviceId, seed: keys[deviceId].seed, ownerPublicKey: owner.publicKey,
+ });
+ auth.setCertificates(certs);
+ return auth;
+ };
+ const peer = create('peer');
+ const host = create('host');
+ const challenge = { kind: 'push', id: 'auth-1', src: 'peer', dst: 'host',
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'request' } } };
+ const signedChallenge = { ...challenge, auth: peer.sign(challenge) };
+ expect(host.verify(signedChallenge)).toBe('ok');
+ const acceptance = { kind: 'push', id: 'auth-1', src: 'host', dst: 'peer',
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'response' } } };
+ expect(peer.verify({ ...acceptance, auth: host.sign(acceptance) })).toBe('ok');
+ const opening = { kind: 'link-open', id: 'open-1', src: 'peer', dst: 'host', payload: {} };
+ const signedOpen = { ...opening, auth: peer.sign(opening) };
+ expect(host.verify(signedOpen)).toBe('ok');
+ const write = { kind: 'invoke', id: 'write-1', src: 'peer', dst: 'host', payload: { channel: 'maker:create-session', args: [] } };
+ const executed = { ...write, auth: peer.sign(write) };
+ expect(host.verify(executed)).toBe('ok');
+ expect(host.verify(executed)).toBe('replayed');
+
+ const restarted = create('host');
+ expect(restarted.verify(signedChallenge)).toBe('ok');
+ expect(restarted.verify(signedOpen)).toBe('wrong-session');
+ expect(restarted.verify(executed)).toBe('wrong-session');
+ const receiverBoot = restarted.sign(acceptance).b;
+ // 仅替换挑战也无效;挑战本身必须在签名范围内。
+ expect(restarted.verify({ ...executed, auth: { ...executed.auth, r: receiverBoot } })).toBe('bad-signature');
+ expect(restarted.verify({ ...challenge, id: 'auth-2', auth: peer.sign({ ...challenge, id: 'auth-2' }) })).toBe('ok');
+ const newAcceptance = { ...acceptance, auth: restarted.sign(acceptance) };
+ expect(peer.verify(newAcceptance)).toBe('ok');
+ expect(restarted.verify({ ...write, id: 'write-2', auth: peer.sign({ ...write, id: 'write-2' }) })).toBe('ok');
+ });
+
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);
@@ -414,6 +583,12 @@ describe('self-hosted relay device signatures', () => {
};
const self = authenticator('dev-self', selfKey.seed);
const peer = authenticator('dev-b', peerKey.seed);
+ const challenge = { kind: 'push', id: 'auth-1', src: 'dev-self', dst: 'dev-b',
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'request' } } };
+ expect(peer.verify({ ...challenge, auth: self.sign(challenge) })).toBe('ok');
+ const response = { ...challenge, src: 'dev-b', dst: 'dev-self',
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'response' } } };
+ expect(self.verify({ ...response, auth: peer.sign(response) })).toBe('ok');
const h = makeHarness({
timing: { pingIntervalMs: 60_000 },
frameAuth: () => ({ sign: (frame) => self.sign(frame), verify: (frame) => self.verify(frame) === 'ok' }),
@@ -858,7 +1033,8 @@ function makeRelayClient(
relay: MemoryRelay,
deviceId: string,
timing?: ConstructorParameters<typeof DeviceLinkClient>[0]['timing'],
- extra?: Pick<ConstructorParameters<typeof DeviceLinkClient>[0], 'transferCodec' | 'invokeMetrics' | 'directRuntime'>,
+ extra?: Pick<ConstructorParameters<typeof DeviceLinkClient>[0], 'transferCodec' | 'invokeMetrics' | 'directRuntime' | 'frameAuth'>
+ & { remoteControlEnabled?: boolean },
): DeviceLinkClient {
return new DeviceLinkClient({
...extra,
@@ -868,7 +1044,7 @@ function makeRelayClient(
deviceName: deviceId,
platform: 'darwin',
appVersion: '1.0.0',
- remoteControlEnabled: true,
+ remoteControlEnabled: extra?.remoteControlEnabled ?? true,
busy: false,
}),
createWebSocket: () => relay.makeWebSocket(deviceId),
diff --git a/packages/device-link/src/client.ts b/packages/device-link/src/client.ts
index 6e887b737c..ce0c17adb9 100644
--- a/packages/device-link/src/client.ts
+++ b/packages/device-link/src/client.ts
@@ -70,6 +70,7 @@ import {
type RetransmitEstimate,
} from './transport.js';
import { PLUGIN_SYNC_CHANNEL } from './pluginSyncProtocol.js';
+import { RELAY_AUTH_CHANNEL, relayAuthHandshake } from './selfHostedRelayAuth.js';
import { DIRECT_LINK_CAPABILITY, DIRECT_LINK_SIGNAL, DirectLinkNegotiator, parseDirectSignal,
type DirectRuntime } from './directNegotiation.js';
import { MAKER_EVENT_BATCH_CHANNEL } from './topics.js';
@@ -258,6 +259,21 @@ export type DeviceLinkAuthorizationScheme = 'Bearer' | 'ProviderShareGuest' | 'C
export interface DeviceLinkFrameAuth {
sign(frame: Readonly<Envelope>): unknown;
verify(frame: Readonly<Record<string, unknown>>): boolean;
+ /** 稳定身份用于隔离账号切换前的待发消息;认证交换不创建远控链路。 */
+ peerChallenge?: {
+ session: object;
+ state(deviceId: string): 'ready' | 'needed' | 'unknown';
+ };
+}
+
+interface RelayChallengeQueue {
+ session: object;
+ id: string;
+ startedAt: number;
+ startedMonotonicAt: number;
+ lastProbeAt: number;
+ timer: ReturnType<typeof setTimeout> | null;
+ frames: Map<string, { env: Envelope; bytes: number; pending?: PendingRequest }>;
}
export interface DeviceLinkClientOptions {
@@ -597,6 +613,8 @@ interface PendingReliableMessage {
sent: boolean;
/** 入队时刻(monotonicNow 单调时钟);push 帧按 TRANSPORT_PENDING_PUSH_MAX_AGE_MS 判定过期。 */
enqueuedAt: number;
+ /** 认证身份切换后,旧业务不能用新身份重新签名发送。 */
+ relaySigningSession?: object;
/**
* 本轮(attempts 归零后)首次真正写出的时刻(monotonicNow)。enqueuedAt 可能早于
* 发送(link 未就绪时排队),判断「对端有过 ACK 机会却没回」必须从首发算起。
@@ -831,6 +849,9 @@ export class DeviceLinkClient {
private selfDeviceId: string | null = null;
private readonly pending = new Map<string, PendingRequest>();
+ private readonly relayChallenges = new Map<string, RelayChallengeQueue>();
+ private relayChallengeBytes = 0;
+ private relayChallengeFrames = 0;
/**
* 每个控制端/被控端各自维护一个 stream。stream 在 relay 重连时保留,
* 这样未 ACK 的消息可以在重新 openLink 后继续重发;旧 stream 不会混入
@@ -1518,6 +1539,7 @@ export class DeviceLinkClient {
peer.linkAcceptedInbound = false;
}
} else {
+ this.cancelRelayQueuedControl(dst);
this.rejectPendingLinkOpen(
dst,
'LINK_NOT_OPEN',
@@ -2325,6 +2347,7 @@ export class DeviceLinkClient {
private clearTimers(): void {
this.clearNetworkProbe();
+ for (const peer of this.relayChallenges.keys()) this.clearRelayChallenge(peer);
if (this.reconnectTimer) {
clearTimeout(this.reconnectTimer);
this.reconnectTimer = null;
@@ -2401,10 +2424,14 @@ export class DeviceLinkClient {
return;
}
// 自建中转:对端帧必须带发送设备的有效签名(在任何解码与分发之前核对,中转改不了内容)。
+ const frameAuth = this.opts.frameAuth?.();
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);
+ if (frameAuth.peerChallenge?.state(parsed.src) === 'needed') {
+ try { this.probeRelayChallenge(parsed.src, this.ensureRelayChallenge(parsed.src, frameAuth)); }
+ catch { /* 认证重试有界;失败不触发共享 socket 重连。 */ }
+ }
return;
}
}
@@ -2429,6 +2456,22 @@ export class DeviceLinkClient {
}
}
+ if (frameAuth?.peerChallenge && env.src && ROUTED_KINDS.has(env.kind)) {
+ const handshake = relayAuthHandshake(env);
+ if (handshake === 'request') {
+ // 只回送认证证明,不调用业务 handler,也不改变 remoteControlEnabled 或订阅。
+ try {
+ this.sendEnvelope({ v: PROTOCOL_VERSION, kind: 'push', id: env.id, dst: env.src,
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'response' } } });
+ } catch { /* 对端会在自己的预算内重试。 */ }
+ return;
+ }
+ if (handshake === 'response') {
+ if (frameAuth.peerChallenge.state(env.src) === 'ready') this.flushRelayChallenge(env.src, frameAuth);
+ return;
+ }
+ }
+
const ack = parseTransportAck(env);
if (ack) {
if (env.src) {
@@ -3349,6 +3392,7 @@ export class DeviceLinkClient {
lastSentAt: 0,
sent: false,
enqueuedAt: this.monotonicNow(),
+ relaySigningSession: this.opts.frameAuth?.()?.peerChallenge?.session,
lastBlockedBy: willSendNow ? undefined : !this.isPeerSendReady(peer) ? 'link'
: this.isOutsideReceiveWindow(peer, seq) ? 'receive-window'
: this.shouldHoldRecoverySend(peer, additionalFrames) ? 'recovery-ack' : 'relay-budget',
@@ -3386,6 +3430,18 @@ export class DeviceLinkClient {
* 一分片都没写出才抛;中途竞态只返回已上网的帧数,让恢复预算能结算部分突发。
*/
private sendReliableFrames(peer: PeerTransportState, pending: PendingReliableMessage): number {
+ const frameAuth = this.opts.frameAuth?.();
+ if (pending.relaySigningSession !== frameAuth?.peerChallenge?.session) {
+ pending.relaySigningSession = frameAuth?.peerChallenge?.session;
+ const id = pending.envelope.id!;
+ const request = this.pending.get(id);
+ if (request) {
+ this.pending.delete(id);
+ request.reject(new DeviceLinkError('NOT_CONNECTED', 'relay signing identity changed'));
+ }
+ this.dropReliablePendingForRequest(pending.envelope.dst!, id);
+ return 0;
+ }
// A resume/ACK callback can run before the overdue timeout callback. The
// existing timeout path substitutes a skip at the same sequence number;
// never retransmit an expired command just because its timer ran late.
@@ -3412,6 +3468,13 @@ export class DeviceLinkClient {
const head = peer.pending.values().next().value;
if (head && head !== pending && !head.sent) return 0;
}
+ if (frameAuth?.peerChallenge && frameAuth.peerChallenge.state(pending.envelope.dst!) !== 'ready') {
+ // 逻辑消息保留在已有可靠 pending;分片不能挤进认证队列或被误记为物理已发送。
+ const dst = pending.envelope.dst!;
+ this.probeRelayChallenge(dst, this.ensureRelayChallenge(dst, frameAuth));
+ pending.lastBlockedBy = 'link';
+ return 0;
+ }
const peers = this.getReadyReliablePeers(pending.envelope.dst!);
const budgetNow = this.monotonicNow();
const congestionBudget = this.congestionCloseStreak > 0 ? this.congestionSendBudget : null;
@@ -3444,7 +3507,7 @@ export class DeviceLinkClient {
for (const frame of frames) {
// pending 可在 link down 时入队,并在后续 link generation 才首次上网;
// 路由错误必须归属每次真实物理发送,而不是逻辑消息的入队代次。
- this.sendRoutedEnvelope(frame, peer.linkGeneration);
+ this.sendRoutedEnvelope(frame, peer.linkGeneration, true);
writtenBytes += byteLength(JSON.stringify(encodeScopedEnvelope(frame, ALL_SCOPES)));
pending.sent = true;
sent += 1;
@@ -3765,12 +3828,132 @@ export class DeviceLinkClient {
this.rejectedSignatureCount = 0;
}
- private sendEnvelope(env: Envelope): void {
+ private ensureRelayChallenge(dst: string, auth: DeviceLinkFrameAuth): RelayChallengeQueue {
+ const session = auth.peerChallenge!.session;
+ let queue = this.relayChallenges.get(dst);
+ if (queue && queue.session !== session) {
+ this.clearRelayChallenge(dst, new DeviceLinkError('NOT_CONNECTED', 'relay signing identity changed'));
+ queue = undefined;
+ }
+ if (queue) return queue;
+ if (this.relayChallenges.size >= 32) throw new DeviceLinkError('BACKPRESSURE', 'relay authentication queue is full');
+ queue = { session, id: createRequestId(), startedAt: Date.now(), startedMonotonicAt: this.monotonicNow(),
+ lastProbeAt: -Infinity, timer: null, frames: new Map() };
+ this.relayChallenges.set(dst, queue);
+ const retry = () => {
+ queue!.timer = null;
+ if (this.relayChallenges.get(dst) !== queue) return;
+ const current = this.opts.frameAuth?.();
+ if (current?.peerChallenge?.session !== session) {
+ this.clearRelayChallenge(dst, new DeviceLinkError('NOT_CONNECTED', 'relay signing identity changed'));
+ return;
+ }
+ if (Date.now() - queue!.startedAt >= this.timing.requestTimeoutMs
+ || this.monotonicNow() - queue!.startedMonotonicAt >= this.timing.requestTimeoutMs) {
+ this.clearRelayChallenge(dst, new DeviceLinkError('BACKPRESSURE', 'relay authentication timed out before socket write'));
+ return;
+ }
+ try { this.probeRelayChallenge(dst, queue!); } catch { /* 有界预算内再试。 */ }
+ if (this.relayChallenges.get(dst) !== queue) return;
+ queue!.timer = setTimeout(retry, Math.min(1_000, Math.max(100, this.timing.transportRetryIntervalMs)));
+ };
+ queue.timer = setTimeout(retry, Math.min(1_000, Math.max(100, this.timing.transportRetryIntervalMs)));
+ return queue;
+ }
+
+ private probeRelayChallenge(dst: string, queue: RelayChallengeQueue): void {
+ if (this.monotonicNow() - queue.lastProbeAt < 100) return;
+ queue.lastProbeAt = this.monotonicNow();
+ this.sendEnvelope({ v: PROTOCOL_VERSION, kind: 'push', id: queue.id, dst,
+ payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'request' } } });
+ }
+
+ private clearRelayChallenge(dst: string, error?: DeviceLinkError): RelayChallengeQueue | undefined {
+ const queue = this.relayChallenges.get(dst);
+ if (!queue) return;
+ this.relayChallenges.delete(dst);
+ if (queue.timer) clearTimeout(queue.timer);
+ for (const { env, bytes, pending } of queue.frames.values()) {
+ this.relayChallengeBytes -= bytes;
+ this.relayChallengeFrames--;
+ if (error && pending && env.id && this.pending.get(env.id) === pending) {
+ this.pending.delete(env.id);
+ this.settleOutboundRouteAttemptsForId(dst, env.id);
+ this.dropReliablePendingForRequest(dst, env.id);
+ pending.reject(error);
+ }
+ }
+ return queue;
+ }
+
+ private cancelRelayQueuedControl(dst: string): void {
+ const queue = this.relayChallenges.get(dst);
+ if (!queue) return;
+ for (const [key, { env, bytes, pending }] of queue.frames) {
+ if (isUnlinkedLegacyEnvelope(env)) continue;
+ queue.frames.delete(key);
+ this.relayChallengeBytes -= bytes;
+ this.relayChallengeFrames--;
+ if (env.id) this.settleOutboundRouteAttemptsForId(dst, env.id);
+ if (pending && env.id && this.pending.get(env.id) === pending) {
+ this.pending.delete(env.id);
+ pending.reject(new DeviceLinkError('LINK_NOT_OPEN', 'control link closed before socket write'));
+ }
+ }
+ }
+
+ private flushRelayChallenge(dst: string, auth: DeviceLinkFrameAuth): void {
+ const queue = this.relayChallenges.get(dst);
+ if (!queue) return;
+ if (queue.session !== auth.peerChallenge?.session) {
+ this.clearRelayChallenge(dst, new DeviceLinkError('NOT_CONNECTED', 'relay signing identity changed'));
+ return;
+ }
+ this.clearRelayChallenge(dst);
+ for (const { env, pending } of queue.frames.values()) {
+ // 超时的写请求绝不能因迟到的认证响应在后台继续发送。
+ if (pending && (this.pending.get(env.id!) !== pending || pending.expireIfOverdue?.())) continue;
+ try {
+ if (this.sendEnvelope(env)) pending?.noteFirstWrite?.();
+ } catch (error) {
+ if (pending && this.pending.get(env.id!) === pending) {
+ this.pending.delete(env.id!);
+ this.settleOutboundRouteAttemptsForId(dst, env.id!);
+ this.dropReliablePendingForRequest(dst, env.id!);
+ pending.reject(error instanceof DeviceLinkError ? error : new DeviceLinkError('NOT_CONNECTED', 'socket write failed'));
+ }
+ }
+ }
+ this.retryPending(dst, { ignoreInterval: false, onlyUnsent: true });
+ }
+
+ private sendEnvelope(env: Envelope, allowAuthenticationQueue = true): boolean {
const ws = this.ws;
if (!ws) throw new DeviceLinkError('NOT_CONNECTED', 'no active connection');
let wire = encodeScopedEnvelope(env, this.scopeSupport());
if (wire.dst && ROUTED_KINDS.has(wire.kind)) {
- const auth = this.opts.frameAuth?.()?.sign(wire);
+ const frameAuth = this.opts.frameAuth?.();
+ if (frameAuth?.peerChallenge && !relayAuthHandshake(wire) && frameAuth.peerChallenge.state(wire.dst) !== 'ready') {
+ const bytes = byteLength(JSON.stringify(wire));
+ if (bytes > MAX_FRAME_BYTES) throw new DeviceLinkError('PAYLOAD_TOO_LARGE', 'frame exceeds relay authentication budget');
+ const queue = this.ensureRelayChallenge(wire.dst, frameAuth);
+ if (!allowAuthenticationQueue) {
+ this.probeRelayChallenge(wire.dst, queue);
+ return false;
+ }
+ const key = `${wire.kind}:${wire.id ?? ''}`;
+ if (!queue.frames.has(key)) {
+ if (this.relayChallengeFrames >= 256 || this.relayChallengeBytes + bytes > 2 * MAX_FRAME_BYTES) {
+ throw new DeviceLinkError('BACKPRESSURE', 'relay authentication queue is full');
+ }
+ queue.frames.set(key, { env, bytes, pending: env.id ? this.pending.get(env.id) : undefined });
+ this.relayChallengeFrames++;
+ this.relayChallengeBytes += bytes;
+ }
+ this.probeRelayChallenge(wire.dst, queue);
+ return false;
+ }
+ const auth = frameAuth?.sign(wire);
if (auth !== undefined) wire = { ...wire, auth } as Envelope;
}
const text = JSON.stringify(wire);
@@ -3786,9 +3969,10 @@ export class DeviceLinkClient {
// 时提前拒绝,避免弱网下 native socket 持续吃内存。
this.assertWebSocketCapacity(frameBytes);
ws.send(text);
+ return true;
}
- private sendRoutedEnvelope(env: Envelope, linkGeneration?: number): string | undefined {
+ private sendRoutedEnvelope(env: Envelope, linkGeneration?: number, requirePhysicalWrite = false): string | undefined {
if (!env.dst) {
this.sendEnvelope(env);
return env.id;
@@ -3797,8 +3981,9 @@ export class DeviceLinkClient {
const generation = linkGeneration ?? this.getPeerLinkGeneration(env.dst);
this.rememberOutboundRouteGeneration(routed.id!, env.dst, generation);
try {
- this.sendEnvelope(routed);
- this.pending.get(routed.id!)?.noteFirstWrite?.();
+ const written = this.sendEnvelope(routed, !requirePhysicalWrite);
+ if (written) this.pending.get(routed.id!)?.noteFirstWrite?.();
+ else if (requirePhysicalWrite) throw new DeviceLinkError('BACKPRESSURE', 'awaiting relay authentication');
} catch (err) {
this.rollbackOutboundRouteGeneration(routed.id!, env.dst, generation);
throw err;
diff --git a/packages/device-link/src/selfHostedRelayAuth.ts b/packages/device-link/src/selfHostedRelayAuth.ts
index a5686fa437..500f62fb46 100644
--- a/packages/device-link/src/selfHostedRelayAuth.ts
+++ b/packages/device-link/src/selfHostedRelayAuth.ts
@@ -5,7 +5,7 @@
* (中转 ID + 设备 ID + 设备公钥)。主人公钥随加入链接 / 二维码交给新设备,不经中转。
* - 加入时新设备用链接里的一次性配对秘密(同样不经中转)对自己的公钥做 HMAC,主人电脑核对后
* 才签发证书:中转换不掉新设备的公钥。
- * - 经中转转发的每条对端消息都带 `auth`:时间戳 + 本次启动标识 + 递增计数 + 签名,签名覆盖
+ * - 经中转转发的每条对端消息都带 `auth`:时间戳 + 双方启动标识 + 递增计数 + 签名,签名覆盖
* 中转 ID、收发设备、类型、请求 ID 与完整内容。收到方核对证书、签名、时间与计数,任一不符即丢弃。
*
* 本模块不依赖任何加密库:Desktop 注入 node:crypto,Mobile 注入 @noble。方案见
@@ -17,12 +17,23 @@ 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 FRAME_CONTEXT = 'cindy-relay-frame/2';
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 const RELAY_AUTH_CHANNEL = 'device-link:relay-auth';
+
+export function relayAuthHandshake(frame: RelaySignableFrame): 'request' | 'response' | null {
+ if (frame.kind !== 'push' || !isShortId(frame.id) || !frame.payload || typeof frame.payload !== 'object') return null;
+ const payload = frame.payload as Record<string, unknown>;
+ if (payload.channel !== RELAY_AUTH_CHANNEL || Object.keys(payload).length !== 2 ||
+ !payload.payload || typeof payload.payload !== 'object' || Array.isArray(payload.payload)) return null;
+ const body = payload.payload as Record<string, unknown>;
+ return Object.keys(body).length === 1 && (body.type === 'request' || body.type === 'response') ? body.type : null;
+}
export interface RelayAuthCrypto {
sha256(data: Uint8Array): Uint8Array;
@@ -55,6 +66,8 @@ export interface RelayFrameAuth {
t: number;
/** 本次启动的随机标识。 */
b: string;
+ /** 接收端本次启动挑战;仅认证挑战请求允许为空。 */
+ r: string;
/** 本次启动内严格递增的计数。 */
c: number;
/** 签名,base64url。 */
@@ -291,6 +304,7 @@ export type RelayFrameVerdict =
| 'unsigned'
| 'malformed'
| 'wrong-target'
+ | 'wrong-session'
| 'unknown-signer'
| 'stale'
| 'replayed'
@@ -327,6 +341,7 @@ export class RelayFrameAuthenticator {
private counter = 0;
private signers = new Map<string, { publicKey: Uint8Array; cert: RelayDeviceCert }>();
private readonly windows = new Map<string, Map<string, BootWindow>>();
+ private readonly peerBoots = new Map<string, { boot: string; ready: boolean }>();
private verifiedSinceSweep = 0;
constructor(options: RelayFrameAuthenticatorOptions) {
@@ -356,6 +371,9 @@ export class RelayFrameAuthenticator {
}
next.set(cert.deviceId, { publicKey, cert });
}
+ for (const [deviceId, previous] of this.signers) {
+ if (next.get(deviceId)?.cert.publicKey !== previous.cert.publicKey) this.peerBoots.delete(deviceId);
+ }
this.signers = next;
return { accepted: next.size, rejected };
}
@@ -364,11 +382,17 @@ export class RelayFrameAuthenticator {
return this.signers.has(deviceId);
}
+ peerChallenge(deviceId: string): 'ready' | 'needed' | 'unknown' {
+ if (!this.signers.has(deviceId)) return 'unknown';
+ return this.peerBoots.get(deviceId)?.ready ? 'ready' : 'needed';
+ }
+
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)) };
+ const r = relayAuthHandshake(frame) === 'request' ? '' : this.peerBoots.get(frame.dst ?? '')?.boot ?? '';
+ const digest = this.digest(frame, this.deviceId, frame.dst ?? '', t, this.bootId, r, c);
+ return { t, b: this.bootId, r, c, s: encodeBase64Url(this.crypto.ed25519Sign(this.seed, digest)) };
}
/** 入参是刚解析出的 wire 帧(任意形状),字段类型在这里逐个核对。 */
@@ -386,6 +410,8 @@ export class RelayFrameAuthenticator {
!Number.isSafeInteger(auth.t) ||
typeof auth.b !== 'string' ||
!BOOT_PATTERN.test(auth.b) ||
+ typeof auth.r !== 'string' ||
+ (auth.r !== '' && !BOOT_PATTERN.test(auth.r)) ||
typeof auth.c !== 'number' ||
!Number.isSafeInteger(auth.c) ||
auth.c <= 0 ||
@@ -411,13 +437,21 @@ export class RelayFrameAuthenticator {
try {
valid = this.crypto.ed25519Verify(
signer.publicKey,
- this.digest({ kind, id, payload: frame.payload }, src, this.deviceId, auth.t, auth.b, auth.c),
+ this.digest({ kind, id, payload: frame.payload }, src, this.deviceId, auth.t, auth.b, auth.r, auth.c),
signature,
);
} catch {
valid = false;
}
if (!valid) return 'bad-signature';
+ const handshake = relayAuthHandshake({ kind, id: typeof id === 'string' ? id : undefined, payload: frame.payload });
+ // 只有已验签的专用认证请求可引导挑战;普通建链、查询、推送和写操作一律绑定接收端。
+ if (handshake !== 'request' && auth.r !== this.bootId) {
+ this.peerBoots.delete(src);
+ return 'wrong-session';
+ }
+ const previous = this.peerBoots.get(src);
+ this.peerBoots.set(src, { boot: auth.b, ready: handshake !== 'request' || (previous?.boot === auth.b && previous.ready) });
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);
@@ -436,8 +470,8 @@ export class RelayFrameAuthenticator {
}
}
- 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]);
+ private digest(frame: RelaySignableFrame, src: string, dst: string, t: number, b: string, r: string, c: number): Uint8Array {
+ const header = JSON.stringify([FRAME_CONTEXT, this.relayId, src, dst, frame.kind, frame.id ?? null, t, b, r, c]);
const body = frame.payload === undefined ? '' : JSON.stringify(frame.payload);
return this.crypto.sha256(encodeText(this.crypto, `${header}\n${body}`));
}
diff --git a/scripts/device-link/interop.test.ts b/scripts/device-link/interop.test.ts
index 5ad893b5a3..d24be82b15 100644
--- a/scripts/device-link/interop.test.ts
+++ b/scripts/device-link/interop.test.ts
@@ -1,6 +1,7 @@
import { expect, it, vi } from "vitest";
import { nodeRelayAuthCrypto } from "../../packages/device-link/src/nodeRelayCrypto";
import { RelayFrameAuthenticator } from "../../packages/device-link/src/selfHostedRelayAuth";
+import { PLUGIN_SYNC_CHANNEL } from "../../packages/device-link/src/pluginSyncProtocol";
import {
createClient,
createHost,
@@ -29,6 +30,7 @@ function frameAuthFor(spec: FrameAuthSpec, role: "host" | "controller", rejected
});
auth.setCertificates(spec.certs);
return () => ({
+ peerChallenge: { session: auth, state: (deviceId: string) => auth.peerChallenge(deviceId) },
sign: (frame: Parameters<RelayFrameAuthenticator["sign"]>[0]) => auth.sign(frame),
verify: (frame: Readonly<Record<string, unknown>>) => {
const verdict = auth.verify(frame);
@@ -101,8 +103,26 @@ it("interoperates with an explicitly provisioned isolated relay and automaticall
});
const hostId = host.client.getSelfDeviceId();
if (!hostId) throw new Error("Test relay did not assign host identity");
- recovery = createMobileRecovery(controller.client, hostId);
controller.client.start();
+ await vi.waitFor(() => expect(controller.client.getStatus()).toBe("online"), { timeout: 10_000 });
+ if (frameAuthSpec) {
+ // 首次认证以关闭远控的手机为目标;不能借用会被 relay 拦截的 link-open。
+ const received: unknown[] = [];
+ const off = controller.client.onFrame(frame => {
+ if (frame.kind === "push") received.push(frame.payload);
+ });
+ try {
+ host.client.sendPush(controller.client.getSelfDeviceId()!, PLUGIN_SYNC_CHANNEL, { version: 1, type: "snapshot" });
+ await vi.waitFor(() => expect(received).toEqual([
+ { channel: PLUGIN_SYNC_CHANNEL, payload: { version: 1, type: "snapshot" } },
+ ]), { timeout: 10_000 });
+ const listing = await controller.client.invoke(hostId, { channel: "local-db:sessions:list", args: [] });
+ expect(listing.ok).toBe(true);
+ expect(data.received.some(frame => frame.kind === "link-open")).toBe(false);
+ } finally { off(); }
+ }
+ recovery = createMobileRecovery(controller.client, hostId);
+ recovery.foreground();
await vi.waitFor(
() => expect(recovery!.state.completed).toBeGreaterThan(0),
{ timeout: 10_000 },