PR #180 解读：pairing 与 device access controls

feat/relay-p1-123 · aa07224 · 对比 merge-base a072104 · 56 个文件

1TL;DR

这个分支把 daemon 的认证模型从“只有本机进程 token”扩成三类主体：daemon-runtime、短期 pairing、持久 device。

本机 CLI 可以生成十分钟、单次使用的配对 offer；远端设备用 offer 连接，只能做 daemon.hello 和 pairing.claim，随后换到一枚可撤销的设备 token。

设备 token 的明文只返回一次，数据库只存 sha256；撤销先提交到 SQLite，再关闭该设备已认证的 tRPC 和 terminal WebSocket，后续 blob 请求也会被拒绝。

同时 daemon 的监听地址与对外地址被拆开：bindHost 决定监听，advertisedBaseUrl 决定 offer 告诉设备去哪里连接。

这还不是完整远程桌面体验：客户端 credential strategy、Electron vault、CSP、桌面配对/切换属于后续 P1.4–P1.6。

2变更地图

测试 1,783 行，非测试 1,606 行。没有 rename；主要变更是新增安全承载代码与对应测试，不是机械搬运。

3架构与状态先行

3.1 principal 不再只是一个字符串

export type DaemonRuntimePrincipal = {
  readonly subject: 'daemon-runtime'
}

export type DevicePrincipal = {
  readonly subject: 'device'
  readonly deviceId: string
}

export type VerifiedPrincipal =
  | DaemonRuntimePrincipal
  | DevicePrincipal
  | PairingPrincipal

subject 现在是权限分流的判别字段。尤其要记住：socket 来自 loopback 不代表本地权限，deriveIsLocal 仍要求主体必须是 daemon-runtime。

3.2 设备是关系实体，offer 是进程内临时状态

export const devicesTable = sqliteTable('devices', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  platform: text('platform').notNull(),
  tokenHash: text('token_hash').notNull(),
  createdAt: integer('created_at').notNull(),
  lastSeenAt: integer('last_seen_at'),
  revokedAt: integer('revoked_at'),
}, (table) => ({
  tokenHashUnique: uniqueIndex('devices_token_hash_unique').on(table.tokenHash),
}))

type PairingOfferRecord = {
  expiresAt: number
}

const offers = new Map<string, PairingOfferRecord>()
const offerHashByPrincipal = new WeakMap<PairingPrincipal, string>()

持久设备行承载“以后还能不能登录”；pairing offer 只承载“一次 enrollment 还是否有效”。offer 不写 KV、不写 DB，daemon 重启就失效。

3.3 offer 自带信任锚与入口

export const pairingOfferSchema = z.object({
  serverId: canonicalBase64url32Schema,
  daemonPublicKey: canonicalBase64url32Schema,
  endpoint: remoteDirectEndpointSchema,
  pairingSecret: pairingSecretSchema,
  expiresAt: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
})

设备拿到的不只是 secret，还拿到稳定 daemon id、公钥、可连接 endpoint 与过期时间。后续客户端工作会用这些字段把“连到哪里”和“应该是谁”绑定起来。

4共用底座：网络地址与 credential dispatcher

三条旅程都依赖两个底座：daemon 必须能监听远程可达地址；所有 carrier 必须把同一段 credential 解释成同一种 principal。

export function createCredentialVerifier(deps: CredentialVerifierDeps): CredentialVerifier {
  return (candidate) => {
    if (!candidate) return null
    if (candidate.startsWith(DEVICE_CREDENTIAL_PREFIX)) {
      return deps.devices.verify(candidate.slice(DEVICE_CREDENTIAL_PREFIX.length))
    }
    if (candidate.startsWith(PAIRING_CREDENTIAL_PREFIX)) {
      return deps.pairing.verify(candidate.slice(PAIRING_CREDENTIAL_PREFIX.length))
    }
    if (candidate.includes(':')) return null
    if (!verifyRuntimeToken(deps.runtimeToken, candidate)) return null
    return { subject: 'daemon-runtime' }
  }
}

未知命名空间直接拒绝，不会退回 runtime token 比较。这使未来新增 credential kind 时不会被旧 daemon 当成另一类凭证。

5旅程 A：本机发布一个配对 offer

A.1监听地址与对外地址被刻意拆开

bindHost 可以是 0.0.0.0，但它不能出现在配对链接里；advertisedBaseUrl 必须是客户端实际能到达、并满足 remote-direct TLS 规则的 URL。

network: z.object({
  bindHost: bindHostSchema.default('127.0.0.1'),
  advertisedBaseUrl: advertisedBaseUrlSchema.optional(),
}).default({ bindHost: '127.0.0.1' })

