@huakirax/dsh-plugin-pocket 0.0.0-stage → 0.1.1

package/src/iroh.js

@@ -0,0 +1,260 @@
+import { spawn, spawnSync } from 'node:child_process'
+import { createInterface } from 'node:readline'
+import { chmodSync, existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+import { homedir } from 'node:os'
+import { pipeline } from 'node:stream/promises'
+import { createWriteStream } from 'node:fs'
+import { Readable } from 'node:stream'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const irohRoot = join(here, '..', 'iroh')
+const hostBinName = process.platform === 'win32' ? 'pocket-host.exe' : 'pocket-host'
+
+/** Platform → GitHub release asset name (rolling tag dsh-android-latest). */
+export const PREBUILT_ASSET = {
+  'darwin-arm64': 'pocket-host-darwin-arm64',
+  'darwin-x64': 'pocket-host-darwin-x64',
+  'linux-x64': 'pocket-host-linux-x64',
+  'linux-arm64': 'pocket-host-linux-arm64',
+}
+
+const PREBUILT_BASE =
+  process.env.DSH_POCKET_HOST_URL_BASE
+  ?? 'https://github.com/minglu6/dsh-android/releases/download/dsh-android-latest'
+
+function platKey() {
+  return `${process.platform}-${process.arch}`
+}
+
+function cacheBinPath() {
+  const dir = join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'pocket', 'bin')
+  mkdirSync(dir, { recursive: true })
+  return join(dir, hostBinName)
+}
+
+/**
+ * Resolve the pocket-host binary for this platform (no download / build).
+ * Search order: config → env → cargo target → cache → optional npm package.
+ */
+export function resolveHostBinary(explicit) {
+  if (explicit) return explicit
+  if (process.env.DSH_POCKET_HOST) return process.env.DSH_POCKET_HOST
+  const release = join(irohRoot, 'target', 'release', hostBinName)
+  if (existsSync(release)) return release
+  const debug = join(irohRoot, 'target', 'debug', hostBinName)
+  if (existsSync(debug)) return debug
+  const cached = cacheBinPath()
+  if (existsSync(cached)) return cached
+  const prebuilt = join(irohRoot, 'prebuilt', platKey(), hostBinName)
+  if (existsSync(prebuilt)) return prebuilt
+  try {
+    const pkg = `dsh-pocket-host-${platKey()}`
+    const entry = require.resolve(`${pkg}/package.json`)
+    const bin = join(dirname(entry), hostBinName)
+    if (existsSync(bin)) return bin
+  } catch { /* optional dep missing */ }
+  return undefined
+}
+
+function cargoAvailable() {
+  const r = spawnSync('cargo', ['--version'], { encoding: 'utf8' })
+  return r.status === 0
+}
+
+/** Build pocket-host via cargo in plugin/iroh (synchronous). */
+export function buildHostWithCargo({ log = console.log } = {}) {
+  log('[pocket] building iroh sidecar with cargo (one-time; needs Rust toolchain)…')
+  const r = spawnSync(
+    'cargo',
+    ['build', '--release', '-p', 'pocket-host', '--manifest-path', join(irohRoot, 'Cargo.toml')],
+    { stdio: 'inherit', env: process.env },
+  )
+  if (r.status !== 0) {
+    throw new Error(`cargo build pocket-host failed (exit ${r.status})`)
+  }
+  const bin = join(irohRoot, 'target', 'release', hostBinName)
+  if (!existsSync(bin)) throw new Error(`cargo build succeeded but ${bin} missing`)
+  return bin
+}
+
+/** Download a CI-published pocket-host binary into ~/.dsh/pocket/bin. */
+export async function downloadPrebuiltHost({ log = console.log } = {}) {
+  const asset = PREBUILT_ASSET[platKey()]
+  if (!asset) {
+    throw new Error(`no prebuilt pocket-host for ${platKey()}`)
+  }
+  const url = `${PREBUILT_BASE.replace(/\/$/, '')}/${asset}`
+  log(`[pocket] downloading iroh sidecar from ${url}`)
+  const res = await fetch(url, { redirect: 'follow' })
+  if (!res.ok) {
+    throw new Error(`download failed: HTTP ${res.status} for ${url}`)
+  }
+  const dest = cacheBinPath()
+  const tmp = `${dest}.tmp-${process.pid}`
+  try {
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(tmp))
+    chmodSync(tmp, 0o755)
+    renameSync(tmp, dest)
+  } catch (e) {
+    try { unlinkSync(tmp) } catch { /* ignore */ }
+    throw e
+  }
+  // Write a tiny stamp so we can see which asset we got.
+  try {
+    writeFileSync(`${dest}.url`, `${url}\n`, { mode: 0o644 })
+  } catch { /* ignore */ }
+  return dest
+}
+
+/**
+ * Ensure a pocket-host binary exists: resolve → download prebuilt → cargo build.
+ * Returns the path, or undefined when iroh cannot be enabled (caller keeps WS-only).
+ */
+export async function ensureHostBinary(explicit, { log = (...a) => console.log('[pocket]', ...a), allowDownload = true, allowCargo = true } = {}) {
+  // Explicit path: never fall back to download/cargo (tests / config.hostBinary).
+  if (explicit) return existsSync(explicit) ? explicit : undefined
+
+  const existing = resolveHostBinary()
+  if (existing && existsSync(existing)) return existing
+
+  if (allowDownload && PREBUILT_ASSET[platKey()]) {
+    try {
+      return await downloadPrebuiltHost({ log: (m) => log(m.replace(/^\[pocket\]\s*/, '')) })
+    } catch (e) {
+      log(`prebuilt sidecar download skipped: ${e.message ?? e}`)
+    }
+  }
+
+  if (allowCargo && cargoAvailable()) {
+    try {
+      return buildHostWithCargo({ log: (m) => log(m.replace(/^\[pocket\]\s*/, '')) })
+    } catch (e) {
+      log(`cargo sidecar build failed: ${e.message ?? e}`)
+    }
+  }
+
+  return undefined
+}
+
+function missingSidecarHelp() {
+  const plat = platKey()
+  const asset = PREBUILT_ASSET[plat]
+  return [
+    `iroh sidecar not found for ${plat} — remote phone pairing is unavailable.`,
+    'Phones connect only over iroh (direct hole-punch, else relay); no Tailscale/VPN.',
+    'One-line install (from repo):  cd plugin && npm run build:iroh',
+    asset
+      ? `Or wait for / download the CI prebuilt: ${PREBUILT_BASE}/${asset}`
+      : 'Or install Rust (https://rustup.rs) and re-run; the plugin auto-builds on next start.',
+    'Override path with env DSH_POCKET_HOST=/path/to/pocket-host',
+  ].join('\n[pocket] ')
+}
+
+/**
+ * Spawn pocket-host and bridge peer sessions into the pocket server as pipe clients.
+ * @param {{ server: any, dataDir: string, hostBinary?: string, localOnly?: boolean, log?: (...a:any)=>void }} opts
+ * @returns {Promise<{ endpoint: Promise<{ id: string, directAddress: string | null }>, close: () => Promise<void> } | null>}
+ */
+export async function startIrohSidecar(opts) {
+  const log = opts.log ?? ((...a) => console.log('[pocket]', ...a))
+  const binary = await ensureHostBinary(opts.hostBinary, { log })
+  if (!binary || !existsSync(binary)) {
+    log(missingSidecarHelp())
+    return null
+  }
+  log(`iroh sidecar: ${binary}`)
+  const args = ['host', '--data-dir', opts.dataDir]
+  if (opts.localOnly) args.push('--local-only')
+  const child = spawn(binary, args, { stdio: ['pipe', 'pipe', 'inherit'], windowsHide: true })
+  let gone
+  child.on('exit', (code) => {
+    gone = `sidecar exited (code=${code})`
+    console.error(`[pocket] iroh ${gone}`)
+    rejectReady(new Error(gone))
+  })
+  child.on('error', (error) => {
+    gone = `sidecar failed to start: ${error.message}`
+    console.error(`[pocket] iroh ${gone} (${binary})`)
+    rejectReady(new Error(gone))
+  })
+
+  const send = (msg) => {
+    if (gone || !child.stdin.writable) return
+    child.stdin.write(`${JSON.stringify(msg)}\n`)
+  }
+
+  let resolveReady, rejectReady
+  const endpoint = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject })
+  /** @type {Map<string, { push(line: string): void, close(): void }>} */
+  const sessions = new Map()
+
+  const rl = createInterface({ input: child.stdout })
+  rl.on('line', (line) => {
+    let msg
+    try { msg = JSON.parse(line) } catch {
+      console.error(`[pocket] bad sidecar line: ${line}`)
+      return
+    }
+    switch (msg.type) {
+      case 'ready':
+        resolveReady({ id: msg.endpoint_id, directAddress: msg.direct_addr ?? null })
+        log(`iroh ready, node id: ${msg.endpoint_id}`)
+        break
+      case 'peer-session': {
+        const id = msg.id
+        const peer = msg.peer
+        const client = opts.server.attachPipe({
+          send: (frame) => send({ type: 'session-send', id, line: JSON.stringify(frame) }),
+          close: () => send({ type: 'session-close', id }),
+          meta: { transport: 'iroh', peer },
+        })
+        sessions.set(id, client)
+        log(`iroh peer session ${id} from ${String(peer).slice(0, 16)}…`)
+        break
+      }
+      case 'peer-data': {
+        const client = sessions.get(msg.id)
+        if (!client) return
+        try {
+          const frame = JSON.parse(msg.line)
+          client.onMessage(frame, msg.line.length)
+        } catch {
+          client.close(1007, 'bad json')
+        }
+        break
+      }
+      case 'peer-path':
+        log(`iroh path ${msg.kind} ${msg.remote}`)
+        opts.server.noteIrohPath?.(msg.peer, msg.kind)
+        break
+      case 'peer-session-end': {
+        const client = sessions.get(msg.id)
+        sessions.delete(msg.id)
+        if (msg.peer) opts.server.clearIrohPath?.(msg.peer)
+        client?.onRemoteClose()
+        break
+      }
+      default:
+        console.error(`[pocket] unknown sidecar message: ${line}`)
+    }
+  })
+
+  return {
+    endpoint,
+    /** @returns {Promise<void>} */
+    close: () => new Promise((resolve) => {
+      const done = () => resolve()
+      try { rl.close() } catch { /* ignore */ }
+      try { child.stdin?.destroy() } catch { /* ignore */ }
+      try { child.stdout?.destroy() } catch { /* ignore */ }
+      if (child.exitCode !== null || child.signalCode !== null) { done(); return }
+      const t = setTimeout(() => { try { child.kill('SIGKILL') } catch { /* ignore */ }; done() }, 1500)
+      child.once('exit', () => { clearTimeout(t); done() })
+      try { child.kill('SIGKILL') } catch { clearTimeout(t); done() }
+    }),
+  }
+}

