diff --git a/packages/plugin/src/host-pairing.ts b/packages/plugin/src/host-pairing.ts new file mode 100644 index 0000000..8086fa4 --- /dev/null +++ b/packages/plugin/src/host-pairing.ts @@ -0,0 +1,213 @@ +import { createHash, createHmac, createPrivateKey, createPublicKey, diffieHellman, hkdfSync, randomBytes, createCipheriv, createDecipheriv } from 'node:crypto'; +import { join } from 'node:path'; +import { rm } from 'node:fs/promises'; +import { z } from 'zod'; +import { normalizeServerUrl } from './config.js'; +import { atomicWritePrivate, readPrivateJson } from './server-credentials.js'; +import { ServerApiError, type FetchImplementation } from './server-api.js'; +import type { HostIdentity } from './identity-store.js'; +import { pairingCreatedSchema, pairingStatusSchema, savedPairingSchema, type PairingCredentials, type HostPairingView } from './pairing-contract.js'; +import { uuidV7 } from './ids.js'; +const root = '/api/v1/device-pairing/sessions'; +type Saved = z.infer; +const active = new Set(['created', 'claimed', 'approved']); +function rawKey(text: string): Buffer { + const bytes = Buffer.from(text, 'base64url'); + if (bytes.length !== 32 || bytes.toString('base64url') !== text) + throw new ServerApiError('PAIRING_IDENTITY_INVALID', 'Invalid pairing key.', false); + return bytes; +} +export function pairingProof(privateKey: string, serverKey: string, id: string, path: string, raw: string, side: 'host' | 'mobile' = 'host'): string { + const local = createPrivateKey({ key: Buffer.concat([Buffer.from('302e020100300506032b656e04220420', 'hex'), rawKey(privateKey)]), format: 'der', type: 'pkcs8' }); + const peer = createPublicKey({ key: Buffer.concat([Buffer.from('302a300506032b656e032100', 'hex'), rawKey(serverKey)]), format: 'der', type: 'spki' }); + const shared = diffieHellman({ privateKey: local, publicKey: peer }); + const key = Buffer.from(hkdfSync('sha256', shared, Buffer.from(id), Buffer.from('dsh-pairing-v1/' + side), 32)); + try { + return createHmac('sha256', key).update(`POST\n${path}\n${createHash('sha256').update(raw).digest('hex')}`).digest('base64url'); + } + finally { + shared.fill(0); + key.fill(0); + } +} +export const fullFingerprint = (key: string): string => createHash('sha256').update(rawKey(key)).digest('hex'); +/** Host-only local workflow. No phone code retrieval, model tools or tunnel RPC. */ +export class HostPairing { + private readonly path: string; + private readonly serverUrl: string; + private readonly lifetime = new AbortController(); + private queue: Promise = Promise.resolve(); + constructor(serverUrl: string, directory: string, private readonly identity: HostIdentity, private readonly descriptor: Record, private readonly adopt: (value: PairingCredentials) => Promise, private readonly fetcher: FetchImplementation = fetch, httpServerAllowlist: readonly string[] = []) { + this.serverUrl = normalizeServerUrl(serverUrl, httpServerAllowlist); + this.path = join(directory, 'host-pairing.json'); + } + close(): void { this.lifetime.abort(); } + async discard(): Promise { this.close(); await this.queue.catch(() => undefined); await rm(this.path, { force: true }); } + private serial(fn: () => Promise): Promise { const task = this.queue.catch(() => undefined).then(fn); this.queue = task; return task; } + start(): Promise { + return this.serial(async () => { + const old = await this.load(); + if (old) { + const status = await this.poll(old); + if (active.has(status.state)) + await this.send(old, 'host/cancel', '{}'); + } + const discovery = await this.request('/api/v1/auth/oauth/providers', undefined, undefined, 'GET') as { capabilities?: { devicePairingQr?: unknown } }; + const compactQr = discovery.capabilities?.devicePairingQr === 'fragment-ticket-v1'; + const session = pairingCreatedSchema.parse(await this.request(root, JSON.stringify({ v: 1, device: this.descriptor }))); + this.assertHost(session.host); + if (session.expiresAt <= Date.now() || session.expiresAt > Date.now() + 240000) + throw new ServerApiError('INVALID_MESSAGE', 'Invalid pairing expiry.', false); + const saved: Saved = { serverUrl: this.serverUrl, deviceId: this.identity.deviceId, session, state: 'created', localSaved: false, ...(compactQr ? { qrFormat: 'fragment-ticket-v1' as const } : {}) }; + await this.save(saved); + return this.view(saved); + }); + } + status(): Promise { return this.serial(async () => { const saved = await this.load(); return saved ? this.poll(saved) : undefined; }); } + confirm(id: string, code?: string): Promise { + return this.serial(async () => { + const saved = await this.requireSession(id); + let raw: string; + if (saved.submission !== undefined) { + if (code !== undefined) + throw new ServerApiError('PAIRING_ATTEMPT_USED', 'Recover the original submission without changing the code.', false); + raw = this.crypt(saved.submission, id, false); + } + else { + if (saved.state !== 'claimed' || typeof code !== 'string' || !/^[0-9]{8}$/.test(code)) + throw new ServerApiError('INVALID_MESSAGE', 'Confirm on the phone and enter 8 digits.', false); + raw = JSON.stringify({ submissionId: uuidV7(), verificationCode: code }); + saved.submission = this.crypt(raw, id, true); + await this.save(saved); + } + return this.accept(saved, await this.send(saved, 'host/confirm', raw)); + }); + } + cancel(id: string): Promise { return this.serial(async () => { const s = await this.requireSession(id); return this.accept(s, await this.send(s, 'host/cancel', '{}')); }); } + private async load(): Promise { + const value = await readPrivateJson(this.path); + if (value === undefined) + return undefined; + const s = savedPairingSchema.parse(value); + if (s.serverUrl !== this.serverUrl || s.deviceId !== this.identity.deviceId) + throw new ServerApiError('PAIRING_IDENTITY_INVALID', 'Pairing belongs to another identity.', false); + if (s.session.expiresAt + 300000 <= Date.now()) { + await rm(this.path, { force: true }); + return undefined; + } + return s; + } + private async requireSession(id: string): Promise { + const s = await this.load(); + if (!s || s.session.sessionId !== id) + throw new ServerApiError('PAIRING_CLOSED', 'This pairing was replaced or expired.', false); + return s; + } + private save(s: Saved): Promise { return atomicWritePrivate(this.path, JSON.stringify(s)); } + private async poll(s: Saved): Promise { + try { + return await this.accept(s, await this.send(s, 'host/status', '{}')); + } + catch (e) { + if (!(e instanceof ServerApiError) || e.status !== 404) + throw e; + s.state = 'expired'; + delete s.submission; + await this.save(s); + return this.view(s); + } + } + private assertHost(d: { + deviceId: string; + role: string; + identityKey: string; + }): void { + if (d.deviceId !== this.identity.deviceId || d.role !== 'host' || d.identityKey !== this.identity.publicKey) + throw new ServerApiError('PAIRING_IDENTITY_INVALID', 'Host identity changed.', false); + } + private async accept(s: Saved, value: unknown): Promise { + this.lifetime.signal.throwIfAborted(); + const r = pairingStatusSchema.parse(value); + if (r.sessionId !== s.session.sessionId || r.expiresAt !== s.session.expiresAt) + throw new ServerApiError('INVALID_MESSAGE', 'Pairing session changed.', false); + this.assertHost(r.host); + if (r.mobile) { + if (r.mobile.role !== 'client' || r.mobile.deviceId === this.identity.deviceId || r.mobile.identityKey === this.identity.publicKey + || s.mobile && (s.mobile.deviceId !== r.mobile.deviceId || s.mobile.identityKey !== r.mobile.identityKey)) + throw new ServerApiError('PAIRING_DEVICE_CONFLICT', 'Phone identity changed.', false); + s.mobile = r.mobile; + } + if (r.state === 'completed') { + if (!r.credentials) + throw new ServerApiError('INVALID_MESSAGE', 'Missing Host credentials.', false); + this.assertHost(r.credentials.device); + if (r.credentials.pairingRestricted && !r.credentials.inboundOnly) + throw new ServerApiError('DEVICE_SCOPE_REQUIRED', 'Paired Host must remain inbound only.', false); + if (!s.localSaved) { + await this.adopt(r.credentials); + s.localSaved = true; + } + } + s.state = r.state; + if (!active.has(s.state)) + delete s.submission; + await this.save(s); + return this.view(s, r.failureReason); + } + private view(s: Saved, reason?: string | null): HostPairingView { + return { sessionId: s.session.sessionId, state: s.state, expiresAt: s.session.expiresAt, serverUrl: this.serverUrl, hostFingerprint: fullFingerprint(this.identity.publicKey), + ...(s.state === 'created' ? { qrPayload: s.qrFormat === 'fragment-ticket-v1' ? `${this.serverUrl}/pair#v1.${s.session.scanSecret}` : JSON.stringify({ type: 'dsh.remote.pairing', ...s.session, serverUrl: this.serverUrl }) } : {}), + ...(s.mobile ? { mobile: { deviceId: s.mobile.deviceId, name: s.mobile.name, fingerprint: fullFingerprint(s.mobile.identityKey) } } : {}), + ...(reason ? { failureReason: reason } : {}), canRetry: s.submission !== undefined && active.has(s.state), localSaved: s.localSaved }; + } + private send(s: Saved, action: string, raw: string): Promise { + const path = `${root}/${s.session.sessionId}/${action}`; + return this.request(path, raw, pairingProof(this.identity.privateKey, s.session.serverPublicKey, s.session.sessionId, path, raw)); + } + private async request(path: string, body: string | undefined, proof?: string, method = 'POST'): Promise { + try { + const response = await this.fetcher(this.serverUrl + path, { method, redirect: 'error', headers: { 'Content-Type': 'application/json', ...(proof ? { 'X-DSH-Pairing-Proof': proof } : {}) }, body, signal: AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(10000)]) }); + if (response.status === 404 && method === 'GET' && path === '/api/v1/auth/oauth/providers') return {}; + if (response.status === 404 && path === root) + throw new ServerApiError('PAIRING_UNSUPPORTED', 'This Server does not support pairing.', false); + const text = await response.text(); + if (text.length > 32768) + throw new Error('oversized response'); + const value = JSON.parse(text) as { + error?: { + code?: string; + }; + }; + if (!response.ok) { + const code = value.error?.code; + throw new ServerApiError(typeof code === 'string' && /^[A-Z_]{1,80}$/.test(code) ? code : 'PAIRING_REQUEST_FAILED', 'Pairing failed; recover the original submission if sent.', response.status >= 500 || response.status === 429, response.status); + } + return value; + } + catch (e) { + if (e instanceof ServerApiError) + throw e; + throw new ServerApiError('PAIRING_CONNECTION_FAILED', 'Pairing result is unknown. Recover the original submission.', true); + } + } + private crypt(value: string, id: string, encrypt: boolean): string { + const key = createHash('sha256').update('dsh-pairing-host-submission-v1\0').update(rawKey(this.identity.privateKey)).digest(); + try { + if (encrypt) { + const iv = randomBytes(12); + const c = createCipheriv('aes-256-gcm', key, iv); + c.setAAD(Buffer.from(id)); + const data = Buffer.concat([c.update(value, 'utf8'), c.final()]); + return Buffer.concat([iv, c.getAuthTag(), data]).toString('base64url'); + } + const b = Buffer.from(value, 'base64url'); + const c = createDecipheriv('aes-256-gcm', key, b.subarray(0, 12)); + c.setAAD(Buffer.from(id)); + c.setAuthTag(b.subarray(12, 28)); + return Buffer.concat([c.update(b.subarray(28)), c.final()]).toString('utf8'); + } + finally { + key.fill(0); + } + } +}