if (env.BUFFIN_BIND_HOST !== undefined) {
  const bindHost = bindHostSchema.safeParse(env.BUFFIN_BIND_HOST)
  if (bindHost.success) merged.network.bindHost = bindHost.data
}

无效字段只被局部丢弃：坏的 bindHost 回到 loopback，坏的 advertisedBaseUrl 变成未配置，其他文件设置继续生效。额外的 hardening 会拒绝 0、2130706433、0x7f000001、127.1 这类会被底层解析成 IP 的旧式数字主机。

A.2只有本机 runtime principal 能开始配对

const pairingRouter = router({
  start: localOnlyProcedure
    .output(pairingOfferSchema)
    .mutation(({ ctx }) => callService(() => ctx.services.pairing.start())),
  claim: publicProcedure
    .input(pairingClaimInputSchema)
    .output(pairingClaimDtoSchema)
    .mutation(({ ctx, input }) => {
      const principal = requirePairingPrincipal(ctx.principal)
      return callService(() => ctx.services.pairing.claim(principal, input))
    }),
})

start 与 claim 不共享权限：前者必须来自本机 runtime principal；后者必须来自远端 pairing principal。这个非对称性就是 enrollment 的门闩。

start() {
  if (!deps.advertisedBaseUrl) {
    throw new PairingServiceError(PairingServiceErrorCode.notConfigured)
  }
  const now = clock()
  pruneExpiredOffers(offers, now)
  const pairingSecret = Buffer.from(makeRandomBytes(32)).toString('base64url')
  const expiresAt = now + PAIRING_OFFER_TTL_MS
  const offer = pairingOfferSchema.parse({
    serverId: deps.identity.daemonId,
    daemonPublicKey: Buffer.from(deps.identity.publicKey).toString('base64url'),
    endpoint: deps.advertisedBaseUrl,
    pairingSecret,
    expiresAt,
  })
  offers.set(hashPairingSecret(pairingSecret), { expiresAt })
  return offer
}

A.3CLI 把 offer 放进 URL fragment

const offer = await client.pairing.start.mutate()
if (mode === 'json') return { offer, link: null, qr: null }

const link = createPairingLink(offer)
const qr = await QRCode.toString(link, { type: 'terminal', small: true })
return { offer, link, qr }

交互终端显示 link、QR 和 ISO 过期时间；非 TTY 或 --json 只输出原始 offer，不加载 QR 渲染结果。offer 编码位于 #offer=…，不会成为 HTTP request path/query 的一部分。

6旅程 B：offer 换成持久设备凭证

B.1pairing principal 只有两扇门

客户端在任何业务 RPC 之前都要做 daemon.hello，所以 pairing credential 不能只允许 claim；它允许 hello 以完成身份/协议协商，但除此之外只能 claim。

const pairingAccessMiddleware = t.middleware(({ ctx, path, next }) => {
  if (
    ctx.principal.subject === 'pairing' &&
    path !== 'daemon.hello' &&
    path !== 'pairing.claim'
  ) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
      message: 'Pairing credentials can only negotiate and claim their offer.',
    })
  }
  return next()
})

同一 principal 在 terminal 和 blob 上被直接拒绝；因此拿到配对链接的人不能浏览模型、上传附件或附着终端。

B.2claim 的“原子点”是删除 offer

claim(principal, input) {
  const normalizedInput = pairingClaimInputSchema.parse(input)
  const offerHash = offerHashByPrincipal.get(principal)
  offerHashByPrincipal.delete(principal)
  if (!offerHash) throw unavailableOfferError()

  const record = offers.get(offerHash)
  if (!record || record.expiresAt <= clock()) {
    offers.delete(offerHash)
    throw unavailableOfferError()
  }

  offers.delete(offerHash)
  try {
    return pairingClaimDtoSchema.parse(
      deps.devices.issue(normalizedInput.name, normalizedInput.platform),
    )
  } catch (cause) {
    throw new PairingServiceError(PairingServiceErrorCode.issuanceFailed, { cause })
  }
}

输入先验证，offer 再删除，设备凭证最后签发。两个已经通过 credential 验证的并发 socket 也只能有一个删到 offer；如果设备写入失败，offer 仍保持已烧毁，调用方必须重新开始配对。

B.3设备 token 明文只出现一次

issue(name, platform) {
  const deviceToken = randomBytes(32).toString('base64url')
  const tokenHash = hashToken(deviceToken)
  const row = seam.run((tx) => {
    return tx.db.insert(devicesTable).values({
      id: createId(new Date(createdAt)),
      name: normalizedName,
      platform: normalizedPlatform,
      tokenHash,
      createdAt,
      lastSeenAt: null,
      revokedAt: null,
    }).returning().get()
  }).result
  return { deviceId: row.id, deviceToken }
}