package/src/manage.js

@@ -0,0 +1,122 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { selectNetwork } from './advertise-host.js'
+import { normalizeTransport } from './transport-pref.js'
+
+const PKG = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'))
+
+/**
+ * Phone QR / deep link — host:port only.
+ *
+ * `dshpocket://pair?h=<host:port>&c=<code>`
+ *
+ * @param {{ code?: string, host?: string, port?: number, transport?: string }} opts
+ */
+export function pairingUri({ code, host, port, transport }) {
+  if (!code) return undefined
+  const mode = normalizeTransport(transport) ?? (host ? 'tailscale' : null)
+  if (mode !== 'tailscale') return undefined
+  if (!host || !port) return undefined
+  return `dshpocket://pair?h=${encodeURIComponent(`${host}:${port}`)}&c=${encodeURIComponent(code)}`
+}
+
+/**
+ * Pasteable one-liner — same URI shape as the QR payload.
+ *
+ * @param {{ code?: string, host?: string, port?: number, transport?: string }} opts
+ */
+export function pairingString({ code, host, port, transport }) {
+  return pairingUri({ code, host, port, transport })
+}
+
+/**
+ * Facade used by management HTTP routes and the client half.
+ * @param {{
+ *   getNetworks: () => Array<{type: 'lan'|'tailscale', host: string}>,
+ *   port: number,
+ *   devices: any,
+ *   pairing: any,
+ *   server: any,
+ *   openPairing: Function,
+ *   getTransport: () => 'tailscale',
+ *   setTransport?: (mode: string) => 'tailscale',
+ * }} opts
+ */
+export function createManageApi({
+  getNetworks, port, devices, pairing, server, openPairing, getTransport, setTransport,
+  instanceId, getMdns,
+}) {
+  const transport = () => getTransport()
+  const withOnline = () => {
+    const online = server.onlineDeviceIds()
+    return devices.list().map((d) => ({ ...d, online: online.has(d.id) }))
+  }
+  const listenPort = () => {
+    const address = server.address()
+    return address && typeof address === 'object' ? address.port : port
+  }
+  const enrichPairing = (status, selected, selectedPort) => {
+    if (!selected) return { open: false }
+    const { host } = selected
+    const code = status?.code
+    if (!code) return status?.open ? status : { open: false }
+    const mode = transport()
+    return {
+      open: true,
+      ...status,
+      code,
+      transport: mode,
+      host,
+      port: selectedPort,
+      uri: pairingUri({ code, host, port: selectedPort, transport: mode }),
+      pairingString: pairingString({ code, host, port: selectedPort, transport: mode }),
+    }
+  }
+  return {
+    openPairing: (network) => {
+      const selected = selectNetwork(getNetworks(), network)
+      if (!selected || server.address() === null) {
+        throw Object.assign(new Error('No reachable network is available for pairing'), { statusCode: 503 })
+      }
+      const port = listenPort()
+      openPairing({ ...selected, port })
+      return enrichPairing(pairing.status(), selected, port)
+    },
+    closePairing: () => { pairing.close(); return { open: false } },
+    pairingStatus: (network) => enrichPairing(pairing.status(), selectNetwork(getNetworks(), network), listenPort()),
+    listDevices: withOnline,
+    revokeDevice: (id) => server.revokeDevice(id),
+    renameDevice: (id, name) => devices.rename(id, name),
+    setTransport: (mode) => {
+      if (typeof setTransport !== 'function') throw new Error('setTransport unavailable')
+      return { transport: setTransport(mode) }
+    },
+    getStatus: (network) => {
+      const networks = getNetworks()
+      const selected = selectNetwork(networks, network)
+      const addr = server.address()
+      const listening = addr !== null
+      const listenHost = listening && typeof addr === 'object' ? addr.address : ''
+      const port = listenPort()
+      const mode = transport()
+      return {
+        running: listening,
+        version: PKG.version,
+        plugin: PKG.name,
+        transport: mode,
+        networks,
+        host: selected?.host ?? '',
+        port,
+        instanceId: typeof instanceId === 'string' ? instanceId : undefined,
+        mdns: typeof getMdns === 'function' ? Boolean(getMdns()) : false,
+        connectionType: selected?.type ?? null,
+        listen: listening
+          ? [{ host: listenHost, port, address: typeof addr === 'string' ? addr : `${listenHost}:${port}` }]
+          : [],
+        pairing: enrichPairing(pairing.status(), selected, port),
+        devices: withOnline(),
+      }
+    },
+  }
+}

package/src/mdns-advertise.js

@@ -0,0 +1,75 @@
+/**
+ * Advertise the pocket WebSocket listener via mDNS/Bonjour (_dshpocket._tcp).
+ *
+ * Adapted from dsh-mobile gateway mDNS publish
+ * (https://github.com/saya-ch/dsh-mobile src/gateway.ts), Apache-2.0.
+ */
+import { hostname } from 'node:os'
+import Bonjour from 'bonjour-service'
+
+export const MDNS_SERVICE_TYPE = 'dshpocket'
+export const DISCOVERY_PROTOCOL = 1
+
+/** @returns {string} */
+export function discoveryDeviceName() {
+  const value = [...hostname().trim()].filter((ch) => {
+    const code = ch.codePointAt(0) ?? 0
+    return code >= 0x20 && code !== 0x7f
+  }).join('')
+  return (value === '' ? 'dsh' : value).slice(0, 63)
+}
+
+/** @param {string} instanceId */
+export function discoveryMdnsHost(instanceId) {
+  const label = hostname().toLowerCase().replaceAll(/[^a-z0-9-]/gu, '-').replaceAll(/^-+|-+$/gu, '').slice(0, 40)
+  return `${label === '' ? 'dsh' : label}-${instanceId.slice(0, 8)}.local`
+}
+
+/**
+ * @param {{
+ *   host: string,
+ *   port: number,
+ *   instanceId: string,
+ *   deviceName?: string,
+ *   onError?: (err: Error) => void,
+ *   log?: (...a: unknown[]) => void,
+ * }} opts
+ */
+export function startMdnsAdvertise(opts) {
+  const deviceName = opts.deviceName ?? discoveryDeviceName()
+  const onError = (error) => {
+    try { opts.onError?.(error instanceof Error ? error : new Error(String(error))) } catch { /* ignore */ }
+  }
+  const bonjour = new Bonjour({ disableIPv6: true }, onError)
+  // bonjour-service 1.4.4 does not forward multicast-dns EventEmitter errors
+  // through errorCallback. Keep a listener on its underlying emitter for its lifetime.
+  const mdns = /** @type {{ server: { mdns: { on(event: 'error', listener: (error: Error) => void): void } } }} */ (bonjour).server.mdns
+  mdns.on('error', onError)
+  const service = bonjour.publish({
+    name: `${deviceName} (${opts.instanceId.slice(0, 8)})`,
+    type: MDNS_SERVICE_TYPE,
+    protocol: 'tcp',
+    port: opts.port,
+    host: discoveryMdnsHost(opts.instanceId),
+    disableIPv6: true,
+    txt: {
+      deviceName,
+      host: opts.host,
+      port: String(opts.port),
+      instanceId: opts.instanceId,
+      protocol: String(DISCOVERY_PROTOCOL),
+    },
+  })
+  opts.log?.(`mdns advertising _${MDNS_SERVICE_TYPE}._tcp (${deviceName}, ${opts.host}:${opts.port})`)
+  return {
+    deviceName,
+    service,
+    stop: () => new Promise((resolve) => {
+      try {
+        bonjour.unpublishAll(() => { bonjour.destroy(() => resolve()) })
+      } catch {
+        resolve()
+      }
+    }),
+  }
+}