后续连接携带 device:<token>。daemon 只计算 hash 查唯一索引，并拒绝 revokedAt 非空的行。lastSeenAt 最多每 60 秒写一次；这项 presence 更新失败时不会推翻已经成功的认证。

7旅程 C：撤销设备并终止访问

C.1授权失效先成为持久事实

revoke(deviceId) {
  const device = seam.run((tx) => {
    const current = tx.db.select().from(devicesTable)
      .where(eq(devicesTable.id, deviceId)).get()
    if (current.revokedAt !== null) return toDeviceDto(current)

    const row = tx.db.update(devicesTable)
      .set({ revokedAt: Math.max(clock(), current.createdAt, current.lastSeenAt ?? 0) })
      .where(and(eq(devicesTable.id, deviceId), isNull(devicesTable.revokedAt)))
      .returning().get()
    return toDeviceDto(row)
  }).result
  connections.closeFor(deviceId)
  return device
}

closeFor 在事务结果返回后才执行。于是 socket 被关闭时，下一次认证已经能从数据库观察到撤销，而不是出现“连接断了但 token 仍短暂有效”的反向窗口。

C.2connection registry 只跟踪长连接 carrier

const unregister = deps.connections.register(principal, {
  close: () => opts.res.terminate(),
  forceClose: () => opts.req.socket.destroy(),
})
opts.res.once('close', unregister)

register(principal, termination) {
  const deviceId = deviceIdOf(principal)
  if (deviceId === null) return () => {}
  // 建立 registration，并按 deviceId 放进 Set
  if (revokedDeviceIds.has(deviceId)) attemptClose(deviceId, registration)
  return () => deactivate(deviceId, registration)
},
closeFor(deviceId) {
  revokedDeviceIds.add(deviceId)
  const current = registrations.get(deviceId)
  if (!current) return
  for (const registration of [...current]) attemptClose(deviceId, registration)
}

registry 还维护 transport close、carrier force-close 与有界重试。即使一个已撤销设备在数据库状态切换后才完成 socket 注册，revokedDeviceIds 也会让它立刻进入关闭路径。

C.3blob 不登记连接，而是在每个请求开头重验

app.use('/blob/:sessionId', async (c, next) => {
  c.set('principal', verifyBlobPrincipal(
    credentialVerifier,
    c.req.header(DAEMON_TOKEN_HEADER) ?? null,
  ))
  requireCurrentProtocol(c.req.header(PROTOCOL_VERSION_HEADER))
  await next()
})

function verifyBlobPrincipal(verifier, candidate) {
  const principal = verifier(candidate)
  if (!principal || principal.subject === 'pairing') {
    throw new AppError({ code: BuffinErrorCode.auth.daemonRequired })
  }
  return principal
}

已经通过认证并拿到 response stream 的 blob 下载允许完成；撤销只影响之后开始的请求。这里没有 per-principal AbortController，也不会由 registry 中断流。

8计划 vs 实现的偏差

前三条“为什么”依据提交顺序、PR 描述和随附计划作出的实现意图归纳；第四条由实际文件范围直接确认。

9心智模型补丁

10新词表

11测试与风险地图

12验收提示与覆盖声明

别被这些变化误导

• packages/api/src/devices.js 与 pairing.js 是 Node source TypeScript loader shim，不是第二套实现。
• bun.lock 的 44 行来自 qrcode 及其依赖树；设计逻辑在 CLI command，不在 lockfile。
• Drizzle snapshot 的大块 JSON 与 baseline timestamp 是生成物；真正的新关系模型是 devicesTable。
• apps/desktop/tests/trpc-client-session.test.ts 的变化只是给扩宽后的 Services 填 fixture，不代表桌面已接入 pairing。
• 工作区 6 份 relay 中英文文档目前是未跟踪文件；本报告用它们解释计划，但它们不属于 PR #180 的提交 diff。

覆盖声明

主力逐文件读取了 origin/main...HEAD 的全部 56 个文件 diff（3,389 行变更），没有抽样；对 pairing、device、credential dispatch、network config、tRPC/terminal/blob carrier、connection registry 和 CLI 的当前文件进行了二次精读，并读取 base 侧 runtime auth、WS context、listener/config 以确认 before 管线。

随附英文 relay 设计、P0 review、P1 implementation plan 与对应中文镜像的结构均已核对；计划内容只用于动机、范围与偏差，不作为代码事实替代。生成的 migration snapshot 与 lockfile 已全量看过，但按机械生成物处理。

本次产物验证：bun run check 通过；围绕 API、CLI、daemon config、pairing/device service、真实 tRPC WS、terminal、blob 与 production listener 的 13 个测试文件共 214 个测试通过。

buffin · feat/relay-p1-123 · PR #180 · 3,249 additions / 140 deletions · 本报告为一次性理解辅助，不维护、不作为真相源。