package/src/office-preview.js

@@ -0,0 +1,129 @@
+import { extname } from 'node:path'
+
+export const OFFICE_CHUNK_BYTES = 128 * 1024
+const OUTPUT_LIMIT = 100 * 1024 * 1024
+const failure = (reason) => Object.assign(new Error('Office conversion failed.'), {
+  code: 'document-render/failed', details: { reason },
+})
+const bad = () => Object.assign(new Error('Invalid Office preview request.'), { code: 'gateway/bad-request' })
+const missing = () => Object.assign(new Error('Office preview handle is unavailable.'), { code: 'office/handle-unavailable' })
+
+/** Connection-owned leases over the official converter's caller-owned output; no second conversion cache. */
+export function createOfficePreviewOps(ctx, {
+  leaseMs = 60_000, maxHandles = 8, maxRetainedBytes = 200 * 1024 * 1024,
+  maxOutputBytes = OUTPUT_LIMIT, renderTimeoutMs = 600_000,
+} = {}) {
+  const handles = new Map()
+  let retainedBytes = 0
+  let disposed = false
+  const scopeOf = async (sessionId) => {
+    const live = ctx.sessions.get(sessionId)?.header
+    const stored = live === undefined ? await ctx.get('sessionPersistence')?.stat(sessionId) : undefined
+    const header = live ?? stored?.header
+    if (header === undefined) throw Object.assign(new Error('Session not found.'), { code: 'session/not-found' })
+    const workspaceRoot = header.cwd ?? ctx.sandboxPolicy.workspaceRoot
+    return { sessionId, workspaceRoot }
+  }
+  const release = (entry) => {
+    if (handles.get(entry.id) !== entry) return
+    handles.delete(entry.id)
+    clearTimeout(entry.timer)
+    retainedBytes -= entry.reserved
+    entry.data = undefined
+    if (entry.client.subs.get(entry.id) === entry.ac) entry.client.subs.delete(entry.id)
+    entry.ac.abort()
+  }
+  const renew = (entry, ms = leaseMs, rendering = false) => {
+    clearTimeout(entry.timer)
+    entry.timer = setTimeout(() => {
+      entry.timedOut = rendering
+      release(entry)
+    }, ms)
+    entry.timer.unref?.()
+  }
+  const owned = (a, client) => {
+    const entry = handles.get(a.handle)
+    if (!entry || entry.client !== client || entry.scope?.sessionId !== a.sessionId) throw missing()
+    return entry
+  }
+  const unchanged = async (entry, signal) => {
+    const scope = await scopeOf(entry.scope.sessionId)
+    if (scope.workspaceRoot !== entry.scope.workspaceRoot) throw failure('source-changed')
+    const current = await ctx.workspaceFiles.stat(scope, entry.path, signal)
+    if (current.absolutePath !== entry.meta.absolutePath || current.version !== entry.meta.version) throw failure('source-changed')
+    signal.throwIfAborted()
+  }
+  const ops = {
+    'office.render': async (a, signal, client) => {
+      if (typeof a.sessionId !== 'string' || !a.sessionId || typeof a.path !== 'string' || !a.path ||
+          !/^o-[a-zA-Z0-9-]{1,80}$/.test(a.subId ?? '') || !client?.subs || client.subs.has(a.subId) || handles.has(a.subId)) throw bad()
+      if (!['.doc', '.docx', '.ppt', '.pptx'].includes(extname(a.path).toLowerCase())) throw failure('unsupported-format')
+      if (disposed) throw failure('unavailable')
+      if (handles.size >= maxHandles || retainedBytes + maxOutputBytes > maxRetainedBytes) throw failure('busy')
+      const ac = new AbortController()
+      const entry = { id: a.subId, sessionId: a.sessionId, client, ac, path: a.path, reserved: maxOutputBytes }
+      handles.set(entry.id, entry)
+      retainedBytes += entry.reserved
+      client.subs.set(entry.id, ac)
+      ac.signal.addEventListener('abort', () => release(entry), { once: true })
+      renew(entry, renderTimeoutMs, true)
+      const upstream = AbortSignal.any([ac.signal, signal, AbortSignal.timeout(renderTimeoutMs)])
+      try {
+        entry.scope = await scopeOf(a.sessionId)
+        upstream.throwIfAborted()
+        const result = await ctx.officeToPdf.render(entry.scope, a.path, 'foreground', upstream)
+        upstream.throwIfAborted()
+        if (!(result.data instanceof Uint8Array) || result.eof !== true || result.offset !== 0 ||
+            result.bytes !== result.data.byteLength || result.bytes <= 0 ||
+            typeof result.version !== 'string' || typeof result.generation !== 'string' ||
+            typeof result.absolutePath !== 'string' || !Array.isArray(result.missingFonts) ||
+            !result.missingFonts.every(font => typeof font === 'string')) throw failure('invalid-output')
+        if (result.bytes > maxOutputBytes) throw failure('output-too-large')
+        entry.meta = {
+          handle: entry.id, absolutePath: result.absolutePath, version: result.version,
+          generation: result.generation, bytes: result.bytes, missingFonts: result.missingFonts,
+          chunkBytes: OFFICE_CHUNK_BYTES,
+        }
+        await unchanged(entry, upstream)
+        retainedBytes += result.bytes - entry.reserved
+        entry.reserved = result.bytes
+        entry.data = result.data
+        renew(entry)
+        return entry.meta
+      } catch (error) {
+        const cancelled = upstream.aborted
+        const timedOut = entry.timedOut || upstream.reason?.name === 'TimeoutError'
+        release(entry)
+        if (timedOut) throw failure('timeout')
+        if (cancelled) throw Object.assign(new Error('The document preview was cancelled.'), { code: 'gateway/cancelled' })
+        throw error
+      }
+    },
+    'office.read': async (a, signal, client) => {
+      const entry = owned(a, client)
+      if (!entry.data) throw missing()
+      if (!Number.isSafeInteger(a.offset) || a.offset < 0 || a.offset >= entry.data.byteLength ||
+          !Number.isSafeInteger(a.length) || a.length < 1 || a.length > OFFICE_CHUNK_BYTES) throw bad()
+      try {
+        if (a.version !== entry.meta.version || a.generation !== entry.meta.generation) throw failure('source-changed')
+        const upstream = AbortSignal.any([signal, entry.ac.signal])
+        await unchanged(entry, upstream)
+        const end = Math.min(entry.data.byteLength, a.offset + a.length)
+        const data = Buffer.from(entry.data.buffer, entry.data.byteOffset + a.offset, end - a.offset).toString('base64')
+        renew(entry)
+        return { absolutePath: entry.meta.absolutePath, version: entry.meta.version,
+          generation: entry.meta.generation, bytes: entry.meta.bytes, offset: a.offset,
+          eof: end === entry.data.byteLength, encoding: 'base64', data }
+      } catch (error) { release(entry); throw error }
+    },
+    'office.release': (a, _signal, client) => {
+      const entry = handles.get(a.handle)
+      if (!entry) return { released: false }
+      // Pending renders also have an owner and can be cancelled before scope lookup settles.
+      if (entry.client !== client || entry.sessionId !== a.sessionId) throw missing()
+      release(entry)
+      return { released: true }
+    },
+  }
+  return { ops, dispose() { disposed = true; for (const entry of handles.values()) release(entry) } }
+}

package/src/pairing-uri.js

@@ -0,0 +1,42 @@
+/**
+ * Pure `dshpocket://` pairing URI parser — mirrors Android PairingUriPolicy.
+ * Shared vectors: ../../contract/pairing-uri-cases.json
+ *
+ * Happy path: `dshpocket://pair?h=<host:port>&c=<6-digit>`
+ * Legacy iroh forms (`n=` / `nodeId#code`) are rejected.
+ */
+
+const CODE = /^\d{6}$/
+
+/**
+ * @param {string} raw
+ * @returns {{ host: string, port: number } | null}
+ */
+export function parseHostPort(raw) {
+  const t = String(raw || '').trim().replace(/^wss?:\/\//, '')
+  const match = /^\[?([^[\]]+?)]?:(\d{1,5})$/.exec(t)
+  if (!match) return null
+  const port = Number(match[2])
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null
+  const host = match[1]
+  if (!host) return null
+  return { host, port }
+}
+
+/**
+ * @param {string} text
+ * @returns {{ host: string, port: number, code: string } | null}
+ */
+export function parsePairingUri(text) {
+  const s = String(text ?? '').trim()
+  if (!s.startsWith('dshpocket://pair')) return null
+  const q = new URLSearchParams(s.includes('?') ? s.slice(s.indexOf('?') + 1) : '')
+  const c = q.get('c')
+  if (!c || !CODE.test(c)) return null
+  if (q.get('n')) return null
+  const h = q.get('h')
+  if (!h) return null
+  const hp = parseHostPort(h)
+  if (!hp) return null
+  return { host: hp.host, port: hp.port, code: c }
+}

package/src/pairing.js

@@ -0,0 +1,34 @@
+import { randomInt } from 'node:crypto'
+
+export const PAIRING_TTL_MS = 600_000
+export const PAIRING_MAX_ATTEMPTS = 3
+export const PAIR_NO_WINDOW = 'pair/no-window'
+export const PAIR_EXPIRED = 'pair/expired'
+export const PAIR_TOO_MANY = 'pair/too-many-attempts'
+export const PAIR_BAD_CODE = 'pair/bad-code'
+
+/** One pairing window at a time: 6-digit code, 10 min TTL, 3 attempts (same rules as dsh-tether). */
+export function createPairing({ now = Date.now, ttlMs = PAIRING_TTL_MS } = {}) {
+  let win
+  return {
+    open() {
+      win = { code: String(randomInt(0, 1_000_000)).padStart(6, '0'), deadline: now() + ttlMs, attempts: 0 }
+      return { code: win.code, expiresInSec: Math.round(ttlMs / 1000) }
+    },
+    close() { win = undefined },
+    /** Includes `code` while open so the local management UI can re-render after refresh. */
+    status: () => (win && now() < win.deadline
+      ? { open: true, code: win.code, expiresInSec: Math.round((win.deadline - now()) / 1000), attemptsLeft: PAIRING_MAX_ATTEMPTS - win.attempts }
+      : { open: false }),
+    /** @returns {null | string} null on success (window consumed), else a reason code */
+    attempt(code) {
+      if (!win) return PAIR_NO_WINDOW
+      if (now() >= win.deadline) { win = undefined; return PAIR_EXPIRED }
+      if (win.attempts >= PAIRING_MAX_ATTEMPTS) { win = undefined; return PAIR_TOO_MANY }
+      win.attempts++
+      if (typeof code === 'string' && code === win.code) { win = undefined; return null }
+      if (win.attempts >= PAIRING_MAX_ATTEMPTS) { win = undefined; return PAIR_TOO_MANY }
+      return PAIR_BAD_CODE
+    },
+  }
+}